| 1 |
--- |
| 2 |
short-description: Building a project with Meson |
| 3 |
... |
| 4 |
|
| 5 |
# Running Meson |
| 6 |
|
| 7 |
There are two different ways of invoking Meson. First, you can run it |
| 8 |
directly from the source tree with the command |
| 9 |
`/path/to/source/meson.py`. Second, Meson may also be installed in which case |
| 10 |
the command is simply `meson`. In this manual we only use the latter |
| 11 |
format for simplicity. |
| 12 |
|
| 13 |
At the time of writing only a command line version of Meson is |
| 14 |
available. This means that Meson must be invoked using the terminal. |
| 15 |
If you wish to use the MSVC compiler, you need to run Meson under |
| 16 |
"Visual Studio command prompt". |
| 17 |
|
| 18 |
All available Meson commands are listed on the [commands reference |
| 19 |
page](Commands.md). |
| 20 |
|
| 21 |
## Configuring the build directory |
| 22 |
|
| 23 |
Let us assume that we have a source tree that has a Meson build |
| 24 |
system. This means that at the topmost directory has a file called |
| 25 |
`meson.build`. We run the following commands to get the build started. |
| 26 |
|
| 27 |
```sh |
| 28 |
cd /path/to/source/root |
| 29 |
meson setup builddir |
| 30 |
``` |
| 31 |
|
| 32 |
We invoke Meson with the `setup` command, giving it the location of the build |
| 33 |
directory. Meson uses [out of source |
| 34 |
builds](http://web.archive.org/web/20190715081007/http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/). |
| 35 |
|
| 36 |
Hint: The syntax of Meson is `meson [command] [arguments] [options]`. |
| 37 |
The `setup` command takes a `builddir` and a `srcdir` argument. If no |
| 38 |
`srcdir` is given Meson will deduce the `srcdir` based on `pwd` and |
| 39 |
the location of `meson.build`. |
| 40 |
|
| 41 |
Meson then loads the build configuration file and writes the |
| 42 |
corresponding build backend in the build directory. By default Meson |
| 43 |
generates a *debug build*, which turns on basic warnings and debug |
| 44 |
information and disables compiler optimizations. |
| 45 |
|
| 46 |
Additionally, the invocation can pass options to Meson. The list of |
| 47 |
options is documented [here](Builtin-options.md). |
| 48 |
|
| 49 |
You can specify a different type of build with the `--buildtype` command line |
| 50 |
argument. It can have one of the following values. |
| 51 |
|
| 52 |
| value | meaning | |
| 53 |
| ------ | -------- | |
| 54 |
| `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 | |
| 55 |
| `debug` | debug info is generated but the result is not optimized, this is the default | |
| 56 |
| `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) | |
| 57 |
| `release` | full optimization, no debug info | |
| 58 |
|
| 59 |
The build directory is mandatory. The reason for this is that it |
| 60 |
simplifies the build process immensely. Meson will not, under any |
| 61 |
circumstances, write files inside the source directory (if it does, it |
| 62 |
is a bug and should be fixed). This means that the user does not need |
| 63 |
to add a bunch of files to their revision control's ignore list. It |
| 64 |
also means that you can create arbitrarily many build directories for |
| 65 |
any given source tree. |
| 66 |
|
| 67 |
For example, if we wanted to test building the source code with the |
| 68 |
Clang compiler instead of the system default, we could just type the |
| 69 |
following commands: |
| 70 |
|
| 71 |
```sh |
| 72 |
cd /path/to/source/root |
| 73 |
CC=clang CXX=clang++ meson setup buildclang |
| 74 |
``` |
| 75 |
|
| 76 |
This separation is even more powerful if your code has multiple |
| 77 |
configuration options (such as multiple data backends). You can create |
| 78 |
a separate subdirectory for each of them. You can also have build |
| 79 |
directories for optimized builds, code coverage, static analysis and |
| 80 |
so on. They are all neatly separated and use the same source tree. |
| 81 |
Changing between different configurations is just a question of |
| 82 |
changing to the corresponding directory. |
| 83 |
|
| 84 |
Unless otherwise mentioned, all following command line invocations are |
| 85 |
meant to be run in the source directory. |
| 86 |
|
| 87 |
By default, Meson will use the Ninja backend to build your project. If |
| 88 |
you wish to use any of the other backends, you need to pass the |
| 89 |
corresponding argument during configuration time. As an example, here |
| 90 |
is how you would use Meson to generate a Visual Studio solution. |
| 91 |
|
| 92 |
```sh |
| 93 |
meson setup <build dir> --backend=vs |
| 94 |
``` |
| 95 |
|
| 96 |
You can then open the generated solution with Visual Studio and |
| 97 |
compile it in the usual way. A list of backends can be obtained with |
| 98 |
`meson setup --help`. |
| 99 |
|
| 100 |
## Environment variables |
| 101 |
|
| 102 |
Sometimes you want to add extra compiler flags, this can be done by |
| 103 |
passing them in environment variables when calling Meson. See [the |
| 104 |
reference |
| 105 |
tables](Reference-tables.md#compiler-and-linker-flag-environment-variables) |
| 106 |
for a list of all the environment variables. Be aware however these |
| 107 |
environment variables are only used for the native compiler and will |
| 108 |
not affect the compiler used for cross-compiling, where the flags |
| 109 |
specified in the cross file will be used. |
| 110 |
|
| 111 |
Furthermore it is possible to stop Meson from adding flags itself by |
| 112 |
using the `--buildtype=plain` option, in this case you must provide |
| 113 |
the full compiler and linker arguments needed. |
| 114 |
|
| 115 |
## Building from the source |
| 116 |
|
| 117 |
To start the build, simply type the following command. |
| 118 |
|
| 119 |
```sh |
| 120 |
meson compile -C builddir |
| 121 |
``` |
| 122 |
|
| 123 |
See [`meson compile` description](Commands.md#compile) for more info. |
| 124 |
|
| 125 |
### Building directly with ninja |
| 126 |
|
| 127 |
By default Meson uses the [Ninja build |
| 128 |
system](https://ninja-build.org/) to actually build the code. To start |
| 129 |
the build, simply type the following command. |
| 130 |
|
| 131 |
```sh |
| 132 |
ninja -C builddir |
| 133 |
``` |
| 134 |
|
| 135 |
The main usability difference between Ninja and Make is that Ninja |
| 136 |
will automatically detect the number of CPUs in your computer and |
| 137 |
parallelize itself accordingly. You can override the amount of |
| 138 |
parallel processes used with the command line argument `-j <num |
| 139 |
processes>`. |
| 140 |
|
| 141 |
It should be noted that after the initial configure step `ninja` is |
| 142 |
the only command you ever need to type to compile. No matter how you |
| 143 |
alter your source tree (short of moving it to a completely new |
| 144 |
location), Meson will detect the changes and regenerate itself |
| 145 |
accordingly. This is especially handy if you have multiple build |
| 146 |
directories. Often one of them is used for development (the "debug" |
| 147 |
build) and others only every now and then (such as a "static analysis" |
| 148 |
build). Any configuration can be built just by `cd`'ing to the |
| 149 |
corresponding directory and running Ninja. |
| 150 |
|
| 151 |
## Running tests |
| 152 |
|
| 153 |
Meson provides native support for running tests. The command to do |
| 154 |
that is simple. |
| 155 |
|
| 156 |
```sh |
| 157 |
meson test -C builddir |
| 158 |
``` |
| 159 |
|
| 160 |
See [`meson test` description](Commands.md#test) for more info. |
| 161 |
|
| 162 |
Meson does not force the use of any particular testing framework. You |
| 163 |
are free to use GTest, Boost Test, Check or even custom executables. |
| 164 |
|
| 165 |
Note: it can be also invoked directly with ninja with the following command: |
| 166 |
```sh |
| 167 |
ninja -C builddir test |
| 168 |
``` |
| 169 |
|
| 170 |
## Installing |
| 171 |
|
| 172 |
Installing the built software is just as simple. |
| 173 |
|
| 174 |
```sh |
| 175 |
meson install -C builddir |
| 176 |
``` |
| 177 |
|
| 178 |
See [`meson install` description](Commands.md#install) for more info. |
| 179 |
|
| 180 |
Note that Meson will only install build targets explicitly tagged as |
| 181 |
installable, as detailed in the [installing targets |
| 182 |
documentation](Installing.md). |
| 183 |
|
| 184 |
By default Meson installs to `/usr/local`. This can be changed by |
| 185 |
passing the command line argument `--prefix /your/prefix` to Meson |
| 186 |
during configure time. Meson also supports the `DESTDIR` variable used |
| 187 |
in e.g. building packages. It is used like this: |
| 188 |
|
| 189 |
```sh |
| 190 |
DESTDIR=/path/to/staging meson install -C builddir |
| 191 |
``` |
| 192 |
|
| 193 |
Note: it can be also invoked directly with ninja with the following |
| 194 |
command: |
| 195 |
|
| 196 |
```sh |
| 197 |
ninja -C builddir install |
| 198 |
``` |
| 199 |
|
| 200 |
## Command line help |
| 201 |
|
| 202 |
Meson has a standard command line help feature. It can be accessed |
| 203 |
with the following command. |
| 204 |
|
| 205 |
meson --help |
| 206 |
|
| 207 |
## Exit status |
| 208 |
|
| 209 |
Meson exits with status 0 if successful, 1 for problems with the |
| 210 |
command line or meson.build file, and 2 for internal errors. |