User options can "yield to" a user option of the same name in superproject. Closes ##2853.

2 files changed, 26 insertions, 0 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index 85e8274..74d2355 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -108,3 +108,21 @@ double quotes.
 **NOTE:** If you cannot call `meson configure` you likely have a old
   version of Meson. In that case you can call `mesonconf` instead, but
   that is deprecated in newer versions
+
+## Yielding to superproject option
+
+Suppose you have a master project and a subproject. In some cases it
+might be useful to have an option that has the same value in both of
+them. This can be achieved with the `yield` keyword. Suppose you have
+an option definition like this:
+
+```meson
+option('some_option', type : 'string', value : 'value', yield : true)
+```
+
+If you build this project on its own, this option behaves like
+usual. However if you build this project as a subproject of another
+project which also has an option called `some_option`, then calling
+`get_option` returns the value of the superproject. If the value of
+`yield` is `false`, `get_option` returns the value of the subproject's
+option.
diff --git a/docs/markdown/snippets/yield.md b/docs/markdown/snippets/yield.md
new file mode 100644
index 0000000..3880e67
--- /dev/null
+++ b/docs/markdown/snippets/yield.md
@@ -0,0 +1,8 @@
+## Yielding subproject option to superproject
+
+Normally project options are specific to the current project. However
+sometimes you want to have an option whose value is the same over all
+projects. This can be achieved with the new `yield` keyword for
+options. When set to `true`, getting the value of this option in
+`meson.build` files gets the value from the option with the same name
+in the master project (if such an option exists).