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 from meson.build (e.g. foo from executable('foo', ...)).
  • SUFFIX: name of the suffix of the target from meson.build (e.g. exe from executable('foo', suffix: 'exe', ...)).
  • 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', '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_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.
  • QEMU_LD_PREFIX Since 1.0.0 is set to the sys_root value 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 format VAR=/prepend:$VAR:/append.
  • export: Same as sh but with extra export VAR lines.
  • vscode: Same as sh but without $VAR substitution 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 --output or --inline argument) (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.build file to end with a newline character (default is true).
  • tab_width (int): Width of tab stops, used to compute line length when indent_by uses 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 format put two spaces before inline comments, while muon fmt only puts one.
  • muon fmt can potentially mix crlf and lf end-of-lines, as it is not aware of them. meson format will always be consistent in the output it produces.
  • muon fmt only recognize the indent_by option from .editorconfig files. meson format also recognizes max_line_length, end_of_line, insert_final_newline and tab_width options.
  • meson format has many additional format rules (see option list above).

The results of the search are