8/8/2019 2009 - The Waf Book (v1.5.4)

1/43

The Waf Book (v1.5.4)Thomas Nagy

Copyright 2008-2009 Thomas Nagy

Copies of this book m ay be redistributed, v erbatim, and for non-com mercial purposes. The

license for this boo k is by-nc-n d license

Table of Contents

Preface

About build systems in generalThe Waf approach

Objectives of this book

1. Getting Started

Obtaining W af

InstallingRunning Waf

2. Introduction to t he Waf scripting system

Empty project exampleWorkflow illustration on a more complicated exampleBuilding a project - Introduction to TasksConfiguring a pro jectAdding c ustom command-line optionsInstalling targets

3. The c onfiguration system

Overview of the configuration filesThe co nfiguration environmentsConfiguration helper ex ecutionAdding new configuration helpers

4. Packaging and redistributing the source code

Quick tarb all creationCustom archivesCleaning the project t ree

5. The Task system

Task creation and executionTask execution

Task execution in parallelTask execution orderExec uting tasks only when som ething changes

6. Task encapsulation using task generators

Ex plicit rules for simple transfo rmations (Make-like)Implicit processing based on file name or extension

Custom p rocessing by task generator methodsTask generator method execution

7. The scheduler for ex ecuting the tasks

The task execution modelJob controlWeak task order con straints

8. C and C++ projects

Com mon sc ript for C /C++ applicationsLibrary interaction (uselib)

Customizing object filesUsing configuration headersThe include system

Configuration helpersPkg-config

9. Advanced scenarios

Simple file tr ansformat ionsSame targets, different configurations (variants)Building th e co mpiler firstWriting the output of a program into a header

A compiler producing source files with names unknown in advanceA task without any file dependency

10. C ustomizing th e scripting sy stem

Providing custom commandsChaining com mands

Providing a custom command contextCreating aliases / Injecting new commands

10/10/2010 he Waf Book (v1.5.4)

freehackers.org/~tnagy//single.html 1/43

8/8/2019 2009 - The Waf Book (v1.5.4)

2/43

11. Using the dev elopment version

Tracing the executionBenchmarking

ProfilingTracing parallel task executionObtaining the latest source c ode

Programming co nstraints

12. Ov erview of the Waf architecture

The core library

Build contex t instances

Overv iew of the Waf execu tionPerformance and b uild accuracy

13. C onclusionGlossary

List of T ables

11.1. Debugging zones12.1. The core library

12.2. Build contex t p ersistence12.3. Build context access13.1. Recomm ended links

Preface

Table of Contents

About build systems in generalThe Waf approachObjectives of this book

About build systems in general

As software is becoming increasingly complex, the process of creating software is becomingmore c omplex t oo. To day's so ftware uses v arious languages, requires various com pilers, andthe input data is spread into many files.

Software is now used to express the process of building software, it can take the form ofsimple scripts (shell scripts, makefiles), of co mpilers (CMake, Qmake), or c omp lete

applications (SCons, Waf). The term "build system" is used to design the tools used to buildapplications.

The Waf approach

Build systems make assumptions on software it is trying to build, and are typically limited

where it comes to processing other languages or different projects. For example, Ant isbetter suited than Make for managing Java projects, but is more limited than Make formanaging simple c projects.

There are so many different languages that creating a build system to support all thepossible kind of projects out-of-the-box is likely to be difficult. It looks much more

interesting to create one which can be extended easily.

The Waf approach is to provide a minimalistic and very flexible framework, which is packagedit with a significant amount of default build rules to be usable for most projects, and manyrecipes for the most complicated scenarios.

Objectives of this book

The objectives of this book is to exp ose the use of the W af build system though the use ofWaf in practice, the description o f the W af extension system, and detailed review of the W afinternals. Those who are impatient to see Waf in action should open the folder demos/ inthe Waf distribution, and start looking at the examples.

The first chapters contain a detailed description of the basic use of Waf. The chapters on

Configuration, Tasks, and Task generators describe the internals. These chapters should beread carefully before trying to ex tend W af. The next chapters co ntain examples for thelanguages such as C++, and for special scenarios which may occur in the most complicatedbuilds. The last c hapters are provided as a reference for those who may need to modify W afitself.

Chapter 1. Getting Started

Table of Contents

Obtaining W afInstalling

Running Waf

Obtaining Waf

The Waf project is located on Google Code The current W af version requires Py thon 2.3compiled with support for the bzip2 compression algorithm. Installing Waf is optional, if youwant to install Waf on the system, jump t o the nex t section.

Using the Waf binary

10/10/2010 he Waf Book (v1.5.4)

freehackers.org/~tnagy//single.html 2/43

8/8/2019 2009 - The Waf Book (v1.5.4)

3/43

The Waf binary is ready to use and can be ex ecuted directly. Just rename it into "waf":

Generating Waf from source

The Waf binary is usually generated from the source distribution:

Installing

Waf installation is optional and there are many advantages of not installing Waf, amongthem:

1. Installation: installation is cumberso me, and req uires administrative privileges

2. W af versions: users rarely install the approp riate software version (too old, too new)3. Bugs: newer Waf versions may result in broken builds4. Size: W af is ext remely small (about 70 kB)

5. Operating systems: W af cannot be installed on W indows (yet)

If, despite the advantages enumerated previously, you really want to install the Wafapplication on the system, y ou m ay use th e following command on Unix-like systems such asLinux:

Root privileges may be required depending on the final location.

Waf can be uninstalled using:

Running Waf

The W af script can be used directly:

Or, if the executable permissions are not set properly:

By default, the Waf script uncompresses its library in the current directory, in a hiddenfolder. This means the W af script must reside in a writable folder. The n aming is allow

different Waf v ersions to run from the same folder:

Chapter 2. Introduction to the Waf scripting system

Table of Contents

Empty project exampleWorkflow illustration on a more complicated example

Building a project - Introduction t o TasksConfiguring a p rojectAdding custom comm and-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 projectSource directory: directory containing the source files for an application, it is meant to

be ultimately packaged, and redistributed to other dev elopers or to end users.

10/10/2010 he Waf Book (v1.5.4)

freehackers.org/~tnagy//single.html 3/43

8/8/2019 2009 - The Waf Book (v1.5.4)

4/43

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 intothe build directory. The build directory can be located on t he system, out of the source

directory (like in /tmp for example).

W hen W af is launc hed, it looks for the u ser-defined Waf scr ipts which are files written in thePython language. The most important one is the top-level Waf script file in which severalfunctions and attributes must be prov ided for defining a valid W af project:

srcdir: string representing the source d irectoryblddir: string representing the build directoryset_options: function used for adding custo m c ommand-line optionsconfigure: function called for configuring the projectbuild: 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 followingPython code:

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

Configuring th e project: searching for system parameters and com pilersBuilding the project: building the software

To do this, the following sh ell com mand s will be:

Workflow illustration on a more complicated example

Additional funct ions are usually prov ided in th e top -level wscript file:

APPNAME: project name

VERSION: project versioninit: function called before anything is executedshutdown: function called after a successful build

dist: function called for packaging the application

We will now provide a more complicated wscript file, execute the typical commands, and

look at the output:

The output will be:

10/10/2010 he Waf Book (v1.5.4)

freehackers.org/~tnagy//single.html 4/43

8/8/2019 2009 - The Waf Book (v1.5.4)

5/43

3 4

A few files will be pro duc ed by W af, let us look at t hem no w:

A build directory was created with th