define_from_variant: return an empty string for non-existing variants (#27503)

This permits to use conditional variants without a lot of boilerplate.

1 files changed, 14 insertions, 0 deletions

diff --git a/lib/spack/docs/build_systems/cmakepackage.rst b/lib/spack/docs/build_systems/cmakepackage.rst
index 3c3c96f92c..7ebac48734 100644
--- a/lib/spack/docs/build_systems/cmakepackage.rst
+++ b/lib/spack/docs/build_systems/cmakepackage.rst
@@ -145,6 +145,20 @@ and without the :meth:`~spack.build_systems.cmake.CMakePackage.define` and
 
        return args
 
+Spack supports CMake defines from conditional variants too. Whenever the condition on
+the variant is not met, ``define_from_variant()`` will simply return an empty string,
+and CMake simply ignores the empty command line argument. For example the following
+
+.. code-block:: python
+
+   variant('example', default=True, when='@2.0:')
+
+   def cmake_args(self):
+      return [self.define_from_variant('EXAMPLE', 'example')]
+
+will generate ``'cmake' '-DEXAMPLE=ON' ...`` when `@2.0: +example` is met, but will
+result in ``'cmake' '' ...`` when the spec version is below ``2.0``.
+
 
 ^^^^^^^^^^
 Generators