c_config

C/C++/D configuration helpers

waflib.Tools.c_config.after_method(*k)[source]

Decorator that registers a task generator method which will be executed after the functions of given name(s):

from waflib.TaskGen import feature, after
@feature('myfeature')
@after_method('fun2')
def fun1(self):
        print('feature 1!')
@feature('myfeature')
def fun2(self):
        print('feature 2!')
def build(bld):
        bld(features='myfeature')
Parameters

k (list of string) – method names

waflib.Tools.c_config.feature(*k)

Decorator that registers a task generator method that will be executed when the object attribute feature contains the corresponding key(s):

from waflib.TaskGen import feature
@feature('myfeature')
def myfunction(self):
        print('that is my feature!')
def build(bld):
        bld(features='myfeature')
Parameters

k (list of string) – feature names

waflib.Tools.c_config.conf(f)

Decorator: attach new configuration functions to waflib.Build.BuildContext and waflib.Configure.ConfigurationContext. The methods bound will accept a parameter named ‘mandatory’ to disable the configuration errors:

def configure(conf):
        conf.find_program('abc', mandatory=False)
Parameters

f (function) – method to bind

waflib.Tools.c_config.WAF_CONFIG_H = 'config.h'

default name for the config.h file

waflib.Tools.c_config.parse_flags(self, line, uselib_store, env=None, force_static=False, posix=None)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Parses flags from the input lines, and adds them to the relevant use variables:

def configure(conf):
        conf.parse_flags('-O3', 'FOO')
        # conf.env.CXXFLAGS_FOO = ['-O3']
        # conf.env.CFLAGS_FOO = ['-O3']
Parameters
  • line (string) – flags

  • uselib_store (string) – where to add the flags

  • env (waflib.ConfigSet.ConfigSet) – config set or conf.env by default

  • force_static (bool default False) – force usage of static libraries

  • posix (bool default True) – usage of POSIX mode for shlex lexical analiysis library

