Make all Meson level options overridable per subproject.

2 files changed, 56 insertions, 0 deletions

diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md
index 746e4b16b..974b7ae99 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.8)
+
+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 natively supported. Per project
+options can be added, changed and removed at runtime using the command
+line, in other words, without editing existing `meson.build` files.
+
+Starting with version 1.8 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 a custom
+value to the given subproject:
+
+    meson configure -Dnumbercruncher:optimization=3
+
+Another case might be that you want to build with warnings as errors,
+but some subproject does not support it. To configure `werror` per
+subproject you can do:
+
+    meson configure -Dwerror=true -Dnaughty:werror=false
+
+You can also specify a different value on the top level project. For
+example you could enable optimizations on all subprojects but not the
+top level project:
+
+    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 000000000..53dbdbc42
--- /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, and the
+implementation will evolve over the next few releases of Meson. If
+this change causes an error in your builds, please [report an issue on
+GitHub](https://github.com/mesonbuild/meson/issues/new).
+
+We have tried to keep backwards compatibility as much as possible, but
+this may lead to some build breakage.