Add an option for explicit BYPRODUCTS of custom commands (#14963)

A common idiom in CMake-based build systems is to have custom commands
that generate files not listed explicitly as outputs so that these
files do not have to be newer than the inputs.  The file modification
times of such "byproducts" are updated only when their content changes.
Then other build rules can depend on the byproducts explicitly so that
their dependents rebuild when the content of the original byproducts
really does change.

This "undeclared byproduct" approach is necessary for Makefile, VS, and
Xcode build tools because if a byproduct were listed as an output of a
rule then the rule would always rerun when the input is newer than the
byproduct but the byproduct may never be updated.

Ninja solves this problem by offering a 'restat' feature to check
whether an output was really modified after running a rule and tracking
the fact that it is up to date separately from its timestamp.  However,
Ninja also stats all dependencies up front and will only restat files
that are listed as outputs of rules with the 'restat' option enabled.
Therefore an undeclared byproduct that does not exist at the start of
the build will be considered missing and the build will fail even if
other dependencies would cause the byproduct to be available before its
dependents build.

CMake works around this limitation by adding 'phony' build rules for
custom command dependencies in the build tree that do not have any
explicit specification of what produces them.  This is not optimal
because it prevents Ninja from reporting an error when an input to a
rule really is missing.  A better approach is to allow projects to
explicitly specify the byproducts of their custom commands so that no
phony rules are needed for them.  In order to work with the non-Ninja
generators, the byproducts must be known separately from the outputs.

Add a new "BYPRODUCTS" option to the add_custom_command and
add_custom_target commands to specify byproducts explicitly.  Teach the
Ninja generator to specify byproducts as outputs of the custom commands.
In the case of POST_BUILD, PRE_LINK, and PRE_BUILD events on targets
that link, the byproducts must be specified as outputs of the link rule
that runs the commands.  Activate 'restat' for such rules so that Ninja
knows it needs to check the byproducts, but not for link rules that have
no byproducts.

2 files changed, 45 insertions, 0 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index cb0746b..9fbad4b 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -15,6 +15,7 @@ The first signature is for adding a custom command to produce an output::
                      [COMMAND command2 [ARGS] [args2...] ...]
                      [MAIN_DEPENDENCY depend]
                      [DEPENDS [depends...]]
+                     [BYPRODUCTS [files...]]
                      [IMPLICIT_DEPENDS <lang1> depend1
                                       [<lang2> depend2] ...]
                      [WORKING_DIRECTORY dir]
@@ -44,6 +45,27 @@ The options are:
   options are currently ignored when APPEND is given, but may be
   used in the future.
 
+``BYPRODUCTS``
+  Specify the files the command is expected to produce but whose
+  modification time may or may not be newer than the dependencies.
+  If a byproduct name is a relative path it will be interpreted
+  relative to the build tree directory corresponding to the
+  current source directory.
+  Each byproduct file will be marked with the :prop_sf:`GENERATED`
+  source file property automatically.
+
+  Explicit specification of byproducts is supported by the
+  :generator:`Ninja` generator to tell the ``ninja`` build tool
+  how to regenerate byproducts when they are missing.  It is
+  also useful when other build rules (e.g. custom commands)
+  depend on the byproducts.  Ninja requires a build rule for any
+  generated file on which another rule depends even if there are
+  order-only dependencies to ensure the byproducts will be
+  available before their dependents build.
+
+  The ``BYPRODUCTS`` option is ignored on non-Ninja generators
+  except to mark byproducts ``GENERATED``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
@@ -156,6 +178,7 @@ target is already built, the command will not execute.
                      PRE_BUILD | PRE_LINK | POST_BUILD
                      COMMAND command1 [ARGS] [args1...]
                      [COMMAND command2 [ARGS] [args2...] ...]
+                     [BYPRODUCTS [files...]]
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
                      [VERBATIM] [USES_TERMINAL])
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 8b7472d..996d08e 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -8,6 +8,7 @@ Add a target with no output so it will always be built.
   add_custom_target(Name [ALL] [command1 [args1...]]
                     [COMMAND command2 [args2...] ...]
                     [DEPENDS depend depend depend ... ]
+                    [BYPRODUCTS [files...]]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment]
                     [VERBATIM] [USES_TERMINAL]
@@ -28,6 +29,27 @@ The options are:
   target so that it will be run every time (the command cannot be
   called ``ALL``).
 
+``BYPRODUCTS``
+  Specify the files the command is expected to produce but whose
+  modification time may or may not be updated on subsequent builds.
+  If a byproduct name is a relative path it will be interpreted
+  relative to the build tree directory corresponding to the
+  current source directory.
+  Each byproduct file will be marked with the :prop_sf:`GENERATED`
+  source file property automatically.
+
+  Explicit specification of byproducts is supported by the
+  :generator:`Ninja` generator to tell the ``ninja`` build tool
+  how to regenerate byproducts when they are missing.  It is
+  also useful when other build rules (e.g. custom commands)
+  depend on the byproducts.  Ninja requires a build rule for any
+  generated file on which another rule depends even if there are
+  order-only dependencies to ensure the byproducts will be
+  available before their dependents build.
+
+  The ``BYPRODUCTS`` option is ignored on non-Ninja generators
+  except to mark byproducts ``GENERATED``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,