Debian Codegraph @

subprojects/meson-docs/docs/markdown/Subprojects.md

raw
1 ---
2 short-description: Using Meson projects as subprojects within other Meson projects
3 ...
4
5 # Subprojects
6
7 Some platforms do not provide a native packaging system. In these
8 cases it is common to bundle all third party libraries in your source
9 tree. This is usually frowned upon because it makes it hard to add
10 these kinds of projects into e.g. those Linux distributions that
11 forbid bundled libraries.
12
13 Meson tries to solve this problem by making it extremely easy to
14 provide both at the same time. The way this is done is that Meson
15 allows you to take any other Meson project and make it a part of your
16 build without (in the best case) any changes to its Meson setup. It
17 becomes a transparent part of the project.
18
19 It should be noted that this is only guaranteed to work for subprojects
20 that are built with Meson. The reason is the simple fact that there is
21 no possible way to do this reliably with mixed build systems. Because of
22 this, only Meson subprojects are described here.
23 [CMake based subprojects](CMake-module.md#cmake-subprojects) are also
24 supported but not guaranteed to work.
25
26 ## A subproject example
27
28 Usually dependencies consist of some header files plus a library to
29 link against. To declare this internal dependency use
30 `declare_dependency` function.
31
32 As an example, suppose we have a simple project that provides a shared
33 library. Its `meson.build` would look like this.
34
35 ```meson
36 project('libsimple', 'c')
37
38 inc = include_directories('include')
39 libsimple = shared_library('simple',
40 'simple.c',
41 include_directories : inc,
42 install : true)
43
44 libsimple_dep = declare_dependency(include_directories : inc,
45 link_with : libsimple)
46 ```
47
48 ### Naming convention for dependency variables
49
50 Ideally the dependency variable name should be of `<project_name>_dep`
51 form. This way one can just use it without even looking inside build
52 definitions of that subproject.
53
54 In cases where there are multiple dependencies need to be declared,
55 the default one should be named as `<project_name>_dep` (e.g.
56 `gtest_dep`), and others can have `<project_name>_<other>_<name>_dep`
57 form (e.g. `gtest_main_dep` - gtest with main function).
58
59 There may be exceptions to these rules where common sense should be applied.
60
61 ### Adding variables to the dependency
62
63 *New in 0.54.0*
64
65 In some cases a project may define special variables via pkg-config or
66 cmake that a caller needs to know about. Meson provides a
67 `dependency.get_variable` method to hide what kind of dependency is
68 provided, and this is available to subprojects as well. Use the
69 `variables` keyword to add a dict of strings:
70
71 ```meson
72 my_dep = declare_dependency(..., variables : {'var': 'value', 'number': '3'})
73 ```
74
75 Which another project can access via:
76
77 ```meson
78 var = my_dep.get_variable(internal : 'var', cmake : 'CMAKE_VAR')
79 ```
80
81 The values of the dict must be strings, as pkg-config and cmake will
82 return variables as strings.
83
84 ### Build options in subproject
85
86 All Meson features of the subproject, such as project options keep
87 working and [can be set in the master
88 project](Builtin-options.md#specifying-options-per-subproject). There
89 are a few limitations, the most important being that global compiler
90 arguments must be set in the main project before calling subproject.
91 Subprojects must not set global arguments because there is no way to
92 do that reliably over multiple subprojects. To check whether you are
93 running as a subproject, use [[meson.is_subproject]].
94
95 ## Using a subproject
96
97 All subprojects must be inside `subprojects` directory. The
98 `subprojects` directory must be at the top level of your project.
99 Subproject declaration must be in your top level `meson.build`.
100
101 ### A simple example
102
103 Let's use `libsimple` as a subproject.
104
105 At the top level of your project create `subprojects` directory.
106 Then copy `libsimple` into `subprojects` directory.
107
108 Your project's `meson.build` should look like this.
109
110 ```meson
111 project('my_project', 'cpp')
112
113 libsimple_proj = subproject('libsimple')
114 libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
115
116 executable('my_project',
117 'my_project.cpp',
118 dependencies : libsimple_dep,
119 install : true)
120 ```
121
122 Note that the subproject object is *not* used as the dependency, but
123 rather you need to get the declared dependency from it with
124 `get_variable` because a subproject may have multiple declared
125 dependencies.
126
127 ### Toggling between system libraries and embedded sources
128
129 When building distro packages it is very important that you do not
130 embed any sources. Some distros have a rule forbidding embedded
131 dependencies so your project must be buildable without them or
132 otherwise the packager will hate you.
133
134 Here's how you would use system libraries and fall back to embedding sources
135 if the dependency is not available.
136
137 ```meson
138 project('my_project', 'cpp')
139
140 libsimple_dep = dependency('libsimple', required : false)
141
142 if not libsimple_dep.found()
143 libsimple_proj = subproject('libsimple')
144 libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
145 endif
146
147 executable('my_project',
148 'my_project.cpp',
149 dependencies : libsimple_dep,
150 install : true)
151 ```
152
153 Because this is such a common operation, Meson provides a shortcut for
154 this use case.
155
156 ```meson
157 dep = dependency('foo', fallback : ['subproject_name', 'variable_name'])
158 ```
159
160 The `fallback` keyword argument takes two items, the name of the
161 subproject and the name of the variable that holds the dependency. If
162 you need to do something more complicated, such as extract several
163 different variables, then you need to do it yourself with the manual
164 method described above.
165
166 Using this shortcut the build definition would look like this.
167
168 ```meson
169 project('my_project', 'cpp')
170
171 libsimple_dep = dependency('libsimple', fallback : ['libsimple', 'libsimple_dep'])
172
173 executable('my_project',
174 'my_project.cpp',
175 dependencies : libsimple_dep,
176 install : true)
177 ```
178
179 You may change default [options of the
180 subproject](Builtin-options.md#specifying-options-per-subproject) by
181 adding a keyword argument to the invocation. For example, to change the
182 default library type:
183
184 ```
185 libsimple_dep = dependency(
186 'libsimple',
187 fallback : ['libsimple', 'libsimple_dep'],
188 default_options: ['default_library=static']
189 )
190 ```
191
192 With this setup, when libsimple is provided by the system we use it and
193 completely ignore subproject options (i.e. we link to a shared system
194 library). When that is not the case, we use the embedded version (the
195 one from subprojects).
196
197 Note that `libsimple_dep` can point to an external or an internal
198 dependency but you don't have to worry about their differences. Meson
199 will take care of the details for you.
200
201 ### Subprojects depending on other subprojects
202
203 Subprojects can use other subprojects, but all subprojects must reside
204 in the top level `subprojects` directory. Recursive use of subprojects
205 is not allowed, though, so you can't have subproject `a` that uses
206 subproject `b` and have `b` also use `a`.
207
208 ## Obtaining subprojects
209
210 Meson ships with a dependency system to automatically obtain
211 dependency subprojects. It is documented in the [Wrap dependency
212 system manual](Wrap-dependency-system-manual.md).
213
214 ## Command-line options
215
216 The usage of subprojects can be controlled by users and distros with
217 the following command-line options:
218
219 * **--wrap-mode=nodownload**
220
221 Meson will not use the network to download any subprojects or
222 fetch any wrap information. Only preexisting sources will be used.
223 This is useful (mostly for distros) when you want to only use the
224 sources provided by a software release, and want to manually handle
225 or provide missing dependencies.
226
227 * **--wrap-mode=nofallback**
228
229 Meson will not use subproject fallbacks for any dependency
230 declarations in the build files, and will only look for them in the
231 system. Note that this does not apply to unconditional subproject()
232 calls, and those are meant to be used for sources that cannot be
233 provided by the system, such as copylibs.
234
235 This option may be overridden by `--force-fallback-for` for specific
236 dependencies.
237
238 * **--wrap-mode=forcefallback**
239
240 Meson will not look at the system for any dependencies which have
241 subproject fallbacks available, and will *only* use subprojects for
242 them. This is useful when you want to test your fallback setup, or
243 want to specifically build against the library sources provided by
244 your subprojects.
245
246 * **--force-fallback-for=list,of,dependencies**
247
248 Meson will not look at the system for any dependencies listed there,
249 provided a fallback was supplied when the dependency was declared.
250
251 This option takes precedence over `--wrap-mode=nofallback`, and when
252 used in combination with `--wrap-mode=nodownload` will only work
253 if the dependency has already been downloaded.
254
255 This is useful when your project has many fallback dependencies,
256 but you only want to build against the library sources for a few
257 of them.
258
259 **Warning**: This could lead to mixing system and subproject version of the
260 same library in the same process. Take this case as example:
261 - Libraries `glib-2.0` and `gstreamer-1.0` are installed on your system.
262 - `gstreamer-1.0` depends on `glib-2.0`, pkg-config file `gstreamer-1.0.pc`
263 has `Requires: glib-2.0`.
264 - In your application build definition you do:
265 ```meson
266 executable('app', ...,
267 dependencies: [
268 dependency('glib-2.0', fallback: 'glib'),
269 dependency('gstreamer-1.0', fallback: 'gstreamer')],
270 )
271 ```
272 - You configure with `--force-fallback-for=glib`.
273 This result in linking to two different versions of library `glib-2.0`
274 because `dependency('glib-2.0', fallback: 'glib')` will return the
275 subproject dependency, but `dependency('gstreamer-1.0', fallback: 'gstreamer')`
276 will not fallback and return the system dependency, including `glib-2.0`
277 library. To avoid that situation, every dependency that itself depend on
278 `glib-2.0` must also be forced to fallback, in this case with
279 `--force-fallback-for=glib,gsteamer`.
280
281 * **--wrap-mode=nopromote**
282
283 *Since 0.56.0* Meson will automatically use wrap files found in subprojects
284 and copy them into the main project. That new behavior can be disabled by
285 passing `--wrap-mode=nopromote`. In that case only wraps found in the main
286 project will be used.
287
288 ## `meson subprojects` command
289
290 *Since 0.49.0*
291
292 `meson subprojects` has various subcommands to manage all subprojects.
293 If the subcommand fails on any subproject the execution continues with
294 other subprojects. All subcommands accept `--sourcedir` argument
295 pointing to the root source dir of the main project.
296
297 *Since 0.56.0* all subcommands accept `--types <file|git|hg|svn>`
298 argument to run the subcommands only on subprojects of the given
299 types. Multiple types can be set as comma separated list e.g. `--types
300 git,file`.
301
302 *Since 0.56.0* If the subcommand fails on any subproject an error code
303 is returned at the end instead of returning success.
304
305 ### Download subprojects
306
307 *Since 0.49.0*
308
309 Meson will automatically download needed subprojects during configure,
310 unless **--wrap-mode=nodownload** option is passed. It is sometimes
311 preferable to download all subprojects in advance, so the Meson
312 configure can be performed offline. The command-line `meson
313 subprojects download` can be used for that, it will download all
314 missing subprojects, but will not update already fetched subprojects.
315
316 ### Update subprojects
317
318 *Since 0.49.0*
319
320 Once a subproject has been fetched, Meson will not update it automatically.
321 For example if the wrap file tracks a git branch, it won't pull latest commits.
322
323 To pull latest version of all your subprojects at once, just run the command:
324 `meson subprojects update`.
325 - If the wrap file comes from wrapdb, the latest version of the wrap file will
326 be pulled and used next time meson reconfigure the project. This can be
327 triggered using `meson --reconfigure`. Previous source tree is not deleted, to
328 prevent from any loss of local changes. *Since 0.58.0* If `--reset` is
329 specified, the source tree is deleted and new source is extracted.
330 - If subproject is currently in detached mode, a checkout of the revision from
331 wrap file is performed. *Since 0.56.0* a rebase is also performed in case the
332 revision already existed locally but was outdated. If `--reset` is specified,
333 a hard reset is performed instead of rebase.
334 - If subproject is currently at the same branch as specified by the wrap file,
335 a rebase on `origin` commit is performed. *Since 0.56.0* If `--reset` is
336 specified, a hard reset is performed instead of rebase.
337 - If subproject is currently in a different branch as specified by the wrap file,
338 it is skipped unless `--rebase` option is passed in which case a rebase on
339 `origin` commit is performed. *Since 0.56.0* the `--rebase` argument is
340 deprecated and has no effect. Instead, a checkout of the revision from wrap file
341 file is performed and a rebase is also performed in case the revision already
342 existed locally by was outdated. If `--reset` is specified, a hard reset is
343 performed instead of rebase.
344 - *Since 0.56.0* if the `url` specified in wrap file is different to the URL set
345 on `origin` for a git repository it will not be updated, unless `--reset` is
346 specified in which case the URL of `origin` will be reset first.
347 - *Since 0.56.0* If the subproject directory is not a git repository but has a
348 `[wrap-git]` the subproject is ignored, unless `--reset` is specified in which
349 case the directory is deleted and the new repository is cloned.
350
351 ### Start a topic branch across all git subprojects
352
353 *Since 0.49.0*
354
355 The command-line `meson subprojects checkout <branch_name>` will
356 checkout a branch, or create one with `-b` argument, in every git
357 subprojects. This is useful when starting local changes across
358 multiple subprojects. It is still your responsibility to commit and
359 push in each repository where you made local changes.
360
361 To come back to the revision set in wrap file (i.e. master), just run
362 `meson subprojects checkout` with no branch name.
363
364 *Since 0.56.0* any pending changes are now stashed before checkout a new branch.
365
366 ### Execute a command on all subprojects
367
368 *Since 0.51.0*
369
370 The command-line `meson subprojects foreach <command> [...]` will
371 execute a command in each subproject directory. For example this can
372 be useful to check the status of subprojects (e.g. with `git status`
373 or `git diff`) before performing other actions on them.
374
375 ## Why must all subprojects be inside a single directory?
376
377 There are several reasons.
378
379 First of all, to maintain any sort of sanity, the system must prevent going
380 inside other subprojects with `subdir()` or variations thereof. Having the
381 subprojects in well defined places makes this easy. If subprojects could be
382 anywhere at all, it would be a lot harder.
383
384 Second of all it is extremely important that end users can easily see what
385 subprojects any project has. Because they are in one, and only one, place,
386 reviewing them becomes easy.
387
388 This is also a question of convention. Since all Meson projects have the same
389 layout w.r.t subprojects, switching between projects becomes easier. You don't
390 have to spend time on a new project traipsing through the source tree looking
391 for subprojects. They are always in the same place.
392
393 Finally if you can have subprojects anywhere, this increases the possibility of
394 having many different (possibly incompatible) versions of a dependency in your
395 source tree. Then changing some code (such as changing the order you traverse
396 directories) may cause a completely different version of the subproject to be
397 used by accident.