From b2473b61cc2c61218f5be4057af0e42b63d00048 Mon Sep 17 00:00:00 2001
From: Dylan Baker <dylan@pnwbakers.com>
Date: Wed, 21 Dec 2022 11:23:34 -0800
Subject: interpreter: add FeatureOption.enable_if and .disable_if
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 docs/markdown/snippets/feature_if_methods.md | 77 ++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 docs/markdown/snippets/feature_if_methods.md

(limited to 'docs/markdown/snippets')

diff --git a/docs/markdown/snippets/feature_if_methods.md b/docs/markdown/snippets/feature_if_methods.md
new file mode 100644
index 0000000..9d77534
--- /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()
+```
-- 
cgit v1.1