feat(cmake): add ixm_fallback function

This brings a new function, `ixm_fallback`, which replaces an internal
command `🈯::ixm::default`, and is now available for consumers. This
command is used to assign values to variables that have not yet been
defined. This is most useful when `cmake_parse_arguments` has been
called and an optional value was not passed in to the user.

Behavior regarding it's interaction with CMP0174 has been documented as
well.

Signed-off-by: Izzy Muerte <63051+bruxisma@users.noreply.github.com>

Author: bruxisma

docs/commands/common.md

@@ -8,6 +8,22 @@ order: 1
 IXM's common commands handle several operations users might require as part of
 their day to day routines when writing CMake commands.
 
+## `ixm_fallback`
+
+Sets a default fallback value for a variable if it is not defined. The value
+set is whatever is passed after the `variable` argument (i.e., [`ARGN`][argn]).
+
+> [!IMPORTANT]
+> This function's behavior is directly affected by [CMP0174][policy-174], as it
+> checks if te given `variable` is `DEFINED` or not (i.e., if the variable is
+> "unset", the values provided are assigned).
+
+### Required Parameters {#fallback/required}
+
+`variable`
+: Name of the variable to store values in.
+: *Type*: `identifier`
+
 ## `ixm::unimplemented`
 
 This is a small helper function that simply prints a `FATAL_ERROR` with the
@@ -57,3 +73,6 @@ as `MATCH{<N>}` and `MATCH{COUNT}`. This also replaces instances of
 This command is a holdover from early implementations of IXM. While it may not
 currently be used by IXM, there is some value in rebinding the results of
 `string(REGEX MATCH)` or the condition syntax usage of `MATCHES`.
+
+[policy-174]: https://cmake.org/cmake/help/latest/policy/CMP0174.html
+[argn]: https://cmake.org/cmake/help/latest/command/function.html#arguments

modules/FindCoverage.cmake

@@ -139,12 +139,12 @@ file
 ]============================================================================]
 function (add_llvm_coverage name)
   cmake_parse_arguments(ARG "ALL" "EXPORT;OUTPUT;FORMAT;GITHUB" "TARGETS;IGNORE_FILENAME_REGEX" ${ARGN})
