Debian Codegraph @

subprojects/meson-docs/docs/markdown/Commands.md

raw
1 # Command-line commands
2
3 There are two different ways of invoking Meson. First, you can run it
4 directly from the source tree with the command
5 `/path/to/source/meson.py`. Meson may also be installed in which case
6 the command is simply `meson`. In this manual we only use the latter
7 format for simplicity.
8
9 Meson is invoked using the following syntax:
10 `meson [COMMAND] [COMMAND_OPTIONS]`
11
12 This section describes all available commands and some of their
13 Optional arguments. The most common workflow is to run
14 [`setup`](#setup), followed by [`compile`](#compile), and then
15 [`install`](#install).
16
17 For the full list of all available options for a specific command use
18 the following syntax: `meson COMMAND --help`
19
20 ### configure
21
22 {{ configure_usage.inc }}
23
24 Changes options of a configured meson project.
25
26 {{ configure_arguments.inc }}
27
28 Most arguments are the same as in [`setup`](#setup).
29
30 Note: reconfiguring project will not reset options to their default
31 values (even if they were changed in `meson.build`).
32
33 #### Examples:
34
35 List all available options:
36 ```
37 meson configure builddir
38 ```
39
40 Change value of a single option:
41 ```
42 meson configure builddir -Doption=new_value
43 ```
44
45 ### compile
46
47 *(since 0.54.0)*
48
49 {{ compile_usage.inc }}
50
51 Builds a default or a specified target of a configured Meson project.
52
53 {{ compile_arguments.inc }}
54
55 `--verbose` argument is available since 0.55.0.
56
57 #### Targets
58
59 *(since 0.55.0)*
60
61 `TARGET` has the following syntax `[PATH/]NAME.SUFFIX[:TYPE]`, where:
62 - `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`).
63 - `SUFFIX`: name of the suffix of the target from `meson.build` (e.g. `exe` from `executable('foo', suffix: 'exe', ...)`).
64 - `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`.
65 - `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'alias', 'run', 'jar'.
66
67 `PATH`, `SUFFIX`, and `TYPE` can all be omitted if the resulting `TARGET` can be
68 used to uniquely identify the target in `meson.build`.
69
70 Note that `SUFFIX` did not exist prior to 1.3.0.
71
72 #### Backend specific arguments
73
74 *(since 0.55.0)*
75
76 `BACKEND-args` use the following syntax:
77
78 If you only pass a single string, then it is considered to have all
79 values separated by commas. Thus invoking the following command:
80
81 ```
82 $ meson compile --ninja-args=-n,-d,explain
83 ```
84
85 would add `-n`, `-d` and `explain` arguments to ninja invocation.
86
87 If you need to have commas or spaces in your string values, then you
88 need to pass the value with proper shell quoting like this:
89
90 ```
91 $ meson compile "--ninja-args=['a,b', 'c d']"
92 ```
93
94 #### Examples:
95
96 Build the project:
97 ```
98 meson compile -C builddir
99 ```
100
101 Execute a dry run on ninja backend with additional debug info:
102
103 ```
104 meson compile --ninja-args=-n,-d,explain
105 ```
106
107 Build three targets: two targets that have the same `foo` name, but
108 different type, and a `bar` target:
109
110 ```
111 meson compile foo:shared_library foo:static_library bar
112 ```
113
114 Produce a coverage html report (if available):
115
116 ```
117 ninja coverage-html
118 ```
119
120 ### dist
121
122 *(since 0.52.0)*
123
124 {{ dist_usage.inc }}
125
126 Generates a release archive from the current source tree.
127
128 {{ dist_arguments.inc }}
129
130 See [notes about creating releases](Creating-releases.md) for more info.
131
132 #### Examples:
133
134 Create a release archive:
135 ```
136 meson dist -C builddir
137 ```
138
139 ### init
140
141 *(since 0.45.0)*
142
143 {{ init_usage.inc }}
144
145 Creates a basic set of build files based on a template.
146
147 {{ init_arguments.inc }}
148
149 #### Examples:
150
151 Create a project in `sourcedir`:
152 ```
153 meson init -C sourcedir
154 ```
155
156 ### env2mfile
157
158 *This command is experimental and subject to change.*
159
160 *{Since 0.62.0}*
161
162 {{ env2mfile_usage.inc }}
163
164 Create native and cross files from the current environment, typically
165 by sniffing environment variables like `CC` and `CFLAGS`.
166
167 {{ env2mfile_arguments.inc }}
168
169 #### Examples:
170
171 Autodetect the current cross build environment:
172
173 ```
174 meson env2mfile --cross -o current_cross.txt --cpu=arm7a --cpu-family=arm --system=linux
175 ```
176
177 Generate a cross build using Debian system information:
178
179 ```
180 meson env2mfile --cross --debarch=armhf -o deb_arm_cross.txt
181 ```
182
183
184
185 ### introspect
186
187 {{ introspect_usage.inc }}
188
189 Displays information about a configured Meson project.
190
191 {{ introspect_arguments.inc }}
192
193 #### Examples:
194
195 Display basic information about a configured project in `builddir`:
196
197 ```
198 meson introspect builddir --projectinfo
199 ```
200
201 ### install
202
203 *(since 0.47.0)*
204
205 {{ install_usage.inc }}
206
207 Installs the project to the prefix specified in [`setup`](#setup).
208
209 {{ install_arguments.inc }}
210
211 See [the installation documentation](Installing.md) for more info.
212
213 #### Examples:
214
215 Install project to `prefix`:
216 ```
217 meson install -C builddir
218 ```
219
220 Install project to `$DESTDIR/prefix`:
221 ```
222 DESTDIR=/path/to/staging/area meson install -C builddir
223 ```
224
225 Since *0.60.0* `DESTDIR` and `--destdir` can be a path relative to build
226 directory. An absolute path will be set into environment when executing scripts.
227
228 ### reprotest
229
230 *(since 1.6.0)*
231
232 {{ reprotest_usage.inc }}
233
234 Simple reproducible build tester that compiles the project twice and
235 checks whether the end results are identical.
236
237 This command must be run in the source root of the project you want to
238 test.
239
240 {{ reprotest_arguments.inc }}
241
242 #### Examples
243
244 meson reprotest
245
246 Builds the current project with its default settings.
247
248 meson reprotest --intermediaries -- --buildtype=debugoptimized
249
250 Builds the target and also checks that all intermediate files like
251 object files are also identical. All command line arguments after the
252 `--` are passed directly to the underlying `meson` invocation. Only
253 use option arguments, i.e. those that start with a dash, Meson sets
254 directory arguments automatically.
255
256 ### rewrite
257
258 *(since 0.50.0)*
259
260 {{ rewrite_usage.inc }}
261
262 Modifies the Meson project.
263
264 {{ rewrite_arguments.inc }}
265
266 See [the Meson file rewriter documentation](Rewriter.md) for more info.
267
268 ### setup
269
270 {{ setup_usage.inc }}
271
272 Configures a build directory for the Meson project.
273
274 *Deprecated since 0.64.0*: This is the default Meson command (invoked if there
275 was no COMMAND supplied). However, supplying the command is necessary to avoid
276 clashes with future added commands, so "setup" should be used explicitly.
277
278 *Since 1.1.0* `--reconfigure` is allowed even if the build directory does not
279 already exist, that argument is ignored in that case.
280
281 *Since 1.3.0* If the build directory already exists, options are updated with
282 their new value given on the command line (`-Dopt=value`). Unless `--reconfigure`
283 is also specified, this won't reconfigure immediately. This has the same behaviour
284 as `meson configure <builddir> -Dopt=value`.
285
286 *Since 1.3.0* It is possible to clear the cache and reconfigure in a single command
287 with `meson setup --clearcache --reconfigure <builddir>`.
288
289 {{ setup_arguments.inc }}
290
291 See [Meson introduction
292 page](Running-Meson.md#configuring-the-build-directory) for more info.
293
294 #### Examples:
295
296 Configures `builddir` with default values:
297 ```
298 meson setup builddir
299 ```
300
301 ### subprojects
302
303 *(since 0.49.0)*
304
305 {{ subprojects_usage.inc }}
306
307 Manages subprojects of the Meson project. *Since 0.59.0* commands are run on
308 multiple subprojects in parallel by default, use `--num-processes=1` if it is
309 not desired.
310
311 Since *0.64.0* the `update` subcommand will not download new wrap files
312 from WrapDB any more. Use `meson wrap update` command for that instead.
313
314 {{ subprojects_arguments.inc }}
315
316 ### test
317
318 {{ test_usage.inc }}
319
320 Run tests for the configure Meson project.
321
322 {{ test_arguments.inc }}
323
324 See [the unit test documentation](Unit-tests.md) for more info.
325
326 Since *1.2.0* you can use wildcards in *args* for test names.
327 For example, "bas*" will match all test with names beginning with "bas".
328
329 Since *1.2.0* it is an error to provide a test name or wildcard that
330 does not match any test.
331
332 #### Examples:
333
334 Run tests for the project:
335 ```
336 meson test -C builddir
337 ```
338
339 Run only `specific_test_1` and `specific_test_2`:
340 ```
341 meson test -C builddir specific_test_1 specific_test_2
342 ```
343
344 ### wrap
345
346 {{ wrap_usage.inc }}
347
348 An utility to manage WrapDB dependencies.
349
350 {{ wrap_arguments.inc }}
351
352 See [the WrapDB tool documentation](Using-wraptool.md) for more info.
353
354 ### devenv
355
356 *(since 0.58.0)*
357
358 {{ devenv_usage.inc }}
359
360 Runs a command, or open interactive shell if no command is provided, with
361 environment setup to run project from the build directory, without installation.
362
363 We automatically handle `bash` and set `$PS1` accordingly. If the automatic `$PS1`
364 override is not desired (maybe you have a fancy custom prompt), set the
365 `$MESON_DISABLE_PS1_OVERRIDE` environment variable and use `$MESON_PROJECT_NAME`
366 when setting the custom prompt, for example with a snippet like the following:
367
368 ```bash
369 ...
370 if [[ -n "${MESON_PROJECT_NAME-}" ]];
371 then
372 PS1+="[ ${MESON_PROJECT_NAME} ]"
373 fi
374 ...
375 ```
376
377 These variables are set in environment in addition to those set using [[meson.add_devenv]]:
378 - `MESON_DEVENV` is defined to `'1'`.
379 - `MESON_PROJECT_NAME` is defined to the main project's name.
380 - `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
381 files.
382 - `PATH` includes every directory where there is an executable that would be
383 installed into `bindir`. On windows it also includes every directory where there
384 is a DLL needed to run those executables.
385 - `LD_LIBRARY_PATH` includes every directory where there is a shared library that
386 would be installed into `libdir`. This allows to run system application using
387 custom build of some libraries. For example running system GEdit when building
388 GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
389 `PATH` on Windows.
390 - `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
391 typelib is built. This is automatically set when using `gnome.generate_gir()`.
392 - `GSETTINGS_SCHEMA_DIR` *Since 0.59.0* includes every directory where a GSettings
393 schemas is compiled. This is automatically set when using `gnome.compile_schemas()`.
394 Note that this requires GLib >= 2.64 when `gnome.compile_schemas()` is used in
395 more than one directory.
396 - `QEMU_LD_PREFIX` *Since 1.0.0* is set to the `sys_root` value from cross file
397 when cross compiling and that property is defined.
398
399 *Since 0.62.0* if bash-completion scripts are being installed and the
400 shell is bash, they will be automatically sourced.
401
402 *Since 0.62.0* when GDB helper scripts (*-gdb.py, *-gdb.gdb, and *-gdb.csm)
403 are installed with a library name that matches one being built, Meson adds the
404 needed auto-load commands into `<builddir>/.gdbinit` file. When running gdb from
405 top build directory, that file is loaded by gdb automatically. In the case of
406 python scripts that needs to load other python modules, `PYTHONPATH` may need
407 to be modified using `meson.add_devenv()`.
408
409 *Since 0.63.0* when cross compiling for Windows `WINEPATH` is used instead
410 of `PATH` which allows running Windows executables using wine. Note that since
411 `WINEPATH` size is currently limited to 1024 characters, paths relative to the
412 root of build directory are used. That means current workdir must be the root of
413 build directory when running wine.
414
415 *Since 1.1.0* `meson devenv --dump [<filename>]` command takes an optional
416 filename argument to write the environment into a file instead of printing to
417 stdout.
418
419 *Since 1.1.0* `--dump-format` argument has been added to select which shell
420 format should be used. There are currently 3 formats supported:
421 - `sh`: Lines are in the format `VAR=/prepend:$VAR:/append`.
422 - `export`: Same as `sh` but with extra `export VAR` lines.
423 - `vscode`: Same as `sh` but without `$VAR` substitution because they do not
424 seems to be properly supported by vscode.
425
426 {{ devenv_arguments.inc }}
427
428
429 ### format
430
431 *(since 1.5.0)*
432
433 {{ format_usage.inc }}
434
435 Format specified `meson.build` documents. For compatibility with `muon`, `fmt`
436 is an alias to `format`.
437
438 {{ format_arguments.inc }}
439
440 The configuration file is a `.ini` file. If a `meson.format` file exists
441 beside the provided build file to analyze, and no configuration file is
442 provided on the command line, the `meson.format` file is automatically used.
443
444 If no build file is provided on the command line, the `meson.build` file in
445 current directory is analyzed.
446
447 The following options are recognized:
448
449 - max_line_length (int): When an array, a dict, a function or a method
450 would be longer that this, it is formatted one argument per line
451 (Default is 80).
452 - indent_by (str): Indentation to use (Default is four spaces `' '`).
453 - space_array (bool): Whether to add spaces between `[]` and array
454 arguments (default is false).
455 - kwargs_force_multiline (bool): If true, arguments are formatted one per
456 line as soon as there is a keyword argument (default is false).
457 - wide_colon (bool): If true, a space is placed before colon in dict
458 and in keyword arguments (default is false).
459 - no_single_comma_function (bool): If true, a comma is never appended
460 to function arguments if there is only one argument, even if
461 using multiline arguments (default is false).
462 - end_of_line ('cr', 'lf', 'crlf', 'native'): Line ending to use
463 (applied when using `--output` or `--inline` argument) (default
464 is 'native).
465 - indent_before_comments (str): Indentation to use before inline comments
466 (default is two spaces `' '`).
467 - simplify_string_literals (bool): When true, multiline strings are
468 converted to single line strings if they don't contain newlines.
469 Formatted strings are converted to normal strings if they don't
470 contain substitutions (default is true).
471 - insert_final_newline (bool): If true, force the `meson.build` file
472 to end with a newline character (default is true).
473 - tab_width (int): Width of tab stops, used to compute line length
474 when `indent_by` uses tab characters (default is 4).
475 - sort_files (bool): When true, arguments of `files()` function are
476 sorted alphabetically (default is false).
477 - group_arg_value (bool): When true, string argument with `--` prefix
478 followed by string argument without `--` prefix are grouped on the
479 same line, in multiline arguments (default is false).
480 - use_editor_config (bool): When true, also uses config from .editorconfig .
481
482 The first six options are the same than for the `muon fmt` command.
483
484 It is also possible to use a `.editorconfig` file, by providing
485 the `--editor-config` option on the command line, or with the
486 `use_editor_config` option in the config file.
487
488 When `--recursive` option is specified, `meson.build` files from
489 `subdir` are also analyzed (must be used in conjunction with `--inplace`
490 or `--check-only` option).
491
492 *Since 1.7.0* You can use `-` as source file name to read source from standard
493 input instead of reading it from a file. This cannot be used with `--recursive`
494 or `--inline` arguments.
495
496
497 #### Differences with `muon fmt`
498
499 The `meson format` command should be compatible with the `muon fmt` command.
500 However, it has more features, and some differences:
501
502 - By default, `meson format` put two spaces before inline comments,
503 while `muon fmt` only puts one.
504 - `muon fmt` can potentially mix crlf and lf end-of-lines, as it is not aware
505 of them. `meson format` will always be consistent in the output it produces.
506 - `muon fmt` only recognize the `indent_by` option from .editorconfig files.
507 `meson format` also recognizes `max_line_length`, `end_of_line`,
508 `insert_final_newline` and `tab_width` options.
509 - `meson format` has many additional format rules (see option list above).