Add UserFeatureOption type

This is a special type of option to be passed to most 'required' keyword
arguments. It adds a 3rd state to the traditional boolean value to cause
those methods to always return not-found even if the dependency could be
found.

Since integrators doesn't want enabled features to be a surprise there
is a global option "auto_features" to enable or disable all
automatic features.

3 files changed, 58 insertions, 3 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index ec4a3bb..0093a1b 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -19,6 +19,7 @@ option('combo_opt', type : 'combo', choices : ['one', 'two', 'three'], value : '
 option('integer_opt', type : 'integer', min : 0, max : 5, value : 3) # Since 0.45.0
 option('free_array_opt', type : 'array', value : ['one', 'two'])
 option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two'])
+option('some_feature', type : 'feature', value : 'enabled')
 ```
 
 ## Build option types
@@ -62,6 +63,41 @@ default.
 
 This type is available since version 0.44.0
 
+### Features
+
+A `feature` option has three states: `enabled`, `disabled` or `auto`. It is intended
+to be passed as value for the `required` keyword argument of most functions.
+Currently supported in
+[`dependency()`](Reference-manual.md#dependency),
+[`find_library()`](Reference-manual.md#compiler-object),
+[`find_program()`](Reference-manual.md#find_program) and
+[`add_languages()`](Reference-manual.md#add_languages) functions.
+
+- `enabled` is the same as passing `required : true`.
+- `auto` is the same as passing `required : false`.
+- `disabled` do not look for the dependency and always return 'not-found'.
+
+When getting the value of this type of option using `get_option()`, a special
+object is returned instead of the string representation of the option's value.
+That object has three methods returning boolean and taking no argument:
+`enabled()`, `disabled()`, and `auto()`.
+
+```meson
+d = dependency('foo', required : get_option('myfeature'))
+if d.found()
+  app = executable('myapp', 'main.c', dependencies : [d])
+endif
+```
+
+If the value of a `feature` option is set to `auto`, that value is overriden by
+the global `auto_features` option (which defaults to `auto`). This is intended
+to be used by packagers who want to have full control on which dependencies are
+required and which are disabled, and not rely on build-deps being installed
+(at the right version) to get a feature enabled. They could set
+`auto_features=enabled` to enable all features and disable explicitly only the
+few they don't want, if any.
+
+This type is available since version 0.47.0
 
 ## Using build options
 
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 9829781..f75030f 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -60,7 +60,8 @@ endif
 Takes one keyword argument, `required`. It defaults to `true`, which
 means that if any of the languages specified is not found, Meson will
 halt. Returns true if all languages specified were found and false
-otherwise.
+otherwise. Since *0.47.0*  the value of a [`feature`](Build-options.md#features)
+option can also be passed to the `required` keyword argument.
 
 ### add_project_arguments()
 
@@ -354,7 +355,8 @@ otherwise. This function supports the following keyword arguments:
   cross compiled binary will run on), usually only needed if you build
   a tool to be used during compilation.
 - `required`, when set to false, Meson will proceed with the build
-  even if the dependency is not found
+  even if the dependency is not found. Since *0.47.0* the value of a
+  [`feature`](Build-options.md#features) option can also be passed.
 - `static` tells the dependency provider to try to get static
   libraries instead of dynamic ones (note that this is not supported
   by all dependency backends)
@@ -540,7 +542,9 @@ Keyword arguments are the following:
   abort if no program can be found. If `required` is set to `false`,
   Meson continue even if none of the programs can be found. You can
   then use the `.found()` method on the returned object to check
-  whether it was found or not.
+  whether it was found or not. Since *0.47.0*  the value of a
+  [`feature`](Build-options.md#features) option can also be passed to the
+  `required` keyword argument.
 
 - `native` *(since 0.43)* defines how this executable should be searched. By default
   it is set to `false`, which causes Meson to first look for the
@@ -675,6 +679,9 @@ handles that as expected, but if you need the absolute path to one of these
 e.g. to use in a define etc., you should use `join_paths(get_option('prefix'),
 get_option('localstatedir')))`
 
+For options of type `feature` a special object is returned instead of a string.
+See [`feature` options](Build-options.md#features) documentation for more details.
+
 ### get_variable()
 
 ``` meson
@@ -1564,6 +1571,8 @@ the following methods:
   library is searched for in the system library directory
   (e.g. /usr/lib). This can be overridden with the `dirs` keyword
   argument, which can be either a string or a list of strings.
+  Since *0.47.0*  the value of a [`feature`](Build-options.md#features) option
+  can also be passed to the `required` keyword argument.
 
 - `first_supported_argument(list_of_strings)`, given a list of
   strings, returns the first argument that passes the `has_argument`
diff --git a/docs/markdown/snippets/feature_options.md b/docs/markdown/snippets/feature_options.md
new file mode 100644
index 0000000..22d9201
--- /dev/null
+++ b/docs/markdown/snippets/feature_options.md
@@ -0,0 +1,10 @@
+## New feature option type
+
+A new type of option can be defined in `meson_options.txt` for the traditional
+`enabled / disabled / auto` tristate. The value of this option can be passed to
+the `required` keyword argument of functions `dependency()`, `find_library()`,
+`find_program()` and `add_languages()`.
+
+A new global option `auto_features` has been added to override the value of all
+`auto` features. It is intended to be used by packagers to have full control on
+which feature must be enabled or disabled.