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