MESON(1) User Commands MESON(1)

meson - a high productivity build system

Meson is a build system designed to optimize programmer productivity. It aims to do this by providing simple, out-of-the-box support for modern software development tools and practices, such as unit tests, coverage reports, Valgrind, Ccache and the like.

The main Meson executable provides many subcommands to access all the functionality.

Using Meson is simple and follows the common two-phase process of most build systems. First you run Meson to configure your build:

meson setup [ options ] [ build directory ] [ source directory ]

Note that the build directory must be different from the source directory. Meson does not support building inside the source directory and attempting to do that leads to an error.

After a successful configuration step you can build the source by running the actual build command in the build directory. The default backend of Meson is Ninja, which can be invoked like this.

ninja [ target ]

You only need to run the Meson command once: when you first configure your build dir. After that you just run the build command. Meson will autodetect changes in your source tree and regenerate all files needed to build the project.

The setup command is the default operation. If no actual command is specified, Meson will assume you meant to do a setup. That means that you can set up a build directory without the setup command like this:

meson [ options ] [ build directory ] [ source directory ]

print version number
print command line help

meson configure provides a way to configure a Meson project from the command line. Its usage is simple:

meson configure [ build directory ] [ options to set ]

If build directory is omitted, the current directory is used instead.

If no parameters are set, meson configure will print the value of all build options to the console.

To set values, use the -D command line argument like this.

meson configure -Dopt1=value1 -Dopt2=value2

meson dist generates a release archive.

meson dist [ options ]

show this help message and exit
directory to cd into before running
Allow even when repository contains uncommitted changes.
Comma separated list of archive types to create. Supports xztar (default), gztar, and zip.
Include source code of subprojects that have been used for the build.
Do not build and test generated packages.

meson install installs the project.

meson install [ options ]

show this help message and exit
directory to cd into before running
Do not rebuild before installing.
Only overwrite files that are older than the copied file.
Do not print every file that was installed.
Sets or overrides DESTDIR environment. (Since 0.57.0)
Doesn't actually install, but print logs. (Since 0.57.0)
Do not install files from given subprojects. (Since 0.58.0)
Install only targets having one of the given tags. (Since 0.60.0)
Strip targets even if strip option was not set during configure. (Since 0.62.0)

Meson introspect is a command designed to make it simple to integrate with other tools, such as IDEs. The output of this command is in JSON.

meson introspect [ build directory ] [ option ]

If build directory is omitted, the current directory is used instead.

print all top level targets (executables, libraries, etc)
print the source files of the given target
print all files that make up the build system (meson.build, meson.options, meson_options.txt etc)
print all unit tests
print command line help

meson init creates a new project

meson init [ options ] [ sourcefile... ]

positional arguments:

source files. default: all recognized files in current directory

show this help message and exit
directory to cd into before running
project name. default: name of current directory
executable name. default: project name
dependencies, comma-separated
project language. default: autodetected based on source files
build after generation
directory for build
force overwrite of existing files and directories.
project type. default: executable based project
project version. default: 0.1

meson test is a helper tool for running test suites of projects using Meson. The default way of running tests is to invoke the default build command:

ninja [ test ]

meson test provides a richer set of tools for invoking tests.

meson test automatically rebuilds the necessary targets to run tests when used with the Ninja backend. Upon build failure, meson test will return an exit code of 125. This return code tells git bisect run to skip the current commit. Thus bisecting using git can be done conveniently like this.

git bisect run meson test -C build_dir

run tests as many times as specified
run tests under gdb
list all available tests
invoke all tests via the given wrapper (e.g. valgrind)
Change into the given directory before running tests (must be root of build directory).
run tests in this suite
do not run tests in this suite
do not split stderr and stdout in test logs
run benchmarks instead of tests
base of file name to use for writing test logs
how many parallel processes to use to run tests
do not redirect stdout and stderr
a multiplier to use for test timeout values (usually something like 100 for Valgrind)
use the specified test setup

Wraptool is a helper utility to manage source dependencies using the online wrapdb service.

meson wrap < command > [ options ]

You should run this command in the top level source directory of your project.

list all available projects
search projects by name
install a project with the given name
update the specified project to latest available version
show available versions of the specified project
show installed and available versions of currently used subprojects

meson subprojects is used to manage subprojects.

meson subprojects [ options ] [ command ]

show this help message and exit

Update all subprojects from wrap files
Checkout a branch (git only)
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.
Execute a command in each subproject directory.
Remove all wrap-based subproject artifacts
Manage the packagefiles overlay

meson rewrite modifies the project definition.

meson rewrite [ options ] [ command ]

show this help message and exit
Path to source directory.
Enable verbose output
Skip errors instead of aborting

Modify a target
Modify keyword arguments
Modify the project default options
Execute a JSON array of commands

meson compile builds the project.

meson compile [ options ] [ TARGET... ]

positional arguments:

Targets to build. Target has the following format: [PATH_TO_TARGET/]TARGET_NAME.TARGET_SUFFIX[:TARGET_TYPE].

show this help message and exit
Clean the build directory.
directory to cd into before running
The number of worker jobs to run (if supported). If the value is less than 1 the build program will guess.
The system load average to try to maintain (if supported).
Show more verbose output.
Arguments to pass to `ninja` (applied only on `ninja` backend).
Arguments to pass to `msbuild` (applied only on `vs` backend).
Arguments to pass to `xcodebuild` (applied only on `xcode` backend).

meson devenv runs commands in the developer environment.

meson devenv [ options ] [ command ]

positional arguments:

Command to run in developer environment (default: interactive shell)

show this help message and exit
Path to build directory
Directory to cd into before running (default: builddir, Since 1.0.0)
Only print required environment (Since 0.62.0) Takes an optional file path (Since 1.1.0)
Format used with --dump (Since 1.1.0)

meson env2mfile converts the current environment to a cross or native file.

meson env2mfile [ options ]

show this help message and exit
The dpkg architecture to generate.
A particular gcc version suffix if necessary.
The output file.
Generate a cross compilation file.
Generate a native compilation file.
Define system for cross compilation.
Define subsystem for cross compilation.
Define kernel for cross compilation.
Define cpu for cross compilation.
Define cpu family for cross compilation.
Define endianness for cross compilation.

meson format formats a meson source file.

meson format [ options ] [ sources... ]

positional arguments:

meson source files

show this help message and exit
exit with 1 if files would be modified by meson format
format files in-place
recurse subdirs (requires --check-only or --inplace option)
read configuration from meson.format
try to read configuration from .editorconfig
output file (implies having exactly one input)

0
Successful.
1
Usage error, or an error parsing or executing meson.build.
2
Internal error.
125
meson test could not rebuild the required targets.

http://mesonbuild.com/

https://wrapdb.mesonbuild.com/

July 2024 meson 1.5.1