Links

• Manual
• Core Modules
• api
  • find_file / find_program
  • ant_glob
• Waf Book
  • pdf
• Directory-based Tasks
• AddingNewToolsToWaf
• Examples
  • waflib/extras/scala.py
  • rules function
  • wafsamba.py tool
  • Build a python extension module easily
  • See Tools/flex.py for chaining example.
  • Config - append_unique
  • pre/post build actions

Notes

• ctx.env := ConfigSet.ConfigSet()
• Non-existing values return an empty list.
• Waf commands are functions that take a single parameter (the waf context) and do not have to return any particular value.
• The context parameter is a new object for each command executed. The classes are also different: ConfigureContext for configure, BuildContext for build, OptionContext for option, and Context for any other command.
  • The attribute cmd holds the name of the command being executed.
  • The method recurse, and the attribute path are available on all waf context classes
  • The variable ctx.env is called a Configuration set, and is an instance of the class ConfigSet. The class is a wrapper around Python dicts to handle serialization. So it should be used for simple variables only (no functions or classes).
  • Though reading and writing values to ctx.env is possible in both configuration and build commands, the values are stored to a file only during the configuration phase.
  • You can use either key based access (dict like) or attribute based access (object like) to read/write ctx.env items.
  • There are also the convenience functions append_unique, append_value and prepend_value (but no prepend_unique) that work if the value is a list. (And if the key is undefined, it is assumed to be a list.)
• When you use the waflib.Configure.conf decorator, those methods are all called with different context objects!
  • So it's not the same as chaining to such functions by calling them directly and passing the context object that was received.
• Global variables in wscript file
  • top = '.'
    • string: the project directory.
    • In general, top is set to .
    • top may also be set to a relative path such as ../.. or an absolute path such as /checkout/perforce/project
  • out = 'build_directory'
    • string: the build directory.
    • Default is build
    • It may also be set to an a different path such as /tmp/build.
    • It is important to be able to remove the build directory safely, so it should never be given as . or ...
  • APPNAME = 'app'
    • string: Default value is noname.
    • The dist command uses this for the archive file it creates.
  • VERSION = '2.0'
    • string: Default value is 1.0
    • The dist command uses this for the archive file it creates.
• Calling waf from a subfolder will execute the commands from the same wscript file used for the configuration
  • So if you can waf configure from some top level directory and later cd into a subdirectory and run a waf command there, it will run the original wscript from that same top level folder.
• Accessing a command-line option is possible from any command.
  • e.g. To access the value of the prefix option, use ctx.options.prefix
• Commands
  • configure
  • distclean
    • Removes the build directory and the lock file created during the configuration.

dist command

• Creates an archive of the project.
• See 2.2.3: Packaging the project sources (the dist command)

Overriding the default dist command

def dist(ctx):
    # The archive name may be given directly instead of computing from APPNAME and VERSION
    ctx.base_name = 'foo_2.0'

    # The default compression format is tar.bz2. Other valid formats are zip and tar.gz
    ctx.algo      = 'zip'

    # Exclude patterns passed to give to ctx.path.ant_glob() which is used to find the files
    ctx.excl      = ' **/.waf-1* **/*~ **/*.pyc **/*.swp **/.lock-w*'

    # The files to add to the archive may be given as Waf node objects (excl is therefore ignored)
    ctx.files     = ctx.path.ant_glob('**/wscript')