-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathWrap-dependency-system-manual.html
634 lines (593 loc) · 26.4 KB
/
Wrap-dependency-system-manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
<!DOCTYPE html>
<html lang="en">
<head>
<base href=".">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Wrap dependency system manual</title>
<link rel="stylesheet" href="assets/css/dark-frontend.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/light-frontend.css" type="text/css" title="light">
<link rel="stylesheet" href="assets/css/bootstrap-toc.min.css" type="text/css">
<link rel="stylesheet" href="assets/css/jquery.mCustomScrollbar.min.css">
<link rel="stylesheet" href="assets/js/search/enable_search.css" type="text/css">
<link rel="stylesheet" href="assets/css/notes.css" type="text/css">
<link rel="stylesheet" href="assets/css/prism-tomorrow.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/prism.css" type="text/css" title="light">
<script src="assets/js/mustache.min.js"></script>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/bootstrap.js"></script>
<script src="assets/js/scrollspy.js"></script>
<script src="assets/js/typeahead.jquery.min.js"></script>
<script src="assets/js/search.js"></script>
<script src="assets/js/compare-versions.js"></script>
<script src="assets/js/jquery.mCustomScrollbar.concat.min.js"></script>
<script src="assets/js/bootstrap-toc.min.js"></script>
<script src="assets/js/jquery.touchSwipe.min.js"></script>
<script src="assets/js/anchor.min.js"></script>
<script src="assets/js/tag_filtering.js"></script>
<script src="assets/js/language_switching.js"></script>
<script src="assets/js/styleswitcher.js"></script>
<script src="assets/js/lines_around_headings.js"></script>
<script src="assets/js/prism-core.js"></script>
<script src="assets/js/prism-autoloader.js"></script>
<script src="assets/js/prism_autoloader_path_override.js"></script>
<script src="assets/js/prism-keep-markup.js"></script>
<script src="assets/js/trie.js"></script>
<link rel="icon" type="image/png" href="assets/images/favicon.png">
<link rel="shortcut icon" href="assets/images/favicon.png">
</head>
<body class="no-script
">
<script>
$('body').removeClass('no-script');
</script>
<nav class="navbar navbar-fixed-top navbar-default" id="topnav">
<div class="container-fluid">
<div class="navbar-right">
<a id="toc-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-wrapper" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span title="light mode switch" class="glyphicon glyphicon-sunglasses pull-right" id="lightmode-icon"></span>
<form class="navbar-form pull-right" id="navbar-search-form">
<div class="form-group has-feedback">
<input type="text" class="form-control input-sm" name="search" id="sidenav-lookup-field" placeholder="search" disabled>
<span class="glyphicon glyphicon-search form-control-feedback" id="search-mgn-glass"></span>
</div>
</form>
</div>
<div class="navbar-header">
<a id="sidenav-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<a id="home-link" href="index.html" class="hotdoc-navbar-brand">
<img src="assets/images/meson_logo.png" alt="Home">
</a>
</div>
<div class="navbar-collapse collapse" id="navbar-wrapper">
<ul class="nav navbar-nav" id="menu">
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Modules <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="modules-menu">
<li>
<a href="CMake-module.html">CMake</a>
</li>
<li>
<a href="Cuda-module.html">CUDA</a>
</li>
<li>
<a href="Dlang-module.html">Dlang</a>
</li>
<li>
<a href="External-Project-module.html">External Project</a>
</li>
<li>
<a href="Fs-module.html">Filesystem</a>
</li>
<li>
<a href="Gnome-module.html">GNOME</a>
</li>
<li>
<a href="Hotdoc-module.html">Hotdoc</a>
</li>
<li>
<a href="i18n-module.html">i18n</a>
</li>
<li>
<a href="Icestorm-module.html">Icestorm</a>
</li>
<li>
<a href="Java-module.html">Java</a>
</li>
<li>
<a href="Keyval-module.html">Keyval</a>
</li>
<li>
<a href="Pkgconfig-module.html">Pkgconfig</a>
</li>
<li>
<a href="Python-3-module.html">Python 3</a>
</li>
<li>
<a href="Python-module.html">Python</a>
</li>
<li>
<a href="Qt4-module.html">Qt4</a>
</li>
<li>
<a href="Qt5-module.html">Qt5</a>
</li>
<li>
<a href="Qt6-module.html">Qt6</a>
</li>
<li>
<a href="Rust-module.html">Rust</a>
</li>
<li>
<a href="Simd-module.html">Simd</a>
</li>
<li>
<a href="SourceSet-module.html">SourceSet</a>
</li>
<li>
<a href="Wayland-module.html">Wayland</a>
</li>
<li>
<a href="Windows-module.html">Windows</a>
</li>
</ul>
</li>
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Quick References <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="quick-refs-menu">
<li>
<a href="Reference-manual.html">Functions</a>
</li>
<li>
<a href="Build-options.html">Options</a>
</li>
<li>
<a href="Configuration.html">Configuration</a>
</li>
<li>
<a href="Dependencies.html">Dependencies</a>
</li>
<li>
<a href="Unit-tests.html">Tests</a>
</li>
<li>
<a href="Syntax.html">Syntax</a>
</li>
</ul>
</li>
</ul>
<div class="hidden-xs hidden-sm navbar-text navbar-center">
<p><b>The Meson Build System</b></p>
</div>
</div>
</div>
</nav>
<main>
<div data-extension="core" data-hotdoc-in-toplevel="True" data-hotdoc-project="Meson-documentation" data-hotdoc-ref="Wrap-dependency-system-manual.html" class="page_container" id="page-wrapper">
<script src="assets/js/utils.js"></script>
<div class="panel panel-collapse oc-collapsed" id="sidenav" data-hotdoc-role="navigation">
<script src="assets/js/full-width.js"></script>
<div id="sitenav-wrapper">
<iframe src="hotdoc-sitemap.html" id="sitenav-frame"></iframe>
</div>
</div>
<div id="body">
<div id="main">
<div id="page-description" data-hotdoc-role="main">
<h1 id="wrap-dependency-system-manual">Wrap dependency system manual</h1>
<p>One of the major problems of multiplatform development is wrangling
all your dependencies. This is awkward on many platforms, especially
on ones that do not have a built-in package manager. The latter problem
has been worked around by having third party package managers. They
are not really a solution for end user deployment, because you can't
tell them to install a package manager just to use your app. On these
platforms you must produce self-contained applications. Same applies
when destination platform is missing (up-to-date versions of) your
application's dependencies.</p>
<p>The traditional approach to this has been to bundle dependencies
inside your own project. Either as prebuilt libraries and headers or
by embedding the source code inside your source tree and rewriting
your build system to build them as part of your project.</p>
<p>This is both tedious and error prone because it is always done by
hand. The Wrap dependency system of Meson aims to provide an automated
way to do this.</p>
<h2 id="how-it-works">How it works</h2>
<p>Meson has a concept of <a href="Subprojects.html">subprojects</a>. They are a way
of nesting one Meson project inside another. Any project that builds
with Meson can detect that it is built as a subproject and build
itself in a way that makes it easy to use (usually this means as a
static library).</p>
<p>To use this kind of a project as a dependency you could just copy and
extract it inside your project's <code>subprojects</code> directory.</p>
<p>However there is a simpler way. You can specify a Wrap file that tells
Meson how to download it for you. If you then use this subproject in
your build, Meson will automatically download and extract it during
build. This makes subproject embedding extremely easy.</p>
<p>All wrap files must have a name of <code><project_name>.wrap</code> form and be
in <code>subprojects</code> dir.</p>
<p>Currently Meson has four kinds of wraps:</p>
<ul>
<li>wrap-file</li>
<li>wrap-git</li>
<li>wrap-hg</li>
<li>wrap-svn</li>
</ul>
<h2 id="wrap-format">wrap format</h2>
<p>Wrap files are written in ini format, with a single header containing
the type of wrap, followed by properties describing how to obtain the
sources, validate them, and modify them if needed. An example
wrap-file for the wrap named <code>libfoobar</code> would have a filename
<code>libfoobar.wrap</code> and would look like this:</p>
<pre><code class="language-ini">[wrap-file]
directory = libfoobar-1.0
source_url = https://example.com/foobar-1.0.tar.gz
source_filename = foobar-1.0.tar.gz
source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663
</code></pre>
<p>An example wrap-git will look like this:</p>
<pre><code class="language-ini">[wrap-git]
url = https://github.com/libfoobar/libfoobar.git
revision = HEAD
depth = 1
</code></pre>
<h2 id="accepted-configuration-properties-for-wraps">Accepted configuration properties for wraps</h2>
<ul>
<li>
<code>directory</code> - name of the subproject root directory, defaults to the
name of the wrap.</li>
</ul>
<p>Since <em>0.55.0</em> those can be used in all wrap types, they were
previously reserved to <code>wrap-file</code>:</p>
<ul>
<li>
<code>patch_url</code> - download url to retrieve an optional overlay archive</li>
<li>
<code>patch_fallback_url</code> - fallback URL to be used when download from <code>patch_url</code> fails <em>Since: 0.55.0</em>
</li>
<li>
<code>patch_filename</code> - filename of the downloaded overlay archive</li>
<li>
<code>patch_hash</code> - sha256 checksum of the downloaded overlay archive</li>
<li>
<code>patch_directory</code> - <em>Since 0.55.0</em> Overlay directory, alternative to <code>patch_filename</code> in the case
files are local instead of a downloaded archive. The directory must be placed in
<code>subprojects/packagefiles</code>.</li>
<li>
<code>diff_files</code> - <em>Since 0.63.0</em> Comma-separated list of local diff files (see
<a href="Wrap-dependency-system-manual.html#diff-files">Diff files</a> below).</li>
<li>
<code>method</code> - <em>Since 1.3.0</em> The build system used by this subproject. Defaults to <code>meson</code>.
Supported methods:
<ul>
<li>
<code>meson</code> requires <code>meson.build</code> file.</li>
<li>
<code>cmake</code> requires <code>CMakeLists.txt</code> file. <a href="Wrap-dependency-system-manual.html#cmake-wraps">See details</a>.</li>
<li>
<code>cargo</code> requires <code>Cargo.toml</code> file. <a href="Wrap-dependency-system-manual.html#cargo-wraps">See details</a>.</li>
</ul>
</li>
</ul>
<h3 id="specific-to-wrapfile">Specific to wrap-file</h3>
<ul>
<li>
<code>source_url</code> - download url to retrieve the wrap-file source archive</li>
<li>
<code>source_fallback_url</code> - fallback URL to be used when download from <code>source_url</code> fails <em>Since: 0.55.0</em>
</li>
<li>
<code>source_filename</code> - filename of the downloaded source archive</li>
<li>
<code>source_hash</code> - sha256 checksum of the downloaded source archive</li>
<li>
<code>lead_directory_missing</code> - for <code>wrap-file</code> create the leading
directory name. Needed when the source file does not have a leading
directory.</li>
</ul>
<p>Since <em>0.55.0</em> it is possible to use only the <code>source_filename</code> and
<code>patch_filename</code> value in a .wrap file (without <code>source_url</code> and
<code>patch_url</code>) to specify a local archive in the
<code>subprojects/packagefiles</code> directory. The <code>*_hash</code> entries are
optional when using this method. This method should be preferred over
the old <code>packagecache</code> approach described below.</p>
<p>Since <em>0.49.0</em> if <code>source_filename</code> or <code>patch_filename</code> is found in the
project's <code>subprojects/packagecache</code> directory, it will be used instead
of downloading the file, even if <code>--wrap-mode</code> option is set to
<code>nodownload</code>. The file's hash will be checked.</p>
<p>Since <em>1.3.0</em> if the <code>MESON_PACKAGE_CACHE_DIR</code> environment variable is set, it is used instead of
the project's <code>subprojects/packagecache</code>. This allows sharing the cache across multiple
projects. In addition it can contain an already extracted source tree as long as it
has the same directory name as the <code>directory</code> field in the wrap file. In that
case, the directory will be copied into <code>subprojects/</code> before applying patches.</p>
<h3 id="specific-to-vcsbased-wraps">Specific to VCS-based wraps</h3>
<ul>
<li>
<code>url</code> - name of the wrap-git repository to clone. Required.</li>
<li>
<code>revision</code> - name of the revision to checkout. Must be either: a
valid value (such as a git tag) for the VCS's <code>checkout</code> command, or
(for git) <code>HEAD</code> to track upstream's default branch. Required.</li>
</ul>
<h3 id="specific-to-wrapgit">Specific to wrap-git</h3>
<ul>
<li>
<code>depth</code> - shallowly clone the repository to X number of commits. This saves bandwidth and disk
space, and should typically always be specified unless commit history is needed. Note
that git always allow shallowly cloning branches, but in order to
clone commit ids shallowly, the server must support
<code>uploadpack.allowReachableSHA1InWant=true</code>. <em>(since 0.52.0)</em>
</li>
<li>
<code>push-url</code> - alternative url to configure as a git push-url. Useful if
the subproject will be developed and changes pushed upstream.
<em>(since 0.37.0)</em>
</li>
<li>
<code>clone-recursive</code> - also clone submodules of the repository
<em>(since 0.48.0)</em>
</li>
</ul>
<h2 id="wrapfile-with-meson-build-patch">wrap-file with Meson build patch</h2>
<p>Unfortunately most software projects in the world do not build with
Meson. Because of this Meson allows you to specify a patch URL.</p>
<p>For historic reasons this is called a "patch", however, it serves as an
overlay to add or replace files rather than modifying them. The file
must be an archive; it is downloaded and automatically extracted into
the subproject. The extracted files will include a Meson build
definition for the given subproject.</p>
<p>This approach makes it extremely simple to embed dependencies that
require build system changes. You can write the Meson build definition
for the dependency in total isolation. This is a lot better than doing
it inside your own source tree, especially if it contains hundreds of
thousands of lines of code. Once you have a working build definition,
just zip up the Meson build files (and others you have changed) and
put them somewhere where you can download them.</p>
<p>Prior to <em>0.55.0</em> Meson build patches were only supported for
wrap-file mode. When using wrap-git, the repository must contain all
Meson build definitions. Since <em>0.55.0</em> Meson build patches are
supported for any wrap modes, including wrap-git.</p>
<h2 id="diff-files">Diff files</h2>
<p><em>Since: 0.63.0</em></p>
<p>You can also provide local patch files in <code>diff</code> format. For historic reasons,
they are referred to as "diff files", since the "patch" name is already used for
overlay archives.</p>
<p>The diff files are described by the <code>diff_files</code> property (a comma-separated
list), and must be available locally in the <code>subprojects/packagefiles</code>
directory.</p>
<p>Meson will apply the diff files after extracting or cloning the project, and
after applying the overlay archive (<code>patch_*</code>). For this feature, the <code>patch</code> or
<code>git</code> command-line tool must be available.</p>
<p>The diff files will be applied with <code>-p1</code>, i.e. treating the first path
component as a prefix to be stripped. This is the default for diffs produced by
Git.</p>
<pre><code class="language-ini">[wrap-file]
directory = libfoobar-1.0
source_url = https://example.com/foobar-1.0.tar.gz
source_filename = foobar-1.0.tar.gz
source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663
diff_files = libfoobar-1.0/0001.patch, libfoobar-1.0/0002.patch
</code></pre>
<h2 id="provide-section">
<code>provide</code> section</h2>
<p>*Since <em>0.55.0</em></p>
<p>Wrap files can define the dependencies it provides in the <code>[provide]</code>
section.</p>
<pre><code class="language-ini">[provide]
dependency_names = foo-1.0
</code></pre>
<p>When a wrap file provides the dependency <code>foo-1.0</code>, as above, any call to
<code>dependency('foo-1.0')</code> will automatically fallback to that subproject even if
no <code>fallback</code> keyword argument is given. A wrap file named <code>foo.wrap</code> implicitly
provides the dependency name <code>foo</code> even when the <code>[provide]</code> section is missing.</p>
<p>Optional dependencies, like <code>dependency('foo-1.0', required: get_option('foo_opt'))</code>
where <code>foo_opt</code> is a feature option set to <code>auto</code>, will not fallback to the
subproject defined in the wrap file, for 2 reasons:</p>
<ul>
<li>It allows for looking the dependency in other ways first, for example using
<code>cc.find_library('foo')</code>, and only fallback if that fails:</li>
</ul>
<pre><code class="language-meson"># this won't use fallback defined in foo.wrap
foo_dep = dependency('foo-1.0', required: false)
if not foo_dep.found()
foo_dep = cc.find_library('foo', has_headers: 'foo.h', required: false)
if not foo_dep.found()
# This will use the fallback
foo_dep = dependency('foo-1.0')
# or
foo_dep = dependency('foo-1.0', required: false, fallback: 'foo')
endif
endif
</code></pre>
<ul>
<li>Sometimes not-found dependency is preferable to a fallback when the
feature is not explicitly requested by the user. In that case
<code>dependency('foo-1.0', required: get_option('foo_opt'))</code> will only
fallback when the user sets <code>foo_opt</code> to <code>enabled</code> instead of
<code>auto</code>.
<em>Since 0.58.0</em> optional dependency like above will fallback to the subproject
defined in the wrap file in the case <code>wrap_mode</code> is set to <code>forcefallback</code>
or <code>force_fallback_for</code> contains the subproject.</li>
</ul>
<p>If it is desired to fallback for an optional dependency, the
<code>fallback</code> or <code>allow_fallback</code> keyword arguments must be passed
explicitly. <em>Since 0.56.0</em>, <code>dependency('foo-1.0', required: get_option('foo_opt'), allow_fallback: true)</code> will use the fallback
even when <code>foo_opt</code> is set to <code>auto</code>. On version <em>0.55.0</em> the same
effect could be achieved with <code>dependency('foo-1.0', required: get_option('foo_opt'), fallback: 'foo')</code>.</p>
<p>This mechanism assumes the subproject calls
<code>meson.override_dependency('foo-1.0', foo_dep)</code> so Meson knows which
dependency object should be used as fallback. Since that method was
introduced in version <em>0.54.0</em>, as a transitional aid for projects
that do not yet make use of it the variable name can be provided in
the wrap file with entries in the format <code>foo-1.0 = foo_dep</code>.</p>
<p>For example when using a recent enough version of glib that uses
<code>meson.override_dependency()</code> to override <code>glib-2.0</code>, <code>gobject-2.0</code>
and <code>gio-2.0</code>, a wrap file would look like:</p>
<pre><code class="language-ini">[wrap-git]
url=https://gitlab.gnome.org/GNOME/glib.git
revision=glib-2-62
depth=1
[provide]
dependency_names = glib-2.0, gobject-2.0, gio-2.0
</code></pre>
<p>With older version of glib dependency variable names need to be
specified:</p>
<pre><code class="language-ini">[wrap-git]
url=https://gitlab.gnome.org/GNOME/glib.git
revision=glib-2-62
depth=1
[provide]
glib-2.0=glib_dep
gobject-2.0=gobject_dep
gio-2.0=gio_dep
</code></pre>
<p>Programs can also be provided by wrap files, with the <code>program_names</code>
key:</p>
<pre><code class="language-ini">[provide]
program_names = myprog, otherprog
</code></pre>
<p>With such wrap file, <code>find_program('myprog')</code> will automatically
fallback to use the subproject, assuming it uses
<code>meson.override_find_program('myprog')</code>.</p>
<h3 id="cmake-wraps">CMake wraps</h3>
<p><strong>Note</strong>: This is experimental and has no backwards or forwards compatibility guarantees.
See <a href="Mixing-build-systems.html">Meson's rules on mixing build systems</a>.</p>
<p>Since the CMake module does not know the public name of the provided
dependencies, a CMake <code>.wrap</code> file cannot use the <code>dependency_names = foo</code>
syntax. Instead, the <code>dep_name = <target_name>_dep</code> syntax should be used, where
<code><target_name></code> is the name of a CMake library with all non alphanumeric
characters replaced by underscores <code>_</code>.</p>
<p>For example, a CMake project that contains <code>add_library(foo-bar ...)</code> in its
<code>CMakeList.txt</code> and that applications would usually find using the dependency
name <code>foo-bar-1.0</code> (e.g. via pkg-config) would have a wrap file like this:</p>
<pre><code class="language-ini">[wrap-file]
...
method = cmake
[provide]
foo-bar-1.0 = foo_bar_dep
</code></pre>
<h3 id="cargo-wraps">Cargo wraps</h3>
<p><strong>Note</strong>: This is experimental and has no backwards or forwards compatibility guarantees.
See <a href="Mixing-build-systems.html">Meson's rules on mixing build systems</a>.</p>
<p>Cargo subprojects automatically override the <code><package_name>-<version>-rs</code> dependency
name:</p>
<ul>
<li>
<code>package_name</code> is defined in <code>[package] name = ...</code> section of the <code>Cargo.toml</code>.</li>
<li>
<code>version</code> is the API version deduced from <code>[package] version = ...</code> as follow:
<ul>
<li>
<code>x.y.z</code> -> 'x'</li>
<li>
<code>0.x.y</code> -> '0.x'</li>
<li>
<code>0.0.x</code> -> '0'
It allows to make different dependencies for incompatible versions of the same
crate.</li>
</ul>
</li>
<li>
<code>-rs</code> suffix is added to distinguish from regular system dependencies, for
example <code>gstreamer-1.0</code> is a system pkg-config dependency and <code>gstreamer-0.22-rs</code>
is a Cargo dependency.</li>
</ul>
<p>That means the <code>.wrap</code> file should have <code>dependency_names = foo-1-rs</code> in their
<code>[provide]</code> section when <code>Cargo.toml</code> has package name <code>foo</code> and version <code>1.2</code>.</p>
<p>Note that the version component was added in Meson 1.4, previous versions were
using <code><package_name>-rs</code> format.</p>
<p>Cargo subprojects require a toml parser. Python >= 3.11 have one built-in, older
Python versions require either the external <code>tomli</code> module or <code>toml2json</code> program.</p>
<p>For example, a Cargo project with the package name <code>foo-bar</code> would have a wrap
file like that:</p>
<pre><code class="language-ini">[wrap-file]
...
method = cargo
[provide]
dependency_names = foo-bar-0.1-rs
</code></pre>
<p>In addition, if the file <code>meson/meson.build</code> exists, Meson will call <code>subdir('meson')</code>
where the project can add manual logic that would usually be part of <code>build.rs</code>.
Some naming conventions need to be respected:</p>
<ul>
<li>The <code>extra_args</code> variable is pre-defined and can be used to add any Rust arguments.
This is typically used as <code>extra_args += ['--cfg', 'foo']</code>.</li>
<li>The <code>extra_deps</code> variable is pre-defined and can be used to add extra dependencies.
This is typically used as <code>extra_deps += dependency('foo')</code>.</li>
</ul>
<p>Since <em>1.5.0</em> Cargo wraps can also be provided with <code>Cargo.lock</code> file at the root
of (sub)project source tree. Meson will automatically load that file and convert
it into a series of wraps definitions.</p>
<h2 id="using-wrapped-projects">Using wrapped projects</h2>
<p>Wraps provide a convenient way of obtaining a project into your
subproject directory. Then you use it as a regular subproject (see
<a href="Subprojects.html">subprojects</a>).</p>
<h2 id="getting-wraps">Getting wraps</h2>
<p>Usually you don't want to write your wraps by hand.</p>
<p>There is an online repository called
<a href="https://wrapdb.mesonbuild.com">WrapDB</a> that provides many
dependencies ready to use. You can read more about WrapDB
<a href="Using-the-WrapDB.html">here</a>.</p>
<p>There is also a Meson subcommand to get and manage wraps (see <a href="Using-wraptool.html">using
wraptool</a>).</p>
</div>
<div id="subpages">
<p><b>Subpages:</b></p>
<div class="thumb-subpages">
</div>
<p>
<a href="Adding-new-projects-to-wrapdb.html">Adding new projects to WrapDB</a>
</p>
<p>
<a href="Using-the-WrapDB.html">Using the WrapDB</a>
</p>
<p>
<a href="Using-wraptool.html">Using wraptool</a>
</p>
<p>
<a href="Wrap-best-practices-and-tips.html">Wrap best practices and tips</a>
</p>
<p>
<a href="Shipping-prebuilt-binaries-as-wraps.html">Shipping prebuilt binaries as wraps</a>
</p>
</div>
</div>
<div id="search_results">
<p>The results of the search are</p>
</div>
<div id="footer">
<hr>
<div class="license-description">
Website licensing information are available on the <a href="legal.html">Legal</a> page.
</div>
</div>
</div>
<div id="toc-column">
<div class="edit-button">
<a href="https://github.com/mesonbuild/meson/edit/master/docs/markdown/Wrap-dependency-system-manual.md" data-hotdoc-role="edit-button">Edit on GitHub</a>
</div>
<div id="toc-wrapper">
<nav id="toc"></nav>
</div>
</div>
</div>
</main>
<script src="assets/js/navbar_offset_scroller.js"></script>
</body>
</html>