Configuration system

A waflib.Configure.ConfigurationContext instance is created when waf configure is called, it is used to:

  • create data dictionaries (ConfigSet instances)

  • store the list of modules to import

  • hold configuration routines such as find_program, etc

waflib.Configure.WAF_CONFIG_LOG = 'config.log'

Name of the configuration log file

waflib.Configure.autoconfig = False

Execute the configuration automatically

class waflib.Configure.ConfigurationContext(**kw)[source]

Configure the project.

Waf tools may bind new methods to this class:

from waflib.Configure import conf
def myhelper(self):

def configure(ctx):
cmd = 'configure'
error_handlers = []

Additional functions to handle configuration errors

setenv(name, env=None)[source]

Set a new config set for conf.env. If a config set of that name already exists, recall it without modification.

The name is the filename prefix to save to c4che/, and it is also used as variants by the build commands. Though related to variants, whatever kind of data may be stored in the config set:

def configure(cfg):
        cfg.env.ONE = 1
        cfg.env.ONE = 2

def build(bld):
        2 == bld.env_of_name('foo').ONE
  • name (string) – name of the configuration set

  • env (waflib.ConfigSet.ConfigSet) – ConfigSet to copy, or an empty ConfigSet is created


Getter for the env property


Setter for the env property

property env

Getter for the env property


Initialize the project directory and the build directory


See waflib.Context.Context.execute()


Insert PREFIX, BINDIR and LIBDIR values into env


env (waflib.ConfigSet.ConfigSet) – a ConfigSet, usually conf.env


Save the config results into the cache file

load(tool_list, tooldir=None, funs=None, with_sys_path=True, cache=False)[source]

Load Waf tools, which will be imported whenever a build is started.

  • tool_list (list of string) – waf tools to import

  • tooldir (list of string) – paths for the imports

  • funs (list of string) – functions to execute from the waf tools

  • cache (bool) – whether to prevent the tool from running twice


Records the path and a hash of the scripts visited, see waflib.Context.Context.post_recurse()


node (waflib.Node.Node) – script


Execute configuration tests provided as list of functions to run


rules (list of string) – list of configuration method names

__annotations__ = {}
fun = 'configure'

Decorator: attach new configuration functions to waflib.Build.BuildContext and waflib.Configure.ConfigurationContext. The methods bound will accept a parameter named ‘mandatory’ to disable the configuration errors:

def configure(conf):
        conf.find_program('abc', mandatory=False)

f (function) – method to bind

waflib.Configure.add_os_flags(self, var, dest=None, dup=False)[source]

Import operating system environment values into conf.env dict:

def configure(conf):
  • var (string) – variable to use

  • dest (string) – destination variable, by default the same as var

  • dup (bool) – add the same set of flags again

waflib.Configure.cmd_to_list(self, cmd)[source]

Detect if a command is written in pseudo shell like ccache g++ and return a list.


cmd (a string or a list of string) – command

waflib.Configure.check_waf_version(self, mini='1.9.99', maxi='2.1.0', **kw)[source]

Raise a Configuration error if the Waf version does not strictly match the given bounds:

conf.check_waf_version(mini='1.9.99', maxi='2.1.0')
  • mini (number, tuple or string) – Minimum required version

  • maxi (number, tuple or string) – Maximum allowed version

waflib.Configure.find_file(self, filename, path_list=[])[source]

Find a file in a list of paths

  • filename – name of the file to search for

  • path_list – list of directories to search


the first matching filename; else a configuration exception is raised

waflib.Configure.find_program(self, filename, **kw)[source]

Search for a program on the operating system

When var is used, you may set os.environ[var] to help find a specific program version, for example:

$ CC='ccache gcc' waf configure
  • path_list – paths to use for searching

  • var (string) – store the result to conf.env[var] where var defaults to filename.upper() if not provided; the result is stored as a list of strings

  • value (list or string (list is preferred)) – obtain the program from the value passed exclusively

  • exts (list of string) – list of extensions for the binary (do not add an extension for portability)

  • msg (string) – name to display in the log, by default filename is used

  • interpreter (ConfigSet variable key) – interpreter for the program



waflib.Configure.run_build(self, *k, **kw)[source]

Create a temporary build context to execute a build. A temporary reference to that build context is kept on self.test_bld for debugging purposes. The arguments to this function are passed to a single task generator for that build. Only three parameters are mandatory:

  • features (list of string) – features to pass to a task generator created in the build

  • compile_filename (string) – file to create for the compilation (default: test.c)

  • code (string) – input file contents

Though this function returns 0 by default, the build may bind attribute named retval on the build context object to return a particular value. See waflib.Tools.c_config.test_exec_fun() for example.

The temporary builds creates a temporary folder; the name of that folder is calculated by hashing input arguments to this function, with the exception of waflib.ConfigSet.ConfigSet objects which are used for both reading and writing values.

This function also features a cache which is disabled by default; that cache relies on the hash value calculated as indicated above:

def options(opt):
        opt.add_option('--confcache', dest='confcache', default=0,
                action='count', help='Use a configuration cache')

And execute the configuration with the following command-line:

$ waf configure --confcache