| # Command-line commands | |
| There are two different ways of invoking Meson. First, you can run it directly | |
| from the source tree with the command `/path/to/source/meson.py`. Meson may | |
| also be installed in which case the command is simply `meson`. In this manual | |
| we only use the latter format for simplicity. | |
| Meson is invoked using the following syntax: | |
| `meson [COMMAND] [COMMAND_OPTIONS]` | |
| This section describes all available commands and some of their Optional arguments. | |
| The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install). | |
| For the full list of all available options for a specific command use the following syntax: | |
| `meson COMMAND --help` | |
| ### configure | |
| ``` | |
| {{ cmd_help['configure']['usage'] }} | |
| ``` | |
| Changes options of a configured meson project. | |
| ``` | |
| {{ cmd_help['configure']['arguments'] }} | |
| ``` | |
| Most arguments are the same as in [`setup`](#setup). | |
| Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`). | |
| #### Examples: | |
| List all available options: | |
| ``` | |
| meson configure builddir | |
| ``` | |
| Change value of a single option: | |
| ``` | |
| meson configure builddir -Doption=new_value | |
| ``` | |
| ### compile | |
| *(since 0.54.0)* | |
| ``` | |
| {{ cmd_help['compile']['usage'] }} | |
| ``` | |
| Builds a default or a specified target of a configured meson project. | |
| ``` | |
| {{ cmd_help['compile']['arguments'] }} | |
| ``` | |
| `--verbose` argument is available since 0.55.0. | |
| #### Targets | |
| *(since 0.55.0)* | |
| `TARGET` has the following syntax `[PATH/]NAME[:TYPE]`, where: | |
| - `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`). | |
| - `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 `./`. | |
| - `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'. | |
| `PATH` and/or `TYPE` can be ommited if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`. | |
| #### Backend specific arguments | |
| *(since 0.55.0)* | |
| `BACKEND-args` use the following syntax: | |
| If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command: | |
| ``` | |
| $ meson compile --ninja-args=-n,-d,explain | |
| ``` | |
| would add `-n`, `-d` and `explain` arguments to ninja invocation. | |
| If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this: | |
| ``` | |
| $ meson compile "--ninja-args=['a,b', 'c d']" | |
| ``` | |
| #### Examples: | |
| Build the project: | |
| ``` | |
| meson compile -C builddir | |
| ``` | |
| Execute a dry run on ninja backend with additional debug info: | |
| ``` | |
| meson compile --ninja-args=-n,-d,explain | |
| ``` | |
| Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target: | |
| ``` | |
| meson compile foo:shared_library foo:static_library bar | |
| ``` | |
| Produce a coverage html report (if available): | |
| ``` | |
| meson compile coverage-html | |
| ``` | |
| ### dist | |
| *(since 0.52.0)* | |
| ``` | |
| {{ cmd_help['dist']['usage'] }} | |
| ``` | |
| Generates a release archive from the current source tree. | |
| ``` | |
| {{ cmd_help['dist']['arguments'] }} | |
| ``` | |
| See [notes about creating releases](Creating-releases.md) for more info. | |
| #### Examples: | |
| Create a release archive: | |
| ``` | |
| meson dist -C builddir | |
| ``` | |
| ### init | |
| *(since 0.45.0)* | |
| ``` | |
| {{ cmd_help['init']['usage'] }} | |
| ``` | |
| Creates a basic set of build files based on a template. | |
| ``` | |
| {{ cmd_help['init']['arguments'] }} | |
| ``` | |
| #### Examples: | |
| Create a project in `sourcedir`: | |
| ``` | |
| meson init -C sourcedir | |
| ``` | |
| ### introspect | |
| ``` | |
| {{ cmd_help['introspect']['usage'] }} | |
| ``` | |
| Displays information about a configured meson project. | |
| ``` | |
| {{ cmd_help['introspect']['arguments'] }} | |
| ``` | |
| #### Examples: | |
| Display basic information about a configured project in `builddir`: | |
| ``` | |
| meson introspect builddir | |
| ``` | |
| ### install | |
| *(since 0.47.0)* | |
| ``` | |
| {{ cmd_help['install']['usage'] }} | |
| ``` | |
| Installs the project to the prefix specified in [`setup`](#setup). | |
| ``` | |
| {{ cmd_help['install']['arguments'] }} | |
| ``` | |
| See [the installation documentation](Installing.md) for more info. | |
| #### Examples: | |
| Install project to `prefix`: | |
| ``` | |
| meson install -C builddir | |
| ``` | |
| Install project to `$DESTDIR/prefix`: | |
| ``` | |
| DESTDIR=/path/to/staging/area meson install -C builddir | |
| ``` | |
| ### rewrite | |
| *(since 0.50.0)* | |
| ``` | |
| {{ cmd_help['rewrite']['usage'] }} | |
| ``` | |
| Modifies the meson project. | |
| ``` | |
| {{ cmd_help['rewrite']['arguments'] }} | |
| ``` | |
| See [the meson file rewriter documentation](Rewriter.md) for more info. | |
| ### setup | |
| ``` | |
| {{ cmd_help['setup']['usage'] }} | |
| ``` | |
| Configures a build directory for the meson project. | |
| This is the default meson command (invoked if there was no COMMAND supplied). | |
| ``` | |
| {{ cmd_help['setup']['arguments'] }} | |
| ``` | |
| See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info. | |
| #### Examples: | |
| Configures `builddir` with default values: | |
| ``` | |
| meson setup builddir | |
| ``` | |
| ### subprojects | |
| *(since 0.49.0)* | |
| ``` | |
| {{ cmd_help['subprojects']['usage'] }} | |
| ``` | |
| Manages subprojects of the meson project. | |
| ``` | |
| {{ cmd_help['subprojects']['arguments'] }} | |
| ``` | |
| ### test | |
| ``` | |
| {{ cmd_help['test']['usage'] }} | |
| ``` | |
| Run tests for the configure meson project. | |
| ``` | |
| {{ cmd_help['test']['arguments'] }} | |
| ``` | |
| See [the unit test documentation](Unit-tests.md) for more info. | |
| #### Examples: | |
| Run tests for the project: | |
| ``` | |
| meson test -C builddir | |
| ``` | |
| Run only `specific_test_1` and `specific_test_2`: | |
| ``` | |
| meson test -C builddir specific_test_1 specific_test_2 | |
| ``` | |
| ### wrap | |
| ``` | |
| {{ cmd_help['wrap']['usage'] }} | |
| ``` | |
| An utility to manage WrapDB dependencies. | |
| ``` | |
| {{ cmd_help['wrap']['arguments'] }} | |
| ``` | |
| See [the WrapDB tool documentation](Using-wraptool.md) for more info. |