add_custom_command: Add CODEGEN support

By specifying CODEGEN as an argument to add_custom_command the
custom command will be added to a codegen build target.

The intent is to provide a convenient way for users to get
their generated files without having to build the whole project.

This can be helpful for code analysis tools which can be useful
for IDEs and CI.

4 files changed, 76 insertions, 0 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 77357c0..6169038 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -26,6 +26,7 @@ The first signature is for adding a custom command to produce an output:
                      [JOB_POOL job_pool]
                      [JOB_SERVER_AWARE <bool>]
                      [VERBATIM] [APPEND] [USES_TERMINAL]
+                     [CODEGEN]
                      [COMMAND_EXPAND_LISTS]
                      [DEPENDS_EXPLICIT_ONLY])
 
@@ -203,6 +204,18 @@ The options are:
   ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
   to be properly expanded.
 
+``CODEGEN``
+  .. versionadded:: 3.31
+
+  Adds the custom command to a global ``codegen`` target that can be
+  used to execute the custom command while avoiding the majority of the
+  build graph.
+
+  This option is supported only by :ref:`Ninja Generators` and
+  :ref:`Makefile Generators`, and is ignored by other generators.
+  Furthermore, this option is allowed only if policy :policy:`CMP0171`
+  is set to ``NEW``.
+
 ``IMPLICIT_DEPENDS``
   Request scanning of implicit dependencies of an input file.
   The language given specifies the programming language whose
@@ -454,6 +467,25 @@ will re-run whenever ``in.txt`` changes.
   where ``<config>`` is the build configuration, and then compile the generated
   source as part of a library.
 
+.. versionadded:: 3.31
+  Use the ``CODEGEN`` option to add a custom command's outputs to the builtin
+  ``codegen`` target.  This is useful to make generated code available for
+   static analysis without building the entire project.  For example:
+
+  .. code-block:: cmake
+
+    add_executable(someTool someTool.c)
+
+    add_custom_command(
+      OUTPUT out.c
+      COMMAND someTool -o out.c
+      CODEGEN)
+
+    add_library(myLib out.c)
+
+  A user may build the ``codegen`` target to generate ``out.c``.
+  ``someTool`` is built as dependency, but ``myLib`` is not built at all.
+
 Example: Generating Files for Multiple Targets
 """"""""""""""""""""""""""""""""""""""""""""""
 
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 7155404..90c71b7 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.31
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0171: 'codegen' is a reserved target name. </policy/CMP0171>
+
 Policies Introduced by CMake 3.30
 =================================
 
diff --git a/Help/policy/CMP0171.rst b/Help/policy/CMP0171.rst
new file mode 100644
index 0000000..c364bf4
--- /dev/null
+++ b/Help/policy/CMP0171.rst
@@ -0,0 +1,26 @@
+CMP0171
+-------
+
+.. versionadded:: 3.31
+
+``codegen`` is a reserved target name.
+
+CMake 3.30 and earlier did not reserve ``codegen`` as a builtin target name,
+leaving projects free to create their own target with that name.
+CMake 3.31 and later prefer to reserve ``codegen`` as a builtin target name
+to drive custom commands created with the ``CODEGEN`` option to
+:command:`add_custom_command`.  In order to support building the ``codegen``
+target in scripted environments, e.g., ``cmake --build . --target codegen``,
+the ``codegen`` target needs to be generated even if no custom commands
+use the ``CODEGEN`` option.  This policy provides compatibility for projects
+that have not been updated to avoid creating a target named ``codegen``.
+
+The ``OLD`` behavior of this policy allows projects to create a target
+with the name ``codegen``.  The ``NEW`` behavior halts with a fatal error
+if a target with the name ``codegen`` is created.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/codegen.rst b/Help/release/dev/codegen.rst
new file mode 100644
index 0000000..e8b61c9
--- /dev/null
+++ b/Help/release/dev/codegen.rst
@@ -0,0 +1,10 @@
+codegen
+-------
+
+* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
+  a ``codegen`` build target.  See policy :policy:`CMP0171`.  It drives a
+  subset of the build graph sufficient to run custom commands created with
+  :command:`add_custom_command`'s new ``CODEGEN`` option.
+
+* The :command:`add_custom_command` command gained a ``CODEGEN`` option
+  to mark a custom commands outputs as dependencies of a ``codegen`` target.