diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/snippets/feature_if_methods.md | 77 | ||||
| -rw-r--r-- | docs/yaml/objects/feature.yaml | 60 |
2 files changed, 137 insertions, 0 deletions
diff --git a/docs/markdown/snippets/feature_if_methods.md b/docs/markdown/snippets/feature_if_methods.md new file mode 100644 index 000000000..9d7753446 --- /dev/null +++ b/docs/markdown/snippets/feature_if_methods.md @@ -0,0 +1,77 @@ +## Add a FeatureOption.enable_if and .disable_if + +These are useful when features need to be constrained to pass to [[dependency]], +as the behavior of an `auto` and `disabled` or `enabled` feature is markedly +different. consider the following case: + +```meson +opt = get_option('feature').disable_auto_if(not foo) +if opt.enabled() and not foo + error('Cannot enable feat when foo is not also enabled') +endif +dep = dependency('foo', required : opt) +``` + +This could be simplified to +```meson +opt = get_option('feature').disable_if(not foo, error_message : 'Cannot enable feature when foo is not also enabled') +dep = dependency('foo', required : opt) +``` + +For a real life example, here is some code in mesa: +```meson +_llvm = get_option('llvm') +dep_llvm = null_dep +with_llvm = false +if _llvm.allowed() + dep_llvm = dependency( + 'llvm', + version : _llvm_version, + modules : llvm_modules, + optional_modules : llvm_optional_modules, + required : ( + with_amd_vk or with_gallium_radeonsi or with_gallium_opencl or with_clc + or _llvm.enabled() + ), + static : not _shared_llvm, + fallback : ['llvm', 'dep_llvm'], + include_type : 'system', + ) + with_llvm = dep_llvm.found() +endif +if with_llvm + ... +elif with_amd_vk and with_aco_tests + error('ACO tests require LLVM, but LLVM is disabled.') +elif with_gallium_radeonsi or with_swrast_vk + error('The following drivers require LLVM: RadeonSI, SWR, Lavapipe. One of these is enabled, but LLVM is disabled.') +elif with_gallium_opencl + error('The OpenCL "Clover" state tracker requires LLVM, but LLVM is disabled.') +elif with_clc + error('The CLC compiler requires LLVM, but LLVM is disabled.') +else + draw_with_llvm = false +endif +``` + +simplified to: +```meson +_llvm = get_option('llvm') \ + .enable_if(with_amd_vk and with_aco_tests, error_message : 'ACO tests requires LLVM') \ + .enable_if(with_gallium_radeonsi, error_message : 'RadeonSI requires LLVM') \ + .enable_if(with_swrast_vk, error_message : 'Vulkan SWRAST requires LLVM') \ + .enable_if(with_gallium_opencl, error_message : 'The OpenCL Clover state trackers requires LLVM') \ + .enable_if(with_clc, error_message : 'CLC library requires LLVM') + +dep_llvm = dependency( + 'llvm', + version : _llvm_version, + modules : llvm_modules, + optional_modules : llvm_optional_modules, + required : _llvm, + static : not _shared_llvm, + fallback : ['llvm', 'dep_llvm'], + include_type : 'system', +) +with_llvm = dep_llvm.found() +``` diff --git a/docs/yaml/objects/feature.yaml b/docs/yaml/objects/feature.yaml index 01209eb53..9cb597be8 100644 --- a/docs/yaml/objects/feature.yaml +++ b/docs/yaml/objects/feature.yaml @@ -85,3 +85,63 @@ methods: 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. + + 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', require : 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. + + 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', require : 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 |