---
short-description: Building a project with Meson
...
# 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` . Meson may
also be installed in which case the command is simply `meson` . In this manual
we only use the latter format for simplicity.
Additionally, the invocation can pass options to meson. The list of options is
documented [here ](Builtin-options.md ).
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".
## Configuring the source
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
mkdir builddir
cd builddir
meson ..
First we create a directory to hold all files generated during the build. Then
we go into it and invoke Meson, giving it the location of the source root.
Hint: The syntax of meson is `meson [options] [srcdir] [builddir]` , but you may
omit either `srcdir` or `builddir` . Meson will deduce the `srcdir` by the
location of `meson.build` . The other one will be your `pwd` .
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.
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. 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
mkdir buildclang
cd buildclang
CC=clang CXX=clang++ meson ..
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 build 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 < source dir > < build dir > --backend=vs2010
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 --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](Reference-tables.md#compiler-and-linker-flag-envrionment-variables) 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 the source
If you are not using an IDE, Meson uses the [Ninja build
system](https://ninja-build.org/) to actually build the code. To start the
build, simply type the following command.
ninja
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.
ninja test
Meson does not force the use of any particular testing framework. You are free
to use GTest, Boost Test, Check or even custom executables.
## Installing
Installing the built software is just as simple.
ninja install
Note that Meson will only install build targets explicitly tagged as
installable, as detailed in the [installing targets
documentation](Installing.md).
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 ninja 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.
