Allow OBJECT libraries to be installed, exported, and imported

Teach install() and export() to handle the actual object files.
Disallow this on Xcode with multiple architectures because it
still cannot be cleanly supported there.

Co-Author: Brad King <brad.king@kitware.com>

8 files changed, 52 insertions, 19 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index af75a39..3a76040 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -64,7 +64,7 @@ Imported Libraries
 
 ::
 
-  add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
+  add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
               [GLOBAL])
 
 An :ref:`IMPORTED library target <Imported Targets>` references a library
@@ -106,10 +106,9 @@ 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 imported, exported, installed, or linked.  Some native build
-systems 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>``.
+cannot be linked.  Some native build systems 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/install.rst b/Help/command/install.rst
index 70087a4..58438b7 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -73,7 +73,7 @@ Installing Targets
 ::
 
   install(TARGETS targets... [EXPORT <export-name>]
-          [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
+          [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
             PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
            [DESTINATION <dir>]
            [PERMISSIONS permissions...]
@@ -86,10 +86,10 @@ Installing Targets
           )
 
 The ``TARGETS`` form specifies rules for installing targets from a
-project.  There are five kinds of target files that may be installed:
-``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``.
-Executables are treated as ``RUNTIME`` targets, except that those
-marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
+project.  There are six kinds of target files that may be installed:
+``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and
+``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that
+those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
 targets on OS X.  Static libraries are treated as ``ARCHIVE`` targets,
 except that those marked with the ``FRAMEWORK`` property are treated
 as ``FRAMEWORK`` targets on OS X.
@@ -99,10 +99,11 @@ targets, except that those marked with the ``FRAMEWORK`` property are
 treated as ``FRAMEWORK`` targets on OS X.  For DLL platforms the DLL
 part of a shared library is treated as a ``RUNTIME`` target and the
 corresponding import library is treated as an ``ARCHIVE`` target.
-All Windows-based systems including Cygwin are DLL platforms.
-The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, and ``FRAMEWORK`` arguments
-change the type of target to which the subsequent properties apply.
-If none is given the installation properties apply to all target
+All Windows-based systems including Cygwin are DLL platforms. Object
+libraries are always treated as ``OBJECTS`` targets.
+The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK``
+arguments change the type of target to which the subsequent properties
+apply. If none is given the installation properties apply to all target
 types.  If only one is given then only targets of that type will be
 installed (which can be used to install just a DLL or just an import
 library).
@@ -165,8 +166,8 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
 
 The ``EXPORT`` option associates the installed target files with an
 export called ``<export-name>``.  It must appear before any ``RUNTIME``,
-``LIBRARY``, or ``ARCHIVE`` options.  To actually install the export
-file itself, call ``install(EXPORT)``, documented below.
+``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options.  To actually install the
+export file itself, call ``install(EXPORT)``, documented below.
 
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 65d87bf..95f5b87 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -125,10 +125,10 @@ The object files collection can be used as source inputs to other targets:
 
   add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
 
-``OBJECT`` libraries may only be used locally as sources in a buildsystem --
-they may not be installed, exported, or used in the right hand side of
+``OBJECT`` libraries may not be used in the right hand side of
 :command:`target_link_libraries`.  They also may not be used as the ``TARGET``
-in a use of the :command:`add_custom_command(TARGET)` command signature.
+in a use of the :command:`add_custom_command(TARGET)` command signature.  They
+may be installed, and will be exported as an INTERFACE library.
 
 Although object libraries may not be named directly in calls to
 the :command:`target_link_libraries` command, they can be "linked"
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 27c75dc..31b2389 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -194,6 +194,8 @@ Properties on Targets
    /prop_tgt/IMPORTED_LOCATION
    /prop_tgt/IMPORTED_NO_SONAME_CONFIG
    /prop_tgt/IMPORTED_NO_SONAME
+   /prop_tgt/IMPORTED_OBJECTS_CONFIG
+   /prop_tgt/IMPORTED_OBJECTS
    /prop_tgt/IMPORTED
    /prop_tgt/IMPORTED_SONAME_CONFIG
    /prop_tgt/IMPORTED_SONAME
diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst
new file mode 100644
index 0000000..222e6cc
--- /dev/null
+++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst
@@ -0,0 +1,11 @@
+IMPORTED_OBJECTS
+----------------
+
+:ref:`;-list <CMake Language Lists>` of absolute paths to the object
+files on disk for an :ref:`imported <Imported targets>`
+:ref:`object library <object libraries>`.
+
+Ignored for non-imported targets.
+
+Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific
+property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead.
diff --git a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst
new file mode 100644
index 0000000..4419ed1
--- /dev/null
+++ b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst
@@ -0,0 +1,7 @@
+IMPORTED_OBJECTS_<CONFIG>
+-------------------------
+
+<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property.
+
+Configuration names correspond to those provided by the project from
+which the target is imported.
diff --git a/Help/release/dev/add_library-TARGET_OBJECTS.rst b/Help/release/dev/add_library-TARGET_OBJECTS.rst
new file mode 100644
index 0000000..964064e
--- /dev/null
+++ b/Help/release/dev/add_library-TARGET_OBJECTS.rst
@@ -0,0 +1,5 @@
+add_library-TARGET_OBJECTS
+--------------------------
+
+* The :command:`add_library` command ``IMPORTED`` option learned to support
+  :ref:`Object Libraries`.
diff --git a/Help/release/dev/install-TARGET_OBJECTS.rst b/Help/release/dev/install-TARGET_OBJECTS.rst
new file mode 100644
index 0000000..dbcf635
--- /dev/null
+++ b/Help/release/dev/install-TARGET_OBJECTS.rst
@@ -0,0 +1,8 @@
+install-TARGET_OBJECTS
+----------------------
+
+* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
+  specify where to install :ref:`Object Libraries`.
+
+* The :command:`install(EXPORT)` command learned how to export
+  :ref:`Object Libraries`.