-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathAdding-new-projects-to-wrapdb.html
381 lines (344 loc) · 14.7 KB
/
Adding-new-projects-to-wrapdb.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
<!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>Adding new projects to WrapDB</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="Adding-new-projects-to-wrapdb.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="adding-new-projects-to-wrapdb">Adding new projects to WrapDB</h1>
<h2 id="how-it-works">How it works</h2>
<p>New wraps must be submitted as a working subproject to the <a href="https://github.com/mesonbuild/wrapdb">wrapdb
repository</a>.</p>
<p>There are two types of wraps on WrapDB - regular wraps and wraps with
Meson build definition patches.</p>
<p>Wraps with Meson build definition patches work in much the same way as
Debian: we take the unaltered upstream source package and add a new
build system to it as a patch. These build systems are stored as a
subdirectory of subprojects/packagefiles/. They only contain build
definition files. You may also think of them as an overlay to upstream
source.</p>
<p>Wraps without Meson build definition patches only contain the wrap
metadata describing how to fetch the project</p>
<p>Whenever a new release is pushed into the wrapdb, a new tag is
generated with an incremented version number, and a new release is
added to the wrapdb API listing. All the old releases remain
unaltered. New commits are always done via GitHub merge requests and
must be reviewed by someone other than the submitter.</p>
<p>Note that your Git repo with wrap must not contain the subdirectory of
the source release. That gets added automatically by the service. You
also must not commit any source code from the original tarball into
the wrap repository.</p>
<h2 id="choosing-the-wrap-name">Choosing the wrap name</h2>
<p>Wrapped subprojects are used much like external dependencies. Thus
they should have the same name as the upstream projects.</p>
<p>NOTE: Wrap names must fully match this regexp: <code>[a-z0-9._]+</code>.</p>
<p>If the project provides a pkg-config file, then the wrap name
should be the same as the pkg-config name. Usually this is the name of
the project, such as <code>libpng</code>. Sometimes it is slightly different,
however. As an example the libogg project's chosen pkg-config name is
<code>ogg</code> instead of <code>libogg</code>, which is the reason why the wrap is
named plain <code>ogg</code>.</p>
<p>If there is no pkg-config file, the name the project uses/promotes
should be used, lowercase only (Catch2 -> catch2).</p>
<p>If the project name is too generic or ambiguous (e.g. <code>benchmark</code>),
consider using <code>organization-project</code> naming format (e.g.
<code>google-benchmark</code>).</p>
<h2 id="how-to-contribute-a-new-wrap">How to contribute a new wrap</h2>
<p>If the project already uses Meson build system, then only a wrap file
<code>project.wrap</code> should be provided. In other case a Meson build
definition patch - a set of <code>meson.build</code> files - should also be
provided.</p>
<h3 id="creating-the-wrap-contents">Creating the wrap contents</h3>
<p>New release branches require a <code>project.wrap</code> file, so create one if
needed.</p>
<pre><code>${EDITOR} upstream.wrap
</code></pre>
<p>The file format is simple, see any existing wrapdb subproject for the
content. The checksum is SHA-256 and can be calculated with the
following command on most unix-like operating systems:</p>
<pre><code>sha256sum path/to/libfoo-1.0.0.tar.gz
</code></pre>
<p>Under macOS the command is the following:</p>
<pre><code>shasum -a 256 path/to/libfoo-1.0.0.tar.gz
</code></pre>
<p>Next you need to add the entries that define what dependencies the
current project provides. This is important, as it is what makes
Meson's automatic dependency resolver work. It is done by adding a
<code>provide</code> entry at the end of the <code>upstream.wrap</code> file. Using the Ogg
library as an example, this is what it would look like:</p>
<pre><code class="language-ini">[provide]
ogg = ogg_dep
</code></pre>
<p>The <code>ogg</code> part on the left refers to the dependency name, which should
be the same as its Pkg-Config name. <code>ogg_dep</code> on the right refers to
the variable in the build definitions that provides the dependency.
Most commonly it holds the result of a <code>declare_dependency</code> call. If a
variable of that name is not defined, Meson will exit with a hard
error. For further details see <a href="Wrap-dependency-system-manual.html">the main Wrap
manual</a>.</p>
<p>Now you can create the build files, if the upstream project does not
contain any, and work on them until the project builds correctly.
Remember that all files go in the directory
<code>subprojects/packagefiles/<project-name></code>.</p>
<pre><code>${EDITOR} meson.build meson.options
</code></pre>
<p>In order to apply the locally added build files to the upstream
release tarball, the <code>wrap-file</code> section must contain a
<code>patch_directory</code> property naming the subdirectory in
subprojects/packagefiles/ with the build files inside, as this is
central to the way the wrapdb works. It will be used by the wrapdb
meson.build, and when a release is created, the files from this
directory will be converted into an archive and a patch_url will be
added to the wrap file.</p>
<p>When you are satisfied with the results, add the build files to Git, update
releases.json as described in
<a href="https://github.com/mesonbuild/wrapdb#readme">README.md</a>, and push the result
to GitHub.</p>
<pre><code><verify that your project builds and runs>
git add releases.json subprojects/project.wrap subprojects/packagefiles/project/
git commit -a -m 'Add wrap files for libfoo-1.0.0'
git push -u origin libfoo
</code></pre>
<p>Now you should create a pull request on GitHub.</p>
<p>If packaging review requires you to do changes, use the <code>--amend</code>
argument to <code>commit</code> so that your branch will have only one commit.</p>
<pre><code>${EDITOR} meson.build
git commit -u --amend
git push --force
</code></pre>
<h2 id="changes-to-original-source">Changes to original source</h2>
<p>The point of a wrap is to provide the upstream project with as few
changes as possible. Most projects should not contain anything more
than a few Meson definition files. Sometimes it may be necessary to
add a template header file or something similar. These should be held
at a minimum.</p>
<p>It should especially be noted that there must <strong>not</strong> be any patches
to functionality. All such changes must be submitted to upstream. You
may also host your own Git repo with the changes if you wish. The Wrap
system has native support for Git subprojects.</p>
<h2 id="passing-automatic-validation">Passing automatic validation</h2>
<p>Every submitted wrap goes through an automated correctness review and
passing it is a requirement for merging. Therefore it is highly
recommended that you run the validation checks yourself so you can fix
any issues faster.</p>
<p>You can test the wrap itself with the following commands:</p>
<pre><code>meson subprojects purge --confirm
meson setup builddir/ -Dwraps=<project-name>
</code></pre>
<p>The first command is to ensure the wrap is correctly fetched from the
latest packagefiles. The second command configures meson and selects a
set of subprojects to enable.</p>
<p>The GitHub project contains automatic CI on pushing to run the project
and check the metadata for obvious mistakes. This can be checked from
your fork before submitting a PR.</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/Adding-new-projects-to-wrapdb.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>