From 08d614fa5e4cacbcb2ba5c46aa49e87c1ed3b172 Mon Sep 17 00:00:00 2001 From: Jussi Pakkanen Date: Wed, 14 Aug 2024 23:10:48 +0300 Subject: [PATCH] Add documentation for per-subproject options. --- .../markdown/Configuring-a-build-directory.md | 37 +++++++++++++++++++ docs/markdown/snippets/optionrefactor.md | 19 ++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/markdown/snippets/optionrefactor.md diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index db6fc03ef453..655903c8c7e1 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -119,3 +119,40 @@ by invoking [`meson configure`](Commands.md#configure) with the project source directory or the path to the root `meson.build`. In this case, Meson will print the default values of all options similar to the example output from above. + +## Per project subproject options rewrite (Since 1.7) + +A common requirement when building large projects with many +subprojects is to build some (or all) subprojects with project options +that are different from the "main project". This has been sort of +possible in a limited way but is now possible in a general way. These +additions can be added, changed and removed at runtime using the +command line or, in other words, without editing existing +`meson.build` files. + +Starting with version 1.7 you can specify per-project option settings. +These can be specified for every top level (i.e. not project) options. +Suppose you have a project that has a single subproject called +`numbercruncher` that does heavy computation. During development you +want to build that subproject with optimizations enabled but your main +project without optimizations. This can be done by specifying an +augment to the given subproject: + + meson configure -Dnumbercruncher:optimization=3 + +Another case might be that you want to build with errors as warnings, +but some subproject does not support it. It would be set up like this: + + meson configure -Dwerror=true -Anaughty:werror=false + +You can also specify an augment on the top level project. A more +general version of enabling optimizations on all subprojects but not +the top project would be done like this: + + meson configure -Doptimization=2 -D:optimization=0 + +Note the colon after the second `D`. + +Subproject specific values can be removed with -U + + meson configure -Usubproject:optionnname diff --git a/docs/markdown/snippets/optionrefactor.md b/docs/markdown/snippets/optionrefactor.md new file mode 100644 index 000000000000..e9cf74b700e1 --- /dev/null +++ b/docs/markdown/snippets/optionrefactor.md @@ -0,0 +1,19 @@ +## Per project subproject options rewrite + +You can now define per-subproject values for all shared configuration +options. As an example you might want to enable optimizations on only +one subproject: + + meson configure -Dnumbercruncher:optimization=3 + +Subproject specific values can be removed with -U + + meson configure -Unumbercruncher:optimization + +This is a major change in how options are handled. Current +per-subproject options are converted to augments on the fly. It is +expected that the logic might be changed in the next few releases as +logic errors are discovered. + +We have tried to keep backwards compatibility as much as possible, but +this may lead to some build breakage.