| name: feature |
| long_name: Feature option object |
| since: 0.47.0 |
| description: Meson object representing a [`feature` options](Build-options.md#features) |
| |
| methods: |
| - name: enabled |
| returns: bool |
| description: Returns whether the feature was set to `'enabled'` |
| |
| - name: disabled |
| returns: bool |
| description: Returns whether the feature was set to `'disabled'` |
| |
| - name: auto |
| returns: bool |
| description: Returns whether the feature was set to `'auto'` |
| |
| - name: allowed |
| since: 0.59.0 |
| returns: bool |
| description: Returns whether the feature was set to `'enabled'` or `'auto'` |
| |
| - name: disable_auto_if |
| since: 0.59.0 |
| returns: feature |
| description: | |
| Returns the feature, with `'auto'` converted to `'disabled'` if value is true. |
| |
| | Feature | `value = true` | `value = false` | |
| | -------- | -------------- | --------------- | |
| | Auto | Disabled | Auto | |
| | Enabled | Enabled | Enabled | |
| | Disabled | Disabled | Disabled | |
| |
| example: | |
| `disable_auto_if` is useful to give precedence to mutually exclusive dependencies |
| (that provide the same API) if either or both are available: |
| |
| ``` |
| # '-Dfoo=auto -Dbar=enabled' will not pick foo even if installed. |
| use_bar = get_option('bar') |
| use_foo = get_option('foo').disable_auto_if(use_bar.enabled()) |
| dep_foo = dependency('foo', required: use_foo) |
| if not dep_foo.found() |
| dep_foo = dependency('bar', required: use_bar) |
| endif |
| ``` |
| |
| posargs: |
| value: |
| type: bool |
| description: See the table above |
| |
| - name: enable_auto_if |
| since: 1.1.0 |
| returns: feature |
| description: | |
| Returns the feature, with `'auto'` converted to `'enabled'` if value is true. |
| |
| | Feature | `value = true` | `value = false` | |
| | -------- | -------------- | --------------- | |
| | Auto | Enabled | Auto | |
| | Enabled | Enabled | Enabled | |
| | Disabled | Disabled | Disabled | |
| |
| posargs: |
| value: |
| type: bool |
| description: See the table above |
| |
| - name: require |
| returns: feature |
| since: 0.59.0 |
| description: | |
| 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. |
| |
| | Feature | `value = true` | `value = false` | |
| | -------- | -------------- | --------------- | |
| | Auto | Auto | Disabled | |
| | Enabled | Enabled | Error | |
| | Disabled | Disabled | Disabled | |
| |
| example: | |
| `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', true) |
| endif |
| ``` |
| |
| posargs: |
| value: |
| type: bool |
| description: The value to check |
| |
| kwargs: |
| error_message: |
| type: str |
| default: "''" |
| description: The error message to print if the check fails |
| |
| - name: enable_if |
| returns: feature |
| since: 1.1.0 |
| description: | |
| Returns the object itself if the value is false; an error if the object is |
| `'disabled'` and the value is true; an enabled feature if the object |
| is `'auto'` or `'enabled'` and the value is true. |
| |
| | Feature | `value = true` | `value = false` | |
| | -------- | -------------- | --------------- | |
| | Auto | Enabled | Auto | |
| | Enabled | Enabled | Enabled | |
| | Disabled | Error | Disabled | |
| |
| example: | |
| `enable_if` is useful to restrict the applicability of `'auto'` features, |
| particularly when passing them to [[dependency]]: |
| |
| ``` |
| use_llvm = get_option('llvm').enable_if(with_clang).enable_if(with_llvm_libs) |
| dep_llvm = dependency('llvm', required: use_llvm) |
| ``` |
| |
| posargs: |
| value: |
| type: bool |
| description: The value to check |
| |
| kwargs: |
| error_message: |
| type: str |
| default: "''" |
| description: The error message to print if the check fails |
| |
| - name: disable_if |
| returns: feature |
| since: 1.1.0 |
| description: | |
| Returns the object itself if the value is false; an error if the object is |
| `'enabled'` and the value is true; a disabled feature if the object |
| is `'auto'` or `'disabled'` and the value is true. |
| |
| | Feature | `value = true` | `value = false` | |
| | -------- | -------------- | --------------- | |
| | Auto | Disabled | Auto | |
| | Enabled | Error | Enabled | |
| | Disabled | Disabled | Disabled | |
| |
| This is equivalent to `feature_opt.require(not condition)`, but may make |
| code easier to reason about, especially when mixed with `enable_if` |
| |
| example: | |
| `disable_if` is useful to restrict the applicability of `'auto'` features, |
| particularly when passing them to [[dependency]]: |
| |
| ``` |
| use_os_feature = get_option('foo') \ |
| .disable_if(host_machine.system() == 'darwin', error_message : 'os feature not supported on MacOS') |
| dep_os_feature = dependency('os_feature', required: use_os_feature) |
| ``` |
| |
| posargs: |
| value: |
| type: bool |
| description: The value to check |
| |
| kwargs: |
| error_message: |
| type: str |
| default: "''" |
| description: The error message to print if the check fails |
