Help: Document linking behavior of OBJECT libraries

Inspired-by: Deniz Bahadir <dbahadir@benocs.com>
Issue: #14778

4 files changed, 73 insertions, 5 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 3706153..8fa0df7 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -110,10 +110,10 @@ along with those compiled from their own sources.  Object libraries
 may contain only sources that compile, header files, and other files
 that would not affect linking of a normal library (e.g. ``.txt``).
 They may contain custom commands generating such sources, but not
-``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Object libraries
-cannot be linked.  Some native build 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>``.
+``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Some native build
+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>``.
 
 Alias Libraries
 ^^^^^^^^^^^^^^^
diff --git a/Help/command/export.rst b/Help/command/export.rst
index 17fcecb..0c676c6 100644
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@@ -45,7 +45,9 @@ unspecified.
   :ref:`Object Libraries` under :generator:`Xcode` have special handling if
   multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`.
   In this case they will be exported as :ref:`Interface Libraries` with
-  no object files available to clients.
+  no object files available to clients.  This is sufficient to satisfy
+  transitive usage requirements of other targets that link to the
+  object libraries in their implementation.
 
 ::
 
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 1cedc35..eb7b07c 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -187,6 +187,8 @@ export file itself, call ``install(EXPORT)``, documented below.
 They install no artifacts but will be included in an associated ``EXPORT``.
 If :ref:`Object Libraries` are listed but given no destination for their
 object files, they will be exported as :ref:`Interface Libraries`.
+This is sufficient to satisfy transitive usage requirements of other
+targets that link to the object libraries in their implementation.
 
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 2ec8744..fcc2c07 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -183,6 +183,70 @@ is not ``NEW``, they are also appended to the
 ``general`` (or without any keyword) are treated as if specified for both
 ``debug`` and ``optimized``.
 
+Linking Object Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:ref:`Object Libraries` may be used as the ``<target>`` (first) argument
+of ``target_link_libraries`` to specify dependencies of their sources
+on other libraries.  For example, the code
+
+.. code-block:: cmake
+
+  add_library(A SHARED a.c)
+  target_compile_definitions(A PUBLIC A)
+
+  add_library(obj OBJECT obj.c)
+  target_compile_definitions(obj PUBLIC OBJ)
+  target_link_libraries(obj PUBLIC A)
+
+compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements
+for ``obj`` that propagate to its dependents.
+
+Normal libraries and executables may link to :ref:`Object Libraries`
+to get their objects and usage requirements.  Continuing the above
+example, the code
+
+.. code-block:: cmake
+
+  add_library(B SHARED b.c)
+  target_link_libraries(B PUBLIC obj)
+
+compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B``
+with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``.
+Furthermore, the code
+
+.. code-block:: cmake
+
+  add_executable(main main.c)
+  target_link_libraries(main B)
+
+compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main``
+to ``B`` and ``A``.  The object library's usage requirements are
+propagated transitively through ``B``, but its object files are not.
+
+:ref:`Object Libraries` may "link" to other object libraries to get
+usage requirements, but since they do not have a link step nothing
+is done with their object files.  Continuing from the above example,
+the code:
+
+.. code-block:: cmake
+
+  add_library(obj2 OBJECT obj2.c)
+  target_link_libraries(obj2 PUBLIC obj)
+
+  add_executable(main2 main2.c)
+  target_link_libraries(main2 obj2)
+
+compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2``
+with object files from ``main2.c`` and ``obj2.c``, and links ``main2``
+to ``A``.
+
+In other words, when :ref:`Object Libraries` appear in a target's
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be
+treated as :ref:`Interface Libraries`, but when they appear in
+a target's :prop_tgt:`LINK_LIBRARIES` property their object files
+will be included in the link too.
+
 Cyclic Dependencies of Static Libraries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^