Context¶
Classes and functions enabling the command system
- waflib.Context.HEXVERSION = 33560832¶
Constant updated on new releases
- waflib.Context.WAFVERSION = '2.0.25'¶
Constant updated on new releases
- waflib.Context.WAFREVISION = '2db0b41b2805cd5db3b55476c06b23c1e46d319f'¶
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-50988784-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 bywaflib.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
- class waflib.Context.store_context(name, bases, dct)[source]¶
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.- __annotations__ = {}¶
- class waflib.Context.ctx¶
Base class for all
waflib.Context.Context
classes- __annotations__ = {}¶
- class waflib.Context.Context(**kw)[source]¶
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 = <module 'waflib.Errors' from '/home/jenkins/builds/workspace/waf-apidocs/waflib/Errors.py'>¶
Shortcut to
waflib.Errors
provided for convenience
- tools = {}¶
A module cache for wscript files; see
Context.Context.load()
- __annotations__ = {}¶
- 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. Atooldir
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 onself.cur_script
, and the current path is bound toself.path
- Parameters
node (
waflib.Node.Node
) – script
- post_recurse(node)[source]¶
Restores
self.cur_script
andself.path
right afterwaflib.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()
andwaflib.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
- 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 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 settingin_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]¶
Imports 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