diff options
Diffstat (limited to 'docs/markdown_dynamic/Commands.md')
| -rw-r--r-- | docs/markdown_dynamic/Commands.md | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/docs/markdown_dynamic/Commands.md b/docs/markdown_dynamic/Commands.md new file mode 100644 index 0000000..a35b4da --- /dev/null +++ b/docs/markdown_dynamic/Commands.md @@ -0,0 +1,296 @@ +# 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. |