Merge topic 'custom-command-output-genex-nmc'

1526ae3aba Tests: Add cases for Ninja Multi-Config cross-config custom commands
dcf9f4d2f7 Ninja Multi-Config: Add support for cross-config custom commands
15467f12f7 cmLocalGenerator: Adopt custom target 'force' output name generation
7b64b0cd5a cmLocalGenerator: Refactor custom command generator construction
d29da8ed3e cmMakefile: Simplify custom target 'force' output name generation
2b1cc175ee Help: Clarify version adding add_custom_{command,target} OUTPUT genex support

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5612

5 files changed, 124 insertions, 34 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 4464ad6..567af16 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -79,8 +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)>`.
+  .. versionadded:: 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.
@@ -229,8 +230,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)>`.
+  .. versionadded:: 3.20
+    Arguments to ``OUTPUT`` may use
+    :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
 ``USES_TERMINAL``
   .. versionadded:: 3.2
@@ -291,23 +293,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:
+.. versionadded:: 3.20
+  One may use generator expressions to specify per-configuration outputs.
+  For example, the code:
 
-.. code-block:: cmake
+  .. 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")
+    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.
+  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
 ^^^^^^^^^^^^
@@ -377,20 +380,30 @@ 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:
+.. versionadded:: 3.20
+  One may use generator expressions to specify per-configuration byproducts.
+  For example, the code:
 
-.. code-block:: cmake
+  .. 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")
+    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.
+
+Ninja Multi-Config
+^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.20
 
-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.
+  ``add_custom_command`` supports the :generator:`Ninja Multi-Config`
+  generator's cross-config capabilities. See the generator documentation
+  for more information.
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 85e1e16..9c4d60d 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -54,8 +54,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)>`.
+  .. versionadded:: 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.
@@ -167,3 +168,12 @@ The options are:
   .. versionadded:: 3.13
     Arguments to ``WORKING_DIRECTORY`` may use
     :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+Ninja Multi-Config
+^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.20
+
+  ``add_custom_target`` supports the :generator:`Ninja Multi-Config`
+  generator's cross-config capabilities. See the generator documentation
+  for more information.
diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
index 112db74..d1df42b 100644
--- a/Help/generator/Ninja Multi-Config.rst
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -86,3 +86,47 @@ used to generate ``generated.c``, which would be used to build the ``Debug``
 configuration of ``generated``. This is useful for running a release-optimized
 version of a generator utility while still building the debug version of the
 targets built with the generated code.
+
+Custom Commands
+^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.20
+
+The ``Ninja Multi-Config`` generator adds extra capabilities to
+:command:`add_custom_command` and :command:`add_custom_target` through its
+cross-config mode. The ``COMMAND``, ``DEPENDS``, and ``WORKING_DIRECTORY``
+arguments can be evaluated in the context of either the "command config" (the
+"native" configuration of the ``build-<Config>.ninja`` file in use) or the
+"output config" (the configuration used to evaluate the ``OUTPUT`` and
+``BYPRODUCTS``).
+
+If either ``OUTPUT`` or ``BYPRODUCTS`` names a path that is common to
+more than one configuration (e.g. it does not use any generator expressions),
+all arguments are evaluated in the command config by default.
+If all ``OUTPUT`` and ``BYPRODUCTS`` paths are unique to each configuration
+(e.g. by using the ``$<CONFIG>`` generator expression), the first argument of
+``COMMAND`` is still evaluated in the command config by default, while all
+subsequent arguments, as well as the arguments to ``DEPENDS`` and
+``WORKING_DIRECTORY``, are evaluated in the output config. These defaults can
+be overridden with the ``$<OUTPUT_CONFIG:...>`` and ``$<COMMAND_CONFIG:...>``
+generator-expressions. Note that if a target is specified by its name in
+``DEPENDS``, or as the first argument of ``COMMAND``, it is always evaluated
+in the command config, even if it is wrapped in ``$<OUTPUT_CONFIG:...>``
+(because its plain name is not a generator expression).
+
+As an example, consider the following:
+
+.. code-block:: cmake
+
+  add_custom_command(
+    OUTPUT "$<CONFIG>.txt"
+    COMMAND generator "$<CONFIG>.txt" "$<OUTPUT_CONFIG:$<CONFIG>>" "$<COMMAND_CONFIG:$<CONFIG>>"
+    DEPENDS tgt1 "$<TARGET_FILE:tgt2>" "$<OUTPUT_CONFIG:$<TARGET_FILE:tgt3>>" "$<COMMAND_CONFIG:$<TARGET_FILE:tgt4>>"
+    )
+
+Assume that ``generator``, ``tgt1``, ``tgt2``, ``tgt3``, and ``tgt4`` are all
+executable targets, and assume that ``$<CONFIG>.txt`` is built in the ``Debug``
+output config using the ``Release`` command config. The ``Release`` build of
+the ``generator`` target is called with ``Debug.txt Debug Release`` as
+arguments. The command depends on the ``Release`` builds of ``tgt1`` and
+``tgt4``, and the ``Debug`` builds of ``tgt2`` and ``tgt3``.
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 482b14e..c949ce1 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -816,6 +816,24 @@ Output-Related Expressions
   ``;`` on Windows).  Be sure to enclose the argument containing this genex
   in double quotes in CMake source code so that ``;`` does not split arguments.
 
+``$<OUTPUT_CONFIG:...>``
+  .. versionadded:: 3.20
+
+  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
+  as the outer-most generator expression in an argument.
+  With the :generator:`Ninja Multi-Config` generator, generator expressions
+  in ``...`` are evaluated using the custom command's "output config".
+  With other generators, the content of ``...`` is evaluated normally.
+
+``$<COMMAND_CONFIG:...>``
+  .. versionadded:: 3.20
+
+  Only valid in :command:`add_custom_command` and :command:`add_custom_target`
+  as the outer-most generator expression in an argument.
+  With the :generator:`Ninja Multi-Config` generator, generator expressions
+  in ``...`` are evaluated using the custom command's "command config".
+  With other generators, the content of ``...`` is evaluated normally.
+
 Debugging
 =========
 
diff --git a/Help/release/dev/custom-command-output-genex.rst b/Help/release/dev/custom-command-output-genex.rst
index 215349f..471713a 100644
--- a/Help/release/dev/custom-command-output-genex.rst
+++ b/Help/release/dev/custom-command-output-genex.rst
@@ -4,3 +4,8 @@ custom-command-output-genex
 * :command:`add_custom_command` and :command:`add_custom_target` now
   support :manual:`generator expressions <cmake-generator-expressions(7)>`
   in their ``OUTPUT`` and ``BYPRODUCTS`` options.
+
+  Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
+  support for new generator expressions ``$<COMMAND_CONFIG:...>`` and
+  ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using
+  the :generator:`Ninja Multi-Config` generator.