Debian Codegraph @

subprojects/meson-docs/docs/markdown/Builtin-options.md

raw
1 ---
2 short-description: Built-in options to configure project properties
3 ...
4
5 # Built-in options
6
7 Meson provides two kinds of options: [build options provided by the
8 build files](Build-options.md) and built-in options that are either
9 universal options, base options, compiler options.
10
11 ## Universal options
12
13 All these can be set by passing `-Doption=value` to `meson` (aka `meson
14 setup`), or by setting them inside `default_options` of [[project]] in your
15 `meson.build`. Some options can also be set by `--option=value`, or `--option
16 value` -- a list is shown by running `meson setup --help`.
17
18 For legacy reasons `--warnlevel` is the cli argument for the
19 `warning_level` option.
20
21 They can also be edited after setup using `meson configure
22 -Doption=value`.
23
24 Installation options are usually relative to the prefix but it should
25 not be relied on, since they can be absolute paths in the following cases:
26
27 * When the prefix is `/usr`: `sysconfdir` defaults to `/etc`,
28 `localstatedir` defaults to `/var`, and `sharedstatedir` defaults to
29 `/var/lib`
30 * When the prefix is `/usr/local`: `localstatedir` defaults
31 to `/var/local`, and `sharedstatedir` defaults to `/var/local/lib`
32 * When an absolute path outside of prefix is provided by the user/distributor.
33
34 ### Directories
35
36 | Option | Default value | Description |
37 | ------ | ------------- | ----------- |
38 | prefix | see below | Installation prefix |
39 | bindir | bin | Executable directory |
40 | datadir | share | Data file directory |
41 | includedir | include | Header file directory |
42 | infodir | share/info | Info page directory |
43 | libdir | see below | Library directory |
44 | licensedir | see below | Licenses directory (since 1.1.0)|
45 | libexecdir | libexec | Library executable directory |
46 | localedir | share/locale | Locale data directory |
47 | localstatedir | var | Localstate data directory |
48 | mandir | share/man | Manual page directory |
49 | sbindir | sbin | System executable directory |
50 | sharedstatedir | com | Architecture-independent data directory |
51 | sysconfdir | etc | Sysconf data directory |
52
53
54 `prefix` defaults to `C:/` on Windows, and `/usr/local` otherwise. You
55 should always override this value.
56
57 `libdir` is automatically detected based on your platform, it should
58 be correct when doing "native" (build machine == host machine)
59 compilation. For cross compiles Meson will try to guess the correct
60 libdir, but it may not be accurate, especially on Linux where
61 different distributions have different defaults. Using a [cross
62 file](Cross-compilation.md#defining-the-environment), particularly the
63 paths section may be necessary.
64
65 `licensedir` is empty by default. If set, it defines the default location
66 to install a dependency manifest and project licenses. For more details,
67 see [[meson.install_dependency_manifest]].
68
69 ### Core options
70
71 Options that are labeled "per machine" in the table are set per
72 machine. See the [specifying options per
73 machine](#specifying-options-per-machine) section for details.
74
75 | Option | Default value | Description | Is per machine | Is per subproject |
76 | -------------------------------------- | ------------- | ----------- | -------------- | ----------------- |
77 | auto_features {enabled, disabled, auto} | auto | Override value of all 'auto' features | no | no |
78 | backend {ninja, vs,<br>vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, vs2022, xcode, none} | ninja | Backend to use | no | no |
79 | genvslite {vs2022} | vs2022 | Setup multi-builtype ninja build directories and Visual Studio solution | no | no |
80 | buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug | Build type to use | no | no |
81 | debug | true | Enable debug symbols and other information | no | no |
82 | default_both_libraries {shared, static, auto} | shared | Default library type for both_libraries | no | no |
83 | default_library {shared, static, both} | shared | Default library type | no | yes |
84 | errorlogs | true | Whether to print the logs from failing tests. | no | no |
85 | install_umask {preserve, 0000-0777} | 022 | Default umask to apply on permissions of installed files | no | no |
86 | layout {mirror,flat} | mirror | Build directory layout | no | no |
87 | optimization {plain, 0, g, 1, 2, 3, s} | 0 | Optimization level | no | no |
88 | pkg_config_path {OS separated path} | '' | Additional paths for pkg-config to search before builtin paths | yes | no |
89 | prefer_static | false | Whether to try static linking before shared linking | no | no |
90 | cmake_prefix_path | [] | Additional prefixes for cmake to search before builtin paths | yes | no |
91 | stdsplit | true | Split stdout and stderr in test logs | no | no |
92 | strip | false | Strip targets on install | no | no |
93 | unity {on, off, subprojects} | off | Unity build | no | no |
94 | unity_size {>=2} | 4 | Unity file block size | no | no |
95 | warning_level {0, 1, 2, 3, everything} | 1 | Set the warning level. From 0 = compiler default to everything = highest | no | yes |
96 | werror | false | Treat warnings as errors | no | yes |
97 | wrap_mode {default, nofallback,<br>nodownload, forcefallback, nopromote} | default | Wrap mode to use | no | no |
98 | force_fallback_for | [] | Force fallback for those dependencies | no | no |
99 | vsenv | false | Activate Visual Studio environment | no | no |
100
101 (For the Rust language only, `warning_level=0` disables all warnings).
102
103 #### Details for `backend`
104
105 Several build file formats are supported as command runners to build the
106 configured project. Meson prefers ninja by default, but platform-specific
107 backends are also available for better IDE integration with native tooling:
108 Visual Studio for Windows, and xcode for macOS. It is also possible to
109 configure with no backend at all, which is an error if you have targets to
110 build, but for projects that need configuration + testing + installation allows
111 for a lighter automated build pipeline.
112
113 #### Details for `genvslite`
114
115 Setup multiple buildtype-suffixed, ninja-backend build directories (e.g.
116 [builddir]_[debug/release/etc.]) and generate [builddir]_vs containing a Visual
117 Studio solution with multiple configurations that invoke a meson compile of the
118 setup build directories, as appropriate for the current configuration (builtype).
119
120 This has the effect of a simple setup macro of multiple 'meson setup ...'
121 invocations with a set of different buildtype values. E.g.
122 `meson setup ... --genvslite vs2022 somebuilddir` does the following -
123 ```
124 meson setup ... --backend ninja --buildtype debug somebuilddir_debug
125 meson setup ... --backend ninja --buildtype debugoptimized somebuilddir_debugoptimized
126 meson setup ... --backend ninja --buildtype release somebuilddir_release
127 ```
128 and additionally creates another 'somebuilddir_vs' directory that contains
129 a generated multi-configuration visual studio solution and project(s) that are
130 set to build/compile with the somebuilddir_[...] that's appropriate for the
131 solution's selected buildtype configuration.
132
133 #### Details for `buildtype`
134
135 <a name="build-type-options"></a> For setting optimization levels and
136 toggling debug, you can either set the `buildtype` option, or you can
137 set the `optimization` and `debug` options which give finer control
138 over the same. Whichever you decide to use, the other will be deduced
139 from it. For example, `-Dbuildtype=debugoptimized` is the same as
140 `-Ddebug=true -Doptimization=2` and vice-versa. This table documents
141 the two-way mapping:
142
143 | buildtype | debug | optimization |
144 | --------- | ----- | ------------ |
145 | plain | false | plain |
146 | debug | true | 0 |
147 | debugoptimized | true | 2 |
148 | release | false | 3 |
149 | minsize | true | s |
150
151 All other combinations of `debug` and `optimization` set `buildtype` to `'custom'`.
152
153 #### Details for `warning_level`
154
155 Exact flags per warning level is compiler specific, but there is an approximative
156 table for most common compilers.
157
158 | Warning level | GCC/Clang | MSVC |
159 | ------------- | --- | ---- |
160 | 0 | | |
161 | 1 | -Wall | /W2 |
162 | 2 | -Wall -Wextra | /W3 |
163 | 3 | -Wall -Wextra -Wpedantic | /W4 |
164 | everything | -Weverything | /Wall |
165
166 Clang's `-Weverything` is emulated on GCC by passing all known warning flags.
167
168 #### Details for `vsenv`
169
170 The `--vsenv` argument is supported since `0.60.0`, `-Dvsenv=true` syntax is supported
171 since `1.1.0`.
172
173 Since `0.59.0`, meson automatically activates a Visual Studio environment on Windows
174 for all its subcommands, but only if no other compilers (e.g. `gcc` or `clang`)
175 are found, and silently continues if Visual Studio activation fails.
176
177 Setting the `vsenv` option to `true` forces Visual Studio activation even when other
178 compilers are found. It also make Meson abort with an error message when activation
179 fails.
180
181 `vsenv` is `true` by default when using the `vs` backend.
182
183
184 #### Details for `default_both_libraries`
185
186 Since `1.6.0`, you can select the default type of library selected when using
187 a `both_libraries` object. This can be either 'shared' (default value, compatible
188 with previous meson versions), 'static', or 'auto'. With auto, the value from
189 `default_library` option is used, unless it is 'both', in which case 'shared'
190 is used instead.
191
192 When `default_both_libraries` is 'auto', passing a [[@both_libs]] dependency
193 in [[both_libraries]] will link the static dependency with the static lib,
194 and the shared dependency with the shared lib.
195
196 ## Base options
197
198 These are set in the same way as universal options, either by
199 `-Doption=value`, or by setting them inside `default_options` of
200 [[project]] in your `meson.build`. However, they cannot be shown in
201 the output of `meson setup --help` because they depend on both the current
202 platform and the compiler that will be selected. The only way to see
203 them is to setup a builddir and then run `meson configure` on it with
204 no options.
205
206 The following options are available. Note that they may not be
207 available on all platforms or with all compilers:
208
209 | Option | Default value | Possible values | Description |
210 |---------------------|----------------------|---------------------------------------------------------------|--------------------------------------------------------------------------------|
211 | b_asneeded | true | true, false | Use -Wl,--as-needed when linking |
212 | b_bitcode | false | true, false | Embed Apple bitcode, see below |
213 | b_colorout | always | auto, always, never | Use colored output |
214 | b_coverage | false | true, false | Enable coverage tracking |
215 | b_lundef | true | true, false | Don't allow undefined symbols when linking |
216 | b_lto | false | true, false | Use link time optimization |
217 | b_lto_threads | 0 | Any integer* | Use multiple threads for lto. *(Added in 0.57.0)* |
218 | b_lto_mode | default | default, thin | Select between lto modes, thin and default. *(Added in 0.57.0)* |
219 | b_thinlto_cache | false | true, false | Enable LLVM's ThinLTO cache for faster incremental builds. *(Added in 0.64.0)* |
220 | b_thinlto_cache_dir | (Internal build dir) | true, false | Specify where to store ThinLTO cache objects. *(Added in 0.64.0)* |
221 | b_ndebug | false | true, false, if-release | Disable asserts |
222 | b_pch | true | true, false | Use precompiled headers |
223 | b_pgo | off | off, generate, use | Use profile guided optimization |
224 | b_sanitize | none | see below | Code sanitizer to use |
225 | b_staticpic | true | true, false | Build static libraries as position independent |
226 | b_pie | false | true, false | Build position-independent executables (since 0.49.0) |
227 | b_vscrt | from_buildtype | none, md, mdd, mt, mtd, from_buildtype, static_from_buildtype | VS runtime library to use (since 0.48.0) (static_from_buildtype since 0.56.0) |
228
229 The value of `b_sanitize` can be one of: `none`, `address`, `thread`,
230 `undefined`, `memory`, `leak`, `address,undefined`, but note that some
231 compilers might not support all of them. For example Visual Studio
232 only supports the address sanitizer.
233
234 \* < 0 means disable, == 0 means automatic selection, > 0 sets a specific number to use
235
236 LLVM supports `thin` lto, for more discussion see [LLVM's documentation](https://clang.llvm.org/docs/ThinLTO.html)
237
238 <a name="b_vscrt-from_buildtype"></a>
239 The default value of `b_vscrt` is `from_buildtype`. The following table is
240 used internally to pick the CRT compiler arguments for `from_buildtype` or
241 `static_from_buildtype` *(since 0.56)* based on the value of the `buildtype`
242 option:
243
244 | buildtype | from_buildtype | static_from_buildtype |
245 | -------- | -------------- | --------------------- |
246 | debug | `/MDd` | `/MTd` |
247 | debugoptimized | `/MD` | `/MT` |
248 | release | `/MD` | `/MT` |
249 | minsize | `/MD` | `/MT` |
250 | custom | error! | error! |
251
252 ### Notes about Apple Bitcode support
253
254 `b_bitcode` will pass `-fembed-bitcode` while compiling and will pass
255 `-Wl,-bitcode_bundle` while linking. These options are incompatible
256 with `b_asneeded`, so that option will be silently disabled.
257
258 [[shared_module]]s will not have
259 bitcode embedded because `-Wl,-bitcode_bundle` is incompatible with
260 both `-bundle` and `-Wl,-undefined,dynamic_lookup` which are necessary
261 for shared modules to work.
262
263 ## Compiler options
264
265 Same caveats as base options above.
266
267 The following options are available. They can be set by passing
268 `-Doption=value` to `meson`. Note that both the options themselves and
269 the possible values they can take will depend on the target platform
270 or compiler being used:
271
272 | Option | Default value | Possible values | Description |
273 | ------ | ------------- | --------------- | ----------- |
274 | c_args | | free-form comma-separated list | C compile arguments to use |
275 | c_link_args | | free-form comma-separated list | C link arguments to use |
276 | c_std | none | none, c89, c99, c11, c17, c18, c2x, c23, gnu89, gnu99, gnu11, gnu17, gnu18, gnu2x, gnu23 | C language standard to use |
277 | c_winlibs | see below | free-form comma-separated list | Standard Windows libs to link against |
278 | c_thread_count | 4 | integer value ≥ 0 | Number of threads to use with emcc when using threads |
279 | cpp_args | | free-form comma-separated list | C++ compile arguments to use |
280 | cpp_link_args | | free-form comma-separated list | C++ link arguments to use |
281 | cpp_std | none | none, c++98, c++03, c++11, c++14, c++17, c++20 <br/>c++2a, c++1z, gnu++03, gnu++11, gnu++14, gnu++17, gnu++1z, <br/> gnu++2a, gnu++20, vc++14, vc++17, vc++20, vc++latest | C++ language standard to use |
282 | cpp_debugstl | false | true, false | C++ STL debug mode |
283 | cpp_eh | default | none, default, a, s, sc | C++ exception handling type |
284 | cpp_rtti | true | true, false | Whether to enable RTTI (runtime type identification) |
285 | cpp_thread_count | 4 | integer value ≥ 0 | Number of threads to use with emcc when using threads |
286 | cpp_winlibs | see below | free-form comma-separated list | Standard Windows libs to link against |
287 | fortran_std | none | [none, legacy, f95, f2003, f2008, f2018] | Fortran language standard to use |
288 | cuda_ccbindir | | filesystem path | CUDA non-default toolchain directory to use (-ccbin) *(Added in 0.57.1)* |
289
290 The default values of `c_winlibs` and `cpp_winlibs` are in
291 compiler-specific argument forms, but the libraries are: kernel32,
292 user32, gdi32, winspool, shell32, ole32, oleaut32, uuid, comdlg32,
293 advapi32.
294
295 All these `<lang>_*` options are specified per machine. See below in
296 the [specifying options per machine](#specifying-options-per-machine)
297 section on how to do this in cross builds.
298
299 When using MSVC, `cpp_eh=[value]` will result in `/EH[value]` being passed.
300 The magic value `none` translates to `s-c-` to disable exceptions. *Since
301 0.51.0* `default` translates to `sc`. When using gcc-style compilers, nothing
302 is passed (allowing exceptions to work), while `cpp_eh=none` passes
303 `-fno-exceptions`.
304
305 Since *0.54.0* The `<lang>_thread_count` option can be used to control
306 the value passed to `-s PTHREAD_POOL_SIZE` when using emcc. No other
307 c/c++ compiler supports this option.
308
309 Since *0.63.0* all compiler options can be set per subproject, see
310 [here](#specifying-options-per-subproject) for details on how the default value
311 is inherited from the main project. This is useful, for example, when the main
312 project requires C++11, but a subproject requires C++14. The `cpp_std` value
313 from the subproject's `default_options` is now respected.
314
315 Since *1.3.0* `c_std` and `cpp_std` options now accept a list of values.
316 Projects that prefer GNU C, but can fallback to ISO C, can now set, for
317 example, `default_options: 'c_std=gnu11,c11'`, and it will use `gnu11` when
318 available, but fallback to c11 otherwise. It is an error only if none of the
319 values are supported by the current compiler.
320 Likewise, a project that can take benefit of `c++17` but can still build with
321 `c++11` can set `default_options: 'cpp_std=c++17,c++11'`.
322 This allows us to deprecate `gnuXX` values from the MSVC compiler. That means
323 that `default_options: 'c_std=gnu11'` will now print a warning with MSVC
324 but fallback to `c11`. No warning is printed if at least one
325 of the values is valid, i.e. `default_options: 'c_std=gnu11,c11'`.
326 In the future that deprecation warning will become an hard error because
327 `c_std=gnu11` should mean GNU is required, for projects that cannot be
328 built with MSVC for example.
329
330 ## Specifying options per machine
331
332 Since *0.51.0*, some options are specified per machine rather than
333 globally for all machine configurations. Prefixing the option with
334 `build.` only affects the build machine configuration, while leaving it
335 unprefixed only affects the host machine configuration.
336 For example:
337
338 - `build.pkg_config_path` controls the paths pkg-config will search
339 for `native: true` (build machine) dependencies.
340
341 - `pkg_config_path` controls the paths pkg-config will search for
342 `native: false` (host machine) dependencies.
343
344 This is useful for cross builds. In native builds, the build and host
345 machines are the same, and the unprefixed option alone will suffice.
346
347 Prior to *0.51.0*, these options only affected native builds when
348 specified on the command line as there was no `build.` prefix.
349 Similarly named fields in the `[properties]` section of the cross file
350 would affect cross compilers, but the code paths were fairly different,
351 allowing differences in behavior to crop out.
352
353 ## Specifying options per subproject
354
355 Since *0.54.0* `default_library` and `werror` built-in options can be
356 defined per subproject. This is useful, for example, when building
357 shared libraries in the main project and statically linking a subproject,
358 or when the main project must build with no warnings but some subprojects
359 cannot.
360
361 Most of the time, this would be used either in the parent project by
362 setting subproject's default_options (e.g. `subproject('foo',
363 default_options: 'default_library=static')`), or by the user through the
364 command line: `-Dfoo:default_library=static`.
365
366 The value is overridden in this order:
367 - Value from parent project
368 - Value from subproject's default_options if set
369 - Value from subproject() default_options if set
370 - Value from command line if set
371
372 Since *0.56.0* `warning_level` can also be defined per subproject.
373
374 ## Module options
375
376 Some Meson modules have built-in options. They can be set by prefixing the
377 option with the module's name:
378 `-D<module>.<option>=<value>` (e.g. `-Dpython.platlibdir=/foo`).
379
380 ### Pkgconfig module
381
382 | Option | Default value | Possible values | Description |
383 |-------------|---------------|-----------------|------------------------------------------------------------|
384 | relocatable | false | true, false | Generate the pkgconfig files as relocatable (Since 0.63.0) |
385
386 *Since 0.63.0* The `pkgconfig.relocatable` option is used by the
387 pkgconfig module–namely [`pkg.generate()`](Pkgconfig-module.md)–and
388 affects how the `prefix` (not to be confused with the
389 [install prefix](#directories)) in the generated pkgconfig file is set.
390 When it is `true`, the `prefix` will be relative to the `install_dir`-this
391 allows the pkgconfig file to be moved around and still work, as long
392 as the relative path is not broken. In general, this allows for the whole
393 installed package to be placed anywhere on the system and still work as a
394 dependency. When it is set to `false`, the `prefix` will be the same as
395 the install prefix.
396
397 An error will be raised if `pkgconfig.relocatable` is `true` and the
398 `install_dir` for a generated pkgconfig file points outside the
399 install prefix. For example: if the install prefix is `/usr` and the
400 `install_dir` for a pkgconfig file is `/var/lib/pkgconfig`.
401
402 ### Python module
403
404 | Option | Default value | Possible values | Description |
405 | ------ | ------------- | ----------------- | ----------- |
406 | bytecompile | 0 | integer from -1 to 2 | What bytecode optimization level to use (Since 1.2.0) |
407 | install_env | prefix | {auto,prefix,system,venv} | Which python environment to install to (Since 0.62.0) |
408 | platlibdir | | Directory path | Directory for site-specific, platform-specific files (Since 0.60.0) |
409 | purelibdir | | Directory path | Directory for site-specific, non-platform-specific files (Since 0.60.0) |
410 | allow_limited_api | true | true, false | Disables project-wide use of the Python Limited API (Since 1.3.0) |
411
412 *Since 0.60.0* The `python.platlibdir` and `python.purelibdir` options are used
413 by the python module methods `python.install_sources()` and
414 `python.get_install_dir()`; Meson tries to detect the correct installation paths
415 and make them relative to the installation `prefix` by default which will often
416 result in the interpreter not finding the installed python modules unless
417 `prefix` is `/usr` on Linux, or, for instance, `C:\Python39` on Windows. These
418 options can be absolute paths outside of `prefix`.
419
420 *Since 0.62.0* The `python.install_env` option is used to detect the correct
421 installation path. Setting to `system` will avoid making the paths relative to
422 `prefix` and instead use the global site-packages of the selected python
423 interpreter directly, even if it is a venv. Setting to `venv` will instead use
424 the paths for the virtualenv the python found installation comes from (or fail
425 if it is not a virtualenv). Setting to `auto` will check if the found
426 installation is a virtualenv, and use `venv` or `system` as appropriate (but
427 never `prefix`). Note that Conda environments are treated as `system`.
428 This option is mutually exclusive with the `platlibdir`/`purelibdir`.
429
430 For backwards compatibility purposes, the default `install_env` is `prefix`.
431
432 *Since 1.2.0* The `python.bytecompile` option can be used to enable compiling
433 python bytecode. Bytecode has 3 optimization levels:
434
435 - 0, bytecode without optimizations
436 - 1, bytecode with some optimizations
437 - 2, bytecode with some more optimizations
438
439 To this, Meson adds level `-1`, which is to not attempt to compile bytecode at
440 all.
441
442 *Since 1.3.0* The `python.allow_limited_api` option affects whether the
443 `limited_api` keyword argument of the `extension_module` method is respected.
444 If set to `false`, the effect of the `limited_api` argument is disabled.