mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-31 02:39:48 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Link from usage requirement commands to detailed explanation

Browse Source 
Augment vague mentions of "Transitive Usage Requirements" with links to
a detailed explanation.

Fixes: #23799
This commit is contained in:
Hinell
2022-09-07 17:53:30 +03:00
committed by Brad King
parent cabba23ab2
commit 3d31f99b74
10 changed files with 42 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Help/command/target_compile_definitions.rst
View File

@@ -15,9 +15,9 @@ named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.
The following arguments specify compile definitions. Repeated calls for the
same ``<target>`` append items in the order called.

6
Help/command/target_compile_options.rst
View File

@@ -22,9 +22,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.
The following arguments specify compile options. Repeated calls for the same
``<target>`` append items in the order called.

6
Help/command/target_include_directories.rst
View File

@@ -18,9 +18,9 @@ By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
and prepending, independent of the default.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``.
``PUBLIC`` and ``INTERFACE`` items will populate the
the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
The following arguments specify include directories.

11
Help/command/target_link_directories.rst
View File

@@ -21,11 +21,12 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the items that follow them. ``PRIVATE`` and
``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property
of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
specify the :ref:`scope <Target Usage Requirements>` of the items that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the
:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and
``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only
support ``INTERFACE`` items).
Each item specifies a link directory and will be converted to an absolute
path if necessary before adding it to the relevant property. Repeated
calls for the same ``<target>`` append items in the order called.

4
Help/command/target_link_libraries.rst
View File

@@ -146,8 +146,10 @@ Libraries for a Target and/or its Dependents
<PRIVATE|PUBLIC|INTERFACE> <item>...
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
:ref:`scope <Target Usage Requirements>` keywords can be used to
specify both the link dependencies and the link interface in one command.
Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface. Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface. Libraries

6
Help/command/target_link_options.rst
View File

@@ -32,9 +32,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`LINK_OPTIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
The following arguments specify link options. Repeated calls for the same
``<target>`` append items in the order called.

6
Help/command/target_precompile_headers.rst
View File

@@ -25,9 +25,9 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
Repeated calls for the same ``<target>`` will append items in the order called.

8
Help/command/target_sources.rst
View File

@@ -22,10 +22,10 @@ The named ``<target>`` must have been created by a command such as
``<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
specify the :ref:`scope <Target Usage Requirements>` 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.

14
Help/guide/tutorial/Adding Usage Requirements for a Library.rst
View File

@@ -4,15 +4,20 @@ Step 3: Adding Usage Requirements for a Library
Exercise 1 - Adding Usage Requirements for a Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Usage requirements allow for far better control over a library or
executable's link and include line while also giving more control over the
transitive property of targets inside CMake. The primary commands that
:ref:`Usage requirements <Target Usage Requirements>` of a target parameters
allow for far better control over a library or executable's link and include
line while also giving more control over the transitive property of targets
inside CMake. The primary commands that
leverage usage requirements are:
* :command:`target_compile_definitions`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`
Goal
----
@@ -22,7 +27,6 @@ Add usage requirements for a library.
Helpful Materials
-----------------
* :command:`target_include_directories`
* :variable:`CMAKE_CURRENT_SOURCE_DIR`
Files to Edit

8
Help/manual/cmake-buildsystem.7.rst
View File

@@ -257,7 +257,7 @@ targets in multiple different directories convenient through use of the
Transitive Usage Requirements
-----------------------------
The usage requirements of a target can transitively propagate to dependents.
The usage requirements of a target can transitively propagate to the dependents.
The :command:`target_link_libraries` command has ``PRIVATE``,
``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
@@ -279,8 +279,10 @@ The :command:`target_link_libraries` command has ``PRIVATE``,
# consumer is compiled with -DUSING_ARCHIVE_LIB
target_link_libraries(consumer archiveExtras)
Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
usage requirements of it are propagated to ``consumer`` too. Because
Because the ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
usage requirements of it are propagated to ``consumer`` too.
Because
``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage
requirements of it are not propagated to ``consumer``.