Debian Codegraph @

subprojects/meson-docs/docs/markdown/SourceSet-module.md

raw
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