diff options
Diffstat (limited to 'docs/markdown/Builtin-options.md')
| -rw-r--r-- | docs/markdown/Builtin-options.md | 63 |
1 files changed, 42 insertions, 21 deletions
diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md index faf7a60..7a4d7f0 100644 --- a/docs/markdown/Builtin-options.md +++ b/docs/markdown/Builtin-options.md @@ -72,28 +72,28 @@ Options that are labeled "per machine" in the table are set per machine. See the [specifying options per machine](#specifying-options-per-machine) section for details. -| Option | Default value | Description | Is per machine | Is per subproject | -| -------------------------------------- | ------------- | ----------- | -------------- | ----------------- | +| Option | Default value | Description | Is per machine | Per subproject (since) | +| -------------------------------------- | ------------- | ----------- | -------------- | ---------------------- | | auto_features {enabled, disabled, auto} | auto | Override value of all 'auto' features | no | no | | backend {ninja, vs,<br>vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, vs2022, xcode, none} | ninja | Backend to use | no | no | | genvslite {vs2022} | vs2022 | Setup multi-buildtype ninja build directories and Visual Studio solution | no | no | -| buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug | Build type to use | no | no | -| debug | true | Enable debug symbols and other information | no | no | -| default_both_libraries {shared, static, auto} | shared | Default library type for both_libraries | no | no | -| default_library {shared, static, both} | shared | Default library type | no | yes | +| buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug | Build type to use | no | 1.8.0 | +| debug | true | Enable debug symbols and other information | no | 1.8.0 | +| default_both_libraries {shared, static, auto} | shared | Default library type for both_libraries | no | 1.8.0 | +| default_library {shared, static, both} | shared | Default library type | no | 0.54.0 | | errorlogs | true | Whether to print the logs from failing tests. | no | no | | install_umask {preserve, 0000-0777} | 022 | Default umask to apply on permissions of installed files | no | no | | layout {mirror,flat} | mirror | Build directory layout | no | no | -| optimization {plain, 0, g, 1, 2, 3, s} | 0 | Optimization level | no | no | +| optimization {plain, 0, g, 1, 2, 3, s} | 0 | Optimization level | no | 1.8.0 | | pkg_config_path {OS separated path} | '' | Additional paths for pkg-config to search before builtin paths | yes | no | | prefer_static | false | Whether to try static linking before shared linking | no | no | | cmake_prefix_path | [] | Additional prefixes for cmake to search before builtin paths | yes | no | | stdsplit | true | Split stdout and stderr in test logs | no | no | -| strip | false | Strip targets on install | no | no | -| unity {on, off, subprojects} | off | Unity build | no | no | -| unity_size {>=2} | 4 | Unity file block size | no | no | -| warning_level {0, 1, 2, 3, everything} | 1 | Set the warning level. From 0 = compiler default to everything = highest | no | yes | -| werror | false | Treat warnings as errors | no | yes | +| strip | false | Strip targets on install | no | 1.8.0 | +| unity {on, off, subprojects} | off | Unity build | no | 1.8.0 | +| unity_size {>=2} | 4 | Unity file block size | no | 1.8.0 | +| warning_level {0, 1, 2, 3, everything} | 1 | Set the warning level. From 0 = compiler default to everything = highest | no | 0.56.0 | +| werror | false | Treat warnings as errors | no | 0.54.0 | | wrap_mode {default, nofallback,<br>nodownload, forcefallback, nopromote} | default | Wrap mode to use | no | no | | force_fallback_for | [] | Force fallback for those dependencies | no | no | | vsenv | false | Activate Visual Studio environment | no | no | @@ -150,6 +150,10 @@ the two-way mapping: All other combinations of `debug` and `optimization` set `buildtype` to `'custom'`. +Note that `-Ddebug=false` does not cause the compiler preprocessor macro +`NDEBUG` to be defined. +The macro can be defined using the base option `b_ndebug`, described below. + #### Details for `warning_level` Exact flags per warning level is compiler specific, but there is an approximate @@ -366,11 +370,10 @@ allowing differences in behavior to crop out. ## Specifying options per subproject -Since *0.54.0* `default_library` and `werror` built-in options can be -defined per subproject. This is useful, for example, when building -shared libraries in the main project and statically linking a subproject, -or when the main project must build with no warnings but some subprojects -cannot. +Several built-in options and all compiler options can be defined per subproject. +This is useful, for example, when building shared libraries in the main project +and statically linking a subproject, or when the main project must build +with no warnings but some subprojects cannot. Most of the time, this would be used either in the parent project by setting subproject's default_options (e.g. `subproject('foo', @@ -378,12 +381,30 @@ default_options: 'default_library=static')`), or by the user through the command line: `-Dfoo:default_library=static`. The value is overridden in this order: +- `opt=value` from parent project's `default_options` +- `opt=value` from subproject's `default_options` +- `subp:opt=value` from parent project's default options +- `opt=value` from `subproject()` `default_options` +- `opt=value` from machine file +- `opt=value` from command line +- `subp:opt=value` from machine file +- `subp:opt=value` from command line + +### Old behavior + +Between *0.54.0* and *1.7.x* only a few options could be defined per subproject: +* `default_library` and `werror` since *0.54.0*; +* `warning_level` since *0.56.0*; +* compiler options since *0.63.0* + +The value was overridden in this order: + - Value from parent project -- Value from subproject's default_options if set -- Value from subproject() default_options if set -- Value from command line if set +- Value from subproject's `default_options` +- Value from `subproject()` `default_options` +- Value from machine file +- Value from command line -Since *0.56.0* `warning_level` can also be defined per subproject. ## Module options |