Chapter 2. Introduction to the Waf scripting system

Table of Contents

Empty project example
Workflow illustration on a more complicated example
Building a project - Introduction to Tasks
Configuring a project
Adding custom command-line options
Installing targets

Empty project example

The Waf scripts are based on the following concepts:

  • System files: files and folders which do not belong to the project
  • Source directory: directory containing the source files for an application, it is meant to be ultimately packaged, and redistributed to other developers or to end users.
  • Build directory: all files produced by Waf will be output in that folder

The Waf philosophy is to avoid the pollution of the source directory by letting all files into the build directory. The build directory can be located on the system, out of the source directory (like in /tmp for example).

When Waf is launched, it looks for the user-defined Waf scripts which are files written in the Python language. The most important one is the top-level Waf script file in which several functions and attributes must be provided for defining a valid Waf project:

  • srcdir: string representing the source directory
  • blddir: string representing the build directory
  • set_options: function used for adding custom command-line options
  • configure: function called for configuring the project
  • build: function used for building the project

The top-level Waf script file name is "wscript"

A simple empty Waf project can be declared using a wscript file containing the following Python code:

srcdir = '.'
blddir = 'output'

def set_options(opt):
    print('  setting the options')
def configure(conf):
    print('  executing the configuration')
def build(bld):
    print('  building the project')
		

The minimum workflow for any project consists of the following steps:

  • Configuring the project: searching for system parameters and compilers
  • Building the project: building the software

To do this, the following shell commands will be:

$ waf configure
  setting the options
  executing the configuration
$ waf build
  setting the options
  building the project