Task¶
Tasks represent atomic operations such as processes.
-
waflib.Task.
NOT_RUN
= 0¶ The task was not executed yet
-
waflib.Task.
MISSING
= 1¶ The task has been executed but the files have not been created
-
waflib.Task.
CRASHED
= 2¶ The task execution returned a non-zero exit status
-
waflib.Task.
EXCEPTION
= 3¶ An exception occured in the task execution
-
waflib.Task.
SKIPPED
= 8¶ The task did not have to be executed
-
waflib.Task.
SUCCESS
= 9¶ The task was successfully executed
-
waflib.Task.
ASK_LATER
= -1¶ The task is not ready to be executed
-
waflib.Task.
SKIP_ME
= -2¶ The task does not need to be executed
-
waflib.Task.
RUN_ME
= -3¶ The task must be executed
-
waflib.Task.
classes
= {'bison': <class 'waflib.Tools.bison.bison'>, 'pdflatex': <class 'waflib.Tools.tex.pdflatex'>, 'glib_gresource_source': <class 'waflib.Tools.glib2.glib_gresource_source'>, 'dbus_binding_tool': <class 'waflib.Tools.dbus.dbus_binding_tool'>, 'javac': <class 'waflib.Tools.javaw.javac'>, 'cxx': <class 'waflib.Tools.cxx.cxx'>, 'glib_gresource_base': <class 'waflib.Tools.glib2.glib_gresource_base'>, 'cxxshlib': <class 'waflib.Tools.cxx.cxxshlib'>, 'ts2qm': <class 'waflib.Tools.qt5.ts2qm'>, 'glib_validate_schema': <class 'waflib.Tools.glib2.glib_validate_schema'>, 'fcstlib': <class 'waflib.Tools.fc.fcstlib'>, 'd_with_header': <class 'waflib.Tools.d.d_with_header'>, 'fake_csshlib': <class 'waflib.Tools.cs.fake_csshlib'>, 'xelatex': <class 'waflib.Tools.tex.xelatex'>, 'javadoc': <class 'waflib.Tools.javaw.javadoc'>, 'glib_mkenums': <class 'waflib.Tools.glib2.glib_mkenums'>, 'JTask': <class 'waflib.Tools.javaw.JTask'>, 'fake_o': <class 'waflib.Tools.ccroot.fake_o'>, 'd_header': <class 'waflib.Tools.d.d_header'>, 'fcshlib': <class 'waflib.Tools.fc.fcshlib'>, 'macplist': <class 'waflib.Tools.c_osx.macplist'>, 'grep_for_endianness': <class 'waflib.Tools.c_tests.grep_for_endianness'>, 'dvipdf': <class 'waflib.Tools.tex.dvipdf'>, 'winrc': <class 'waflib.Tools.winres.winrc'>, 'intltool': <class 'waflib.Tools.intltool.intltool'>, 'asmstlib': <class 'waflib.Tools.asm.asmstlib'>, 'trans_update': <class 'waflib.Tools.qt5.trans_update'>, 'luac': <class 'waflib.Tools.lua.luac'>, 'c': <class 'waflib.Tools.c.c'>, 'glib_genmarshal': <class 'waflib.Tools.glib2.glib_genmarshal'>, 'utest': <class 'waflib.Tools.waf_unit_test.utest'>, 'fcprogram': <class 'waflib.Tools.fc.fcprogram'>, 'subst': <class 'waflib.TaskGen.subst'>, 'asmshlib': <class 'waflib.Tools.asm.asmshlib'>, 'cxxprogram': <class 'waflib.Tools.cxx.cxxprogram'>, 'stlink_task': <class 'waflib.Tools.ccroot.stlink_task'>, 'dvips': <class 'waflib.Tools.tex.dvips'>, 'glib_gresource_bundle': <class 'waflib.Tools.glib2.glib_gresource_bundle'>, 'cshlib': <class 'waflib.Tools.c.cshlib'>, 'rcc': <class 'waflib.Tools.qt5.rcc'>, 'flex': <class 'waflib.Task.flex'>, 'Task': <class 'waflib.Task.Task'>, 'latex': <class 'waflib.Tools.tex.latex'>, 'valac': <class 'waflib.Tools.vala.valac'>, 'run_ruby': <class 'waflib.Tools.ruby.run_ruby'>, 'cprogram': <class 'waflib.Tools.c.cprogram'>, 'xsubpp': <class 'waflib.Tools.perl.xsubpp'>, 'fc': <class 'waflib.Tools.fc.fc'>, 'inst': <class 'waflib.Build.inst'>, 'po': <class 'waflib.Tools.intltool.po'>, 'pyo': <class 'waflib.Tools.python.pyo'>, 'moc': <class 'waflib.Tools.qt5.moc'>, 'pdf2ps': <class 'waflib.Tools.tex.pdf2ps'>, 'vnum': <class 'waflib.Tools.ccroot.vnum'>, 'pyc': <class 'waflib.Tools.python.pyc'>, 'mcs': <class 'waflib.Tools.cs.mcs'>, 'asm': <class 'waflib.Tools.asm.asm'>, 'd': <class 'waflib.Tools.d.d'>, 'dstlib': <class 'waflib.Tools.d.dstlib'>, 'test_exec': <class 'waflib.Tools.c_config.test_exec'>, 'fake_shlib': <class 'waflib.Tools.ccroot.fake_shlib'>, 'macapp': <class 'waflib.Tools.c_osx.macapp'>, 'link_task': <class 'waflib.Tools.ccroot.link_task'>, 'cfgtask': <class 'waflib.Tools.c_config.cfgtask'>, 'asmprogram': <class 'waflib.Tools.asm.asmprogram'>, 'tex': <class 'waflib.Tools.tex.tex'>, 'jar_create': <class 'waflib.Tools.javaw.jar_create'>, 'cxxstlib': <class 'waflib.Tools.cxx.cxxstlib'>, 'dprogram': <class 'waflib.Tools.d.dprogram'>, 'subst_pc': <class 'waflib.TaskGen.subst_pc'>, 'qm2rcc': <class 'waflib.Tools.qt5.qm2rcc'>, 'dshlib': <class 'waflib.Tools.d.dshlib'>, 'cstlib': <class 'waflib.Tools.c.cstlib'>, 'ui5': <class 'waflib.Tools.qt5.ui5'>, 'qxx': <class 'waflib.Tools.qt5.qxx'>, 'fcprogram_test': <class 'waflib.Tools.fc.fcprogram_test'>, 'fake_stlib': <class 'waflib.Tools.ccroot.fake_stlib'>}¶ The metaclass
waflib.Task.store_task_type
stores all class tasks created by user scripts or Waf tools to this dict. It maps class names to class objects.
-
class
waflib.Task.
store_task_type
(name, bases, dict)[source]¶ Bases:
type
Metaclass: store the task classes into the dict pointed by the class attribute ‘register’ which defaults to
waflib.Task.classes
,The attribute ‘run_str’ is compiled into a method ‘run’ bound to the task class.
-
class
waflib.Task.
evil
¶ Bases:
object
Base class provided to avoid writing a metaclass, so the code can run in python 2.6 and 3.x unmodified
-
class
waflib.Task.
TaskBase
(*k, **kw)[source]¶ Bases:
waflib.Task.evil
Base class for all Waf tasks, which should be seen as an interface. For illustration purposes, instances of this class will execute the attribute ‘fun’ in
waflib.Task.TaskBase.run()
. When in doubt, create subclasses ofwaflib.Task.Task
instead.Subclasses must override these methods:
- __str__: string to display to the user
- runnable_status: ask the task if it should be run, skipped, or if we have to ask later
- run: what to do to execute the task
- post_run: what to do after the task has been executed
-
color
= 'GREEN'¶ Color for the console display, see
waflib.Logs.colors_lst
-
ext_in
= []¶ File extensions that objects of this task class may use
-
ext_out
= []¶ File extensions that objects of this task class may create
-
before
= []¶ List of task class names to execute before instances of this class
-
after
= []¶ List of task class names to execute after instances of this class
-
hcode
= ''¶ String representing an additional hash for the class representation
-
keep_last_cmd
= False¶ Whether to keep the last command executed on the instance after execution. This may be useful for certain extensions but it can a lot of memory.
-
__slots__
= ('hasrun', 'generator')¶
-
get_cwd
()[source]¶ Returns: current working directory Return type: waflib.Node.Node
-
quote_flag
(x)[source]¶ Surround a process argument by quotes so that a list of arguments can be written to a file
Parameters: x (string) – flag Returns: quoted flag Return type: string
-
split_argfile
(cmd)[source]¶ Splits a list of process commands into the executable part and its list of arguments
Returns: a tuple containing the executable first and then the rest of arguments Return type: tuple
-
exec_command
(cmd, **kw)[source]¶ Wrapper for
waflib.Context.Context.exec_command()
. This version set the current working directory (build.variant_dir
), applies PATH settings (if self.env.PATH is provided), and can run long commands through a temporary@argfile
.Parameters: cmd (list of string (best) or string (process will use a shell)) – process command to execute Returns: the return code Return type: int
-
runnable_status
()[source]¶ Returns the Task status
Returns: a task state in waflib.Task.RUN_ME
,waflib.Task.SKIP_ME
orwaflib.Task.ASK_LATER
.Return type: int
-
run
()[source]¶ Called by threads to execute the tasks. The default is empty and meant to be overridden in subclasses.
Warning
It is a bad idea to create nodes in this method, so avoid
waflib.Node.Node.ant_glob()
Return type: int
-
display
()[source]¶ Returns an execution status for the console, the progress bar, or the IDE output.
Return type: string
-
hash_constraints
()[source]¶ Identifies a task type for all the constraints relevant for the scheduler: precedence, file production
Returns: a hash value Return type: string
-
format_error
()[source]¶ Returns an error message to display the build failure reasons
Return type: string
-
colon
(var1, var2)[source]¶ Enable scriptlet expressions of the form ${FOO_ST:FOO} If the first variable (FOO_ST) is empty, then an empty list is returned
The results will be slightly different if FOO_ST is a list, for example:
env.FOO_ST = ['-a', '-b'] env.FOO_ST = '-I%s' # ${FOO_ST:FOO} returns ['-Ip1', '-Ip2'] env.FOO = ['p1', 'p2'] # ${FOO_ST:FOO} returns ['-a', '-b', 'p1', '-a', '-b', 'p2']
-
class
waflib.Task.
Task
(*k, **kw)[source]¶ Bases:
waflib.Task.TaskBase
This class deals with the filesystem (
waflib.Node.Node
). The methodwaflib.Task.Task.runnable_status
uses a hash value (fromwaflib.Task.Task.signature
) which is persistent from build to build. When the value changes, the task has to be executed. The methodwaflib.Task.Task.post_run
will assign the task signature to the output nodes (if present).-
vars
= []¶ ConfigSet variables that should trigger a rebuild (class attribute used for
waflib.Task.Task.sig_vars()
)
-
always_run
= False¶ Specify whether task instances must always be executed or not (class attribute)
-
shell
= False¶ Execute the command with the shell (class attribute)
-
env
= None¶ waflib.ConfigSet.ConfigSet
object (make sure to provide one)
-
inputs
= None¶ List of input nodes, which represent the files used by the task instance
-
outputs
= None¶ List of output nodes, which represent the files created by the task instance
-
dep_nodes
= None¶ List of additional nodes to depend on
-
run_after
= None¶ Set of tasks that must be executed before this one
-
uid
()[source]¶ Returns an identifier used to determine if tasks are up-to-date. Since the identifier will be stored between executions, it must be:
- unique for a task: no two tasks return the same value (for a given build context)
- the same for a given task instance
By default, the node paths, the class name, and the function are used as inputs to compute a hash.
The pointer to the object (python built-in ‘id’) will change between build executions, and must be avoided in such hashes.
Returns: hash value Return type: string
-
hcode
= '\tdef run(self):\n\t\t"""\n\t\tCalled by threads to execute the tasks. The default is empty and meant to be overridden in subclasses.\n\n\t\t.. warning:: It is a bad idea to create nodes in this method, so avoid :py:meth:`waflib.Node.Node.ant_glob`\n\n\t\t:rtype: int\n\t\t"""\n\t\tif hasattr(self, \'fun\'):\n\t\t\treturn self.fun(self)\n\t\treturn 0\n'¶
-
set_inputs
(inp)[source]¶ Appends the nodes to the inputs list
Parameters: inp (node or list of nodes) – input nodes
-
set_outputs
(out)[source]¶ Appends the nodes to the outputs list
Parameters: out (node or list of nodes) – output nodes
-
set_run_after
(task)[source]¶ Run this task only after the given task.
Parameters: task ( waflib.Task.Task
) – task
-
signature
()[source]¶ Task signatures are stored between build executions, they are use to track the changes made to the input nodes (not to the outputs!). The signature hashes data from various sources:
- explicit dependencies: files listed in the inputs (list of node objects)
waflib.Task.Task.sig_explicit_deps()
- implicit dependencies: list of nodes returned by scanner methods (when present)
waflib.Task.Task.sig_implicit_deps()
- hashed data: variables/values read from task.__class__.vars/task.env
waflib.Task.Task.sig_vars()
If the signature is expected to give a different result, clear the cache kept in
self.cache_sig
:from waflib import Task class cls(Task.Task): def signature(self): sig = super(Task.Task, self).signature() delattr(self, 'cache_sig') return super(Task.Task, self).signature()
Returns: the signature value Return type: string or bytes - explicit dependencies: files listed in the inputs (list of node objects)
-
sig_explicit_deps
()[source]¶ Used by
waflib.Task.Task.signature()
; it hasheswaflib.Task.Task.inputs
andwaflib.Task.Task.dep_nodes
signatures.
-
sig_vars
()[source]¶ Used by
waflib.Task.Task.signature()
; it hasheswaflib.Task.Task.env
variables/values
-
scan
= None¶ This method, when provided, returns a tuple containing:
- a list of nodes corresponding to real files
- a list of names for files not found in path_lst
For example:
from waflib.Task import Task class mytask(Task): def scan(self, node): return ([], [])
The first and second lists in the tuple are stored in
waflib.Build.BuildContext.node_deps
andwaflib.Build.BuildContext.raw_deps
respectively.
-
sig_implicit_deps
()[source]¶ Used by
waflib.Task.Task.signature()
; it hashes node signatures obtained by scanning for dependencies (waflib.Task.Task.scan()
).The exception
waflib.Errors.TaskRescan
is thrown when a file has changed. In this case, the methodwaflib.Task.Task.signature()
is called once again, and return here to callwaflib.Task.Task.scan()
and searching for dependencies.
-
compute_sig_implicit_deps
()[source]¶ Used by
waflib.Task.Task.sig_implicit_deps()
for computing the actual hash of thewaflib.Node.Node
returned by the scanner.Returns: a hash value for the implicit dependencies Return type: string or bytes
-
-
waflib.Task.
is_before
(t1, t2)[source]¶ Returns a non-zero value if task t1 is to be executed before task t2:
t1.ext_out = '.h' t2.ext_in = '.h' t2.after = ['t1'] t1.before = ['t2'] waflib.Task.is_before(t1, t2) # True
Parameters: - t1 (
waflib.Task.TaskBase
) – Task object - t2 (
waflib.Task.TaskBase
) – Task object
- t1 (
-
waflib.Task.
set_file_constraints
(tasks)[source]¶ Updates the
run_after
attribute of all tasks based on the task inputs and outputsParameters: tasks (list of waflib.Task.TaskBase
) – tasks
-
waflib.Task.
set_precedence_constraints
(tasks)[source]¶ Updates the
run_after
attribute of all tasks based on the after/before/ext_out/ext_in attributesParameters: tasks (list of waflib.Task.TaskBase
) – tasks
-
waflib.Task.
funex
(c)[source]¶ Compiles a scriptlet expression into a Python function
Parameters: c (string) – function to compile Returns: the function ‘f’ declared in the input string Return type: function
-
waflib.Task.
compile_fun_shell
(line)[source]¶ Creates a compiled function to execute a process through a sub-shell
-
waflib.Task.
compile_fun_noshell
(line)[source]¶ Creates a compiled function to execute a process without a sub-shell
-
waflib.Task.
compile_fun
(line, shell=False)[source]¶ Parses a string expression such as ‘${CC} ${SRC} -o ${TGT}’ and returns a pair containing:
- The function created (compiled) for use as
waflib.Task.TaskBase.run()
- The list of variables that must cause rebuilds when env data is modified
for example:
from waflib.Task import compile_fun compile_fun('cxx', '${CXX} -o ${TGT[0]} ${SRC} -I ${SRC[0].parent.bldpath()}') def build(bld): bld(source='wscript', rule='echo "foo\${SRC[0].name}\bar"')
The env variables (CXX, ..) on the task must not hold dicts so as to preserve a consistent order. The reserved keywords
TGT
andSRC
represent the task input and output nodes- The function created (compiled) for use as
-
waflib.Task.
task_factory
(name, func=None, vars=None, color='GREEN', ext_in=[], ext_out=[], before=[], after=[], shell=False, scan=None)[source]¶ Returns a new task subclass with the function
run
compiled from the line given.Parameters: - func (string or function) – method run
- vars (list of string) – list of variables to hash
- color (string) – color to use
- shell (bool) – when func is a string, enable/disable the use of the shell
- scan (function) – method scan
Return type: