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]

Bases: waflib.Context.Context

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


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

Parameters: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()

Parameters:node (waflib.Node.Node) – script

Execute configuration tests provided as list of functions to run

Parameters:rules (list of string) – list of configuration method names
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)
Parameters: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.

Parameters: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 reference to that build context is kept on self.test_bld for debugging purposes, and you should not rely on it too much (read the note on the cache below). The parameters given in the arguments to this function are passed as arguments for a single task generator created in the build. Only three parameters are obligatory:

  • 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) – code to write in the filename to compile

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

This function also provides a limited cache. To use it, provide the following option:

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