The Meson Build System http://mesonbuild.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

354 lines
8.5 KiB

# 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
{{ configure_usage.inc }}
Changes options of a configured meson project.
{{ configure_arguments.inc }}
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)*
{{ compile_usage.inc }}
Builds a default or a specified target of a configured Meson project.
{{ compile_arguments.inc }}
`--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 omitted 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)*
{{ dist_usage.inc }}
Generates a release archive from the current source tree.
{{ dist_arguments.inc }}
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)*
{{ init_usage.inc }}
Creates a basic set of build files based on a template.
{{ init_arguments.inc }}
#### Examples:
Create a project in `sourcedir`:
```
meson init -C sourcedir
```
### env2mfile
*This command is experimental and subject to change.*
*{Since 0.62.0}*
{{ env2mfile_usage.inc }}
Create native and cross files from the current environment, typically
by sniffing environment variables like `CC` and `CFLAGS`.
{{ env2mfile_arguments.inc }}
#### Examples:
Autodetect the current cross build environment:
```
meson env2mfile --cross -o current_cross.txt --cpu=arm7a --cpu-family=arm --system=linux
```
Generate a cross build using Debian system information:
```
meson env2mfile --cross --debarch=armhf -o deb_arm_cross.txt
```
### introspect
{{ introspect_usage.inc }}
Displays information about a configured Meson project.
{{ introspect_arguments.inc }}
#### Examples:
Display basic information about a configured project in `builddir`:
```
meson introspect builddir --projectinfo
```
### install
*(since 0.47.0)*
{{ install_usage.inc }}
Installs the project to the prefix specified in [`setup`](#setup).
{{ install_arguments.inc }}
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
```
Since *0.60.0* `DESTDIR` and `--destdir` can be a path relative to build
directory. An absolute path will be set into environment when executing scripts.
### rewrite
*(since 0.50.0)*
{{ rewrite_usage.inc }}
Modifies the Meson project.
{{ rewrite_arguments.inc }}
See [the Meson file rewriter documentation](Rewriter.md) for more info.
### setup
{{ setup_usage.inc }}
Configures a build directory for the Meson project.
This is the default Meson command (invoked if there was no COMMAND supplied).
{{ setup_arguments.inc }}
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)*
{{ subprojects_usage.inc }}
Manages subprojects of the Meson project. *Since 0.59.0* commands are run on
multiple subprojects in parallel by default, use `--num-processes=1` if it is
not desired.
{{ subprojects_arguments.inc }}
### test
{{ test_usage.inc }}
Run tests for the configure Meson project.
{{ test_arguments.inc }}
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
{{ wrap_usage.inc }}
An utility to manage WrapDB dependencies.
{{ wrap_arguments.inc }}
See [the WrapDB tool documentation](Using-wraptool.md) for more info.
### devenv
*(since 0.58.0)*
{{ devenv_usage.inc }}
Runs a command, or open interactive shell if no command is provided, with
environment setup to run project from the build directory, without installation.
We automatically handle `bash` and set `$PS1` accordingly. If the automatic `$PS1`
override is not desired (maybe you have a fancy custom prompt), set the
`$MESON_DISABLE_PS1_OVERRIDE` environment variable and use `$MESON_PROJECT_NAME`
when setting the custom prompt, for example with a snippet like the following:
```bash
...
if [[ -n "${MESON_PROJECT_NAME-}" ]];
then
PS1+="[ ${MESON_PROJECT_NAME} ]"
fi
...
```
These variables are set in environment in addition to those set using `meson.add_devenv()`:
- `MESON_DEVENV` is defined to `'1'`.
- `MESON_PROJECT_NAME` is defined to the main project's name.
- `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
files.
- `PATH` includes every directory where there is an executable that would be
installed into `bindir`. On windows it also includes every directory where there
is a DLL needed to run those executables.
- `LD_LIBRARY_PATH` includes every directory where there is a shared library that
would be installed into `libdir`. This allows to run system application using
custom build of some libraries. For example running system GEdit when building
GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
`PATH` on Windows.
- `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
typelib is built. This is automatically set when using `gnome.generate_gir()`.
- `GSETTINGS_SCHEMA_DIR` *Since 0.59.0* includes every directory where a GSettings
schemas is compiled. This is automatically set when using `gnome.compile_schemas()`.
Note that this requires GLib >= 2.64 when `gnome.compile_schemas()` is used in
more than one directory.
Since *Since 0.62.0* if bash-completion scripts are being installed and the
shell is bash, they will be automatically sourced.
Since *Since 0.62.0* when GDB helper scripts (*-gdb.py, *-gdb.gdb, and *-gdb.csm)
are installed with a library name that matches one being built, Meson adds the
needed auto-load commands into `<builddir>/.gdbinit` file. When running gdb from
top build directory, that file is loaded by gdb automatically. In the case of
python scripts that needs to load other python modules, `PYTHONPATH` may need
to be modified using `meson.add_devenv()`.
{{ devenv_arguments.inc }}