short-description: Source set module authors: - name: Paolo Bonzini email: pbonzini@redhat.com years: [2019] ...
This module provides support for building many targets against a single set of files; the choice of which files to include in each target depends on the contents of a dictionary or a configuration_data
object. The module can be loaded with:
ssmod = import('sourceset')
A simple example of using the module looks like this:
ss = ssmod.source_set() # Include main.c unconditionally ss.add(files('main.c')) # Include a.c if configuration key FEATURE1 is true ss.add(when: 'FEATURE1', if_true: files('a.c')) # Include zlib.c if the zlib dependency was found, and link zlib # in the executable ss.add(when: zlib, if_true: files('zlib.c')) # many more rules here... ssconfig = ss.apply(config) executable('exe', sources: ssconfig.sources(), dependencies: ssconfig.dependencies())
and it would be equivalent to
sources = files('main.c') dependencies = [] if config['FEATURE1'] then sources += [files('a.c')] endif if zlib.found() then sources += [files('zlib.c')] dependencies += [zlib] endif # many more "if"s here... executable('exe', sources: sources, dependencies: dependencies)
Sourcesets can be used with a single invocation of the apply
method, similar to the example above, but the module is especially useful when multiple executables are generated by applying the same rules to many different configurations.
Added 0.51.0
source_set()
ssmod.source_set()
Create and return a new source set object.
Returns: a [source set][source_set
object]
source_set
objectThe source_set
object provides methods to add files to a source set and to query it. The source set becomes immutable after any method but add
is called.
add()
source_set.add([when: varnames_and_deps], [if_true: sources_and_deps], [if_false: list_of_alt_sources]) source_set.add(sources_and_deps)
Add a rule to a source set. A rule determines the conditions under which some source files or dependency objects are included in a build configuration. All source files must be present in the source tree or they can be created in the build tree via configure_file
, custom_target
or generator
.
varnames_and_deps
is a list of conditions for the rule, which can be either strings or dependency objects (a dependency object is anything that has a found()
method). If all the strings evaluate to true and all dependencies are found, the rule will evaluate to true; apply()
will then include the contents of the if_true
keyword argument in its result. Otherwise, that is if any of the strings in the positional arguments evaluate to false or any dependency is not found, apply()
will instead use the contents of the if_false
keyword argument.
Dependencies can also appear in sources_and_deps
. In this case, a missing dependency will simply be ignored and will not disable the rule, similar to how the dependencies
keyword argument works in build targets.
Note: It is generally better to avoid mixing source sets and disablers. This is because disablers will cause the rule to be dropped altogether, and the list_of_alt_sources
would not be taken into account anymore.
add_all()
source_set.add_all(when: varnames_and_deps, if_true: [source_set1, source_set2, ...]) source_set.add_all(source_set1, source_set2, ...)
Add one or more source sets to another.
For each source set listed in the arguments, apply()
will consider their rules only if the conditions in varnames_and_deps
are evaluated positively. For example, the following:
sources_b = ssmod.source_set() sources_b.add(when: 'HAVE_A', if_true: 'file.c') sources = ssmod.source_set() sources.add_all(when: 'HAVE_B', if_true: sources_b)
is equivalent to:
sources = ssmod.source_set() sources.add(when: ['HAVE_A', 'HAVE_B'], if_true: 'file.c')
all_sources()
list source_set.all_sources(...)
Returns a list of all sources that were placed in the source set using add
(including nested source sets) and that do not have a not-found dependency. If a rule has a not-found dependency, only the if_false
sources are included (if any).
Returns: a list of file objects
all_dependencies()
(since 0.52.0)list source_set.all_dependencies(...)
Returns a list of all dependencies that were placed in the source set using add
(including nested source sets) and that were found.
Returns: a list of dependencies
apply()
source_files source_set.apply(conf_data[, strict: false])
Match the source set against a dictionary or a configuration_data
object and return a source configuration object. A source configuration object allows you to retrieve the sources and dependencies for a specific configuration.
By default, all the variables that were specified in the rules have to be present in conf_data
. However, in some cases the convention is that false
configuration symbols are absent in conf_data
; this is the case for example when the configuration was loaded from a Kconfig file. In that case you can specify the strict: false
keyword argument, which will treat absent variables as false.
Returns: a [source configuration][source_configuration
object]
source_configuration
objectThe source_configuration
object provides methods to query the result of an apply
operation on a source set.
sources()
source_config.sources()
Return the source files corresponding to the applied configuration.
Returns: a list of file objects
dependencies()
source_config.dependencies()
Return the dependencies corresponding to the applied configuration.
Returns: a list of dependency objects