add_custom_{command,target}: Add genex support to OUTPUT and BYPRODUCTS

Move rejection of `#`, `<`, and `>` characters in outputs and byproducts
to a generate-time check.  This removes the front-end check that
disallowed generator expressions.  The generators have already been
updated to handle them.

Fixes: #12877

1 files changed, 48 insertions, 0 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 85d56a3..4464ad6 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -46,6 +46,12 @@ The options are:
   Append the ``COMMAND`` and ``DEPENDS`` option values to the custom
   command for the first output specified.  There must have already
   been a previous call to this command with the same output.
+
+  If the previous call specified the output via a generator expression,
+  the output specified by the current call must match in at least one
+  configuration after evaluating generator expressions.  In this case,
+  the appended commands and dependencies apply to all configurations.
+
   The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
   options are currently ignored when APPEND is given, but may be
   used in the future.
@@ -73,6 +79,9 @@ The options are:
   The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
   :prop_sf:`GENERATED` files during ``make clean``.
 
+  Since CMake 3.20, arguments to ``BYPRODUCTS`` may use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
@@ -220,6 +229,9 @@ The options are:
   as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
   source file property.
 
+  Since CMake 3.20, arguments to ``OUTPUT`` may use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``USES_TERMINAL``
   .. versionadded:: 3.2
 
@@ -279,6 +291,24 @@ adds a custom command to run ``someTool`` to generate ``out.c`` and then
 compile the generated source as part of a library.  The generation rule
 will re-run whenever ``in.txt`` changes.
 
+Since CMake 3.20, one may use generator expressions to specify
+per-configuration outputs.  For example, the code:
+
+.. code-block:: cmake
+
+  add_custom_command(
+    OUTPUT "out-$<CONFIG>.c"
+    COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
+                     -o "out-$<CONFIG>.c"
+                     -c "$<CONFIG>"
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
+    VERBATIM)
+  add_library(myLib "out-$<CONFIG>.c")
+
+adds a custom command to run ``someTool`` to generate ``out-<config>.c``,
+where ``<config>`` is the build configuration, and then compile the generated
+source as part of a library.
+
 Build Events
 ^^^^^^^^^^^^
 
@@ -346,3 +376,21 @@ For example, the code:
 
 will run ``someHasher`` to produce a ``.hash`` file next to the executable
 after linking.
+
+Since CMake 3.20, one may use generator expressions to specify
+per-configuration byproducts.  For example, the code:
+
+.. code-block:: cmake
+
+  add_library(myPlugin MODULE myPlugin.c)
+  add_custom_command(
+    TARGET myPlugin POST_BUILD
+    COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
+                       --as-code "myPlugin-hash-$<CONFIG>.c"
+    BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
+    VERBATIM)
+  add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
+
+will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c``
+file containing code to check the hash of ``myPlugin`` that the ``myExe``
+executable can use to verify it before loading.