-  cmake_language(CALL 🈯::ixm::default ARG_EXPORT "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.lcov.info")
-  cmake_language(CALL 🈯::ixm::default ARG_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.profdata")
-  cmake_language(CALL 🈯::ixm::default ARG_FORMAT lcov)
+  ixm_fallback(ARG_EXPORT "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.lcov.info")
+  ixm_fallback(ARG_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/${name}.profdata")
+  ixm_fallback(ARG_FORMAT lcov)
   # Can't really remember why there's a ARG_GITHUB. Probably for
   # uploading/writing to a step summary automatically?
-  cmake_language(CALL 🈯::ixm::default ARG_GITHUB "${name}")
+  ixm_fallback(ARG_GITHUB "${name}")
   set(ignore.filename.regex $<GENEX_EVAL:$<TARGET_PROPERTY:${name},LLVM_IGNORE_FILENAME_REGEX>>)
   set(test.executables $<GENEX_EVAL:$<TARGET_PROPERTY:${name},LLVM_TEST_EXECUTABLES>>)
   set(profraw.sources $<GENEX_EVAL:$<TARGET_PROPERTY:${name},LLVM_PROFRAW_SOURCES>>)

runtime/common.cmake

@@ -58,15 +58,22 @@ function (🈯::ixm::experiment name uuid)
   endif()
 endfunction()
 
-#[[Used to set missing arguments to a well known default]]
-macro(🈯::ixm::default var default)
-  if (NOT ${var})
-    set(${var} ${default})
-  endif()
-endmacro()
-
 macro(🈯::ixm::requires name)
   if (NOT ARG_${name})
     message(FATAL_ERROR "function '${CMAKE_CURRENT_FUNCTION}' requires a '${name}' argument")
   endif()
 endmacro()
+
+#[============================================================================[
+# @summary Sets a default fallback value for a variable if it is not defined.
+# @description This is intended to be used inside of `function()`s after a call
+# to `cmake_parse_arguments`. While there is technically nothing stopping its
+# use in a general scope, users will most likely not receive this functions
+# benefits.
+# @param {identifier} variable - name of variable to set a fallback value for.
+#]============================================================================]
+function (ixm_fallback variable)
+  if (NOT DEFINED ${variable})
+    set(${variable} ${ARGN} PARENT_SCOPE)
+  endif()
+endfunction()

runtime/features.cmake

@@ -28,7 +28,7 @@ function (ixm::feature)
   cmake_language(CALL 🈯::ixm::requires NAME)
   cmake_language(CALL 🈯::ixm::feature::requirements)
 
-  cmake_language(CALL 🈯::ixm::default ARG_DEFAULT NO)
+  ixm_fallback(ARG_DEFAULT NO)
 
   if (ARG_PROJECT_ONLY)
     list(APPEND requirements PROJECT_IS_TOP_LEVEL)

runtime/find.cmake

@@ -25,15 +25,15 @@ include_guard(GLOBAL)
 #]============================================================================]
 function (ixm::find::program)
   cmake_language(CALL 🈯::ixm::find::prologue "" "" "VERSION" ${ARGN})
-  cmake_language(CALL 🈯::ixm::default ARG_OUTPUT_VARIABLE ${name}_EXECUTABLE)
+  ixm_fallback(ARG_OUTPUT_VARIABLE ${name}_EXECUTABLE)
 
   find_program(${ARG_OUTPUT_VARIABLE} NAMES ${ARG_NAMES} ${ARG_UNPARSED_ARGUMENTS})
   cmake_language(CALL 🈯::ixm::find::log)
   cmake_language(CALL 🈯::ixm::find::properties ${prefix}::{${target}}::program)
 
   if (ARG_VERSION AND ARG_OUTPUT_VARIABLE)
     cmake_parse_arguments(VERSION "" "OPTION;REGEX;VARIABLE;DESCRIPTION" "" ${ARG_VERSION})
-    cmake_language(CALL 🈯::ixm::default VERSION_VARIABLE ${name}_VERSION)
+    ixm_fallback(VERSION_VARIABLE ${name}_VERSION)
     cmake_language(CALL 🈯::ixm::find::version
       OUTPUT_VARIABLE ${VERSION_VARIABLE}
       DESCRIPTION "${VERSION_DESCRIPTION}"
@@ -64,11 +64,11 @@ endfunction()
 #]============================================================================]
 function (ixm::find::library)
   cmake_language(CALL 🈯::ixm::find::prologue "" "" "HEADER" ${ARGN})
-  cmake_language(CALL 🈯::ixm::default ARG_OUTPUT_VARIABLE ${name}_LIBRARY)
+  ixm_fallback(ARG_OUTPUT_VARIABLE ${name}_LIBRARY)
 
   if (DEFINED ARG_HEADER)
     cmake_parse_arguments(HEADER "" "VARIABLE" "" ${ARG_HEADER})
-    cmake_language(CALL 🈯::ixm::default HEADER_VARIABLE ${name}_INCLUDE_DIR)
+    ixm_fallback(HEADER_VARIABLE ${name}_INCLUDE_DIR)
   endif()
 
   find_library(${ARG_OUTPUT_VARIABLE} NAMES ${ARG_NAMES} ${ARG_UNPARSED_ARGUMENTS})
@@ -101,7 +101,7 @@ endfunction()
 #]============================================================================]
 function (ixm::find::header)
   cmake_language(CALL 🈯::ixm::find::prologue "" "" "" ${ARGN})
-  cmake_language(CALL 🈯::ixm::default ARG_OUTPUT_VARIABLE ${name}_INCLUDE_DIR)
+  ixm_fallback(ARG_OUTPUT_VARIABLE ${name}_INCLUDE_DIR)
 
   find_path(${ARG_OUTPUT_VARIABLE} NAMES ${ARG_NAMES} ${ARG_UNPARSED_ARGUMENTS})
   cmake_language(CALL 🈯::ixm::log)
@@ -121,10 +121,10 @@ function (ixm::find::framework)
   cmake_language(CALL 🈯::ixm::find::prologue "" "" "" ${ARGN})
   if (DEFINED ARG_HEADER)
     cmake_parse_arguments(HEADER "" "VARIABLE" "NAMES" ${ARG_HEADER})
-    cmake_language(CALL 🈯::ixm::default HEADER_VARIABLE ${name}_INCLUDE_DIR)
+    ixm_fallback(HEADER_VARIABLE ${name}_INCLUDE_DIR)
 
     # check what name is
-    cmake_language(CALL 🈯::ixm::default HEADER_NAMES "${name}/${name}.h")
+    ixm_fallback(HEADER_NAMES "${name}/${name}.h")
   endif()
   find_library(${ARG_OUTPUT_VARIABLE} NAMES ${ARG_NAMES} ${ARG_UNPARSED_ARGUMENTS})
   find_path(${HEADER_VARIABLE} NAMES ${HEADER_NAMES} ${ARG_UNPARSED_ARGUMENTS})
@@ -139,9 +139,9 @@ endfunction()
 function (🈯::ixm::find::version)
   cmake_parse_arguments(ARG "" "QUIET;OUTPUT_VARIABLE;DESCRIPTION;COMMAND;OPTION;REGEX" "" ${ARGN})
   cmake_language(CALL 🈯::ixm::requires OUTPUT_VARIABLE)
-  cmake_language(CALL 🈯::ixm::default ARG_DESCRIPTION "${ARG_COMMAND} version")
-  cmake_language(CALL 🈯::ixm::default ARG_OPTION "--version")
-  cmake_language(CALL 🈯::ixm::default ARG_REGEX
+  ixm_fallback(ARG_DESCRIPTION "${ARG_COMMAND} version")
+  ixm_fallback(ARG_OPTION "--version")
+  ixm_fallback(ARG_REGEX
     # This is a magic regex. It works in 95% of all cases.
     "[^0-9]*([0-9]+)[.]([0-9]+)?[.]?([0-9]+)?[.]?([0-9]+)?.*")
   if (NOT IS_EXECUTABLE "${ARG_COMMAND}")
@@ -206,11 +206,11 @@ macro (🈯::ixm::find::prologue options monadic variadic)
     ${ARGN})
 
   if (CMAKE_FIND_PACKAGE_NAME)
-    cmake_language(CALL 🈯::ixm::default ARG_NAMES ${CMAKE_FIND_PACKAGE_NAME})
+    ixm_fallback(ARG_NAMES ${CMAKE_FIND_PACKAGE_NAME})
     block (SCOPE_FOR VARIABLES PROPAGATE ARG_DESCRIPTION)
       list(LENGTH ARG_NAMES length)
       if (length EQUAL 1)
-        cmake_language(CALL 🈯::ixm::default ARG_DESCRIPTION "Path to ${ARG_NAMES}")
+        ixm_fallback(ARG_DESCRIPTION "Path to ${ARG_NAMES}")
       endif()
     endblock()