mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-05 13:20:47 -06:00
ad3c2c0b03
Every policy's documentation has a paragraph on what version of CMake introduced it, how to set the policy, and whether CMake warns if the policy is not set. The wording of this paragraph has diverged across policies over time. Factor the paragraph out into a standard advice document included by every policy.
59 lines
2.4 KiB
ReStructuredText
59 lines
2.4 KiB
ReStructuredText
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.
|
|
|
|
Additionally, if the custom command's output is a member of a file set of type
|
|
``CXX_MODULES``, it will additionally not be required to exist before
|
|
compiling other sources in the same target. Since these files should not be
|
|
included at compile time directly, they may not be implicitly required to
|
|
exist for other compilation rules.
|
|
|
|
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.
|
|
|
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.28
|
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
|
|
.. include:: STANDARD_ADVICE.txt
|
|
|
|
.. include:: DEPRECATED.txt
|