interpreter: add feature.require()

Add a method to perform a logical AND on a feature object.  The method
also takes care of raising an error if 'enabled' is ANDed with false.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index f6b3fc2..12ddfce 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -2819,6 +2819,21 @@ The following methods are defined for all [`feature` options](Build-options.md#f
 - `disabled()`: returns whether the feature was set to `'disabled'`
 - `auto()`: returns whether the feature was set to `'auto'`
 - `allowed()` *(since 0.59.0)*: returns whether the feature was set to `'enabled'` or `'auto'`
+- `require(value, error_message: '')` *(since 0.59.0)*: returns
+  the object itself if the value is true; an error if the object is
+  `'enabled'` and the value is false; a disabled feature if the object
+  is `'auto'` or `'disabled'` and the value is false.
+
+`require` is useful to restrict the applicability of `'auto'` features,
+for example based on other features or on properties of the host machine:
+
+```
+if get_option('directx').require(host_machine.system() == 'windows',
+       error_message: 'DirectX only available on Windows').allowed() then
+  src += ['directx.c']
+  config.set10('HAVE_DIRECTX', 1)
+endif
+```
 
 ### `generator` object