Build

Classes related to the build phase (build, clean, install, step, etc)

The inheritance tree is the following:

waflib.Build.CACHE_DIR = 'c4che'

Location of the cache files

waflib.Build.CACHE_SUFFIX = '_cache.py'

Suffix for the cache files

waflib.Build.INSTALL = 1337

Positive value ‘->’ install, see waflib.Build.BuildContext.is_install

waflib.Build.UNINSTALL = -1337

Negative value ‘<-‘ uninstall, see waflib.Build.BuildContext.is_install

waflib.Build.SAVED_ATTRS = ['root', 'node_deps', 'raw_deps', 'task_sigs']

Build class members to save between the runs (root, node_deps, raw_deps, task_sigs)

waflib.Build.CFG_FILES = 'cfg_files'

Files from the build directory to hash before starting the build (config.h written during the configuration)

waflib.Build.POST_AT_ONCE = 0

Post mode: all task generators are posted before the build really starts

waflib.Build.POST_LAZY = 1

Post mode: post the task generators group after group

waflib.Build.POST_BOTH = 2

Post mode: post the task generators at once, then re-check them for each group

class waflib.Build.BuildContext(**kw)

Bases: waflib.Context.Context

executes the build

cmd = 'build'

variant = ''

is_install = None

Non-zero value when installing or uninstalling file

post_mode = None

post the task generators at once, group-by-group, or both

task_sigs = None

Signatures of the tasks (persists between build executions)

node_deps = None

Dict of node dependencies found by waflib.Task.Task.scan() (persists between build executions)

raw_deps = None

Dict of custom data returned by waflib.Task.Task.scan() (persists between build executions)

deps_man = None

Manual dependencies set by waflib.Build.BuildContext.add_manual_dependency()

current_group = None

Current build group

groups = None

List containing lists of task generators

group_names = None

Map group names to the group lists. See waflib.Build.BuildContext.add_group()

get_variant_dir()

Getter for the variant_dir attribute

variant_dir

Getter for the variant_dir attribute

__call__(*k, **kw)

Create a task generator and add it to the current build group. The following forms are equivalent:

def build(bld):
        tg = bld(a=1, b=2)

def build(bld):
        tg = bld()
        tg.a = 1
        tg.b = 2

def build(bld):
        tg = TaskGen.task_gen(a=1, b=2)
        bld.add_to_group(tg, None)

Parameters:group (string) – group name to add the task generator to

rule(*k, **kw)

Wrapper for creating a task generator using the decorator notation. The following code:

@bld.rule(
        target = "foo"
)
def _(tsk):
        print("bar")

is equivalent to:

def bar(tsk):
        print("bar")

bld(
        target = "foo",
        rule = bar,
)

__copy__()

Implemented to prevents copies of build contexts (raises an exception)

install_files(*k, **kw)

Actual implementation provided by waflib.Build.InstallContext.install_files()

install_as(*k, **kw)

Actual implementation provided by waflib.Build.InstallContext.install_as()

symlink_as(*k, **kw)

Actual implementation provided by waflib.Build.InstallContext.symlink_as()

load_envs()

The configuration command creates files of the form build/c4che/NAMEcache.py. This method creates a waflib.ConfigSet.ConfigSet instance for each NAME by reading those files. The config sets are then stored in the dict waflib.Build.BuildContext.allenvs.

init_dirs()

Initialize the project directory and the build directory by creating the nodes waflib.Build.BuildContext.srcnode and waflib.Build.BuildContext.bldnode corresponding to top_dir and variant_dir respectively. The bldnode directory will be created if it does not exist.

execute()

Restore the data from previous builds and call waflib.Build.BuildContext.execute_build(). Overrides from waflib.Context.Context.execute()

execute_build()

Execute the build by:

• reading the scripts (see waflib.Context.Context.recurse())
• calling waflib.Build.BuildContext.pre_build() to call user build functions
• calling waflib.Build.BuildContext.compile() to process the tasks
• calling waflib.Build.BuildContext.post_build() to call user build functions

restore()

Load the data from a previous run, sets the attributes listed in waflib.Build.SAVED_ATTRS

store()

Store the data for next runs, sets the attributes listed in waflib.Build.SAVED_ATTRS. Uses a temporary file to avoid problems on ctrl+c.

compile()

Run the build by creating an instance of waflib.Runner.Parallel The cache file is not written if the build is up to date (no task executed).

setup(tool, tooldir=None, funs=None)

Import waf tools, used to import those accessed during the configuration:

def configure(conf):
        conf.load('glib2')

def build(bld):
        pass # glib2 is imported implicitly

Parameters:

• tool (list) – tool list
• tooldir (list of string) – optional tool directory (sys.path)
• funs – unused variable

get_env()

Getter for the env property

set_env(val)

Setter for the env property

env

Getter for the env property

add_manual_dependency(path, value)

Adds a dependency from a node object to a value:

def build(bld):
        bld.add_manual_dependency(
                bld.path.find_resource('wscript'),
                bld.root.find_resource('/etc/fstab'))

Parameters:

• path (string or waflib.Node.Node) – file path
• value (waflib.Node.Node, string, or function returning a string) – value to depend on

launch_node()

Returns the launch directory as a waflib.Node.Node object

hash_env_vars(env, vars_lst)

Hash configuration set variables:

def build(bld):
        bld.hash_env_vars(bld.env, ['CXX', 'CC'])

Parameters:

• env (waflib.ConfigSet.ConfigSet) – Configuration Set
• vars_lst – list of variables

get_tgen_by_name(name)

Retrieves a task generator from its name or its target name the name must be unique:

def build(bld):
        tg = bld(name='foo')
        tg == bld.get_tgen_by_name('foo')

progress_line(state, total, col1, col2)

Compute the progress bar used by waf -p

declare_chain(*k, **kw)

Wrapper for waflib.TaskGen.declare_chain() provided for convenience

pre_build()

Execute user-defined methods before the build starts, see waflib.Build.BuildContext.add_pre_fun()

post_build()

Executes the user-defined methods after the build is successful, see waflib.Build.BuildContext.add_post_fun()

add_pre_fun(meth)

Bind a method to execute after the scripts are read and before the build starts:

def mycallback(bld):

print(“Hello, world!”)

def build(bld):

bld.add_pre_fun(mycallback)

add_post_fun(meth)

Bind a method to execute immediately after the build is successful:

def call_ldconfig(bld):

bld.exec_command(‘/sbin/ldconfig’)

def build(bld):

if bld.cmd == ‘install’:

bld.add_pre_fun(call_ldconfig)

get_group(x)

Get the group x, or return the current group if x is None

Parameters:x (string, int or None) – name or number or None

add_to_group(tgen, group=None)

add a task or a task generator for the build

get_group_name(g)

name for the group g (utility)

get_group_idx(tg)

Index of the group containing the task generator given as argument:

def build(bld):
        tg = bld(name='nada')
        0 == bld.get_group_idx(tg)

Parameters:tg (waflib.TaskGen.task_gen) – Task generator object

add_group(name=None, move=True)

Add a new group of tasks/task generators. By default the new group becomes the default group for new task generators.

Parameters:

• name (string) – name for this group
• move (bool) – set the group created as default group (True by default)

set_group(idx)

Set the current group to be idx: now new task generators will be added to this group by default:

def build(bld):
        bld(rule='touch ${TGT}', target='foo.txt')
        bld.add_group() # now the current group is 1
        bld(rule='touch ${TGT}', target='bar.txt')
        bld.set_group(0) # now the current group is 0
        bld(rule='touch ${TGT}', target='truc.txt') # build truc.txt before bar.txt

Parameters:idx (string or int) – group name or group index

total()

Approximate task count: this value may be inaccurate if task generators are posted lazily (see waflib.Build.BuildContext.post_mode). The value waflib.Runner.Parallel.total is updated during the task execution.

get_targets()

Return the task generator corresponding to the ‘targets’ list, used by waflib.Build.BuildContext.get_build_iterator():

$ waf --targets=myprogram,myshlib

get_all_task_gen()

Utility method, returns a list of all task generators - if you need something more complicated, implement your own

post_group()

Post the task generators from the group indexed by self.cur, used by waflib.Build.BuildContext.get_build_iterator()

get_tasks_group(idx)

Return all the tasks for the group of num idx, used by waflib.Build.BuildContext.get_build_iterator()

get_build_iterator()

Creates a generator object that returns lists of tasks executable in parallel (yield)

Returns:tasks which can be executed immediatly Return type:list of waflib.Task.TaskBase

__doc__ = 'executes the build'

__module__ = 'waflib.Build'

fun = 'build'

class waflib.Build.inst(*k, **kw)

Bases: waflib.Task.Task

Special task used for installing files and symlinks, it behaves both like a task and like a task generator

color = 'CYAN'

post()

Same interface as in waflib.TaskGen.task_gen.post()

runnable_status()

Installation tasks are always executed, so this method returns either waflib.Task.ASK_LATER or waflib.Task.RUN_ME.

__str__()

Return an empty string to disable the display

run()

The attribute ‘exec_task’ holds the method to execute

get_install_path(destdir=True)

Installation path obtained from self.dest and prefixed by the destdir. The variables such as ‘${PREFIX}/bin’ are substituted.

exec_install_files()

Predefined method for installing files

exec_install_as()

Predefined method for installing one file with a given name

exec_symlink_as()

Predefined method for installing a symlink

__doc__ = '\n\tSpecial task used for installing files and symlinks, it behaves both like a task\n\tand like a task generator\n\t'

__module__ = 'waflib.Build'