waflib.Tools.c_config.validate_cfg(self, kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Searches for the program pkg-config if missing, and validates the parameters to pass to waflib.Tools.c_config.exec_cfg().

Parameters
  • path (list of string) – the -config program to use (default is pkg-config)

  • msg (string) – message to display to describe the test executed

  • okmsg (string) – message to display when the test is successful

  • errmsg (string) – message to display in case of error

waflib.Tools.c_config.exec_cfg(self, kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Executes pkg-config or other -config applications to collect configuration flags:

  • if atleast_pkgconfig_version is given, check that pkg-config has the version n and return

  • if modversion is given, then return the module version

  • else, execute the -config program with the args and variables given, and set the flags on the conf.env.FLAGS_name variable

Parameters
  • path (list of string) – the -config program to use

  • atleast_pkgconfig_version (string) – minimum pkg-config version to use (disable other tests)

  • package (string) – package name, for example gtk+-2.0

  • uselib_store (string) – if the test is successful, define HAVE_*name*. It is also used to define conf.env.FLAGS_name variables.

  • modversion (string) – if provided, return the version of the given module and define name_VERSION

  • args (list of string) – arguments to give to package when retrieving flags

  • variables (list of string) – return the values of particular variables

  • define_variable (dict(string: string)) – additional variables to define (also in conf.env.PKG_CONFIG_DEFINES)

  • pkg_config_path (string, list of directories separated by colon) – paths where pkg-config should search for .pc config files (overrides env.PKG_CONFIG_PATH if exists)

  • force_static (bool default False) – force usage of static libraries

  • posix (bool default True) – usage of POSIX mode for shlex lexical analiysis library

waflib.Tools.c_config.check_cfg(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Checks for configuration flags using a -config-like program (pkg-config, sdl-config, etc). This wraps internal calls to waflib.Tools.c_config.validate_cfg() and waflib.Tools.c_config.exec_cfg() so check exec_cfg parameters descriptions for more details on kw passed

A few examples:

def configure(conf):
        conf.load('compiler_c')
        conf.check_cfg(package='glib-2.0', args='--libs --cflags')
        conf.check_cfg(package='pango')
        conf.check_cfg(package='pango', uselib_store='MYPANGO', args=['--cflags', '--libs'])
        conf.check_cfg(package='pango',
                args=['pango >= 0.1.0', 'pango < 9.9.9', '--cflags', '--libs'],
                msg="Checking for 'pango 0.1.0'")
        conf.check_cfg(path='sdl-config', args='--cflags --libs', package='', uselib_store='SDL')
        conf.check_cfg(path='mpicc', args='--showme:compile --showme:link',
                package='', uselib_store='OPEN_MPI', mandatory=False)
        # variables
        conf.check_cfg(package='gtk+-2.0', variables=['includedir', 'prefix'], uselib_store='FOO')
        print(conf.env.FOO_includedir)
waflib.Tools.c_config.build_fun(bld)[source]

Build function that is used for running configuration tests with conf.check()

waflib.Tools.c_config.validate_c(self, kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Pre-checks the parameters that will be given to waflib.Configure.run_build()

Parameters
  • compiler (string) – c or cxx (tries to guess what is best)

  • type (binary to create) – cprogram, cshlib, cstlib - not required if features are given directly

  • feature (list of string) – desired features for the task generator that will execute the test, for example cxx cxxstlib

  • fragment (string) – provide a piece of code for the test (default is to let the system create one)

  • uselib_store (string) – define variables after the test is executed (IMPORTANT!)

  • use (list of string) – parameters to use for building (just like the normal use keyword)

  • define_name (string) – define to set when the check is over

  • execute (bool) – execute the resulting binary

  • define_ret (bool) – if execute is set to True, use the execution output in both the define and the return value

  • header_name (string) – check for a particular header

  • auto_add_header_name (bool) – if header_name was set, add the headers in env.INCKEYS so the next tests will include these headers

waflib.Tools.c_config.post_check(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Sets the variables after a test executed in waflib.Tools.c_config.check() was run successfully

waflib.Tools.c_config.check(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Performs a configuration test by calling waflib.Configure.run_build(). For the complete list of parameters, see waflib.Tools.c_config.validate_c(). To force a specific compiler, pass compiler='c' or compiler='cxx' to the list of arguments

Besides build targets, complete builds can be given through a build function. All files will be written to a temporary directory:

def build(bld):
        lib_node = bld.srcnode.make_node('libdir/liblc1.c')
        lib_node.parent.mkdir()
        lib_node.write('#include <stdio.h>\nint lib_func(void) { FILE *f = fopen("foo", "r");}\n', 'w')
        bld(features='c cshlib', source=[lib_node], linkflags=conf.env.EXTRA_LDFLAGS, target='liblc')
conf.check(build_fun=build, msg=msg)
class waflib.Tools.c_config.test_exec(*k, **kw)[source]

A task that runs programs after they are built. See waflib.Tools.c_config.test_exec_fun().

color = 'PINK'

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

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

hcode = b"\tdef run(self):\n\t\tcmd = [self.inputs[0].abspath()] + getattr(self.generator, 'test_args', [])\n\t\tif getattr(self.generator, 'rpath', None):\n\t\t\tif getattr(self.generator, 'define_ret', False):\n\t\t\t\tself.generator.bld.retval = self.generator.bld.cmd_and_log(cmd)\n\t\t\telse:\n\t\t\t\tself.generator.bld.retval = self.generator.bld.exec_command(cmd)\n\t\telse:\n\t\t\tenv = self.env.env or {}\n\t\t\tenv.update(dict(os.environ))\n\t\t\tfor var in ('LD_LIBRARY_PATH', 'DYLD_LIBRARY_PATH', 'PATH'):\n\t\t\t\tenv[var] = self.inputs[0].parent.abspath() + os.path.pathsep + env.get(var, '')\n\t\t\tif getattr(self.generator, 'define_ret', False):\n\t\t\t\tself.generator.bld.retval = self.generator.bld.cmd_and_log(cmd, env=env)\n\t\t\telse:\n\t\t\t\tself.generator.bld.retval = self.generator.bld.exec_command(cmd, env=env)\n"

String representing an additional hash for the class representation

waflib.Tools.c_config.test_exec_fun(self)[source]

Task generator method

The feature test_exec is used to create a task that will to execute the binary created (link task output) during the build. The exit status will be set on the build context, so only one program may have the feature test_exec. This is used by configuration tests:

def configure(conf):
        conf.check(execute=True)
Feature

test_exec

waflib.Tools.c_config.check_cxx(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Runs a test with a task generator of the form:

conf.check(features='cxx cxxprogram', ...)
waflib.Tools.c_config.check_cc(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Runs a test with a task generator of the form:

conf.check(features='c cprogram', ...)
waflib.Tools.c_config.set_define_comment(self, key, comment)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Sets a comment that will appear in the configuration header

waflib.Tools.c_config.get_define_comment(self, key)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Returns the comment associated to a define

waflib.Tools.c_config.define(self, key, val, quote=True, comment='')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Stores a single define and its state into conf.env.DEFINES. The value is cast to an integer (0/1).

Parameters
  • key (string) – define name

  • val (int or string) – value

  • quote (bool) – enclose strings in quotes (yes by default)

waflib.Tools.c_config.undefine(self, key, comment='')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Removes a global define from conf.env.DEFINES

Parameters

key (string) – define name

waflib.Tools.c_config.define_cond(self, key, val, comment='')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Conditionally defines a name:

def configure(conf):
        conf.define_cond('A', True)
        # equivalent to:
        # if val: conf.define('A', 1)
        # else: conf.undefine('A')
Parameters
  • key (string) – define name

  • val (int or string) – value

waflib.Tools.c_config.is_defined(self, key)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Indicates whether a particular define is globally set in conf.env.DEFINES.

Parameters

key (string) – define name

Returns

True if the define is set

Return type

bool

waflib.Tools.c_config.get_define(self, key)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Returns the value of an existing define, or None if not found

Parameters

key (string) – define name

Return type

string

waflib.Tools.c_config.have_define(self, key)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Returns a variable suitable for command-line or header use by removing invalid characters and prefixing it with HAVE_

Parameters

key (string) – define name

Returns

the input key prefixed by HAVE_ and substitute any invalid characters.

Return type

string

waflib.Tools.c_config.write_config_header(self, configfile='', guard='', top=False, defines=True, headers=False, remove=True, define_prefix='')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Writes a configuration header containing defines and includes:

def configure(cnf):
        cnf.define('A', 1)
        cnf.write_config_header('config.h')

This function only adds include guards (if necessary), consult waflib.Tools.c_config.get_config_header() for details on the body.

Parameters
  • configfile (string) – path to the file to create (relative or absolute)

  • guard (string) – include guard name to add, by default it is computed from the file name

  • top (bool) – write the configuration header from the build directory (default is from the current path)

  • defines (bool) – add the defines (yes by default)

  • headers (bool) – add #include in the file

  • remove (bool) – remove the defines after they are added (yes by default, works like in autoconf)

  • define_prefix (string) – prefix all the defines in the file with a particular prefix

waflib.Tools.c_config.get_config_header(self, defines=True, headers=False, define_prefix='')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Creates the contents of a config.h file from the defines and includes set in conf.env.define_key / conf.env.include_key. No include guards are added.

A prelude will be added from the variable env.WAF_CONFIG_H_PRELUDE if provided. This can be used to insert complex macros or include guards:

def configure(conf):
        conf.env.WAF_CONFIG_H_PRELUDE = '#include <unistd.h>\n'
        conf.write_config_header('config.h')
Parameters
  • defines (bool) – write the defines values

  • headers (bool) – write include entries for each element in self.env.INCKEYS

  • define_prefix (string) – prefix all the defines with a particular prefix

Returns

the contents of a config.h file

Return type

string

waflib.Tools.c_config.cc_add_flags(conf)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Adds CFLAGS / CPPFLAGS from os.environ to conf.env

waflib.Tools.c_config.cxx_add_flags(conf)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Adds CXXFLAGS / CPPFLAGS from os.environ to conf.env

Configuration Method bound to waflib.Configure.ConfigurationContext

Adds LINKFLAGS / LDFLAGS from os.environ to conf.env

waflib.Tools.c_config.cc_load_tools(conf)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Loads the Waf c extensions

waflib.Tools.c_config.cxx_load_tools(conf)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Loads the Waf c++ extensions

waflib.Tools.c_config.get_cc_version(conf, cc, gcc=False, icc=False, clang=False)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Runs the preprocessor to determine the gcc/icc/clang version

The variables CC_VERSION, DEST_OS, DEST_BINFMT and DEST_CPU will be set in conf.env

Raise

waflib.Errors.ConfigurationError

waflib.Tools.c_config.get_xlc_version(conf, cc)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Returns the Aix compiler version

Raise

waflib.Errors.ConfigurationError

waflib.Tools.c_config.get_suncc_version(conf, cc)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Returns the Sun compiler version

Raise

waflib.Errors.ConfigurationError

class waflib.Tools.c_config.cfgtask(*k, **kw)[source]

A task that executes build configuration tests (calls conf.check)

Make sure to use locks if concurrent access to the same conf.env data is necessary.

run_after

Set of tasks that must be executed before this one

display()[source]

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

Return type

string

runnable_status()[source]

Returns the Task status

Returns

a task state in waflib.Task.RUN_ME, waflib.Task.SKIP_ME, waflib.Task.CANCEL_ME or waflib.Task.ASK_LATER.

Return type

int

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

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:

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

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

hcode = b"\tdef run(self):\n\t\tconf = self.conf\n\t\tbld = Build.BuildContext(top_dir=conf.srcnode.abspath(), out_dir=conf.bldnode.abspath())\n\t\tbld.env = conf.env\n\t\tbld.init_dirs()\n\t\tbld.in_msg = 1 # suppress top-level start_msg\n\t\tbld.logger = self.logger\n\t\tbld.multicheck_task = self\n\t\targs = self.args\n\t\ttry:\n\t\t\tif 'func' in args:\n\t\t\t\tbld.test(build_fun=args['func'],\n\t\t\t\t\tmsg=args.get('msg', ''),\n\t\t\t\t\tokmsg=args.get('okmsg', ''),\n\t\t\t\t\terrmsg=args.get('errmsg', ''),\n\t\t\t\t\t)\n\t\t\telse:\n\t\t\t\targs['multicheck_mandatory'] = args.get('mandatory', True)\n\t\t\t\targs['mandatory'] = True\n\t\t\t\ttry:\n\t\t\t\t\tbld.check(**args)\n\t\t\t\tfinally:\n\t\t\t\t\targs['mandatory'] = args['multicheck_mandatory']\n\t\texcept Exception:\n\t\t\treturn 1\n"

String representing an additional hash for the class representation

waflib.Tools.c_config.multicheck(self, *k, **kw)[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Runs configuration tests in parallel; results are printed sequentially at the end of the build but each test must provide its own msg value to display a line:

def test_build(ctx):
        ctx.in_msg = True # suppress console outputs
        ctx.check_large_file(mandatory=False)

conf.multicheck(
        {'header_name':'stdio.h', 'msg':'... stdio', 'uselib_store':'STDIO', 'global_define':False},
        {'header_name':'xyztabcd.h', 'msg':'... optional xyztabcd.h', 'mandatory': False},
        {'header_name':'stdlib.h', 'msg':'... stdlib', 'okmsg': 'aye', 'errmsg': 'nope'},
        {'func': test_build, 'msg':'... testing an arbitrary build function', 'okmsg':'ok'},
        msg       = 'Checking for headers in parallel',
        mandatory = True, # mandatory tests raise an error at the end
        run_all_tests = True, # try running all tests
)

The configuration tests may modify the values in conf.env in any order, and the define values can affect configuration tests being executed. It is hence recommended to provide uselib_store values with global_define=False to prevent such issues.

waflib.Tools.c_config.check_gcc_o_space(self, mode='c')[source]

Configuration Method bound to waflib.Configure.ConfigurationContext

Features defined in this module: