| 1 |
# Wrap dependency system manual |
| 2 |
|
| 3 |
One of the major problems of multiplatform development is wrangling |
| 4 |
all your dependencies. This is awkward on many platforms, especially |
| 5 |
on ones that do not have a built-in package manager. The latter problem |
| 6 |
has been worked around by having third party package managers. They |
| 7 |
are not really a solution for end user deployment, because you can't |
| 8 |
tell them to install a package manager just to use your app. On these |
| 9 |
platforms you must produce self-contained applications. Same applies |
| 10 |
when destination platform is missing (up-to-date versions of) your |
| 11 |
application's dependencies. |
| 12 |
|
| 13 |
The traditional approach to this has been to bundle dependencies |
| 14 |
inside your own project. Either as prebuilt libraries and headers or |
| 15 |
by embedding the source code inside your source tree and rewriting |
| 16 |
your build system to build them as part of your project. |
| 17 |
|
| 18 |
This is both tedious and error prone because it is always done by |
| 19 |
hand. The Wrap dependency system of Meson aims to provide an automated |
| 20 |
way to do this. |
| 21 |
|
| 22 |
## How it works |
| 23 |
|
| 24 |
Meson has a concept of [subprojects](Subprojects.md). They are a way |
| 25 |
of nesting one Meson project inside another. Any project that builds |
| 26 |
with Meson can detect that it is built as a subproject and build |
| 27 |
itself in a way that makes it easy to use (usually this means as a |
| 28 |
static library). |
| 29 |
|
| 30 |
To use this kind of a project as a dependency you could just copy and |
| 31 |
extract it inside your project's `subprojects` directory. |
| 32 |
|
| 33 |
However there is a simpler way. You can specify a Wrap file that tells |
| 34 |
Meson how to download it for you. If you then use this subproject in |
| 35 |
your build, Meson will automatically download and extract it during |
| 36 |
build. This makes subproject embedding extremely easy. |
| 37 |
|
| 38 |
All wrap files must have a name of `<project_name>.wrap` form and be |
| 39 |
in `subprojects` dir. |
| 40 |
|
| 41 |
Currently Meson has four kinds of wraps: |
| 42 |
- wrap-file |
| 43 |
- wrap-git |
| 44 |
- wrap-hg |
| 45 |
- wrap-svn |
| 46 |
|
| 47 |
## wrap format |
| 48 |
|
| 49 |
Wrap files are written in ini format, with a single header containing |
| 50 |
the type of wrap, followed by properties describing how to obtain the |
| 51 |
sources, validate them, and modify them if needed. An example |
| 52 |
wrap-file for the wrap named `libfoobar` would have a filename |
| 53 |
`libfoobar.wrap` and would look like this: |
| 54 |
|
| 55 |
```ini |
| 56 |
[wrap-file] |
| 57 |
directory = libfoobar-1.0 |
| 58 |
|
| 59 |
source_url = https://example.com/foobar-1.0.tar.gz |
| 60 |
source_filename = foobar-1.0.tar.gz |
| 61 |
source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663 |
| 62 |
``` |
| 63 |
|
| 64 |
An example wrap-git will look like this: |
| 65 |
|
| 66 |
```ini |
| 67 |
[wrap-git] |
| 68 |
url = https://github.com/libfoobar/libfoobar.git |
| 69 |
revision = HEAD |
| 70 |
depth = 1 |
| 71 |
``` |
| 72 |
|
| 73 |
## Accepted configuration properties for wraps |
| 74 |
|
| 75 |
- `directory` - name of the subproject root directory, defaults to the |
| 76 |
name of the wrap. |
| 77 |
|
| 78 |
Since *0.55.0* those can be used in all wrap types, they were |
| 79 |
previously reserved to `wrap-file`: |
| 80 |
|
| 81 |
- `patch_url` - download url to retrieve an optional overlay archive |
| 82 |
- `patch_fallback_url` - fallback URL to be used when download from `patch_url` fails *Since: 0.55.0* |
| 83 |
- `patch_filename` - filename of the downloaded overlay archive |
| 84 |
- `patch_hash` - sha256 checksum of the downloaded overlay archive |
| 85 |
- `patch_directory` - *Since 0.55.0* Overlay directory, alternative to `patch_filename` in the case |
| 86 |
files are local instead of a downloaded archive. The directory must be placed in |
| 87 |
`subprojects/packagefiles`. |
| 88 |
- `diff_files` - *Since 0.63.0* Comma-separated list of local diff files (see |
| 89 |
[Diff files](#diff-files) below). |
| 90 |
- `method` - *Since 1.3.0* The build system used by this subproject. Defaults to `meson`. |
| 91 |
Supported methods: |
| 92 |
- `meson` requires `meson.build` file. |
| 93 |
- `cmake` requires `CMakeLists.txt` file. [See details](#cmake-wraps). |
| 94 |
- `cargo` requires `Cargo.toml` file. [See details](#cargo-wraps). |
| 95 |
|
| 96 |
### Specific to wrap-file |
| 97 |
- `source_url` - download url to retrieve the wrap-file source archive |
| 98 |
- `source_fallback_url` - fallback URL to be used when download from `source_url` fails *Since: 0.55.0* |
| 99 |
- `source_filename` - filename of the downloaded source archive |
| 100 |
- `source_hash` - sha256 checksum of the downloaded source archive |
| 101 |
- `lead_directory_missing` - for `wrap-file` create the leading |
| 102 |
directory name. Needed when the source file does not have a leading |
| 103 |
directory. |
| 104 |
|
| 105 |
Since *0.55.0* it is possible to use only the `source_filename` and |
| 106 |
`patch_filename` value in a .wrap file (without `source_url` and |
| 107 |
`patch_url`) to specify a local archive in the |
| 108 |
`subprojects/packagefiles` directory. The `*_hash` entries are |
| 109 |
optional when using this method. This method should be preferred over |
| 110 |
the old `packagecache` approach described below. |
| 111 |
|
| 112 |
Since *0.49.0* if `source_filename` or `patch_filename` is found in the |
| 113 |
project's `subprojects/packagecache` directory, it will be used instead |
| 114 |
of downloading the file, even if `--wrap-mode` option is set to |
| 115 |
`nodownload`. The file's hash will be checked. |
| 116 |
|
| 117 |
Since *1.3.0* if the `MESON_PACKAGE_CACHE_DIR` environment variable is set, it is used instead of |
| 118 |
the project's `subprojects/packagecache`. This allows sharing the cache across multiple |
| 119 |
projects. In addition it can contain an already extracted source tree as long as it |
| 120 |
has the same directory name as the `directory` field in the wrap file. In that |
| 121 |
case, the directory will be copied into `subprojects/` before applying patches. |
| 122 |
|
| 123 |
### Specific to VCS-based wraps |
| 124 |
- `url` - name of the wrap-git repository to clone. Required. |
| 125 |
- `revision` - name of the revision to checkout. Must be either: a |
| 126 |
valid value (such as a git tag) for the VCS's `checkout` command, or |
| 127 |
(for git) `HEAD` to track upstream's default branch. Required. |
| 128 |
|
| 129 |
### Specific to wrap-git |
| 130 |
- `depth` - shallowly clone the repository to X number of commits. This saves bandwidth and disk |
| 131 |
space, and should typically always be specified unless commit history is needed. Note |
| 132 |
that git always allow shallowly cloning branches, but in order to |
| 133 |
clone commit ids shallowly, the server must support |
| 134 |
`uploadpack.allowReachableSHA1InWant=true`. *(since 0.52.0)* |
| 135 |
- `push-url` - alternative url to configure as a git push-url. Useful if |
| 136 |
the subproject will be developed and changes pushed upstream. |
| 137 |
*(since 0.37.0)* |
| 138 |
- `clone-recursive` - also clone submodules of the repository |
| 139 |
*(since 0.48.0)* |
| 140 |
|
| 141 |
## wrap-file with Meson build patch |
| 142 |
|
| 143 |
Unfortunately most software projects in the world do not build with |
| 144 |
Meson. Because of this Meson allows you to specify a patch URL. |
| 145 |
|
| 146 |
For historic reasons this is called a "patch", however, it serves as an |
| 147 |
overlay to add or replace files rather than modifying them. The file |
| 148 |
must be an archive; it is downloaded and automatically extracted into |
| 149 |
the subproject. The extracted files will include a Meson build |
| 150 |
definition for the given subproject. |
| 151 |
|
| 152 |
This approach makes it extremely simple to embed dependencies that |
| 153 |
require build system changes. You can write the Meson build definition |
| 154 |
for the dependency in total isolation. This is a lot better than doing |
| 155 |
it inside your own source tree, especially if it contains hundreds of |
| 156 |
thousands of lines of code. Once you have a working build definition, |
| 157 |
just zip up the Meson build files (and others you have changed) and |
| 158 |
put them somewhere where you can download them. |
| 159 |
|
| 160 |
Prior to *0.55.0* Meson build patches were only supported for |
| 161 |
wrap-file mode. When using wrap-git, the repository must contain all |
| 162 |
Meson build definitions. Since *0.55.0* Meson build patches are |
| 163 |
supported for any wrap modes, including wrap-git. |
| 164 |
|
| 165 |
## Diff files |
| 166 |
|
| 167 |
*Since: 0.63.0* |
| 168 |
|
| 169 |
You can also provide local patch files in `diff` format. For historic reasons, |
| 170 |
they are referred to as "diff files", since the "patch" name is already used for |
| 171 |
overlay archives. |
| 172 |
|
| 173 |
The diff files are described by the `diff_files` property (a comma-separated |
| 174 |
list), and must be available locally in the `subprojects/packagefiles` |
| 175 |
directory. |
| 176 |
|
| 177 |
Meson will apply the diff files after extracting or cloning the project, and |
| 178 |
after applying the overlay archive (`patch_*`). For this feature, the `patch` or |
| 179 |
`git` command-line tool must be available. |
| 180 |
|
| 181 |
The diff files will be applied with `-p1`, i.e. treating the first path |
| 182 |
component as a prefix to be stripped. This is the default for diffs produced by |
| 183 |
Git. |
| 184 |
|
| 185 |
```ini |
| 186 |
[wrap-file] |
| 187 |
directory = libfoobar-1.0 |
| 188 |
|
| 189 |
source_url = https://example.com/foobar-1.0.tar.gz |
| 190 |
source_filename = foobar-1.0.tar.gz |
| 191 |
source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663 |
| 192 |
|
| 193 |
diff_files = libfoobar-1.0/0001.patch, libfoobar-1.0/0002.patch |
| 194 |
``` |
| 195 |
|
| 196 |
## `provide` section |
| 197 |
|
| 198 |
*Since *0.55.0* |
| 199 |
|
| 200 |
Wrap files can define the dependencies it provides in the `[provide]` |
| 201 |
section. |
| 202 |
|
| 203 |
```ini |
| 204 |
[provide] |
| 205 |
dependency_names = foo-1.0 |
| 206 |
``` |
| 207 |
|
| 208 |
When a wrap file provides the dependency `foo-1.0`, as above, any call to |
| 209 |
`dependency('foo-1.0')` will automatically fallback to that subproject even if |
| 210 |
no `fallback` keyword argument is given. A wrap file named `foo.wrap` implicitly |
| 211 |
provides the dependency name `foo` even when the `[provide]` section is missing. |
| 212 |
|
| 213 |
Optional dependencies, like `dependency('foo-1.0', required: get_option('foo_opt'))` |
| 214 |
where `foo_opt` is a feature option set to `auto`, will not fallback to the |
| 215 |
subproject defined in the wrap file, for 2 reasons: |
| 216 |
- It allows for looking the dependency in other ways first, for example using |
| 217 |
`cc.find_library('foo')`, and only fallback if that fails: |
| 218 |
|
| 219 |
```meson |
| 220 |
# this won't use fallback defined in foo.wrap |
| 221 |
foo_dep = dependency('foo-1.0', required: false) |
| 222 |
if not foo_dep.found() |
| 223 |
foo_dep = cc.find_library('foo', has_headers: 'foo.h', required: false) |
| 224 |
if not foo_dep.found() |
| 225 |
# This will use the fallback |
| 226 |
foo_dep = dependency('foo-1.0') |
| 227 |
# or |
| 228 |
foo_dep = dependency('foo-1.0', required: false, fallback: 'foo') |
| 229 |
endif |
| 230 |
endif |
| 231 |
``` |
| 232 |
|
| 233 |
- Sometimes not-found dependency is preferable to a fallback when the |
| 234 |
feature is not explicitly requested by the user. In that case |
| 235 |
`dependency('foo-1.0', required: get_option('foo_opt'))` will only |
| 236 |
fallback when the user sets `foo_opt` to `enabled` instead of |
| 237 |
`auto`. |
| 238 |
*Since 0.58.0* optional dependency like above will fallback to the subproject |
| 239 |
defined in the wrap file in the case `wrap_mode` is set to `forcefallback` |
| 240 |
or `force_fallback_for` contains the subproject. |
| 241 |
|
| 242 |
If it is desired to fallback for an optional dependency, the |
| 243 |
`fallback` or `allow_fallback` keyword arguments must be passed |
| 244 |
explicitly. *Since 0.56.0*, `dependency('foo-1.0', required: |
| 245 |
get_option('foo_opt'), allow_fallback: true)` will use the fallback |
| 246 |
even when `foo_opt` is set to `auto`. On version *0.55.0* the same |
| 247 |
effect could be achieved with `dependency('foo-1.0', required: |
| 248 |
get_option('foo_opt'), fallback: 'foo')`. |
| 249 |
|
| 250 |
This mechanism assumes the subproject calls |
| 251 |
`meson.override_dependency('foo-1.0', foo_dep)` so Meson knows which |
| 252 |
dependency object should be used as fallback. Since that method was |
| 253 |
introduced in version *0.54.0*, as a transitional aid for projects |
| 254 |
that do not yet make use of it the variable name can be provided in |
| 255 |
the wrap file with entries in the format `foo-1.0 = foo_dep`. |
| 256 |
|
| 257 |
For example when using a recent enough version of glib that uses |
| 258 |
`meson.override_dependency()` to override `glib-2.0`, `gobject-2.0` |
| 259 |
and `gio-2.0`, a wrap file would look like: |
| 260 |
|
| 261 |
```ini |
| 262 |
[wrap-git] |
| 263 |
url=https://gitlab.gnome.org/GNOME/glib.git |
| 264 |
revision=glib-2-62 |
| 265 |
depth=1 |
| 266 |
|
| 267 |
[provide] |
| 268 |
dependency_names = glib-2.0, gobject-2.0, gio-2.0 |
| 269 |
``` |
| 270 |
|
| 271 |
With older version of glib dependency variable names need to be |
| 272 |
specified: |
| 273 |
|
| 274 |
```ini |
| 275 |
[wrap-git] |
| 276 |
url=https://gitlab.gnome.org/GNOME/glib.git |
| 277 |
revision=glib-2-62 |
| 278 |
depth=1 |
| 279 |
|
| 280 |
[provide] |
| 281 |
glib-2.0=glib_dep |
| 282 |
gobject-2.0=gobject_dep |
| 283 |
gio-2.0=gio_dep |
| 284 |
``` |
| 285 |
|
| 286 |
Programs can also be provided by wrap files, with the `program_names` |
| 287 |
key: |
| 288 |
|
| 289 |
```ini |
| 290 |
[provide] |
| 291 |
program_names = myprog, otherprog |
| 292 |
``` |
| 293 |
|
| 294 |
With such wrap file, `find_program('myprog')` will automatically |
| 295 |
fallback to use the subproject, assuming it uses |
| 296 |
`meson.override_find_program('myprog')`. |
| 297 |
|
| 298 |
### CMake wraps |
| 299 |
|
| 300 |
**Note**: This is experimental and has no backwards or forwards compatibility guarantees. |
| 301 |
See [Meson's rules on mixing build systems](Mixing-build-systems.md). |
| 302 |
|
| 303 |
Since the CMake module does not know the public name of the provided |
| 304 |
dependencies, a CMake `.wrap` file cannot use the `dependency_names = foo` |
| 305 |
syntax. Instead, the `dep_name = <target_name>_dep` syntax should be used, where |
| 306 |
`<target_name>` is the name of a CMake library with all non alphanumeric |
| 307 |
characters replaced by underscores `_`. |
| 308 |
|
| 309 |
For example, a CMake project that contains `add_library(foo-bar ...)` in its |
| 310 |
`CMakeList.txt` and that applications would usually find using the dependency |
| 311 |
name `foo-bar-1.0` (e.g. via pkg-config) would have a wrap file like this: |
| 312 |
|
| 313 |
```ini |
| 314 |
[wrap-file] |
| 315 |
... |
| 316 |
method = cmake |
| 317 |
[provide] |
| 318 |
foo-bar-1.0 = foo_bar_dep |
| 319 |
``` |
| 320 |
### Cargo wraps |
| 321 |
|
| 322 |
**Note**: This is experimental and has no backwards or forwards compatibility guarantees. |
| 323 |
See [Meson's rules on mixing build systems](Mixing-build-systems.md). |
| 324 |
|
| 325 |
Cargo subprojects automatically override the `<package_name>-<version>-rs` dependency |
| 326 |
name: |
| 327 |
- `package_name` is defined in `[package] name = ...` section of the `Cargo.toml`. |
| 328 |
- `version` is the API version deduced from `[package] version = ...` as follow: |
| 329 |
* `x.y.z` -> 'x' |
| 330 |
* `0.x.y` -> '0.x' |
| 331 |
* `0.0.x` -> '0' |
| 332 |
It allows to make different dependencies for incompatible versions of the same |
| 333 |
crate. |
| 334 |
- `-rs` suffix is added to distinguish from regular system dependencies, for |
| 335 |
example `gstreamer-1.0` is a system pkg-config dependency and `gstreamer-0.22-rs` |
| 336 |
is a Cargo dependency. |
| 337 |
|
| 338 |
That means the `.wrap` file should have `dependency_names = foo-1-rs` in their |
| 339 |
`[provide]` section when `Cargo.toml` has package name `foo` and version `1.2`. |
| 340 |
|
| 341 |
Note that the version component was added in Meson 1.4, previous versions were |
| 342 |
using `<package_name>-rs` format. |
| 343 |
|
| 344 |
Cargo subprojects require a toml parser. Python >= 3.11 have one built-in, older |
| 345 |
Python versions require either the external `tomli` module or `toml2json` program. |
| 346 |
|
| 347 |
For example, a Cargo project with the package name `foo-bar` would have a wrap |
| 348 |
file like that: |
| 349 |
```ini |
| 350 |
[wrap-file] |
| 351 |
... |
| 352 |
method = cargo |
| 353 |
[provide] |
| 354 |
dependency_names = foo-bar-0.1-rs |
| 355 |
``` |
| 356 |
|
| 357 |
In addition, if the file `meson/meson.build` exists, Meson will call `subdir('meson')` |
| 358 |
where the project can add manual logic that would usually be part of `build.rs`. |
| 359 |
Some naming conventions need to be respected: |
| 360 |
- The `extra_args` variable is pre-defined and can be used to add any Rust arguments. |
| 361 |
This is typically used as `extra_args += ['--cfg', 'foo']`. |
| 362 |
- The `extra_deps` variable is pre-defined and can be used to add extra dependencies. |
| 363 |
This is typically used as `extra_deps += dependency('foo')`. |
| 364 |
|
| 365 |
Since *1.5.0* Cargo wraps can also be provided with `Cargo.lock` file at the root |
| 366 |
of (sub)project source tree. Meson will automatically load that file and convert |
| 367 |
it into a series of wraps definitions. |
| 368 |
|
| 369 |
## Using wrapped projects |
| 370 |
|
| 371 |
Wraps provide a convenient way of obtaining a project into your |
| 372 |
subproject directory. Then you use it as a regular subproject (see |
| 373 |
[subprojects](Subprojects.md)). |
| 374 |
|
| 375 |
## Getting wraps |
| 376 |
|
| 377 |
Usually you don't want to write your wraps by hand. |
| 378 |
|
| 379 |
There is an online repository called |
| 380 |
[WrapDB](https://wrapdb.mesonbuild.com) that provides many |
| 381 |
dependencies ready to use. You can read more about WrapDB |
| 382 |
[here](Using-the-WrapDB.md). |
| 383 |
|
| 384 |
There is also a Meson subcommand to get and manage wraps (see [using |
| 385 |
wraptool](Using-wraptool.md)). |