Debian Codegraph @

subprojects/meson-docs/docs/markdown/Using-multiple-build-directories.md

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