Debian Codegraph @

subprojects/meson-docs/docs/yaml/objects/feature.yaml

raw
1 name: feature
2 long_name: Feature option object
3 since: 0.47.0
4 description: Meson object representing a [`feature` options](Build-options.md#features)
5
6 methods:
7 - name: enabled
8 returns: bool
9 description: Returns whether the feature was set to `'enabled'`
10
11 - name: disabled
12 returns: bool
13 description: Returns whether the feature was set to `'disabled'`
14
15 - name: auto
16 returns: bool
17 description: Returns whether the feature was set to `'auto'`
18
19 - name: allowed
20 since: 0.59.0
21 returns: bool
22 description: Returns whether the feature was set to `'enabled'` or `'auto'`
23
24 - name: disable_auto_if
25 since: 0.59.0
26 returns: feature
27 description: |
28 Returns the feature, with `'auto'` converted to `'disabled'` if value is true.
29
30 | Feature | `value = true` | `value = false` |
31 | -------- | -------------- | --------------- |
32 | Auto | Disabled | Auto |
33 | Enabled | Enabled | Enabled |
34 | Disabled | Disabled | Disabled |
35
36 example: |
37 `disable_auto_if` is useful to give precedence to mutually exclusive dependencies
38 (that provide the same API) if either or both are available:
39
40 ```
41 # '-Dfoo=auto -Dbar=enabled' will not pick foo even if installed.
42 use_bar = get_option('bar')
43 use_foo = get_option('foo').disable_auto_if(use_bar.enabled())
44 dep_foo = dependency('foo', required: use_foo)
45 if not dep_foo.found()
46 dep_foo = dependency('bar', required: use_bar)
47 endif
48 ```
49
50 posargs:
51 value:
52 type: bool
53 description: See the table above
54
55 - name: enable_auto_if
56 since: 1.1.0
57 returns: feature
58 description: |
59 Returns the feature, with `'auto'` converted to `'enabled'` if value is true.
60
61 | Feature | `value = true` | `value = false` |
62 | -------- | -------------- | --------------- |
63 | Auto | Enabled | Auto |
64 | Enabled | Enabled | Enabled |
65 | Disabled | Disabled | Disabled |
66
67 posargs:
68 value:
69 type: bool
70 description: See the table above
71
72 - name: require
73 returns: feature
74 since: 0.59.0
75 description: |
76 Returns the object itself if the value is true; an error if the object is
77 `'enabled'` and the value is false; a disabled feature if the object
78 is `'auto'` or `'disabled'` and the value is false.
79
80 | Feature | `value = true` | `value = false` |
81 | -------- | -------------- | --------------- |
82 | Auto | Auto | Disabled |
83 | Enabled | Enabled | Error |
84 | Disabled | Disabled | Disabled |
85
86 example: |
87 `require` is useful to restrict the applicability of `'auto'` features,
88 for example based on other features or on properties of the host machine:
89
90 ```
91 if get_option('directx').require(host_machine.system() == 'windows',
92 error_message: 'DirectX only available on Windows').allowed()
93 src += ['directx.c']
94 config.set10('HAVE_DIRECTX', true)
95 endif
96 ```
97
98 posargs:
99 value:
100 type: bool
101 description: The value to check
102
103 kwargs:
104 error_message:
105 type: str
106 default: "''"
107 description: The error message to print if the check fails
108
109 - name: enable_if
110 returns: feature
111 since: 1.1.0
112 description: |
113 Returns the object itself if the value is false; an error if the object is
114 `'disabled'` and the value is true; an enabled feature if the object
115 is `'auto'` or `'enabled'` and the value is true.
116
117 | Feature | `value = true` | `value = false` |
118 | -------- | -------------- | --------------- |
119 | Auto | Enabled | Auto |
120 | Enabled | Enabled | Enabled |
121 | Disabled | Error | Disabled |
122
123 example: |
124 `enable_if` is useful to restrict the applicability of `'auto'` features,
125 particularly when passing them to [[dependency]]:
126
127 ```
128 use_llvm = get_option('llvm').enable_if(with_clang).enable_if(with_llvm_libs)
129 dep_llvm = dependency('llvm', required: use_llvm)
130 ```
131
132 posargs:
133 value:
134 type: bool
135 description: The value to check
136
137 kwargs:
138 error_message:
139 type: str
140 default: "''"
141 description: The error message to print if the check fails
142
143 - name: disable_if
144 returns: feature
145 since: 1.1.0
146 description: |
147 Returns the object itself if the value is false; an error if the object is
148 `'enabled'` and the value is true; a disabled feature if the object
149 is `'auto'` or `'disabled'` and the value is true.
150
151 | Feature | `value = true` | `value = false` |
152 | -------- | -------------- | --------------- |
153 | Auto | Disabled | Auto |
154 | Enabled | Error | Enabled |
155 | Disabled | Disabled | Disabled |
156
157 This is equivalent to `feature_opt.require(not condition)`, but may make
158 code easier to reason about, especially when mixed with `enable_if`
159
160 example: |
161 `disable_if` is useful to restrict the applicability of `'auto'` features,
162 particularly when passing them to [[dependency]]:
163
164 ```
165 use_os_feature = get_option('foo') \
166 .disable_if(host_machine.system() == 'darwin', error_message : 'os feature not supported on MacOS')
167 dep_os_feature = dependency('os_feature', required: use_os_feature)
168 ```
169
170 posargs:
171 value:
172 type: bool
173 description: The value to check
174
175 kwargs:
176 error_message:
177 type: str
178 default: "''"
179 description: The error message to print if the check fails