Running Meson

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. Second, Meson may also be installed in which case the command is simply meson. In this manual we only use the latter format for simplicity.

At the time of writing only a command line version of Meson is available. This means that Meson must be invoked using the terminal. If you wish to use the MSVC compiler, you need to run Meson under "Visual Studio command prompt".

All available Meson commands are listed on the commands reference page.

Configuring the build directory

Let us assume that we have a source tree that has a Meson build system. This means that at the topmost directory has a file called meson.build. We run the following commands to get the build started.

cd /path/to/source/root
meson setup builddir

We invoke Meson with the setup command, giving it the location of the build directory. Meson uses out of source builds.

Hint: The syntax of Meson is meson [command] [arguments] [options]. The setup command takes a builddir and a srcdir argument. If no srcdir is given Meson will deduce the srcdir based on pwd and the location of meson.build.

Meson then loads the build configuration file and writes the corresponding build backend in the build directory. By default Meson generates a debug build, which turns on basic warnings and debug information and disables compiler optimizations.

Additionally, the invocation can pass options to Meson. The list of options is documented here.

You can specify a different type of build with the --buildtype command line argument. It can have one of the following values.

value	meaning
plain	no extra build flags are used, even for compiler warnings, useful for distro packagers and other cases where you need to specify all arguments by yourself
debug	debug info is generated but the result is not optimized, this is the default
debugoptimized	debug info is generated and the code is optimized (on most compilers this means -g -O2)
release	full optimization, no debug info

The build directory is mandatory. The reason for this is that it simplifies the build process immensely. Meson will not, under any circumstances, write files inside the source directory (if it does, it is a bug and should be fixed). This means that the user does not need to add a bunch of files to their revision control's ignore list. It also means that you can create arbitrarily many build directories for any given source tree.

For example, if we wanted to test building the source code with the Clang compiler instead of the system default, we could just type the following commands:

cd /path/to/source/root
CC=clang CXX=clang++ meson setup buildclang

This separation is even more powerful if your code has multiple configuration options (such as multiple data backends). You can create a separate subdirectory for each of them. You can also have build directories for optimized builds, code coverage, static analysis and so on. They are all neatly separated and use the same source tree. Changing between different configurations is just a question of changing to the corresponding directory.

Unless otherwise mentioned, all following command line invocations are meant to be run in the source directory.

By default, Meson will use the Ninja backend to build your project. If you wish to use any of the other backends, you need to pass the corresponding argument during configuration time. As an example, here is how you would use Meson to generate a Visual Studio solution.

meson setup <build dir> --backend=vs

You can then open the generated solution with Visual Studio and compile it in the usual way. A list of backends can be obtained with meson setup --help.

Environment variables

Sometimes you want to add extra compiler flags, this can be done by passing them in environment variables when calling Meson. See the reference tables for a list of all the environment variables. Be aware however these environment variables are only used for the native compiler and will not affect the compiler used for cross-compiling, where the flags specified in the cross file will be used.

Furthermore it is possible to stop Meson from adding flags itself by using the --buildtype=plain option, in this case you must provide the full compiler and linker arguments needed.

Building from the source

To start the build, simply type the following command.

meson compile -C builddir

See meson compile description for more info.

Building directly with ninja

By default Meson uses the Ninja build system to actually build the code. To start the build, simply type the following command.

ninja -C builddir

The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself accordingly. You can override the amount of parallel processes used with the command line argument -j <num processes>.

It should be noted that after the initial configure step ninja is the only command you ever need to type to compile. No matter how you alter your source tree (short of moving it to a completely new location), Meson will detect the changes and regenerate itself accordingly. This is especially handy if you have multiple build directories. Often one of them is used for development (the "debug" build) and others only every now and then (such as a "static analysis" build). Any configuration can be built just by cd'ing to the corresponding directory and running Ninja.

Running tests

Meson provides native support for running tests. The command to do that is simple.

meson test -C builddir

See meson test description for more info.

Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables.

Note: it can be also invoked directly with ninja with the following command:

ninja -C builddir test

Installing

Installing the built software is just as simple.

meson install -C builddir

See meson install description for more info.

Note that Meson will only install build targets explicitly tagged as installable, as detailed in the installing targets documentation.

By default Meson installs to /usr/local. This can be changed by passing the command line argument --prefix /your/prefix to Meson during configure time. Meson also supports the DESTDIR variable used in e.g. building packages. It is used like this:

DESTDIR=/path/to/staging meson install -C builddir

Note: it can be also invoked directly with ninja with the following command:

ninja -C builddir install

Command line help

Meson has a standard command line help feature. It can be accessed with the following command.

meson --help

Exit status

Meson exits with status 0 if successful, 1 for problems with the command line or meson.build file, and 2 for internal errors.