Classes and functions enabling the command system

waflib.Context.HEXVERSION = 33559808

Constant updated on new releases

waflib.Context.WAFVERSION = '2.0.21'

Constant updated on new releases

waflib.Context.WAFREVISION = 'edde20a6425a5c3eb6b47d5f3f5c4fbc93fed5f4'

Git revision when the waf version is updated

waflib.Context.WAFNAME = 'waf'

Application name displayed on –help

waflib.Context.ABI = 20

Version of the build data cache file format (used in waflib.Context.DBFILE)

waflib.Context.DBFILE = '.wafpickle-linux-50857456-20'

Name of the pickle file for storing the build data

waflib.Context.APPNAME = 'APPNAME'

Default application name (used by waf dist)

waflib.Context.VERSION = 'VERSION'

Default application version (used by waf dist)

waflib.Context.TOP = 'top'

The variable name for the top-level directory in wscript files

waflib.Context.OUT = 'out'

The variable name for the output directory in wscript files

waflib.Context.WSCRIPT_FILE = 'wscript'

Name of the waf script files

waflib.Context.launch_dir = ''

Directory from which waf has been called

waflib.Context.run_dir = ''

Location of the wscript file to use as the entry point

waflib.Context.top_dir = ''

Location of the project directory (top), if the project was configured

waflib.Context.out_dir = ''

Location of the build directory (out), if the project was configured

waflib.Context.waf_dir = ''

Directory containing the waf modules

waflib.Context.default_encoding = 'utf-8'

Encoding to use when reading outputs from other processes

waflib.Context.g_module = None

Module representing the top-level wscript file (see waflib.Context.run_dir)

waflib.Context.classes = [<class 'waflib.Configure.ConfigurationContext'>, <class 'waflib.Build.EnvContext'>, <class 'waflib.Build.StepContext'>, <class 'waflib.Build.ListContext'>, <class 'waflib.Build.CleanContext'>, <class 'waflib.Build.UninstallContext'>, <class 'waflib.Build.InstallContext'>, <class 'waflib.Build.BuildContext'>, <class 'waflib.Options.OptionsContext'>]

List of waflib.Context.Context subclasses that can be used as waf commands. The classes are added automatically by a metaclass.

waflib.Context.create_context(cmd_name, *k, **kw)[source]

Returns a new waflib.Context.Context instance corresponding to the given command. Used in particular by waflib.Scripting.run_command()

  • cmd_name (string) – command name
  • k (dict) – arguments to give to the context class initializer
  • k – keyword arguments to give to the context class initializer

Context object

Return type:


class waflib.Context.store_context(name, bases, dct)[source]

Bases: type

Metaclass that registers command classes into the list waflib.Context.classes Context classes must provide an attribute ‘cmd’ representing the command name, and a function attribute ‘fun’ representing the function name that the command uses.

class waflib.Context.ctx

Bases: object

Base class for all waflib.Context.Context classes

class waflib.Context.Context(**kw)[source]

Bases: waflib.Context.ctx

Default context for waf commands, and base class for new command contexts.

Context objects are passed to top-level functions:

def foo(ctx):
        print(ctx.__class__.__name__) # waflib.Context.Context

Subclasses must define the class attributes ‘cmd’ and ‘fun’:

  • cmd (string) – command to execute as in waf cmd
  • fun (string) – function name to execute when the command is called

Inheritance diagram of waflib.Context.Context, waflib.Build.BuildContext, waflib.Build.InstallContext, waflib.Build.UninstallContext, waflib.Build.StepContext, waflib.Build.ListContext, waflib.Configure.ConfigurationContext, waflib.Scripting.Dist, waflib.Scripting.DistCheck, waflib.Build.CleanContext

errors = <module 'waflib.Errors' from '/home/jenkins/builds/workspace/waf-apidocs/waflib/'>

Shortcut to waflib.Errors provided for convenience

tools = {}

A module cache for wscript files; see Context.Context.load()


Called to free resources such as logger files

load(tool_list, *k, **kw)[source]

Loads a Waf tool as a module, and try calling the function named from it. A tooldir argument may be provided as a list of module paths.

Parameters:tool_list (list of string or space-separated string) – list of Waf tool names to load

Here, it calls the function name in the top-level wscript file. Most subclasses redefine this method to provide additional functionality.


Method executed immediately before a folder is read by waflib.Context.Context.recurse(). The current script is bound as a Node object on self.cur_script, and the current path is bound to self.path

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

Restores self.cur_script and self.path right after waflib.Context.Context.recurse() terminates.

Parameters:node (waflib.Node.Node) – script
recurse(dirs, name=None, mandatory=True, once=True, encoding=None)[source]

Runs user-provided functions from the supplied list of directories. The directories can be either absolute, or relative to the directory of the wscript file

The methods waflib.Context.Context.pre_recurse() and waflib.Context.Context.post_recurse() are called immediately before and after a script has been executed.

  • dirs (list of string or space-separated string) – List of directories to visit
  • name (string) – Name of function to invoke from the wscript
  • mandatory (bool) – whether sub wscript files are required to exist
  • once (bool) – read the script file once for a particular context
exec_command(cmd, **kw)[source]

Runs an external process and returns the exit status:

def run(tsk):
        ret = tsk.generator.bld.exec_command('touch foo.txt')
        return ret

If the context has the attribute ‘log’, then captures and logs the process stderr/stdout. Unlike waflib.Context.Context.cmd_and_log(), this method does not return the stdout/stderr values captured.

  • cmd (string or list) – command argument for subprocess.Popen
  • kw (dict) – keyword arguments for subprocess.Popen. The parameters input/timeout will be passed to wait/communicate.

process exit status

Return type:



waflib.Errors.WafError if an invalid executable is specified for a non-shell process


waflib.Errors.WafError in case of execution failure

cmd_and_log(cmd, **kw)[source]

Executes a process and returns stdout/stderr if the execution is successful. An exception is thrown when the exit status is non-0. In that case, both stderr and stdout will be bound to the WafError object (configuration tests):

def configure(conf):
        out = conf.cmd_and_log(['echo', 'hello'], output=waflib.Context.STDOUT, quiet=waflib.Context.BOTH)
        (out, err) = conf.cmd_and_log(['echo', 'hello'], output=waflib.Context.BOTH)
        (out, err) = conf.cmd_and_log(cmd, input='\n'.encode(), output=waflib.Context.STDOUT)
                conf.cmd_and_log(['which', 'someapp'], output=waflib.Context.BOTH)
        except Errors.WafError as e:
                print(e.stdout, e.stderr)
  • cmd (list or string) – args for subprocess.Popen
  • kw (dict) – keyword arguments for subprocess.Popen. The parameters input/timeout will be passed to wait/communicate.

a tuple containing the contents of stdout and stderr

Return type:



waflib.Errors.WafError if an invalid executable is specified for a non-shell process


waflib.Errors.WafError in case of execution failure; stdout/stderr/returncode are bound to the exception object

fatal(msg, ex=None)[source]

Prints an error message in red and stops command execution; this is usually used in the configuration section:

def configure(conf):
        conf.fatal('a requirement is missing')
  • msg (string) – message to display
  • ex (exception) – optional exception object



Logs information to the logger (if present), or to stderr. Empty messages are not printed:

def build(bld):
        bld.to_log('starting the build')

Provide a logger on the context class or override this method if necessary.

Parameters:msg (string) – message
msg(*k, **kw)[source]

Prints a configuration message of the form msg: result. The second part of the message will be in colors. The output can be disabled easily by setting in_msg to a positive value:

def configure(conf):
        self.in_msg = 1
        conf.msg('Checking for library foo', 'ok')
        # no output
  • msg (string) – message to display to the user
  • result (string or boolean) – result to display
  • color (string) – color to use, see waflib.Logs.colors_lst
start_msg(*k, **kw)[source]

Prints the beginning of a ‘Checking for xxx’ message. See waflib.Context.Context.msg()

end_msg(*k, **kw)[source]

Prints the end of a ‘Checking for’ message. See waflib.Context.Context.msg()

load_special_tools(var, ban=[])[source]

Loads third-party extensions modules for certain programming languages by trying to list certain files in the extras/ directory. This method is typically called once for a programming language group, see for example waflib.Tools.compiler_c

  • var (string) – glob expression, for example ‘cxx_*.py’
  • ban (list of string) – list of exact file names to exclude
waflib.Context.cache_modules = {}

Dictionary holding already loaded modules (wscript), indexed by their absolute path. The modules are added automatically by waflib.Context.load_module()

waflib.Context.load_module(path, encoding=None)[source]

Loads a wscript file as a python module. This method caches results in waflib.Context.cache_modules

Parameters:path (string) – file path
Returns:Loaded Python module
Return type:module
waflib.Context.load_tool(tool, tooldir=None, ctx=None, with_sys_path=True)[source]

Imports a Waf tool as a python module, and stores it in the dict

  • tool (string) – Name of the tool
  • tooldir (list) – List of directories to search for the tool module
  • with_sys_path (boolean) – whether or not to search the regular sys.path, besides waf_dir and potentially given tooldirs