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 = {'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'>, 'flex': <class 'waflib.Task.flex'>, 'cxx': <class 'waflib.Tools.msvc.cxx'>, 'glib_gresource_base': <class 'waflib.Tools.glib2.glib_gresource_base'>, 'cxxshlib': <class 'waflib.Tools.msvc.cxxshlib'>, 'valac': <class 'waflib.Tools.vala.valac'>, 'javadoc': <class 'waflib.Tools.javaw.javadoc'>, 'fcstlib': <class 'waflib.Tools.ifort.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'>, 'intltool': <class 'waflib.Tools.intltool.intltool'>, 'pyo': <class 'waflib.Tools.python.pyo'>, 'stlink': <class 'waflib.Tools.ccroot.stlink_task'>, 'd_header': <class 'waflib.Tools.d.d_header'>, 'fcshlib': <class 'waflib.Tools.ifort.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'>, 'fake_o': <class 'waflib.Tools.ccroot.fake_o'>, 'glib_validate_schema': <class 'waflib.Tools.glib2.glib_validate_schema'>, 'trans_update': <class 'waflib.Tools.qt5.trans_update'>, 'asmshlib': <class 'waflib.Tools.asm.asmshlib'>, 'cstlib': <class 'waflib.Tools.msvc.cstlib'>, 'glib_genmarshal': <class 'waflib.Tools.glib2.glib_genmarshal'>, 'utest': <class 'waflib.Tools.waf_unit_test.utest'>, 'fcprogram': <class 'waflib.Tools.ifort.fcprogram'>, 'ui5': <class 'waflib.Tools.qt5.ui5'>, 'subst': <class 'waflib.TaskGen.subst'>, 'glib_mkenums': <class 'waflib.Tools.glib2.glib_mkenums'>, 'run_ruby': <class 'waflib.Tools.ruby.run_ruby'>, 'cxxprogram': <class 'waflib.Tools.msvc.cxxprogram'>, 'xsubpp': <class 'waflib.Tools.perl.xsubpp'>, 'dshlib': <class 'waflib.Tools.d.dshlib'>, 'cshlib': <class 'waflib.Tools.msvc.cshlib'>, 'rcc': <class 'waflib.Tools.qt5.rcc'>, 'glib_gresource_bundle': <class 'waflib.Tools.glib2.glib_gresource_bundle'>, 'Task': <class 'waflib.Task.Task'>, 'latex': <class 'waflib.Tools.tex.latex'>, 'ts2qm': <class 'waflib.Tools.qt5.ts2qm'>, 'msgfmt': <class 'waflib.Tools.kde4.msgfmt'>, 'c': <class 'waflib.Tools.msvc.c'>, 'cprogram': <class 'waflib.Tools.msvc.cprogram'>, 'fc': <class 'waflib.Tools.ifort.fc'>, 'inst': <class 'waflib.Build.inst'>, 'ui4': <class 'waflib.Tools.qt4.ui4'>, 'dvips': <class 'waflib.Tools.tex.dvips'>, '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'>, 'asmstlib': <class 'waflib.Tools.asm.asmstlib'>, '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'>, 'd': <class 'waflib.Tools.d.d'>, 'cfgtask': <class 'waflib.Tools.c_config.cfgtask'>, 'po': <class 'waflib.Tools.intltool.po'>, 'asmprogram': <class 'waflib.Tools.asm.asmprogram'>, 'tex': <class 'waflib.Tools.tex.tex'>, 'jar_create': <class 'waflib.Tools.javaw.jar_create'>, 'cxxstlib': <class 'waflib.Tools.msvc.cxxstlib'>, 'dprogram': <class 'waflib.Tools.d.dprogram'>, 'subst_pc': <class 'waflib.TaskGen.subst_pc'>, 'qm2rcc': <class 'waflib.Tools.qt5.qm2rcc'>, 'bison': <class 'waflib.Tools.bison.bison'>, 'link': <class 'waflib.Tools.ccroot.link_task'>, 'qxx': <class 'waflib.Tools.qt5.qxx'>, 'luac': <class 'waflib.Tools.lua.luac'>, 'fcprogram_test': <class 'waflib.Tools.ifort.fcprogram_test'>, 'fake_stlib': <class 'waflib.Tools.ccroot.fake_stlib'>}

Class tasks created by user scripts or Waf tools (maps names to class objects). Task classes defined in Waf tools are registered here through the metaclass waflib.Task.store_task_type.

class waflib.Task.store_task_type(name, bases, dict)

