1CMP0058 2------- 3 4.. versionadded:: 3.3 5 6Ninja requires custom command byproducts to be explicit. 7 8When an intermediate file generated during the build is consumed 9by an expensive operation or a large tree of dependents, one may 10reduce the work needed for an incremental rebuild by updating the 11file timestamp only when its content changes. With this approach 12the generation rule must have a separate output file that is always 13updated with a new timestamp that is newer than any dependencies of 14the rule so that the build tool re-runs the rule only when the input 15changes. We refer to the separate output file as a rule's *witness* 16and the generated file as a rule's *byproduct*. 17 18Byproducts may not be listed as outputs because their timestamps are 19allowed to be older than the inputs. No build tools (like ``make``) 20that existed when CMake was designed have a way to express byproducts. 21Therefore CMake versions prior to 3.2 had no way to specify them. 22Projects typically left byproducts undeclared in the rules that 23generate them. For example: 24 25.. code-block:: cmake 26 27 add_custom_command( 28 OUTPUT witness.txt 29 COMMAND ${CMAKE_COMMAND} -E copy_if_different 30 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt 31 byproduct.txt # timestamp may not change 32 COMMAND ${CMAKE_COMMAND} -E touch witness.txt 33 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt 34 ) 35 add_custom_target(Provider DEPENDS witness.txt) 36 add_custom_command( 37 OUTPUT generated.c 38 COMMAND expensive-task -i byproduct.txt -o generated.c 39 DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt 40 ) 41 add_library(Consumer generated.c) 42 add_dependencies(Consumer Provider) 43 44This works well for all generators except :generator:`Ninja`. 45The Ninja build tool sees a rule listing ``byproduct.txt`` 46as a dependency and no rule listing it as an output. Ninja then 47complains that there is no way to satisfy the dependency and 48stops building even though there are order-only dependencies 49that ensure ``byproduct.txt`` will exist before its consumers 50need it. See discussion of this problem in `Ninja Issue 760`_ 51for further details on why Ninja works this way. 52 53.. _`Ninja Issue 760`: https://github.com/martine/ninja/issues/760 54 55Instead of leaving byproducts undeclared in the rules that generate 56them, Ninja expects byproducts to be listed along with other outputs. 57Such rules may be marked with a ``restat`` option that tells Ninja 58to check the timestamps of outputs after the rules run. This 59prevents byproducts whose timestamps do not change from causing 60their dependents to re-build unnecessarily. 61 62Since the above approach does not tell CMake what custom command 63generates ``byproduct.txt``, the Ninja generator does not have 64enough information to add the byproduct as an output of any rule. 65CMake 2.8.12 and above work around this problem and allow projects 66using the above approach to build by generating ``phony`` build 67rules to tell Ninja to tolerate such missing files. However, this 68workaround prevents Ninja from diagnosing a dependency that is 69really missing. It also works poorly in in-source builds where 70every custom command dependency, even on source files, needs to 71be treated this way because CMake does not have enough information 72to know which files are generated as byproducts of custom commands. 73 74CMake 3.2 introduced the ``BYPRODUCTS`` option to the 75:command:`add_custom_command` and :command:`add_custom_target` 76commands. This option allows byproducts to be specified explicitly: 77 78.. code-block:: cmake 79 80 add_custom_command( 81 OUTPUT witness.txt 82 BYPRODUCTS byproduct.txt # explicit byproduct specification 83 COMMAND ${CMAKE_COMMAND} -E copy_if_different 84 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt 85 byproduct.txt # timestamp may not change 86 ... 87 88The ``BYPRODUCTS`` option is used by the :generator:`Ninja` generator 89to list byproducts among the outputs of the custom commands that 90generate them, and is ignored by other generators. 91 92CMake 3.3 and above prefer to require projects to specify custom 93command byproducts explicitly so that it can avoid using the 94``phony`` rule workaround altogether. Policy ``CMP0058`` was 95introduced to provide compatibility with existing projects that 96still need the workaround. 97 98This policy has no effect on generators other than :generator:`Ninja`. 99The ``OLD`` behavior for this policy is to generate Ninja ``phony`` 100rules for unknown dependencies in the build tree. The ``NEW`` 101behavior for this policy is to not generate these and instead 102require projects to specify custom command ``BYPRODUCTS`` explicitly. 103 104This policy was introduced in CMake version 3.3. 105CMake version |release| warns when it sees unknown dependencies in 106out-of-source build trees if the policy is not set and then uses 107``OLD`` behavior. Use the :command:`cmake_policy` command to set 108the policy to ``OLD`` or ``NEW`` explicitly. The policy setting 109must be in scope at the end of the top-level ``CMakeLists.txt`` 110file of the project and has global effect. 111 112.. include:: DEPRECATED.txt 113