echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Clarify target_sources path conversion w.r.t generator expressions

Browse Source 
With some of the content expanded, reorder a few paragraphs
and tweak some of the wording to improve the flow.

Co-Authored-By: Craig Scott <craig.scott@crascit.com>
This commit is contained in:
Arcturus Arcturus 2021-10-28 22:05:26 +11:00 committed by Craig Scott
parent 9abd63dd3a
commit 9fac18a4a6
1 changed files with 34 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
Help/command/target_sources.rst
View File

@ -15,37 +15,50 @@ Specifies sources to use when building a target and/or its dependents.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` or
:command:`add_custom_target` and must not be an
:ref:`ALIAS target <Alias Targets>`.
:ref:`ALIAS target <Alias Targets>`. The ``<items>`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
.. versionadded:: 3.20
``<target>`` can be a custom target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the source file paths (``<items>``) that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES`
property of ``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents. A target created by :command:`add_custom_target`
can only have ``PRIVATE`` scope.
Repeated calls for the same ``<target>`` append items in the order called.
.. versionadded:: 3.3
Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on
:ref:`IMPORTED targets <Imported Targets>`.
.. versionchanged:: 3.13
Relative source file paths are interpreted as being relative to the current
source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
See policy :policy:`CMP0076`.
.. versionadded:: 3.20
``<target>`` can be a custom target.
A path that begins with a generator expression is left unmodified.
When a target's :prop_tgt:`SOURCE_DIR` property differs from
:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator
expressions to ensure the sources are correctly assigned to the target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`SOURCES` property of
``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents.
The following arguments specify sources. Repeated calls for the same
``<target>`` append items in the order called. The targets created by
:command:`add_custom_target` can only have ``PRIVATE`` scope.
.. code-block:: cmake
.. versionadded:: 3.3
Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.
# WRONG: starts with generator expression, but relative path used
target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>")
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
# CORRECT: absolute path used inside the generator expression
target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
Arguments to ``target_sources`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
.. code-block:: cmake