-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathRunning-Meson.html
423 lines (386 loc) · 16.4 KB
/
Running-Meson.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
<!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>Running Meson</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="Running-Meson.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="running-meson">Running Meson</h1>
<p>There are two different ways of invoking Meson. First, you can run it
directly from the source tree with the command
<code>/path/to/source/meson.py</code>. Second, Meson may also be installed in which case
the command is simply <code>meson</code>. In this manual we only use the latter
format for simplicity.</p>
<p>At the time of writing only a command line version of Meson is
available. This means that Meson must be invoked using the terminal.
If you wish to use the MSVC compiler, you need to run Meson under
"Visual Studio command prompt".</p>
<p>All available Meson commands are listed on the <a href="Commands.html">commands reference
page</a>.</p>
<h2 id="configuring-the-build-directory">Configuring the build directory</h2>
<p>Let us assume that we have a source tree that has a Meson build
system. This means that at the topmost directory has a file called
<code>meson.build</code>. We run the following commands to get the build started.</p>
<pre><code class="language-sh">cd /path/to/source/root
meson setup builddir
</code></pre>
<p>We invoke Meson with the <code>setup</code> command, giving it the location of the build
directory. Meson uses <a href="http://web.archive.org/web/20190715081007/http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/">out of source
builds</a>.</p>
<p>Hint: The syntax of Meson is <code>meson [command] [arguments] [options]</code>.
The <code>setup</code> command takes a <code>builddir</code> and a <code>srcdir</code> argument. If no
<code>srcdir</code> is given Meson will deduce the <code>srcdir</code> based on <code>pwd</code> and
the location of <code>meson.build</code>.</p>
<p>Meson then loads the build configuration file and writes the
corresponding build backend in the build directory. By default Meson
generates a <em>debug build</em>, which turns on basic warnings and debug
information and disables compiler optimizations.</p>
<p>Additionally, the invocation can pass options to Meson. The list of
options is documented <a href="Builtin-options.html">here</a>.</p>
<p>You can specify a different type of build with the <code>--buildtype</code> command line
argument. It can have one of the following values.</p>
<table>
<thead>
<tr>
<th> value</th>
<th> meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>plain</code>
</td>
<td> no extra build flags are used, even for compiler warnings, useful for distro packagers and other cases where you need to specify all arguments by yourself</td>
</tr>
<tr>
<td> <code>debug</code>
</td>
<td> debug info is generated but the result is not optimized, this is the default</td>
</tr>
<tr>
<td> <code>debugoptimized</code>
</td>
<td> debug info is generated and the code is optimized (on most compilers this means <code>-g -O2</code>)</td>
</tr>
<tr>
<td> <code>release</code>
</td>
<td> full optimization, no debug info</td>
</tr>
</tbody>
</table>
<p>The build directory is mandatory. The reason for this is that it
simplifies the build process immensely. Meson will not, under any
circumstances, write files inside the source directory (if it does, it
is a bug and should be fixed). This means that the user does not need
to add a bunch of files to their revision control's ignore list. It
also means that you can create arbitrarily many build directories for
any given source tree.</p>
<p>For example, if we wanted to test building the source code with the
Clang compiler instead of the system default, we could just type the
following commands:</p>
<pre><code class="language-sh">cd /path/to/source/root
CC=clang CXX=clang++ meson setup buildclang
</code></pre>
<p>This separation is even more powerful if your code has multiple
configuration options (such as multiple data backends). You can create
a separate subdirectory for each of them. You can also have build
directories for optimized builds, code coverage, static analysis and
so on. They are all neatly separated and use the same source tree.
Changing between different configurations is just a question of
changing to the corresponding directory.</p>
<p>Unless otherwise mentioned, all following command line invocations are
meant to be run in the source directory.</p>
<p>By default, Meson will use the Ninja backend to build your project. If
you wish to use any of the other backends, you need to pass the
corresponding argument during configuration time. As an example, here
is how you would use Meson to generate a Visual Studio solution.</p>
<pre><code class="language-sh">meson setup <build dir> --backend=vs
</code></pre>
<p>You can then open the generated solution with Visual Studio and
compile it in the usual way. A list of backends can be obtained with
<code>meson setup --help</code>.</p>
<h2 id="environment-variables">Environment variables</h2>
<p>Sometimes you want to add extra compiler flags, this can be done by
passing them in environment variables when calling Meson. See <a href="Reference-tables.html#compiler-and-linker-flag-environment-variables">the
reference
tables</a>
for a list of all the environment variables. Be aware however these
environment variables are only used for the native compiler and will
not affect the compiler used for cross-compiling, where the flags
specified in the cross file will be used.</p>
<p>Furthermore it is possible to stop Meson from adding flags itself by
using the <code>--buildtype=plain</code> option, in this case you must provide
the full compiler and linker arguments needed.</p>
<h2 id="building-from-the-source">Building from the source</h2>
<p>To start the build, simply type the following command.</p>
<pre><code class="language-sh">meson compile -C builddir
</code></pre>
<p>See <a href="Commands.html#compile"><code>meson compile</code> description</a> for more info.</p>
<h3 id="building-directly-with-ninja">Building directly with ninja</h3>
<p>By default Meson uses the <a href="https://ninja-build.org/">Ninja build
system</a> to actually build the code. To start
the build, simply type the following command.</p>
<pre><code class="language-sh">ninja -C builddir
</code></pre>
<p>The main usability difference between Ninja and Make is that Ninja
will automatically detect the number of CPUs in your computer and
parallelize itself accordingly. You can override the amount of
parallel processes used with the command line argument <code>-j <num processes></code>.</p>
<p>It should be noted that after the initial configure step <code>ninja</code> is
the only command you ever need to type to compile. No matter how you
alter your source tree (short of moving it to a completely new
location), Meson will detect the changes and regenerate itself
accordingly. This is especially handy if you have multiple build
directories. Often one of them is used for development (the "debug"
build) and others only every now and then (such as a "static analysis"
build). Any configuration can be built just by <code>cd</code>'ing to the
corresponding directory and running Ninja.</p>
<h2 id="running-tests">Running tests</h2>
<p>Meson provides native support for running tests. The command to do
that is simple.</p>
<pre><code class="language-sh">meson test -C builddir
</code></pre>
<p>See <a href="Commands.html#test"><code>meson test</code> description</a> for more info.</p>
<p>Meson does not force the use of any particular testing framework. You
are free to use GTest, Boost Test, Check or even custom executables.</p>
<p>Note: it can be also invoked directly with ninja with the following command:</p>
<pre><code class="language-sh">ninja -C builddir test
</code></pre>
<h2 id="installing">Installing</h2>
<p>Installing the built software is just as simple.</p>
<pre><code class="language-sh">meson install -C builddir
</code></pre>
<p>See <a href="Commands.html#install"><code>meson install</code> description</a> for more info.</p>
<p>Note that Meson will only install build targets explicitly tagged as
installable, as detailed in the <a href="Installing.html">installing targets
documentation</a>.</p>
<p>By default Meson installs to <code>/usr/local</code>. This can be changed by
passing the command line argument <code>--prefix /your/prefix</code> to Meson
during configure time. Meson also supports the <code>DESTDIR</code> variable used
in e.g. building packages. It is used like this:</p>
<pre><code class="language-sh">DESTDIR=/path/to/staging meson install -C builddir
</code></pre>
<p>Note: it can be also invoked directly with ninja with the following
command:</p>
<pre><code class="language-sh">ninja -C builddir install
</code></pre>
<h2 id="command-line-help">Command line help</h2>
<p>Meson has a standard command line help feature. It can be accessed
with the following command.</p>
<pre><code>meson --help
</code></pre>
<h2 id="exit-status">Exit status</h2>
<p>Meson exits with status 0 if successful, 1 for problems with the
command line or meson.build file, and 2 for internal errors.</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/Running-Meson.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>