diff options
| author | Martin Duffy <martin.duffy@kitware.com> | 2023-09-14 17:13:38 (GMT) |
|---|---|---|
| committer | Brad King <brad.king@kitware.com> | 2023-09-20 14:25:24 (GMT) |
| commit | ec2ba29ac5e424cf0c52ba8ea5c2e3a4c2667d7a (patch) | |
| tree | eee817eede0b5dec75baf45735268ffc7e5e4997 /Help | |
| parent | 123cdf981661c8ae32335d4ae7e1ddcbcffd09cc (diff) | |
| download | CMake-ec2ba29ac5e424cf0c52ba8ea5c2e3a4c2667d7a.zip CMake-ec2ba29ac5e424cf0c52ba8ea5c2e3a4c2667d7a.tar.gz CMake-ec2ba29ac5e424cf0c52ba8ea5c2e3a4c2667d7a.tar.bz2 | |
Ninja: Allow compilation before generation of dependencies' private sources
This requires knowing when a generated header is public, which we can
model using file sets. Add policy CMP0154 to treat generated sources
as private by default in targets with file sets. Generated public
headers can be specified in public file sets.
Fixes: #24959
Issue: #15555
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/add_custom_command.rst | 10 | ||||
| -rw-r--r-- | Help/command/add_custom_target.rst | 5 | ||||
| -rw-r--r-- | Help/command/target_sources.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0154.rst | 53 | ||||
| -rw-r--r-- | Help/release/dev/fileset-private-dep.rst | 7 |
6 files changed, 78 insertions, 0 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 1fcf06c..5fe4326 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -87,6 +87,11 @@ The options are: :ref:`Target-dependent expressions <Target-Dependent Queries>` are not permitted. + .. versionchanged:: 3.28 + In targets using :ref:`file sets`, custom command byproducts are now + considered private unless they are listed in a non-private file set. + See policy :policy:`CMP0154`. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -270,6 +275,11 @@ The options are: :ref:`Target-dependent expressions <Target-Dependent Queries>` are not permitted. + .. versionchanged:: 3.28 + In targets using :ref:`file sets`, custom command outputs are now + considered private unless they are listed in a non-private file set. + See policy :policy:`CMP0154`. + ``USES_TERMINAL`` .. versionadded:: 3.2 diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index ef0c8d9..0385a93 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -63,6 +63,11 @@ The options are: :ref:`Target-dependent expressions <Target-Dependent Queries>` are not permitted. + .. versionchanged:: 3.28 + In custom targets using :ref:`file sets`, byproducts are now + considered private unless they are listed in a non-private file set. + See policy :policy:`CMP0154`. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 4a8eda2..86bf7fb 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -60,6 +60,8 @@ expressions to ensure the sources are correctly assigned to the target. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. +.. _`File Sets`: + File Sets ^^^^^^^^^ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index a018aff..dff4f34 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.28 .. toctree:: :maxdepth: 1 + CMP0154: Generated files are private by default in targets using file sets. </policy/CMP0154> CMP0153: The exec_program command should not be called. </policy/CMP0153> CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components. </policy/CMP0152> diff --git a/Help/policy/CMP0154.rst b/Help/policy/CMP0154.rst new file mode 100644 index 0000000..cb93d41 --- /dev/null +++ b/Help/policy/CMP0154.rst @@ -0,0 +1,53 @@ +CMP0154 +------- + +.. versionadded:: 3.28 + +Generated files are private by default in targets using :ref:`file sets`. + +CMake 3.27 and below assume that any file generated as an output or byproduct +of :command:`add_custom_command` or :command:`add_custom_target` may be a +public header file meant for inclusion by dependents' source files. This +requires :ref:`Ninja Generators` to add conservative order-only dependencies +that prevent a target's source files from compiling before custom commands +from the target's dependencies are finished, even if those custom commands +only produce sources private to their own target. + +:ref:`File Sets`, introduced by CMake 3.23, provide a way to express the +visibility of generated header files. CMake 3.28 and above prefer to +assume that, in targets using file sets, generated files are private to +their own target by default. Generated public headers must be specified +as members of a ``PUBLIC`` (or ``INTERFACE``) ``FILE_SET``, typically of +type ``HEADERS``. With this information, :ref:`Ninja Generators` may omit +the above-mentioned conservative dependencies and produce more efficient +build graphs. + +This policy provides compatibility for projects using file sets in targets +with generated header files that have not been updated. Such projects +should be updated to express generated public headers in a file set. +For example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h + ... + ) + target_sources(foo + PUBLIC FILE_SET HEADERS + BASE_DIRS ${CMAKE_CURRENT_BINARY_DIR} + FILES ${CMAKE_CURRENT_BINARY_DIR}/foo.h + ) + +The ``OLD`` behavior for this policy is to assume generated files are +public, even in targets using file sets, and for :ref:`Ninja Generators` +to produce conservative build graphs. The ``NEW`` behavior for this +policy is to assume generated files are private in targets using file sets, +and for :ref:`Ninja Generators` to produce more efficient build graphs. + +This policy was introduced in CMake version 3.28. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/release/dev/fileset-private-dep.rst b/Help/release/dev/fileset-private-dep.rst new file mode 100644 index 0000000..5ffb036 --- /dev/null +++ b/Help/release/dev/fileset-private-dep.rst @@ -0,0 +1,7 @@ +fileset-private-dep +------------------- + +* Generated files, in targets using :ref:`file sets`, are now considered + private by default. Generated public headers must be specified using + file sets. This allows :ref:`Ninja Generators` to produce more + efficient build graphs. See policy :policy:`CMP0154`. |