docs/markdown/Running-Meson.md - meson - Git at Google

 ---
 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.

 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](Commands.md).

 ## 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.

 ```sh
 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](http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/).

 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](Builtin-options.md).

 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:

 ```sh
 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.

 ```sh
 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](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 from the source

 To start the build, simply type the following command.

 ```sh
 meson compile -C builddir
 ```

 See [`meson compile` description](Commands.md#compile) for more info.

 ### Building directly with ninja

 By default Meson uses the [Ninja build system](https://ninja-build.org/) to
 actually build the code. To start the build, simply type the following command.

 ```sh
 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.

 ```sh
 meson test -C builddir
 ```

 See [`meson test` description](Commands.md#test) 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:
 ```sh
 ninja -C builddir test
 ```

 ## Installing

 Installing the built software is just as simple.

 ```sh
 meson install -C builddir
 ```

 See [`meson install` description](Commands.md#install) for more info.

 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:

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

 Note: it can be also invoked directly with ninja with the following command:
 ```sh
 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.
	---
	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.

	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](Commands.md).

	## 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.

	```sh
	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](http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/).

	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](Builtin-options.md).

	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:

	```sh
	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.

	```sh
	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](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 from the source

	To start the build, simply type the following command.

	```sh
	meson compile -C builddir
	```

	See [`meson compile` description](Commands.md#compile) for more info.

	### Building directly with ninja

	By default Meson uses the [Ninja build system](https://ninja-build.org/) to
	actually build the code. To start the build, simply type the following command.

	```sh
	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.

	```sh
	meson test -C builddir
	```

	See [`meson test` description](Commands.md#test) 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:
	```sh
	ninja -C builddir test
	```

	## Installing

	Installing the built software is just as simple.

	```sh
	meson install -C builddir
	```

	See [`meson install` description](Commands.md#install) for more info.

	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:

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

	Note: it can be also invoked directly with ninja with the following command:
	```sh
	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.