2009 - The Waf Book (v1.5.4)

of 43

  • date post

  • Category


  • view

  • download


Embed Size (px)

Transcript of 2009 - The Waf Book (v1.5.4)

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


    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


    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)


    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


    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)


    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:


    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)


    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)


    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