Chiebot-Mirror
/
meson
mirror of https://github.com/mesonbuild/meson.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity
The Meson Build System http://mesonbuild.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
14814 Commits
76 Branches
171 Tags
76 MiB
Tag: Branch: Tree: 8548329586
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '8548329586'
${ noResults }
meson/docs/yaml/objects/feature.yaml

180 lines
5.4 KiB
Raw Normal View History Unescape

docs: Add the YAML Reference manual
3 years ago
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.
docs: Add more feature truth tables These are much easier to understand at a glance than free-form text.
1 year ago
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Disabled | Auto |
| Enabled | Enabled | Enabled |
| Disabled | Disabled | Disabled |
docs: Add the YAML Reference manual
3 years ago
docs: Provide example for feature.disable_auto_if
1 year ago
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
```
docs: Add the YAML Reference manual
3 years ago
posargs:
value:
type: bool
description: See the table above
interpreter: add a feature.enable_auto_if It's always been strange to me we don't have an opposite method of the `disable_auto_if` method, but I've been pressed to find a case where we _need_ one, because `disable_auto_if` can't be logically contorted to work. I finally found the case where they're not equivalent: when you don't want to convert to a boolean: ```meson f = get_option('feat').disable_auto_if(not foo) g = get_option('feat').enable_auto_if(foo) dep1 = dependency('foo', required : f) dep2 = dependency('foo', required : g) ```
2 years ago
- name: enable_auto_if
since: 1.1.0
returns: feature
description: |
Returns the feature, with `'auto'` converted to `'enabled'` if value is true.
docs: Add more feature truth tables These are much easier to understand at a glance than free-form text.
1 year ago
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Enabled | Auto |
| Enabled | Enabled | Enabled |
| Disabled | Disabled | Disabled |
interpreter: add a feature.enable_auto_if It's always been strange to me we don't have an opposite method of the `disable_auto_if` method, but I've been pressed to find a case where we _need_ one, because `disable_auto_if` can't be logically contorted to work. I finally found the case where they're not equivalent: when you don't want to convert to a boolean: ```meson f = get_option('feat').disable_auto_if(not foo) g = get_option('feat').enable_auto_if(foo) dep1 = dependency('foo', required : f) dep2 = dependency('foo', required : g) ```
2 years ago
posargs:
value:
type: bool
description: See the table above
docs: Add the YAML Reference manual
3 years ago
- 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.
docs: Add more feature truth tables These are much easier to understand at a glance than free-form text.
1 year ago
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Auto | Disabled |
| Enabled | Enabled | Error |
| Disabled | Disabled | Disabled |
docs: Add the YAML Reference manual
3 years ago
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']
interpreterobjects: deprecated passing a number to configuration_data.set10 This is currently allowed, and is used in at least a few projects. It was not intended to work or documented, but it does and since it is in use a full deprecation period must be used. A warning has also been added for values < 0, which have surprising behavior.
3 years ago
config.set10('HAVE_DIRECTX', true)
docs: Add the YAML Reference manual
3 years ago
endif
```
posargs:
value:
type: bool
description: The value to check
kwargs:
error_message:
type: str
default: "''"
Fix some random capitalization in feature.yaml
1 year ago
description: The error message to print if the check fails
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
- 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.
docs: Add more feature truth tables These are much easier to understand at a glance than free-form text.
1 year ago
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Enabled | Auto |
| Enabled | Enabled | Enabled |
| Disabled | Error | Disabled |
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
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)
docs: Fix some typos in feature option examples
2 years ago
dep_llvm = dependency('llvm', required: use_llvm)
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
```
posargs:
value:
type: bool
description: The value to check
kwargs:
error_message:
type: str
default: "''"
Fix some random capitalization in feature.yaml
1 year ago
description: The error message to print if the check fails
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
- 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.
docs: Add more feature truth tables These are much easier to understand at a glance than free-form text.
1 year ago
| Feature | `value = true` | `value = false` |
| -------- | -------------- | --------------- |
| Auto | Disabled | Auto |
| Enabled | Error | Enabled |
| Disabled | Disabled | Disabled |
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
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')
docs: Fix some typos in feature option examples
2 years ago
dep_os_feature = dependency('os_feature', required: use_os_feature)
interpreter: add FeatureOption.enable_if and .disable_if This adds two new methods, that are conceptually related in the same way that `enable_auto_if` and `disable_auto_if` are. They are different however, in that they will always replace an `auto` value with an `enabled` or `disabled` value, or error if the feature is in the opposite state (calling `feature(disabled).enable_if(true)`, for example). This matters when the feature will be passed to dependency(required : …)`, which has different behavior when passed an enabled feature than an auto one. The `disable_if` method will be controversial, I'm sure, since it can be expressed via `feature.require()` (`feature.require(not condition) == feature.disable_if(condition)`). I have two defences of this: 1) `feature.require` is difficult to reason about, I would expect require to be equivalent to `feature.enable_if(condition)`, not to `feature.disable_if(not condition)`. 2) mixing `enable_if` and `disable_if` in the same call chain is much clearer than mixing `require` and `enable_if`: ```meson get_option('feat') \ .enable_if(foo) \ .disable_if(bar) \ .enable_if(opt) ``` vs ```meson get_option('feat') \ .enable_if(foo) \ .require(not bar) \ .enable_if(opt) ``` In the first chain it's immediately obvious what is happening, in the second, not so much, especially if you're not familiar with what `require` means.
2 years ago
```
posargs:
value:
type: bool
description: The value to check
kwargs:
error_message:
type: str
default: "''"
Fix some random capitalization in feature.yaml
1 year ago
description: The error message to print if the check fails