| 1 |
--- |
| 2 |
short-description: Source set module |
| 3 |
authors: |
| 4 |
- name: Paolo Bonzini |
| 5 |
email: [email protected] |
| 6 |
years: [2019] |
| 7 |
... |
| 8 |
|
| 9 |
# Source set module |
| 10 |
|
| 11 |
This module provides support for building many targets against a |
| 12 |
single set of files; the choice of which files to include in each |
| 13 |
target depends on the contents of a dictionary or a |
| 14 |
`configuration_data` object. The module can be loaded with: |
| 15 |
|
| 16 |
```meson |
| 17 |
ssmod = import('sourceset') |
| 18 |
``` |
| 19 |
|
| 20 |
A simple example of using the module looks like this: |
| 21 |
|
| 22 |
```meson |
| 23 |
ss = ssmod.source_set() |
| 24 |
# Include main.c unconditionally |
| 25 |
ss.add(files('main.c')) |
| 26 |
# Include a.c if configuration key FEATURE1 is true |
| 27 |
ss.add(when: 'FEATURE1', if_true: files('a.c')) |
| 28 |
# Include zlib.c if the zlib dependency was found, and link zlib |
| 29 |
# in the executable |
| 30 |
ss.add(when: zlib, if_true: files('zlib.c')) |
| 31 |
# many more rules here... |
| 32 |
ssconfig = ss.apply(config) |
| 33 |
executable('exe', sources: ssconfig.sources(), |
| 34 |
dependencies: ssconfig.dependencies()) |
| 35 |
``` |
| 36 |
|
| 37 |
and it would be equivalent to |
| 38 |
|
| 39 |
```meson |
| 40 |
sources = files('main.c') |
| 41 |
dependencies = [] |
| 42 |
if config['FEATURE1'] then |
| 43 |
sources += [files('a.c')] |
| 44 |
endif |
| 45 |
if zlib.found() then |
| 46 |
sources += [files('zlib.c')] |
| 47 |
dependencies += [zlib] |
| 48 |
endif |
| 49 |
# many more "if"s here... |
| 50 |
executable('exe', sources: sources, dependencies: dependencies) |
| 51 |
``` |
| 52 |
|
| 53 |
Sourcesets can be used with a single invocation of the `apply` method, |
| 54 |
similar to the example above, but the module is especially useful when |
| 55 |
multiple executables are generated by applying the same rules to many |
| 56 |
different configurations. |
| 57 |
|
| 58 |
*Added 0.51.0* |
| 59 |
|
| 60 |
## Functions |
| 61 |
|
| 62 |
### `source_set()` |
| 63 |
|
| 64 |
```meson |
| 65 |
ssmod.source_set() |
| 66 |
``` |
| 67 |
|
| 68 |
Create and return a new source set object. |
| 69 |
|
| 70 |
**Returns**: a [source set][`source_set` object] |
| 71 |
|
| 72 |
## `source_set` object |
| 73 |
|
| 74 |
The `source_set` object provides methods to add files to a source set |
| 75 |
and to query it. The source set becomes immutable after any method but |
| 76 |
`add` is called. |
| 77 |
|
| 78 |
### Methods |
| 79 |
|
| 80 |
#### `add()` |
| 81 |
|
| 82 |
```meson |
| 83 |
source_set.add([when: varnames_and_deps], |
| 84 |
[if_true: sources_and_deps], |
| 85 |
[if_false: list_of_alt_sources]) |
| 86 |
source_set.add(sources_and_deps) |
| 87 |
``` |
| 88 |
|
| 89 |
Add a *rule* to a source set. A rule determines the conditions under |
| 90 |
which some source files or dependency objects are included in a build |
| 91 |
configuration. All source files must be present in the source tree or |
| 92 |
they can be created in the build tree via `configure_file`, |
| 93 |
`custom_target` or `generator`. |
| 94 |
|
| 95 |
`varnames_and_deps` is a list of conditions for the rule, which can be |
| 96 |
either strings or dependency objects (a dependency object is anything |
| 97 |
that has a `found()` method). If *all* the strings evaluate to true |
| 98 |
and all dependencies are found, the rule will evaluate to true; |
| 99 |
`apply()` will then include the contents of the `if_true` keyword |
| 100 |
argument in its result. Otherwise, that is if any of the strings in |
| 101 |
the positional arguments evaluate to false or any dependency is not |
| 102 |
found, `apply()` will instead use the contents of the `if_false` |
| 103 |
keyword argument. |
| 104 |
|
| 105 |
Dependencies can also appear in `sources_and_deps`. In this case, a |
| 106 |
missing dependency will simply be ignored and will *not* disable the |
| 107 |
rule, similar to how the `dependencies` keyword argument works in |
| 108 |
build targets. |
| 109 |
|
| 110 |
**Note**: It is generally better to avoid mixing source sets and |
| 111 |
disablers. This is because disablers will cause the rule to be dropped |
| 112 |
altogether, and the `list_of_alt_sources` would not be taken into |
| 113 |
account anymore. |
| 114 |
|
| 115 |
#### `add_all()` |
| 116 |
|
| 117 |
```meson |
| 118 |
source_set.add_all(when: varnames_and_deps, |
| 119 |
if_true: [source_set1, source_set2, ...]) |
| 120 |
source_set.add_all(source_set1, source_set2, ...) |
| 121 |
``` |
| 122 |
|
| 123 |
Add one or more source sets to another. |
| 124 |
|
| 125 |
For each source set listed in the arguments, `apply()` will consider |
| 126 |
their rules only if the conditions in `varnames_and_deps` are |
| 127 |
evaluated positively. For example, the following: |
| 128 |
|
| 129 |
```meson |
| 130 |
sources_b = ssmod.source_set() |
| 131 |
sources_b.add(when: 'HAVE_A', if_true: 'file.c') |
| 132 |
sources = ssmod.source_set() |
| 133 |
sources.add_all(when: 'HAVE_B', if_true: sources_b) |
| 134 |
``` |
| 135 |
|
| 136 |
is equivalent to: |
| 137 |
|
| 138 |
```meson |
| 139 |
sources = ssmod.source_set() |
| 140 |
sources.add(when: ['HAVE_A', 'HAVE_B'], if_true: 'file.c') |
| 141 |
``` |
| 142 |
|
| 143 |
#### `all_sources()` |
| 144 |
|
| 145 |
```meson |
| 146 |
list source_set.all_sources(...) |
| 147 |
``` |
| 148 |
|
| 149 |
Returns a list of all sources that were placed in the source set using |
| 150 |
`add` (including nested source sets) and that do not have a not-found |
| 151 |
dependency. If a rule has a not-found dependency, only the `if_false` |
| 152 |
sources are included (if any). |
| 153 |
|
| 154 |
**Returns**: a list of file objects |
| 155 |
|
| 156 |
#### `all_dependencies()` *(since 0.52.0)* |
| 157 |
|
| 158 |
```meson |
| 159 |
list source_set.all_dependencies(...) |
| 160 |
``` |
| 161 |
|
| 162 |
Returns a list of all dependencies that were placed in the source set |
| 163 |
using `add` (including nested source sets) and that were found. |
| 164 |
|
| 165 |
**Returns**: a list of dependencies |
| 166 |
|
| 167 |
#### `apply()` |
| 168 |
|
| 169 |
```meson |
| 170 |
source_files source_set.apply(conf_data[, strict: false]) |
| 171 |
``` |
| 172 |
|
| 173 |
Match the source set against a dictionary or a `configuration_data` |
| 174 |
object and return a *source configuration* object. A source |
| 175 |
configuration object allows you to retrieve the sources and |
| 176 |
dependencies for a specific configuration. |
| 177 |
|
| 178 |
By default, all the variables that were specified in the rules have to |
| 179 |
be present in `conf_data`. However, in some cases the convention is |
| 180 |
that `false` configuration symbols are absent in `conf_data`; this is |
| 181 |
the case for example when the configuration was loaded from a Kconfig |
| 182 |
file. In that case you can specify the `strict: false` keyword |
| 183 |
argument, which will treat absent variables as false. |
| 184 |
|
| 185 |
**Returns**: a [source configuration][`source_configuration` object] |
| 186 |
|
| 187 |
## `source_configuration` object |
| 188 |
|
| 189 |
The `source_configuration` object provides methods to query the result of an |
| 190 |
`apply` operation on a source set. |
| 191 |
|
| 192 |
### Methods |
| 193 |
|
| 194 |
#### `sources()` |
| 195 |
|
| 196 |
```meson |
| 197 |
source_config.sources() |
| 198 |
``` |
| 199 |
|
| 200 |
Return the source files corresponding to the applied configuration. |
| 201 |
|
| 202 |
**Returns**: a list of file objects |
| 203 |
|
| 204 |
#### `dependencies()` |
| 205 |
|
| 206 |
```meson |
| 207 |
source_config.dependencies() |
| 208 |
``` |
| 209 |
|
| 210 |
Return the dependencies corresponding to the applied configuration. |
| 211 |
|
| 212 |
**Returns**: a list of dependency objects |