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, followed by compile, and then
install.
For the full list of all available options for a specific command use
the following syntax: meson COMMAND --help
configure
$ meson configure [-h] [--prefix PREFIX] [--bindir BINDIR]
[--datadir DATADIR] [--includedir INCLUDEDIR]
[--infodir INFODIR] [--libdir LIBDIR]
[--licensedir LICENSEDIR] [--libexecdir LIBEXECDIR]
[--localedir LOCALEDIR] [--localstatedir LOCALSTATEDIR]
[--mandir MANDIR] [--sbindir SBINDIR]
[--sharedstatedir SHAREDSTATEDIR]
[--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}]
[--genvslite {vs2022}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--default-both-libraries {shared,static,auto}]
[--errorlogs] [--install-umask INSTALL_UMASK]
[--layout {mirror,flat}]
[--optimization {plain,0,g,1,2,3,s}] [--prefer-static]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE]
[--warnlevel {0,1,2,3,everything}] [--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}]
[--force-fallback-for FORCE_FALLBACK_FOR] [--vsenv]
[--pkgconfig.relocatable]
[--python.bytecompile PYTHON.BYTECOMPILE]
[--python.install-env {auto,prefix,system,venv}]
[--python.platlibdir PYTHON.PLATLIBDIR]
[--python.purelibdir PYTHON.PURELIBDIR]
[--python.allow-limited-api]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--clearcache] [--no-pager]
[builddir]
Changes options of a configured meson project.
positional arguments:
builddir
options:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--licensedir LICENSEDIR Licenses directory (default: ).
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}
Backend to use (default: ninja).
--genvslite {vs2022} Setup multiple buildtype-suffixed ninja-
backend build directories, and a
[builddir]_vs containing a Visual Studio
meta-backend with multiple
configurations that calls into them
(default: vs2022).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Enable debug symbols and other
information
--default-library {shared,static,both}
Default library type (default: shared).
--default-both-libraries {shared,static,auto}
Default library type for both_libraries
(default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 022).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {plain,0,g,1,2,3,s} Optimization level (default: 0).
--prefer-static Whether to try static linking before
shared linking
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: (2, None,
4)).
--warnlevel {0,1,2,3,everything} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--vsenv Activate Visual Studio environment
--pkgconfig.relocatable Generate pkgconfig files as relocatable
--python.bytecompile PYTHON.BYTECOMPILE
Whether to compile bytecode (default:
(-1, 2, 0)).
--python.install-env {auto,prefix,system,venv}
Which python environment to install to
(default: prefix).
--python.platlibdir PYTHON.PLATLIBDIR
Directory for site-specific, platform-
specific files (default: ).
--python.purelibdir PYTHON.PURELIBDIR
Directory for site-specific, non-
platform-specific files (default: ).
--python.allow-limited-api Whether to allow use of the Python
Limited API
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--clearcache Clear cached state (e.g. found
dependencies)
--no-pager Do not redirect output to a pager
Most arguments are the same as in 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)
$ meson compile [-h] [--clean] [-C WD] [-j JOBS] [-l LOAD_AVERAGE] [-v]
[--ninja-args NINJA_ARGS] [--vs-args VS_ARGS]
[--xcode-args XCODE_ARGS]
[TARGET ...]
Builds a default or a specified target of a configured Meson project.
positional arguments:
TARGET Targets to build. Target has the
following format: [PATH_TO_TARGET/]TARGE
T_NAME.TARGET_SUFFIX[:TARGET_TYPE].
options:
-h, --help show this help message and exit
--clean Clean the build directory.
-C WD directory to cd into before running
-j JOBS, --jobs JOBS The number of worker jobs to run (if
supported). If the value is less than 1
the build program will guess.
-l LOAD_AVERAGE, --load-average LOAD_AVERAGE
The system load average to try to
maintain (if supported).
-v, --verbose Show more verbose output.
--ninja-args NINJA_ARGS Arguments to pass to `ninja` (applied
only on `ninja` backend).
--vs-args VS_ARGS Arguments to pass to `msbuild` (applied
only on `vs` backend).
--xcode-args XCODE_ARGS Arguments to pass to `xcodebuild`
(applied only on `xcode` backend).
--verbose argument is available since 0.55.0.
Targets
(since 0.55.0)
TARGET has the following syntax [PATH/]NAME.SUFFIX[:TYPE], where:
-
NAME: name of the target frommeson.build(e.g.foofromexecutable('foo', ...)). -
SUFFIX: name of the suffix of the target frommeson.build(e.g.exefromexecutable('foo', suffix: 'exe', ...)). -
PATH: path to the target relative to the rootmeson.buildfile. Note: relative path for a target specified in the rootmeson.buildis./. -
TYPE: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'alias', 'run', 'jar'.
PATH, SUFFIX, and TYPE can all be omitted if the resulting TARGET can be
used to uniquely identify the target in meson.build.
Note that SUFFIX did not exist prior to 1.3.0.
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):
ninja coverage-html
dist
(since 0.52.0)
$ meson dist [-h] [-C WD] [--allow-dirty] [--formats FORMATS]
[--include-subprojects] [--no-tests]
Generates a release archive from the current source tree.
options:
-h, --help show this help message and exit
-C WD directory to cd into before running
--allow-dirty Allow even when repository contains uncommitted
changes.
--formats FORMATS Comma separated list of archive types to create.
Supports xztar (default), bztar, gztar, and zip.
--include-subprojects Include source code of subprojects that have been used
for the build.
--no-tests Do not build and test generated packages.
See notes about creating releases for more info.
Examples:
Create a release archive:
meson dist -C builddir
init
(since 0.45.0)
$ meson init [-h] [-C WD] [-n NAME] [-e EXECUTABLE] [-d DEPS]
[-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}] [-b]
[--builddir BUILDDIR] [-f] [--type {executable,library}]
[--version VERSION]
[sourcefile ...]
Creates a basic set of build files based on a template.
positional arguments:
sourcefile source files. default: all recognized
files in current directory
options:
-h, --help show this help message and exit
-C WD directory to cd into before running
-n NAME, --name NAME project name. default: name of current
directory
-e EXECUTABLE, --executable EXECUTABLE
executable name. default: project name
-d DEPS, --deps DEPS dependencies, comma-separated
-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}, --language {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}
project language. default: autodetected
based on source files
-b, --build build after generation
--builddir BUILDDIR directory for build
-f, --force force overwrite of existing files and
directories.
--type {executable,library} project type. default: executable based
project
--version VERSION project version. default: 0.1
Examples:
Create a project in sourcedir:
meson init -C sourcedir
env2mfile
This command is experimental and subject to change.
{Since 0.62.0}
$ meson env2mfile [-h] [--debarch DEBARCH] [--gccsuffix GCCSUFFIX] -o
OUTFILE [--cross] [--native] [--use-for-build]
[--system SYSTEM] [--subsystem SUBSYSTEM]
[--kernel KERNEL] [--cpu CPU] [--cpu-family CPU_FAMILY]
[--endian {big,little}]
Create native and cross files from the current environment, typically
by sniffing environment variables like CC and CFLAGS.
options:
-h, --help show this help message and exit
--debarch DEBARCH The dpkg architecture to generate.
--gccsuffix GCCSUFFIX A particular gcc version suffix if necessary.
-o OUTFILE The output file.
--cross Generate a cross compilation file.
--native Generate a native compilation file.
--use-for-build Use _FOR_BUILD envvars.
--system SYSTEM Define system for cross compilation.
--subsystem SUBSYSTEM Define subsystem for cross compilation.
--kernel KERNEL Define kernel for cross compilation.
--cpu CPU Define cpu for cross compilation.
--cpu-family CPU_FAMILY Define cpu family for cross compilation.
--endian {big,little} Define endianness for cross compilation.
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
$ meson introspect [-h] [--ast] [--benchmarks] [--buildoptions]
[--buildsystem-files] [--compilers] [--dependencies]
[--scan-dependencies] [--installed] [--install-plan]
[--machines] [--projectinfo] [--targets] [--tests]
[--backend {ninja,none,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode}]
[-a] [-i] [-f]
[builddir]
Displays information about a configured Meson project.
positional arguments:
builddir The build directory
options:
-h, --help show this help message and exit
--ast Dump the AST of the meson file.
--benchmarks List all benchmarks.
--buildoptions List all build options.
--buildsystem-files List files that make up the build
system.
--compilers List used compilers.
--dependencies List external dependencies.
--scan-dependencies Scan for dependencies used in the
meson.build file.
--installed List all installed files and
directories.
--install-plan List all installed files and directories
with their details.
--machines Information about host, build, and
target machines.
--projectinfo Information about projects.
--targets List top level targets.
--tests List all unit tests.
--backend {ninja,none,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode}
The backend to use for the
--buildoptions introspection.
-a, --all Print all available information.
-i, --indent Enable pretty printed JSON.
-f, --force-object-output Always use the new JSON format for
multiple entries (even for 0 and 1
introspection commands)
Examples:
Display basic information about a configured project in builddir:
meson introspect builddir --projectinfo
install
(since 0.47.0)
$ meson install [-h] [-C WD] [--no-rebuild] [--only-changed] [-q]
[--destdir DESTDIR] [-n]
[--skip-subprojects [SKIP_SUBPROJECTS]] [--tags TAGS]
[--strip]
Installs the project to the prefix specified in setup.
options:
-h, --help show this help message and exit
-C WD directory to cd into before running
--no-rebuild Do not rebuild before installing.
--only-changed Only overwrite files that are older than
the copied file.
-q, --quiet Do not print every file that was
installed.
--destdir DESTDIR Sets or overrides DESTDIR environment.
(Since 0.57.0)
-n, --dry-run Doesn't actually install, but print
logs. (Since 0.57.0)
--skip-subprojects [SKIP_SUBPROJECTS]
Do not install files from given
subprojects. (Since 0.58.0)
--tags TAGS Install only targets having one of the
given tags. (Since 0.60.0)
--strip Strip targets even if strip option was
not set during configure. (Since 0.62.0)
See the installation documentation 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.
reprotest
(since 1.6.0)
$ meson reprotest [-h] [--intermediaries] [mesonargs ...]
Simple reproducible build tester that compiles the project twice and checks whether the end results are identical.
This command must be run in the source root of the project you want to test.
positional arguments:
mesonargs Arguments to pass to "meson setup".
options:
-h, --help show this help message and exit
--intermediaries Check intermediate files.
Examples
meson reprotest
Builds the current project with its default settings.
meson reprotest --intermediaries -- --buildtype=debugoptimized
Builds the target and also checks that all intermediate files like
object files are also identical. All command line arguments after the
-- are passed directly to the underlying meson invocation. Only
use option arguments, i.e. those that start with a dash, Meson sets
directory arguments automatically.
rewrite
(since 0.50.0)
$ meson rewrite [-h] [-s SRCDIR] [-V] [-S]
{target,tgt,kwargs,default-options,def,command,cmd} ...
Modifies the Meson project.
options:
-h, --help show this help message and exit
-s SRCDIR, --sourcedir SRCDIR Path to source directory.
-V, --verbose Enable verbose output
-S, --skip-errors Skip errors instead of aborting
Rewriter commands:
Rewrite command to execute
{target,tgt,kwargs,default-options,def,command,cmd}
target (tgt) Modify a target
kwargs Modify keyword arguments
default-options (def) Modify the project default options
command (cmd) Execute a JSON array of commands
See the Meson file rewriter documentation for more info.
setup
$ meson setup [-h] [--prefix PREFIX] [--bindir BINDIR] [--datadir DATADIR]
[--includedir INCLUDEDIR] [--infodir INFODIR]
[--libdir LIBDIR] [--licensedir LICENSEDIR]
[--libexecdir LIBEXECDIR] [--localedir LOCALEDIR]
[--localstatedir LOCALSTATEDIR] [--mandir MANDIR]
[--sbindir SBINDIR] [--sharedstatedir SHAREDSTATEDIR]
[--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}]
[--genvslite {vs2022}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--default-both-libraries {shared,static,auto}] [--errorlogs]
[--install-umask INSTALL_UMASK] [--layout {mirror,flat}]
[--optimization {plain,0,g,1,2,3,s}] [--prefer-static]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3,everything}]
[--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}]
[--force-fallback-for FORCE_FALLBACK_FOR] [--vsenv]
[--pkgconfig.relocatable]
[--python.bytecompile PYTHON.BYTECOMPILE]
[--python.install-env {auto,prefix,system,venv}]
[--python.platlibdir PYTHON.PLATLIBDIR]
[--python.purelibdir PYTHON.PURELIBDIR]
[--python.allow-limited-api]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--native-file NATIVE_FILE]
[--cross-file CROSS_FILE] [-v] [--fatal-meson-warnings]
[--reconfigure] [--wipe] [--clearcache]
[builddir] [sourcedir]
Configures a build directory for the Meson project.
Deprecated since 0.64.0: This is the default Meson command (invoked if there was no COMMAND supplied). However, supplying the command is necessary to avoid clashes with future added commands, so "setup" should be used explicitly.
Since 1.1.0 --reconfigure is allowed even if the build directory does not
already exist, that argument is ignored in that case.
Since 1.3.0 If the build directory already exists, options are updated with
their new value given on the command line (-Dopt=value). Unless --reconfigure
is also specified, this won't reconfigure immediately. This has the same behaviour
as meson configure <builddir> -Dopt=value.
Since 1.3.0 It is possible to clear the cache and reconfigure in a single command
with meson setup --clearcache --reconfigure <builddir>.
positional arguments:
builddir
sourcedir
options:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--licensedir LICENSEDIR Licenses directory (default: ).
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}
Backend to use (default: ninja).
--genvslite {vs2022} Setup multiple buildtype-suffixed ninja-
backend build directories, and a
[builddir]_vs containing a Visual Studio
meta-backend with multiple
configurations that calls into them
(default: vs2022).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Enable debug symbols and other
information
--default-library {shared,static,both}
Default library type (default: shared).
--default-both-libraries {shared,static,auto}
Default library type for both_libraries
(default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 022).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {plain,0,g,1,2,3,s} Optimization level (default: 0).
--prefer-static Whether to try static linking before
shared linking
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: (2, None,
4)).
--warnlevel {0,1,2,3,everything} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--vsenv Activate Visual Studio environment
--pkgconfig.relocatable Generate pkgconfig files as relocatable
--python.bytecompile PYTHON.BYTECOMPILE
Whether to compile bytecode (default:
(-1, 2, 0)).
--python.install-env {auto,prefix,system,venv}
Which python environment to install to
(default: prefix).
--python.platlibdir PYTHON.PLATLIBDIR
Directory for site-specific, platform-
specific files (default: ).
--python.purelibdir PYTHON.PURELIBDIR
Directory for site-specific, non-
platform-specific files (default: ).
--python.allow-limited-api Whether to allow use of the Python
Limited API
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--native-file NATIVE_FILE File containing overrides for native
compilation environment.
--cross-file CROSS_FILE File describing cross compilation
environment.
-v, --version show program's version number and exit
--fatal-meson-warnings Make all Meson warnings fatal
--reconfigure Set options and reconfigure the project.
Useful when new options have been added
to the project and the default value is
not working.
--wipe Wipe build directory and reconfigure
using previous command line options.
Useful when build directory got
corrupted, or when rebuilding with a
newer version of meson.
--clearcache Clear cached state (e.g. found
dependencies). Since 1.3.0.
See Meson introduction page for more info.
Examples:
Configures builddir with default values:
meson setup builddir
subprojects
(since 0.49.0)
$ meson subprojects [-h]
{update,checkout,download,foreach,purge,packagefiles}
...
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.
Since 0.64.0 the update subcommand will not download new wrap files
from WrapDB any more. Use meson wrap update command for that instead.
options:
-h, --help show this help message and exit
Commands:
{update,checkout,download,foreach,purge,packagefiles}
update Update all subprojects from wrap files
checkout Checkout a branch (git only)
download Ensure subprojects are fetched, even if
not in use. Already downloaded
subprojects are not modified. This can
be used to pre-fetch all subprojects and
avoid downloads during configure.
foreach Execute a command in each subproject
directory.
purge Remove all wrap-based subproject
artifacts
packagefiles Manage the packagefiles overlay
test
$ meson test [-h] [--maxfail MAXFAIL] [--repeat REPEAT] [--no-rebuild]
[--gdb] [--gdb-path GDB_PATH] [-i] [--list]
[--wrapper WRAPPER] [-C WD] [--suite SUITE] [--no-suite SUITE]
[--no-stdsplit] [--print-errorlogs] [--benchmark]
[--logbase LOGBASE] [-j NUM_PROCESSES] [-v] [-q]
[-t TIMEOUT_MULTIPLIER] [--setup SETUP]
[--test-args TEST_ARGS] [--max-lines MAX_LINES]
[args ...]
Run tests for the configure Meson project.
positional arguments:
args Optional list of test names to run.
"testname" to run all tests with that
name, "subprojname:testname" to
specifically run "testname" from
"subprojname", "subprojname:" to run all
tests defined by "subprojname".
options:
-h, --help show this help message and exit
--maxfail MAXFAIL Number of failing tests before aborting
the test run. (default: 0, to disable
aborting on failure)
--repeat REPEAT Number of times to run the tests.
--no-rebuild Do not rebuild before running tests.
--gdb Run test under gdb.
--gdb-path GDB_PATH Path to the gdb binary (default: gdb).
-i, --interactive Run tests with interactive input/output.
--list List available tests.
--wrapper WRAPPER wrapper to run tests with (e.g.
Valgrind)
-C WD directory to cd into before running
--suite SUITE Only run tests belonging to the given
suite.
--no-suite SUITE Do not run tests belonging to the given
suite.
--no-stdsplit Do not split stderr and stdout in test
logs.
--print-errorlogs Whether to print failing tests' logs.
--benchmark Run benchmarks instead of tests.
--logbase LOGBASE Base name for log file.
-j NUM_PROCESSES, --num-processes NUM_PROCESSES
How many parallel processes to use.
-v, --verbose Do not redirect stdout and stderr
-q, --quiet Produce less output to the terminal.
-t TIMEOUT_MULTIPLIER, --timeout-multiplier TIMEOUT_MULTIPLIER
Define a multiplier for test timeout,
for example when running tests in
particular conditions they might take
more time to execute. (<= 0 to disable
timeout)
--setup SETUP Which test setup to use.
--test-args TEST_ARGS Arguments to pass to the specified
test(s) or all tests
--max-lines MAX_LINES Maximum number of lines to show from a
long test log. Since 1.5.0.
See the unit test documentation for more info.
Since 1.2.0 you can use wildcards in args for test names. For example, "bas*" will match all test with names beginning with "bas".
Since 1.2.0 it is an error to provide a test name or wildcard that does not match any test.
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
$ meson wrap [-h]
{list,search,install,update,info,status,promote,update-db} ...
An utility to manage WrapDB dependencies.
options:
-h, --help show this help message and exit
Commands:
{list,search,install,update,info,status,promote,update-db}
list show all available projects
search search the db by name
install install the specified project
update Update wrap files from WrapDB (Since
0.63.0)
info show available versions of a project
status show installed and available versions of
your projects
promote bring a subsubproject up to the master
project
update-db Update list of projects available in
WrapDB (Since 0.61.0)
See the WrapDB tool documentation for more info.
devenv
(since 0.58.0)
$ meson devenv [-h] [-C BUILDDIR] [--workdir WORKDIR] [--dump [DUMP]]
[--dump-format {sh,export,vscode}]
...
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:
...
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_DEVENVis defined to'1'. -
MESON_PROJECT_NAMEis defined to the main project's name. -
PKG_CONFIG_PATHincludes the directory where Meson generates-uninstalled.pcfiles. -
PATHincludes every directory where there is an executable that would be installed intobindir. On windows it also includes every directory where there is a DLL needed to run those executables. -
LD_LIBRARY_PATHincludes every directory where there is a shared library that would be installed intolibdir. 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 isDYLD_LIBRARY_PATHandPATHon Windows. -
GI_TYPELIB_PATHincludes every directory where a GObject Introspection typelib is built. This is automatically set when usinggnome.generate_gir(). -
GSETTINGS_SCHEMA_DIRSince 0.59.0 includes every directory where a GSettings schemas is compiled. This is automatically set when usinggnome.compile_schemas(). Note that this requires GLib >= 2.64 whengnome.compile_schemas()is used in more than one directory. -
QEMU_LD_PREFIXSince 1.0.0 is set to thesys_rootvalue from cross file when cross compiling and that property is defined.
Since 0.62.0 if bash-completion scripts are being installed and the shell is bash, they will be automatically sourced.
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().
Since 0.63.0 when cross compiling for Windows WINEPATH is used instead
of PATH which allows running Windows executables using wine. Note that since
WINEPATH size is currently limited to 1024 characters, paths relative to the
root of build directory are used. That means current workdir must be the root of
build directory when running wine.
Since 1.1.0 meson devenv --dump [<filename>] command takes an optional
filename argument to write the environment into a file instead of printing to
stdout.
Since 1.1.0 --dump-format argument has been added to select which shell
format should be used. There are currently 3 formats supported:
-
sh: Lines are in the formatVAR=/prepend:$VAR:/append. -
export: Same asshbut with extraexport VARlines. -
vscode: Same asshbut without$VARsubstitution because they do not seems to be properly supported by vscode.
positional arguments:
command Command to run in developer environment
(default: interactive shell)
options:
-h, --help show this help message and exit
-C BUILDDIR Path to build directory
--workdir WORKDIR, -w WORKDIR Directory to cd into before running
(default: builddir, Since 1.0.0)
--dump [DUMP] Only print required environment (Since
0.62.0) Takes an optional file path (Since
1.1.0)
--dump-format {sh,export,vscode} Format used with --dump (Since 1.1.0)
format
(since 1.5.0)
$ meson format [-h] [-q | -i] [-r] [-c meson.format] [-e] [-o OUTPUT]
[sources ...]
Format specified meson.build documents. For compatibility with muon, fmt
is an alias to format.
positional arguments:
sources meson source files
options:
-h, --help show this help message and exit
-q, --check-only exit with 1 if files would be modified
by meson format
-i, --inplace format files in-place
-r, --recursive recurse subdirs (requires --check-only
or --inplace option)
-c meson.format, --configuration meson.format
read configuration from meson.format
-e, --editor-config try to read configuration from
.editorconfig
-o OUTPUT, --output OUTPUT output file (implies having exactly one
input)
The configuration file is a .ini file. If a meson.format file exists
beside the provided build file to analyze, and no configuration file is
provided on the command line, the meson.format file is automatically used.
If no build file is provided on the command line, the meson.build file in
current directory is analyzed.
The following options are recognized:
- max_line_length (int): When an array, a dict, a function or a method would be longer that this, it is formatted one argument per line (Default is 80).
- indent_by (str): Indentation to use (Default is four spaces
' '). - space_array (bool): Whether to add spaces between
[]and array arguments (default is false). - kwargs_force_multiline (bool): If true, arguments are formatted one per line as soon as there is a keyword argument (default is false).
- wide_colon (bool): If true, a space is placed before colon in dict and in keyword arguments (default is false).
- no_single_comma_function (bool): If true, a comma is never appended to function arguments if there is only one argument, even if using multiline arguments (default is false).
- end_of_line ('cr', 'lf', 'crlf', 'native'): Line ending to use
(applied when using
--outputor--inlineargument) (default is 'native). - indent_before_comments (str): Indentation to use before inline comments
(default is two spaces
' '). - simplify_string_literals (bool): When true, multiline strings are converted to single line strings if they don't contain newlines. Formatted strings are converted to normal strings if they don't contain substitutions (default is true).
- insert_final_newline (bool): If true, force the
meson.buildfile to end with a newline character (default is true). - tab_width (int): Width of tab stops, used to compute line length
when
indent_byuses tab characters (default is 4). - sort_files (bool): When true, arguments of
files()function are sorted alphabetically (default is false). - group_arg_value (bool): When true, string argument with
--prefix followed by string argument without--prefix are grouped on the same line, in multiline arguments (default is false). - use_editor_config (bool): When true, also uses config from .editorconfig .
The first six options are the same than for the muon fmt command.
It is also possible to use a .editorconfig file, by providing
the --editor-config option on the command line, or with the
use_editor_config option in the config file.
When --recursive option is specified, meson.build files from
subdir are also analyzed (must be used in conjunction with --inplace
or --check-only option).
Since 1.7.0 You can use - as source file name to read source from standard
input instead of reading it from a file. This cannot be used with --recursive
or --inline arguments.
Differences with muon fmt
The meson format command should be compatible with the muon fmt command.
However, it has more features, and some differences:
- By default,
meson formatput two spaces before inline comments, whilemuon fmtonly puts one. -
muon fmtcan potentially mix crlf and lf end-of-lines, as it is not aware of them.meson formatwill always be consistent in the output it produces. -
muon fmtonly recognize theindent_byoption from .editorconfig files.meson formatalso recognizesmax_line_length,end_of_line,insert_final_newlineandtab_widthoptions. -
meson formathas many additional format rules (see option list above).
The results of the search are