Debian Codegraph @

subprojects/meson-docs/docs/markdown/Running-Meson.md

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