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