| 1 |
# Using multiple build directories |
| 2 |
|
| 3 |
One of the main design goals of Meson has been to build all projects |
| 4 |
out-of-source. This means that *all* files generated during the build |
| 5 |
are placed in a separate subdirectory. This goes against common Unix |
| 6 |
tradition where you build your projects in-source. Building out of |
| 7 |
source gives two major advantages. |
| 8 |
|
| 9 |
First of all this makes for very simple VCS "ignore" files. In |
| 10 |
classical build systems you may need to have tens of lines of |
| 11 |
definitions, most of which contain wildcards. When doing out of source |
| 12 |
builds all of this busywork goes away. A common ignore file for a |
| 13 |
Meson project only contains a few lines that are the build directory |
| 14 |
and IDE project files. (Note that since Meson 0.57.0, build directories |
| 15 |
are automatically ignored for git and mercurial by generating an ignore |
| 16 |
file inside the build directory.) |
| 17 |
|
| 18 |
Secondly this makes it very easy to clean your projects: just delete |
| 19 |
the build subdirectory and you are done. There is no need to guess |
| 20 |
whether you need to run `make clean`, `make distclean`, `make |
| 21 |
mrproper` or something else. When you delete a build subdirectory |
| 22 |
there is no possible way to have any lingering state from your old |
| 23 |
builds. |
| 24 |
|
| 25 |
The true benefit comes from somewhere else, though. |
| 26 |
|
| 27 |
## Multiple build directories for the same source tree |
| 28 |
|
| 29 |
Since a build directory is fully self contained and treats the source |
| 30 |
tree as a read-only piece of data, it follows that you can have |
| 31 |
arbitrarily many build trees for any source tree at the same time. |
| 32 |
Since all build trees can have different configuration, this is |
| 33 |
extremely powerful. Now you might be wondering why one would want to |
| 34 |
have multiple build setups at the same time. Let's examine this by |
| 35 |
setting up a hypothetical project. |
| 36 |
|
| 37 |
The first thing to do is to set up the default build, that is, the one |
| 38 |
we are going to use over 90% of the time. In this we use the system |
| 39 |
compiler and build with debug enabled and no optimizations so it |
| 40 |
builds as fast as possible. This is the default project type for |
| 41 |
Meson, so setting it up is simple. |
| 42 |
|
| 43 |
mkdir builddir |
| 44 |
meson setup builddir |
| 45 |
|
| 46 |
Another common setup is to build with debug and optimizations to, for |
| 47 |
example, run performance tests. Setting this up is just as simple. |
| 48 |
|
| 49 |
mkdir buildopt |
| 50 |
meson --buildtype=debugoptimized buildopt |
| 51 |
|
| 52 |
For systems where the default compiler is GCC, we would like to |
| 53 |
compile with Clang, too. So let's do that. |
| 54 |
|
| 55 |
mkdir buildclang |
| 56 |
CC=clang CXX=clang++ meson setup buildclang |
| 57 |
|
| 58 |
You can add cross builds, too. As an example, let's set up a Linux -> |
| 59 |
Windows cross compilation build using MinGW. |
| 60 |
|
| 61 |
mkdir buildwine |
| 62 |
meson --cross-file=mingw-cross.txt buildwine |
| 63 |
|
| 64 |
The cross compilation file sets up Wine so that not only can you |
| 65 |
compile your application, you can also run the unit test suite just by |
| 66 |
issuing the command `meson test`. |
| 67 |
|
| 68 |
To compile any of these build types, just cd into the corresponding |
| 69 |
build directory and run `meson compile` or instruct your IDE to do the |
| 70 |
same. Note that once you have set up your build directory once, you |
| 71 |
can just run Ninja and Meson will ensure that the resulting build is |
| 72 |
fully up to date according to the source. Even if you have not touched |
| 73 |
one of the directories in weeks and have done major changes to your |
| 74 |
build configuration, Meson will detect this and bring the build |
| 75 |
directory up to date (or print an error if it can't do that). This |
| 76 |
allows you to do most of your work in the default directory and use |
| 77 |
the others every now and then without having to babysit your build |
| 78 |
directories. |
| 79 |
|
| 80 |
## Specialized uses |
| 81 |
|
| 82 |
Separate build directories allows easy integration for various |
| 83 |
different kinds of tools. As an example, Clang comes with a static |
| 84 |
analyzer. It is meant to be run from scratch on a given source tree. |
| 85 |
The steps to run it with Meson are very simple. |
| 86 |
|
| 87 |
rm -rf buildscan |
| 88 |
mkdir buildscan |
| 89 |
scan-build meson setup buildscan |
| 90 |
cd buildscan |
| 91 |
scan-build ninja |
| 92 |
|
| 93 |
These commands are the same for every single Meson project, so they |
| 94 |
could even be put in a script turning static analysis into a single |
| 95 |
command. |