# 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 ``` $ meson configure [-h] [--prefix PREFIX] [--bindir BINDIR] [--datadir DATADIR] [--includedir INCLUDEDIR] [--infodir INFODIR] [--libdir LIBDIR] [--libexecdir LIBEXECDIR] [--localedir LOCALEDIR] [--localstatedir LOCALSTATEDIR] [--mandir MANDIR] [--sbindir SBINDIR] [--sharedstatedir SHAREDSTATEDIR] [--sysconfdir SYSCONFDIR] [--auto-features {enabled,disabled,auto}] [--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}] [--buildtype {plain,debug,debugoptimized,release,minsize,custom}] [--debug] [--default-library {shared,static,both}] [--errorlogs] [--install-umask INSTALL_UMASK] [--layout {mirror,flat}] [--optimization {0,g,1,2,3,s}] [--stdsplit] [--strip] [--unity {on,off,subprojects}] [--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3}] [--werror] [--wrap-mode {default,nofallback,nodownload,forcefallback}] [--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] [builddir] ``` Changes options of a configured meson project. ``` positional arguments: builddir optional arguments: -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. --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,vs2015,vs2017,vs2019,xcode} Backend to use (default: ninja). --buildtype {plain,debug,debugoptimized,release,minsize,custom} Build type to use (default: debug). --debug Debug --default-library {shared,static,both} Default library type (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 {0,g,1,2,3,s} Optimization level (default: 0). --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} Compiler warning level to use (default: 1). --werror Treat warnings as errors --wrap-mode {default,nofallback,nodownload,forcefallback} Wrap mode (default: default). --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) ``` 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)* ``` $ meson compile [-h] [-j JOBS] [-l LOAD_AVERAGE] [--clean] [-C BUILDDIR] ``` Builds a default or a specified target of a configured meson project. ``` optional arguments: -h, --help show this help message and exit -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) --clean Clean the build directory. -C BUILDDIR The directory containing build files to be built. ``` #### Examples: Build the project: ``` meson compile -C builddir ``` ### dist *(since 0.52.0)* ``` $ meson dist [-h] [-C WD] [--formats FORMATS] [--include-subprojects] [--no-tests] ``` Generates a release archive from the current source tree. ``` optional arguments: -h, --help show this help message and exit -C WD directory to cd into before running --formats FORMATS Comma separated list of archive types to create. --include-subprojects Include source code of subprojects that have been used for the build. --no-tests Do not build and test generated packages. ``` This creates a file called `projectname-version.tar.xz` in the build tree subdirectory `meson-dist`. This archive contains the full contents of the latest commit in revision control including all the submodules (recursively). All revision control metadata is removed. Meson then takes this archive and tests that it works by doing a full compile + test + install cycle. If all these pass, Meson will then create a SHA-256 checksum file next to the archive. **Note**: Meson behaviour is different from Autotools. The Autotools "dist" target packages up the current source tree. Meson packages the latest revision control commit. The reason for this is that it prevents developers from doing accidental releases where the distributed archive does not match any commit in revision control (especially the one tagged for the release). #### 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}] [-b] [--builddir BUILDDIR] [-f] [--type {executable,library}] [--version VERSION] [sourcefile [sourcefile ...]] ``` Creates a basic set of build files based on a template. ``` positional arguments: sourcefile source files. default: all recognized files in current directory optional arguments: -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}, --language {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust} 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 ``` ### introspect ``` $ meson introspect [-h] [--ast] [--benchmarks] [--buildoptions] [--buildsystem-files] [--dependencies] [--scan-dependencies] [--installed] [--projectinfo] [--targets] [--tests] [--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}] [-a] [-i] [-f] [builddir] ``` Displays information about a configured meson project. ``` positional arguments: builddir The build directory optional arguments: -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. --dependencies List external dependencies. --scan-dependencies Scan for dependencies used in the meson.build file. --installed List all installed files and directories. --projectinfo Information about projects. --targets List top level targets. --tests List all unit tests. --backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,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 ``` ### install *(since 0.47.0)* ``` $ meson install [-h] [-C WD] [--no-rebuild] [--only-changed] [--quiet] ``` Installs the project to the prefix specified in `setup`. ``` optional arguments: -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. --quiet Do not print every file that was installed. ``` See [the installation documentation](Installing.md) for more info. #### Examples: Install project to `prefix` (see [`setup`](#setup)): ``` meson install -C builddir ``` Install project to `$DESTDIR/prefix`: ``` DESTDIR=/path/to/staging/area meson install -C builddir ``` ### rewrite *(since 0.50.0)* ``` $ meson rewrite [-h] [-s SRCDIR] [-V] [-S] {target,kwargs,default-options,command} ... ``` Modifies the meson project. ``` optional arguments: -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,kwargs,default-options,command} target Modify a target kwargs Modify keyword arguments default-options Modify the project default options command Execute a JSON array of commands ``` See [the meson file rewriter documentation](Rewriter.md) for more info. ### setup ``` $ meson setup [-h] [--prefix PREFIX] [--bindir BINDIR] [--datadir DATADIR] [--includedir INCLUDEDIR] [--infodir INFODIR] [--libdir LIBDIR] [--libexecdir LIBEXECDIR] [--localedir LOCALEDIR] [--localstatedir LOCALSTATEDIR] [--mandir MANDIR] [--sbindir SBINDIR] [--sharedstatedir SHAREDSTATEDIR] [--sysconfdir SYSCONFDIR] [--auto-features {enabled,disabled,auto}] [--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}] [--buildtype {plain,debug,debugoptimized,release,minsize,custom}] [--debug] [--default-library {shared,static,both}] [--errorlogs] [--install-umask INSTALL_UMASK] [--layout {mirror,flat}] [--optimization {0,g,1,2,3,s}] [--stdsplit] [--strip] [--unity {on,off,subprojects}] [--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3}] [--werror] [--wrap-mode {default,nofallback,nodownload,forcefallback}] [--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] [builddir] [sourcedir] ``` Configures a build directory for the meson project. This is the default meson command (invoked if there was no COMMAND supplied). ``` positional arguments: builddir sourcedir optional arguments: -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. --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,vs2015,vs2017,vs2019,xcode} Backend to use (default: ninja). --buildtype {plain,debug,debugoptimized,release,minsize,custom} Build type to use (default: debug). --debug Debug --default-library {shared,static,both} Default library type (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 {0,g,1,2,3,s} Optimization level (default: 0). --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} Compiler warning level to use (default: 1). --werror Treat warnings as errors --wrap-mode {default,nofallback,nodownload,forcefallback} Wrap mode (default: default). --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. ``` 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)* ``` $ meson subprojects [-h] {update,checkout,download,foreach} ... ``` Manages subprojects of the meson project. ``` optional arguments: -h, --help show this help message and exit Commands: {update,checkout,download,foreach} 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. ``` ### test ``` $ meson test [-h] [--repeat REPEAT] [--no-rebuild] [--gdb] [--gdb-path GDB_PATH] [--list] [--wrapper WRAPPER] [-C WD] [--suite SUITE] [--no-suite SUITE] [--no-stdsplit] [--print-errorlogs] [--benchmark] [--logbase LOGBASE] [--num-processes NUM_PROCESSES] [-v] [-q] [-t TIMEOUT_MULTIPLIER] [--setup SETUP] [--test-args TEST_ARGS] [args [args ...]] ``` Run tests for the configure meson project. ``` positional arguments: args Optional list of tests to run optional arguments: -h, --help show this help message and exit --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). --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. --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. --setup SETUP Which test setup to use. --test-args TEST_ARGS Arguments to pass to the specified test(s) or all tests ``` 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 ``` $ meson wrap [-h] {list,search,install,update,info,status,promote} ... ``` An utility to manage WrapDB dependencies. ``` optional arguments: -h, --help show this help message and exit Commands: {list,search,install,update,info,status,promote} list show all available projects search search the db by name install install the specified project update update the project to its newest available release 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 ``` See [the WrapDB tool documentation](Using-wraptool.md) for more info.