Merge topic 'transitive-usage-reqs-lnks'

3d31f99b74 Help: Link from usage requirement commands to detailed explanation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !7653

Help/command/target_compile_definitions.rst

@@ -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.

Help/command/target_compile_options.rst

@@ -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.

Help/command/target_include_directories.rst

@@ -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.
 

Help/command/target_link_directories.rst

@@ -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.

Help/command/target_link_libraries.rst

@@ -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

Help/command/target_link_options.rst

@@ -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.

Help/command/target_precompile_headers.rst

@@ -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.

Help/command/target_sources.rst

@@ -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.

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

@@ -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

Help/manual/cmake-buildsystem.7.rst

@@ -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``.