hcode = '\tdef run(self):\n\t\t"""The attribute \'exec_task\' holds the method to execute"""\n\t\treturn self.generator.exec_task()\n'

class waflib.Build.InstallContext(**kw)

Bases: waflib.Build.BuildContext

installs the targets on the system

cmd = 'install'

do_install(src, tgt, **kw)

Copy a file from src to tgt with given file permissions. The actual copy is not performed if the source and target file have the same size and the same timestamps. When the copy occurs, the file is first removed and then copied (prevent stale inodes).

This method is overridden in waflib.Build.UninstallContext.do_install() to remove the file.

Parameters:

• src (string) – file name as absolute path
• tgt (string) – file destination, as absolute path
• chmod (int) – installation mode

do_link(src, tgt, **kw)

Create a symlink from tgt to src.

This method is overridden in waflib.Build.UninstallContext.do_link() to remove the symlink.

Parameters:

• src (string) – file name as absolute path
• tgt (string) – file destination, as absolute path

run_task_now(tsk, postpone)

This method is called by waflib.Build.InstallContext.install_files(), waflib.Build.InstallContext.install_as() and waflib.Build.InstallContext.symlink_as() immediately after the installation task is created. Its role is to force the immediate execution if necessary, that is when postpone=False was given.

install_files(dest, files, env=None, chmod=420, relative_trick=False, cwd=None, add=True, postpone=True, task=None)

Create a task to install files on the system:

def build(bld):
        bld.install_files('${DATADIR}', self.path.find_resource('wscript'))

Parameters:

• dest (string) – absolute path of the destination directory
• files (list of strings or list of nodes) – input files
• env (Configuration set) – configuration set for performing substitutions in dest
• relative_trick (bool) – preserve the folder hierarchy when installing whole folders
• cwd (waflib.Node.Node) – parent node for searching srcfile, when srcfile is not a waflib.Node.Node
• add (bool) – add the task created to a build group - set False only if the installation task is created after the build has started
• postpone (bool) – execute the task immediately to perform the installation

install_as(dest, srcfile, env=None, chmod=420, cwd=None, add=True, postpone=True, task=None)

Create a task to install a file on the system with a different name:

def build(bld):
        bld.install_as('${PREFIX}/bin', 'myapp', chmod=Utils.O755)

Parameters:

• dest (string) – absolute path of the destination file
• srcfile (string or node) – input file
• cwd (waflib.Node.Node) – parent node for searching srcfile, when srcfile is not a waflib.Node.Node
• env (Configuration set) – configuration set for performing substitutions in dest
• add (bool) – add the task created to a build group - set False only if the installation task is created after the build has started
• postpone (bool) – execute the task immediately to perform the installation

symlink_as(dest, src, env=None, cwd=None, add=True, postpone=True, relative_trick=False, task=None)

Create a task to install a symlink:

def build(bld):
        bld.symlink_as('${PREFIX}/lib/libfoo.so', 'libfoo.so.1.2.3')

Parameters:

• dest (string) – absolute path of the symlink
• src (string) – absolute or relative path of the link
• env (Configuration set) – configuration set for performing substitutions in dest
• add (bool) – add the task created to a build group - set False only if the installation task is created after the build has started
• postpone (bool) – execute the task immediately to perform the installation
• relative_trick (bool) – make the symlink relative (default: False)

__doc__ = 'installs the targets on the system'

__module__ = 'waflib.Build'

class waflib.Build.UninstallContext(**kw)

Bases: waflib.Build.InstallContext

removes the targets installed

__doc__ = 'removes the targets installed'

__module__ = 'waflib.Build'

cmd = 'uninstall'

do_install(src, tgt, **kw)

See waflib.Build.InstallContext.do_install()

do_link(src, tgt, **kw)

See waflib.Build.InstallContext.do_link()

execute()

See waflib.Context.Context.execute()

class waflib.Build.CleanContext(**kw)

Bases: waflib.Build.BuildContext

cleans the project

__doc__ = 'cleans the project'

__module__ = 'waflib.Build'

cmd = 'clean'

execute()

See waflib.Context.Context.execute()

clean()

Remove files from the build directory if possible, and reset the caches

class waflib.Build.ListContext(**kw)

Bases: waflib.Build.BuildContext

lists the targets to execute

__doc__ = 'lists the targets to execute'

__module__ = 'waflib.Build'

cmd = 'list'

execute()

See waflib.Context.Context.execute().

class waflib.Build.StepContext(**kw)

Bases: waflib.Build.BuildContext

executes tasks in a step-by-step fashion, for debugging

__doc__ = 'executes tasks in a step-by-step fashion, for debugging'

__module__ = 'waflib.Build'

cmd = 'step'

compile()

Compile the tasks matching the input/output files given (regular expression matching). Derived from waflib.Build.BuildContext.compile():

$ waf step --files=foo.c,bar.c,in:truc.c,out:bar.o
$ waf step --files=in:foo.cpp.1.o # link task only