Bases: type

Metaclass: store the task classes into waflib.Task.classes, or to the dict pointed by the class attribute ‘register’. The attribute ‘run_str’ will be processed to compute a method ‘run’ on the task class The decorator waflib.Task.cache_outputs() is also applied to the class

__doc__ = "\n\tMetaclass: store the task classes into :py:const:`waflib.Task.classes`, or to the dict pointed\n\tby the class attribute 'register'.\n\tThe attribute 'run_str' will be processed to compute a method 'run' on the task class\n\tThe decorator :py:func:`waflib.Task.cache_outputs` is also applied to the class\n\t"

__module__ = 'waflib.Task'

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

__module__ = 'waflib.Task'

class waflib.Task.TaskBase(*k, **kw)

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 of waflib.Task.Task instead.

Subclasses should override these methods:

1. __str__: string to display to the user
2. runnable_status: ask the task if it should be run, skipped, or if we have to ask later
3. run: let threads execute the task
4. post_run: let threads update the data regarding the task (cache)

Warning

For backward compatibility reasons, the suffix “_task” is truncated in derived class names. This limitation will be removed in Waf 1.9.

color = 'GREEN'

Color for the console display, see waflib.Logs.colors_lst

ext_in = []

File extensions that objects of this task class might use

ext_out = []

File extensions that objects of this task class might 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

__init__(*k, **kw)

The base task class requires a task generator, which will be itself if missing

__repr__()

for debugging purposes

__str__()

string to display to the user

__hash__()

Very fast hashing scheme but not persistent (replace/implement in subclasses and see waflib.Task.Task.uid())

exec_command(cmd, **kw)

Wrapper for waflib.Context.Context.exec_command() which sets a current working directory to build.variant_dir

Returns:the return code Return type:int

runnable_status()

State of the task

Returns:a task state in waflib.Task.RUN_ME, waflib.Task.SKIP_ME or waflib.Task.ASK_LATER. Return type:int

run()

Called by threads to execute the tasks. The default is empty and meant to be overridden in subclasses. It is a bad idea to create nodes in this method (so, no node.ant_glob)

Return type:int

post_run()

Update the cache files (executed by threads). Override in subclasses.

log_display(bld)

Write the execution status on the context logger

display()

Return an execution status for the console, the progress bar, or the IDE output.

Return type:string

attr(att, default=None)

Retrieve an attribute from the instance or from the class.

Parameters:

• att (string) – variable name
• default – default value

hash_constraints()

Identify a task type for all the constraints relevant for the scheduler: precedence, file production

Returns:a hash value Return type:string

format_error()

Error message to display to the user when a build fails

Return type:string

colon(var1, var2)

