Context

Classes and functions enabling the command system

waflib.Context.HEXVERSION

Constant updated on new releases

waflib.Context.WAFVERSION

Constant updated on new releases

waflib.Context.WAFREVISION

Git revision when the waf version is updated

waflib.Context.ABI

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

waflib.Context.DBFILE

Name of the pickle file for storing the build data

waflib.Context.APPNAME

Default application name (used by waf dist)

waflib.Context.VERSION

Default application version (used by waf dist)

waflib.Context.TOP

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

waflib.Context.OUT

The variable name for the output directory in wscript files

waflib.Context.WSCRIPT_FILE

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.g_module

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

waflib.Context.classes

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

Parameters:
  • 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
Returns:

Context object

Return type:

waflib.Context.Context

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’:

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

errors

Shortcut to waflib.Errors provided for convenience

tools

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

finalize()[source]

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 waflib.Context.Context.fun 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
execute()[source]

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

pre_recurse(node)[source]

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
post_recurse(node)[source]

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.

Parameters:
  • 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.

Parameters:
  • 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.
Returns:

process exit status

Return type:

integer

Raises :

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

Raises :

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)
        try:
                conf.cmd_and_log(['which', 'someapp'], output=waflib.Context.BOTH)
        except Errors.WafError as e:
                print(e.stdout, e.stderr)
Parameters:
  • 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.
Returns:

a tuple containing the contents of stdout and stderr

Return type:

string

Raises :

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

Raises :

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')
Parameters:
  • msg (string) – message to display
  • ex (exception) – optional exception object
Raises :

waflib.Errors.ConfigurationError

to_log(msg)[source]

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 methid 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 easly by setting in_msg to a positive value:

def configure(conf):
        self.in_msg = 1
        conf.msg('Checking for library foo', 'ok')
        # no output
Parameters:
  • 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

Parameters:
  • 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]

Importx a Waf tool as a python module, and stores it in the dict waflib.Context.Context.tools

Parameters:
  • 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

Previous topic

Configure

Next topic

Errors

This Page