Debian Codegraph @

subprojects/meson-docs/docs/markdown/Wrap-dependency-system-manual.md

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