Build¶

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

The inheritance tree is the following:

waflib.Build.CACHE_DIR = 'c4che'¶: Name of the cache directory

waflib.Build.CACHE_SUFFIX = '_cache.py'¶: ConfigSet cache files for variants are written under :py:attr:´waflib.Build.CACHE_DIR´ in the form ´variant_name´_cache.py

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_sigs', 'task_sigs', 'imp_sigs', 'raw_deps', 'node_deps', 'hashes_md5_tstamp']¶: Build class members to save between the runs; these should be all dicts except for root which represents a waflib.Node.Node instance

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 any task executed

waflib.Build.POST_LAZY = 1¶: Post mode: post the task generators group after group, the tasks in the next group are created when the tasks in the previous groups are done

class waflib.Build.BuildContext(**kw)[source]¶

executes the build

cmd = 'build'¶

variant = ''¶

is_install¶: Non-zero value when installing or uninstalling file

top_dir¶: See waflib.Context.top_dir; prefer waflib.Build.BuildContext.srcnode

out_dir¶: See waflib.Context.out_dir; prefer waflib.Build.BuildContext.bldnode

run_dir¶: See waflib.Context.run_dir

launch_dir¶: See waflib.Context.out_dir; prefer waflib.Build.BuildContext.launch_node()

post_mode¶: Whether to post the task generators at once or group-by-group (default is group-by-group)

all_envs¶: Map names to waflib.ConfigSet.ConfigSet, the empty string must map to the default environment

node_sigs¶: Dict mapping build nodes to task identifier (uid), it indicates whether a task created a particular file (persists across builds)

task_sigs¶: Dict mapping task identifiers (uid) to task signatures (persists across builds)

imp_sigs¶: Dict mapping task identifiers (uid) to implicit task dependencies used for scanning targets (persists across builds)

node_deps¶: Dict mapping task identifiers (uid) to node dependencies found by waflib.Task.Task.scan() (persists across builds)

raw_deps¶: Dict mapping task identifiers (uid) to custom data returned by waflib.Task.Task.scan() (persists across builds)

jobs¶: Amount of jobs to run in parallel

targets¶: List of targets to build (default: *)

keep¶: Whether the build should continue past errors

progress_bar¶

Level of progress status:

normal output
progress bar
IDE output
No output at all

deps_man¶: Manual dependencies set by waflib.Build.BuildContext.add_manual_dependency()

current_group¶: Current build group

groups¶: List containing lists of task generators

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

get_variant_dir()[source]¶: Getter for the variant_dir attribute

property variant_dir¶: Getter for the variant_dir attribute

__call__(*k, **kw)[source]¶

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

__copy__()[source]¶

Build contexts cannot be copied

Raises: waflib.Errors.WafError

load_envs()[source]¶: 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 and stores them in waflib.Build.BuildContext.allenvs.

init_dirs()[source]¶: 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 is created if necessary.

execute()[source]¶: Restore data from previous builds and call waflib.Build.BuildContext.execute_build(). Overrides from waflib.Context.Context.execute()

execute_build()[source]¶

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()[source]¶: Load data from a previous run, sets the attributes listed in waflib.Build.SAVED_ATTRS

store()[source]¶: Store data for next runs, set the attributes listed in waflib.Build.SAVED_ATTRS. Uses a temporary file to avoid problems on ctrl+c.

compile()[source]¶

Run the build by creating an instance of waflib.Runner.Parallel The cache file is written when at least a task was executed.

Raises: waflib.Errors.BuildError in case the build fails

setup(tool, tooldir=None, funs=None)[source]¶

Import waf tools defined 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()[source]¶: Getter for the env property

set_env(val)[source]¶: Setter for the env property

property env¶: Getter for the env property

add_manual_dependency(path, value)[source]¶

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, byte object, or function returning a byte object) – value to depend

launch_node()[source]¶: Returns the launch directory as a waflib.Node.Node object (cached)

hash_env_vars(env, vars_lst)[source]¶

Hashes configuration set variables:

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

This method uses an internal cache.

Parameters

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

get_tgen_by_name(name)[source]¶

Fetches a task generator by its name or its target attribute; the name must be unique in a build:

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

This method use a private internal cache.

Parameters: name – Task generator name
Raises: waflib.Errors.WafError in case there is no task genenerator by that name

progress_line(idx, total, col1, col2)[source]¶

Computes a progress bar line displayed when running waf -p

Returns: progress bar line
Return type: string

declare_chain(*k, **kw)[source]¶: Wraps waflib.TaskGen.declare_chain() for convenience

pre_build()[source]¶: Executes user-defined methods before the build starts, see waflib.Build.BuildContext.add_pre_fun()

post_build()[source]¶: Executes user-defined methods after the build is successful, see waflib.Build.BuildContext.add_post_fun()

add_pre_fun(meth)[source]¶

Binds a callback 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)[source]¶

Binds a callback 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)[source]¶

Returns the build group named x, or the current group if x is None

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

add_to_group(tgen, group=None)[source]¶: Adds a task or a task generator to the build; there is no attempt to remove it if it was already added.

get_group_name(g)[source]¶

Returns the name of the input build group

Parameters: g (integer or list) – build group object or build group index
Returns: name
Return type: string

get_group_idx(tg)[source]¶

Returns the 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
Return type: int

add_group(name=None, move=True)[source]¶

Adds a new group of tasks/task generators. By default the new group becomes the default group for new task generators (make sure to create build groups in order).

Parameters

name (string) – name for this group
move (bool) – set this new group as default group (True by default)

Raises

waflib.Errors.WafError if a group by the name given already exists

set_group(idx)[source]¶

Sets the build group at position idx as current so that newly added task generators are added to this one 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()[source]¶

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.

Return type: int

get_targets()[source]¶

This method returns a pair containing the index of the last build group to post, and the list of task generator objects corresponding to the target names.

This is used internally by waflib.Build.BuildContext.get_build_iterator() to perform partial builds:

$ waf --targets=myprogram,myshlib

Returns: the minimum build group index, and list of task generators
Return type: tuple

get_all_task_gen()[source]¶: Returns a list of all task generators for troubleshooting purposes.

post_group()[source]¶: Post task generators from the group indexed by self.current_group; used internally by waflib.Build.BuildContext.get_build_iterator()

get_tasks_group(idx)[source]¶

Returns all task instances for the build group at position idx, used internally by waflib.Build.BuildContext.get_build_iterator()

Return type: list of waflib.Task.Task

get_build_iterator()[source]¶

Creates a Python generator object that returns lists of tasks that may be processed in parallel.

Returns: tasks which can be executed immediately
Return type: generator returning lists of waflib.Task.Task

install_files(dest, files, **kw)[source]¶

Creates a task generator to install files on the system:

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

Parameters

dest (waflib.Node.Node or string (absolute path)) – path representing the destination directory
files (list of strings or list of waflib.Node.Node) – input files
env (waflib.ConfigSet.ConfigSet) – configuration set to expand 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 an instance of waflib.Node.Node
postpone (bool) – execute the task immediately to perform the installation (False by default)

install_as(dest, srcfile, **kw)[source]¶

Creates a task generator 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 (waflib.Node.Node or string (absolute path)) – destination file
srcfile (string or waflib.Node.Node) – input file
cwd (waflib.Node.Node) – parent node for searching srcfile, when srcfile is not an instance of waflib.Node.Node
env (waflib.ConfigSet.ConfigSet) – configuration set for performing substitutions in dest
postpone (bool) – execute the task immediately to perform the installation (False by default)

symlink_as(dest, src, **kw)[source]¶

Creates a task generator to install a symlink:

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

Parameters

dest (waflib.Node.Node or string (absolute path)) – absolute path of the symlink
src (string) – link contents, which is a relative or absolute path which may exist or not
env (waflib.ConfigSet.ConfigSet) – 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)

fun = 'build'¶

waflib.Build.process_install_task(self)[source]¶

Task generator method

Creates the installation task for the current task generator; uses waflib.Build.add_install_task() internally.

feature: install_task

waflib.Build.add_install_task(self, **kw)[source]¶

Task generator method

Creates the installation task for the current task generator, and executes it immediately if necessary

Returns: An installation task
Return type: waflib.Build.inst

waflib.Build.add_install_files(self, **kw)[source]¶

Task generator method

Creates an installation task for files

Returns: An installation task
Return type: waflib.Build.inst

waflib.Build.add_install_as(self, **kw)[source]¶

Task generator method

Creates an installation task for a single file

Returns: An installation task
Return type: waflib.Build.inst

waflib.Build.add_symlink_as(self, **kw)[source]¶

Task generator method

Creates an installation task for a symbolic link

Returns: An installation task
Return type: waflib.Build.inst

class waflib.Build.inst(*k, **kw)[source]¶

Task that installs files or symlinks; it is typically executed by waflib.Build.InstallContext and waflib.Build.UnInstallContext

__str__()[source]¶: Returns an empty string to disable the standard task display

uid()[source]¶: Returns a unique identifier for the task

init_files()[source]¶: Initializes the task input and output nodes

runnable_status()[source]¶: Installation tasks are always executed, so this method returns either waflib.Task.ASK_LATER or waflib.Task.RUN_ME.

post_run()[source]¶: Disables any post-run operations

get_install_path(destdir=True)[source]¶

Returns the destination path where files will be installed, pre-pending destdir.

Relative paths will be interpreted relative to PREFIX if no destdir is given.

Return type: string

copy_fun(src, tgt)[source]¶

Copies a file from src to tgt, preserving permissions and trying to work around path limitations on Windows platforms. On Unix-like platforms, the owner/group of the target file may be set through install_user/install_group

Parameters

src (string) – absolute path
tgt (string) – absolute path

rm_empty_dirs(tgt)[source]¶

Removes empty folders recursively when uninstalling.

Parameters: tgt (string) – absolute path

run()[source]¶: Performs file or symlink installation

run_now()[source]¶

Try executing the installation task right now

Raises: waflib.Errors.TaskNotReady

hasrun¶

generator¶

env¶: waflib.ConfigSet.ConfigSet object (make sure to provide one)

inputs¶: List of input nodes, which represent the files used by the task instance

outputs¶: List of output nodes, which represent the files created by the task instance

dep_nodes¶: List of additional nodes to depend on

run_after¶: Set of tasks that must be executed before this one

do_install(src, tgt, lbl, **kw)[source]¶

Copies a file from src to tgt with given file permissions. The actual copy is only performed if the source and target file sizes or timestamps differ. When the copy occurs, the file is always first removed and then copied so as to prevent stale inodes.

Parameters

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

Raises

waflib.Errors.WafError if the file cannot be written

hcode = b'\tdef run(self):\n\t\t"""\n\t\tPerforms file or symlink installation\n\t\t"""\n\t\tis_install = self.generator.bld.is_install\n\t\tif not is_install: # unnecessary?\n\t\t\treturn\n\n\t\tfor x in self.outputs:\n\t\t\tif is_install == INSTALL:\n\t\t\t\tx.parent.mkdir()\n\t\tif self.type == \'symlink_as\':\n\t\t\tfun = is_install == INSTALL and self.do_link or self.do_unlink\n\t\t\tfun(self.link, self.outputs[0].abspath())\n\t\telse:\n\t\t\tfun = is_install == INSTALL and self.do_install or self.do_uninstall\n\t\t\tlaunch_node = self.generator.bld.launch_node()\n\t\t\tfor x, y in zip(self.inputs, self.outputs):\n\t\t\t\tfun(x.abspath(), y.abspath(), x.path_from(launch_node))\n'¶: String representing an additional hash for the class representation

fix_perms(tgt)[source]¶

Change the ownership of the file/folder/link pointed by the given path This looks up for install_user or install_group attributes on the task or on the task generator:

def build(bld):
        bld.install_as('${PREFIX}/wscript',
                'wscript',
                install_user='nobody', install_group='nogroup')
        bld.symlink_as('${PREFIX}/wscript_link',
                Utils.subst_vars('${PREFIX}/wscript', bld.env),
                install_user='nobody', install_group='nogroup')

do_link(src, tgt, **kw)[source]¶

Creates a symlink from tgt to src.

Parameters

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

do_uninstall(src, tgt, lbl, **kw)[source]¶: See waflib.Build.inst.do_install()

do_unlink(src, tgt, **kw)[source]¶: See waflib.Build.inst.do_link()

class waflib.Build.InstallContext(**kw)[source]¶

installs the targets on the system

__annotations__ = {}¶

cmd = 'install'¶

class waflib.Build.UninstallContext(**kw)[source]¶

removes the targets installed

__annotations__ = {}¶

cmd = 'uninstall'¶

class waflib.Build.CleanContext(**kw)[source]¶

cleans the project

__annotations__ = {}¶

cmd = 'clean'¶

execute()[source]¶: See waflib.Build.BuildContext.execute().

clean()[source]¶

Remove most files from the build directory, and reset all caches.

Custom lists of files to clean can be declared as bld.clean_files. For example, exclude build/program/myprogram from getting removed:

def build(bld):
        bld.clean_files = bld.bldnode.ant_glob('**',
                excl='.lock* config.log c4che/* config.h program/myprogram',
                quiet=True, generator=True)

class waflib.Build.ListContext(**kw)[source]¶

lists the targets to execute

__annotations__ = {}¶

cmd = 'list'¶

execute()[source]¶

In addition to printing the name of each build target, a description column will include text for each task generator which has a “description” field set.

See waflib.Build.BuildContext.execute().

class waflib.Build.StepContext(**kw)[source]¶

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

__annotations__ = {}¶

cmd = 'step'¶

compile()[source]¶

Overrides waflib.Build.BuildContext.compile() to perform a partial build on tasks matching the input/output pattern given (regular expression matching):

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

get_matcher(pat)[source]¶

Converts a step pattern into a function

Param: pat: pattern of the form in:truc.c,out:bar.o
Returns: Python function that uses Node objects as inputs and returns matches
Return type: function

class waflib.Build.EnvContext(**kw)[source]¶

Subclass EnvContext to create commands that require configuration data in ‘env’

__annotations__ = {}¶

execute()[source]¶: See waflib.Build.BuildContext.execute().

Build¶

Previous topic

Next topic

This Page