| 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. |