feat(cmake): add ixm_property command to the public runtime (#40)

This introduces `ixm_property`, a command that was originally
implemented as `ixm_target_property` in #21. However, as that PR is
broken apart and into separate pieces I've been re-evaluating how each
component should be named or how it works. Not much has changed with
this command's implementation however it's name required an update as
only target properties can be used with this command anyhow. There are
possibly more useful additions that can be added for the final generator
expression that is generated, however I'm keeping it as simple as it can
be for now given its use-cases.

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

Author: bruxisma

docs/commands/common.md

@@ -21,8 +21,51 @@ set is whatever is passed after the `variable` argument (i.e., [`ARGN`][argn]).
 ### Required Parameters {#fallback/required}
 
 `variable`
+: *Type*: `identifier`
 : Name of the variable to store values in.
+
+## `ixm_property`
+
+Creates a generator expression for reading from a target property, as well as
+ensuring that any resulting values from said generator expression are also
+evaluated. Supports both the `$<TARGET_PROPERTY:target,property>` format, as
+well as `$<TARGET_PROPERTY:property>`.
+
+### Required Parameters {#property/required}
+
+`property`
 : *Type*: `identifier`
+: Name of the property to create the generator expression for.
+
+
+### Keyword Parameters {#property/required}
+
+`CONTEXT`
+: *Type*: `option`
+: Use `TARGET_GENEX_EVAL` instead of `GENEX_EVAL` for the generator expression.
+
+`TARGET`
+: *Type*: `target`
+: Name of target or a generator expression that evaluates to a target name.
+
+`OUTPUT_VARIABLE`
+: *Type*: `identifier`
+: *Default: `${property}`
+: Name of the variable to write the generator expression to.
+
+`PREFIX`
+: *Type*: `identifier[]`
+: Any number of identifiers to prefix to the property. These are joined via the
+  `_` character, and are most useful when the `OUTPUT_VARIABLE` argument isn't
+  used and the user wishes to use the provided `property` instead.
+
+### Example
+
+```cmake
+ixm_property(IMPORTED_LOCATION TARGET ccache::ccache)
+set_property(TARGET ${PROJECT_NAME} PROPERTY
+  CXX_COMPILER_LAUNCHER ${IMPORTED_LOCATION})
+```
 
 ## `ixm::unimplemented`
 

runtime/common.cmake

@@ -77,3 +77,36 @@ function (ixm_fallback variable)
     set(${variable} ${ARGN} PARENT_SCOPE)
   endif()
 endfunction()
+#[============================================================================[
+# @summary Creates a generator expression for reading from a target property.
+# @description This command permits creating generator expressions for targets
+# that are *not yet defined*, even if the `TARGET` parameter is passed in.
+#
+# @param {identifier} property - Name of the property to create generator
+# expression for.
+# @param {option} [CONTEXT] - Use `TARGET_GENEX_EVAL` instead of `GENEX_EVAL`.
+# Does nothing if `TARGET` has not been specified.
+# @param {target} [TARGET] - Name of a target to use for context and scope.
+# @param {identifier} [OUTPUT_VARIABLE=${property}] - Name of the variable to
+# output.
+# @param {list} [PREFIX] - Additional prefixes to prepend to the property.
+# These are joined via the `_` character. Useful if `OUTPUT_VARIABLE` is not
+# provided, as this allows for more complex property generator expressions with
+# simple output variables.
+#]============================================================================]
+function (ixm_property property)
+  cmake_parse_arguments(PARSE_ARGV 1 ARG "CONTEXT" "TARGET;OUTPUT_VARIABLE" "PREFIX")
+  ixm_fallback(ARG_OUTPUT_VARIABLE ${property})
+  string(JOIN _ property ${ARG_PREFIX} ${property})
+
+  set(eval GENEX_EVAL:)
+  set(target)
+  if (ARG_TARGET)
+    set(target "${ARG_TARGET},") # note the `,` at the end of the string
+    if (ARG_CONTEXT)
+      set(eval TARGET_GENEX_EVAL:${target})
+    endif()
+  endif()
+
+  set(${ARG_OUTPUT_VARIABLE} "$<${eval}$<TARGET_PROPERTY:${target}${property}>>" PARENT_SCOPE)
+endfunction()