Support code for scriptlet expressions such as ${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']

__doc__ = '\n\tBase class for all Waf tasks, which should be seen as an interface.\n\tFor illustration purposes, instances of this class will execute the attribute\n\t\'fun\' in :py:meth:`waflib.Task.TaskBase.run`. When in doubt, create\n\tsubclasses of :py:class:`waflib.Task.Task` instead.\n\n\tSubclasses should override these methods:\n\n\t#. __str__: string to display to the user\n\t#. runnable_status: ask the task if it should be run, skipped, or if we have to ask later\n\t#. run: let threads execute the task\n\t#. post_run: let threads update the data regarding the task (cache)\n\n\t.. warning:: For backward compatibility reasons, the suffix "_task" is truncated in derived class names. This limitation will be removed in Waf 1.9.\n\t'

__module__ = 'waflib.Task'

class waflib.Task.Task(*k, **kw)

Bases: waflib.Task.TaskBase

This class deals with the filesystem (waflib.Node.Node). The method waflib.Task.Task.runnable_status uses a hash value (from waflib.Task.Task.signature) which is persistent from build to build. When the value changes, the task has to be executed. The method waflib.Task.Task.post_run will assign the task signature to the output nodes (if present).

Warning

For backward compatibility reasons, the suffix “_task” is truncated in derived class names. This limitation will be removed in Waf 1.9.

vars = []

Variables to depend on (class attribute used for waflib.Task.Task.sig_vars())

shell = False

Execute the command with the shell (class attribute)

env = None

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

__str__()

string to display to the user

__repr__()

for debugging purposes

__doc__ = '\n\tThis class deals with the filesystem (:py:class:`waflib.Node.Node`). The method :py:class:`waflib.Task.Task.runnable_status`\n\tuses a hash value (from :py:class:`waflib.Task.Task.signature`) which is persistent from build to build. When the value changes,\n\tthe task has to be executed. The method :py:class:`waflib.Task.Task.post_run` will assign the task signature to the output\n\tnodes (if present).\n\n\t.. warning:: For backward compatibility reasons, the suffix "_task" is truncated in derived class names. This limitation will be removed in Waf 1.9.\n\t'

__module__ = 'waflib.Task'

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\t\tIt is a bad idea to create nodes in this method (so, no 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'

uid()

Return an identifier used to determine if tasks are up-to-date. Since the identifier will be stored between executions, it must be:

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

set_inputs(inp)

Append the nodes to the inputs

Parameters:inp (node or list of nodes) – input nodes

set_outputs(out)

Append the nodes to the outputs

Parameters:out (node or list of nodes) – output nodes

set_run_after(task)

Run this task only after task. Affect waflib.Task.runnable_status() You probably want to use tsk.run_after.add(task) directly

Parameters:task (waflib.Task.Task) – task

signature()

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

runnable_status()

Override waflib.Task.TaskBase.runnable_status() to determine if the task is ready to be run (waflib.Task.Task.run_after)

post_run()

Update the cache files (executed by threads). Override in subclasses.

sig_explicit_deps()

Used by waflib.Task.Task.signature(), hash waflib.Task.Task.inputs and waflib.Task.Task.dep_nodes signatures.

Return type:hash value

sig_vars()

Used by waflib.Task.Task.signature(), hash waflib.Task.Task.env variables/values

Return type:hash value

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 are stored in waflib.Build.BuildContext.node_deps and waflib.Build.BuildContext.raw_deps respectively.

sig_implicit_deps()

Used by waflib.Task.Task.signature() hashes node signatures obtained by scanning for dependencies (waflib.Task.Task.scan()).

The exception waflib.Errors.TaskRescan is thrown when a file has changed. When this occurs, waflib.Task.Task.signature() is called once again, and this method will be executed once again, this time calling waflib.Task.Task.scan() for searching the dependencies.

Return type:hash value

compute_sig_implicit_deps()

Used by waflib.Task.Task.sig_implicit_deps() for computing the actual hash of the waflib.Node.Node returned by the scanner.

Returns:hash value Return type:string

are_implicit_nodes_ready()

For each node returned by the scanner, see if there is a task behind it, and force the build order

The performance impact on null builds is nearly invisible (1.66s->1.86s), but this is due to agressive caching (1.86s->28s)

waflib.Task.is_before(t1, t2)

Return 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
• t2 (waflib.Task.TaskBase) – task

waflib.Task.set_file_constraints(tasks)

Adds tasks to the task ‘run_after’ attribute based on the task inputs and outputs

Parameters:tasks (list of waflib.Task.TaskBase) – tasks

waflib.Task.set_precedence_constraints(tasks)

Add tasks to the task ‘run_after’ attribute based on the after/before/ext_out/ext_in attributes

Parameters:tasks (list of waflib.Task.TaskBase) – tasks

waflib.Task.funex(c)

Compile a function by ‘exec’

Parameters:c (string) – function to compile Returns:the function ‘f’ declared in the input string Return type:function

waflib.Task.compile_fun_shell(line)

Create a compiled function to execute a process with the shell WARNING: this method may disappear anytime, so use compile_fun instead

waflib.Task.compile_fun_noshell(line)

Create a compiled function to execute a process without the shell WARNING: this method may disappear anytime, so use compile_fun instead

waflib.Task.compile_fun(line, shell=False)

Parse a string expression such as “${CC} ${SRC} -o ${TGT}” and return a pair containing:

• the function created (compiled) for use as waflib.Task.TaskBase.run()
• the list of variables that imply a dependency from self.env

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 (order) The reserved keywords TGT and SRC represent the task input and output nodes

waflib.Task.task_factory(name, func=None, vars=None, color='GREEN', ext_in=[], ext_out=[], before=[], after=[], shell=False, scan=None)

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:

waflib.Task.Task

waflib.Task.always_run(cls)

Task class decorator

Set all task instances of this class to be executed whenever a build is started The task signature is calculated, but the result of the comparation between task signatures is bypassed

waflib.Task.update_outputs(cls)

Task class decorator

If you want to create files in the source directory. For example, to keep foo.txt in the source directory, create it first and declare:

def build(bld):
        bld(rule='cp ${SRC} ${TGT}', source='wscript', target='foo.txt', update_outputs=True)