From 3d31f99b744f97d25cbead8aaa55ce8bcb85367b Mon Sep 17 00:00:00 2001 From: Hinell Date: Wed, 7 Sep 2022 17:53:30 +0300 Subject: Help: Link from usage requirement commands to detailed explanation Augment vague mentions of "Transitive Usage Requirements" with links to a detailed explanation. Fixes: #23799 --- Help/command/target_compile_definitions.rst | 6 +++--- Help/command/target_compile_options.rst | 6 +++--- Help/command/target_include_directories.rst | 6 +++--- Help/command/target_link_directories.rst | 11 ++++++----- Help/command/target_link_libraries.rst | 4 +++- Help/command/target_link_options.rst | 6 +++--- Help/command/target_precompile_headers.rst | 6 +++--- Help/command/target_sources.rst | 8 ++++---- .../tutorial/Adding Usage Requirements for a Library.rst | 14 +++++++++----- Help/manual/cmake-buildsystem.7.rst | 8 +++++--- 10 files changed, 42 insertions(+), 33 deletions(-) diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 3fb113a..2d292af 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -15,9 +15,9 @@ named ```` must have been created by a command such as :ref:`ALIAS target `. 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 -````. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope ` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS` +property of ````. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ````. The following arguments specify compile definitions. Repeated calls for the same ```` append items in the order called. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index e45b209..0d86c91 100644 --- a/Help/command/target_compile_options.rst +++ b/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 -````. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope ` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS` +property of ````. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ````. The following arguments specify compile options. Repeated calls for the same ```` append items in the order called. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 9a99a7d..f13ff29 100644 --- a/Help/command/target_include_directories.rst +++ b/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 ````. -``PUBLIC`` and ``INTERFACE`` items will populate the +the :ref:`scope ` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES` +property of ````. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ````. The following arguments specify include directories. diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index bb75a3d..b72f746 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -21,11 +21,12 @@ The named ```` must have been created by a command such as :ref:`ALIAS target `. 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 ````. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ```` -(:ref:`IMPORTED targets ` only support ``INTERFACE`` items). +specify the :ref:`scope ` of the items that follow +them. ``PRIVATE`` and ``PUBLIC`` items will populate the +:prop_tgt:`LINK_DIRECTORIES` property of ````. ``PUBLIC`` and +``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES` +property of ```` (:ref:`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 ```` append items in the order called. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index c85094a..bb7b5cc 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -146,8 +146,10 @@ Libraries for a Target and/or its Dependents ... [ ...]...) -The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` +:ref:`scope ` 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 diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 87dff39..3cd0e64 100644 --- a/Help/command/target_link_options.rst +++ b/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 -````. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope ` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS` +property of ````. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_OPTIONS` property of ````. The following arguments specify link options. Repeated calls for the same ```` append items in the order called. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 9f7dabb..84f5d12 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -25,9 +25,9 @@ The named ```` must have been created by a command such as :ref:`ALIAS target `. 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 -````. ``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope ` of the following arguments. +``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS` +property of ````. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ```` (:ref:`IMPORTED targets ` only support ``INTERFACE`` items). Repeated calls for the same ```` will append items in the order called. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 146b850..461175a 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -22,10 +22,10 @@ The named ```` must have been created by a command such as ```` can be a custom target. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the source file paths (````) that follow -them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` -property of ````, which are used when building the target itself. -``PUBLIC`` and ``INTERFACE`` items will populate the +specify the :ref:`scope ` of the source file paths +(````) that follow them. ``PRIVATE`` and ``PUBLIC`` items will +populate the :prop_tgt:`SOURCES` property of ````, which are used when +building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_SOURCES` property of ````, which are used when building dependents. A target created by :command:`add_custom_target` can only have ``PRIVATE`` scope. diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index b521896..9d3bf64 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/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 ` 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 diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index bceff2d..b14160c 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/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``. -- cgit v0.12