diff options
Diffstat (limited to 'docs/markdown/SourceSet-module.md')
| -rw-r--r-- | docs/markdown/SourceSet-module.md | 85 |
1 files changed, 45 insertions, 40 deletions
diff --git a/docs/markdown/SourceSet-module.md b/docs/markdown/SourceSet-module.md index 4b34ff7..af31570 100644 --- a/docs/markdown/SourceSet-module.md +++ b/docs/markdown/SourceSet-module.md @@ -8,10 +8,10 @@ authors: # Source set module -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: +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: ``` meson ssmod = import('sourceset') @@ -51,9 +51,9 @@ 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. +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* @@ -71,9 +71,9 @@ Create and return a new source set object. ## `source_set` object -The `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. +The `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. ### Methods @@ -86,27 +86,31 @@ source_set.add([when: varnames_and_deps], 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`. +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. +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()` @@ -118,9 +122,9 @@ 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: +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: ``` meson sources_b = ssmod.source_set() @@ -144,7 +148,7 @@ 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` +dependency. If a rule has a not-found dependency, only the `if_false` sources are included (if any). **Returns**: a list of file objects @@ -166,16 +170,17 @@ using `add` (including nested source sets) and that were found. 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. +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 +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. +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] |