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
; preferwaflib.Build.BuildContext.srcnode
- out_dir¶
See
waflib.Context.out_dir
; preferwaflib.Build.BuildContext.bldnode
- run_dir¶
- launch_dir¶
See
waflib.Context.out_dir
; preferwaflib.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()
- 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
- load_envs()[source]¶
The configuration command creates files of the form
build/c4che/NAMEcache.py
. This method creates awaflib.ConfigSet.ConfigSet
instance for eachNAME
by reading those files and stores them inwaflib.Build.BuildContext.allenvs
.
- init_dirs()[source]¶
Initialize the project directory and the build directory by creating the nodes
waflib.Build.BuildContext.srcnode
andwaflib.Build.BuildContext.bldnode
corresponding totop_dir
andvariant_dir
respectively. Thebldnode
directory is created if necessary.
- execute()[source]¶
Restore data from previous builds and call
waflib.Build.BuildContext.execute_build()
. Overrides fromwaflib.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 functionscalling
waflib.Build.BuildContext.compile()
to process the taskscalling
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
- 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 pathvalue (
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 Setvars_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 valuewaflib.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
- 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 directoryfiles (list of strings or list of
waflib.Node.Node
) – input filesenv (
waflib.ConfigSet.ConfigSet
) – configuration set to expand destrelative_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 ofwaflib.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 filesrcfile (string or
waflib.Node.Node
) – input filecwd (
waflib.Node.Node
) – parent node for searching srcfile, when srcfile is not an instance ofwaflib.Node.Node
env (
waflib.ConfigSet.ConfigSet
) – configuration set for performing substitutions in destpostpone (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 symlinksrc (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 destadd (bool) – add the task created to a build group - set
False
only if the installation task is created after the build has startedpostpone (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
- Creates the installation task for the current task generator; uses
- 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.add_install_files(self, **kw)[source]¶
Task generator method
Creates an installation task for files
- Returns
An installation task
- Return type
- 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.add_symlink_as(self, **kw)[source]¶
Task generator method
Creates an installation task for a symbolic link
- Returns
An installation task
- Return type
- class waflib.Build.inst(*k, **kw)[source]¶
Task that installs files or symlinks; it is typically executed by
waflib.Build.InstallContext
andwaflib.Build.UnInstallContext
- runnable_status()[source]¶
Installation tasks are always executed, so this method returns either
waflib.Task.ASK_LATER
orwaflib.Task.RUN_ME
.
- 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
- 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
- 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'¶
- 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'¶
- 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