Merge topic 'doc-add_library-updates'

ee5b58f491 Help: State in add_library that INTERFACE libraries have no build targets
99b1e85f07 Help: Consolidate add_library documentation on IMPORTED libraries
716e76be3e Help: Re-order add_library sections
1b0adeea81 Help: Clarify target_sources PRIVATE/PUBLIC/INTERFACE scopes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5086

2 files changed, 82 insertions, 74 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 01c415a..ed8447e 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -64,42 +64,6 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
 pre-processed, and you want to have the original sources reachable from
 within IDE.
 
-Imported Libraries
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: cmake
-
-  add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
-              [GLOBAL])
-
-An :ref:`IMPORTED library target <Imported Targets>` references a library
-file located outside the project.  No rules are generated to build it, and
-the :prop_tgt:`IMPORTED` target property is ``True``.  The target name has
-scope in the directory in which it is created and below, but the ``GLOBAL``
-option extends visibility.  It may be referenced like any target built
-within the project.  ``IMPORTED`` libraries are useful for convenient
-reference from commands like :command:`target_link_libraries`.  Details
-about the imported library are specified by setting properties whose names
-begin in ``IMPORTED_`` and ``INTERFACE_``.
-
-The most important properties are:
-
-* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
-  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
-  location of the main library file on disk.
-* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
-  for object libraries, specifies the locations of object files on disk.
-* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
-
-See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
-for more information.
-
-An ``UNKNOWN`` library type is typically only used in the implementation of
-:ref:`Find Modules`.  It allows the path to an imported library (often found
-using the :command:`find_library` command) to be used without having to know
-what type of library it is.  This is especially useful on Windows where a
-static library and a DLL's import library both have the same file extension.
-
 Object Libraries
 ^^^^^^^^^^^^^^^^
 
@@ -129,6 +93,80 @@ systems (such as Xcode) may not like targets that have only object files, so
 consider adding at least one real source file to any target that references
 ``$<TARGET_OBJECTS:objlib>``.
 
+Interface Libraries
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+  add_library(<name> INTERFACE)
+
+Creates an :ref:`Interface Library <Interface Libraries>`.
+An ``INTERFACE`` library target does not compile sources and does
+not produce a library artifact on disk.  However, it may have
+properties set on it and it may be installed and exported.
+Typically, ``INTERFACE_*`` properties are populated on an interface
+target using the commands:
+
+* :command:`set_property`,
+* :command:`target_link_libraries(INTERFACE)`,
+* :command:`target_link_options(INTERFACE)`,
+* :command:`target_include_directories(INTERFACE)`,
+* :command:`target_compile_options(INTERFACE)`,
+* :command:`target_compile_definitions(INTERFACE)`, and
+* :command:`target_sources(INTERFACE)`,
+
+and then it is used as an argument to :command:`target_link_libraries`
+like any other target.
+
+An interface library has no source files itself and is not included
+as a target in the generated buildsystem.
+
+Imported Libraries
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+  add_library(<name> <type> IMPORTED [GLOBAL])
+
+Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
+No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
+property is ``True``.  The target name has scope in the directory in which
+it is created and below, but the ``GLOBAL`` option extends visibility.
+It may be referenced like any target built within the project.
+``IMPORTED`` libraries are useful for convenient reference from commands
+like :command:`target_link_libraries`.  Details about the imported library
+are specified by setting properties whose names begin in ``IMPORTED_`` and
+``INTERFACE_``.
+
+The ``<type>`` must be one of:
+
+``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
+  References a library file located outside the project.  The
+  :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
+  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
+  location of the main library file on disk.
+  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
+
+  An ``UNKNOWN`` library type is typically only used in the implementation of
+  :ref:`Find Modules`.  It allows the path to an imported library (often found
+  using the :command:`find_library` command) to be used without having to know
+  what type of library it is.  This is especially useful on Windows where a
+  static library and a DLL's import library both have the same file extension.
+
+``OBJECT``
+  References a set of object files located outside the project.
+  The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
+  variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
+  object files on disk.
+  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
+
+``INTERFACE``
+  Does not reference any library or object files on disk, but may
+  specify usage requirements in ``INTERFACE_*`` properties.
+
+See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
+for more information.
+
 Alias Libraries
 ^^^^^^^^^^^^^^^
 
@@ -153,35 +191,3 @@ to modify properties of ``<target>``, that is, it may not be used as the
 operand of :command:`set_property`, :command:`set_target_properties`,
 :command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
 installed or exported.
-
-Interface Libraries
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: cmake
-
-  add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
-
-Creates an :ref:`Interface Library <Interface Libraries>`.  An ``INTERFACE``
-library target does not directly create build output, though it may
-have properties set on it and it may be installed, exported and
-imported. Typically the ``INTERFACE_*`` properties are populated on
-the interface target using the commands:
-
-* :command:`set_property`,
-* :command:`target_link_libraries(INTERFACE)`,
-* :command:`target_link_options(INTERFACE)`,
-* :command:`target_include_directories(INTERFACE)`,
-* :command:`target_compile_options(INTERFACE)`,
-* :command:`target_compile_definitions(INTERFACE)`, and
-* :command:`target_sources(INTERFACE)`,
-
-and then it is used as an argument to :command:`target_link_libraries`
-like any other target.
-
-An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
-created with this signature.  An ``IMPORTED`` library target references a
-library defined outside the project.  The target name has scope in the
-directory in which it is created and below, but the ``GLOBAL`` option
-extends visibility.  It may be referenced like any target built within
-the project.  ``IMPORTED`` libraries are useful for convenient reference
-from commands like :command:`target_link_libraries`.
diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst
index 856d869..653b8d7 100644
--- a/Help/command/target_sources.rst
+++ b/Help/command/target_sources.rst
@@ -11,19 +11,21 @@ Add sources to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specifies sources to use when compiling a given target.  Relative
-source file paths are interpreted as being relative to the current
+Specifies sources to use when building a target and/or its dependents.
+Relative source file paths are interpreted as being relative to the current
 source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the scope of the items following them.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`SOURCES` property of
-``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``.
-(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+``<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.  (:ref:`IMPORTED targets <Imported Targets>`
+only support ``INTERFACE`` items because they are not build targets.)
 The following arguments specify sources.  Repeated calls for the same
 ``<target>`` append items in the order called.