Document OBJECT library type in add_library command

Describe the OBJECT library signature of add_library and the
$<TARGET_OBJECTS:...> expressions needed to use object libraries.
Also document the what is not allowed for object library targets.

1 files changed, 20 insertions, 0 deletions

diff --git a/Source/cmAddLibraryCommand.h b/Source/cmAddLibraryCommand.h
index 9ca9cbe..b1ae202 100644
--- a/Source/cmAddLibraryCommand.h
+++ b/Source/cmAddLibraryCommand.h
@@ -112,6 +112,26 @@ public:
       "(and its per-configuration version IMPORTED_LOCATION_<CONFIG>) "
       "which specifies the location of the main library file on disk.  "
       "See documentation of the IMPORTED_* properties for more information."
+      "\n"
+      "The signature\n"
+      "  add_library(<name> OBJECT <src>...)\n"
+      "creates a special \"object library\" target.  "
+      "An object library compiles source files but does not archive or link "
+      "their object files into a library.  "
+      "Instead other targets created by add_library or add_executable may "
+      "reference the objects using an expression of the form "
+      "$<TARGET_OBJECTS:objlib> as a source, where \"objlib\" is the "
+      "object library name.  "
+      "For example:\n"
+      "  add_library(... $<TARGET_OBJECTS:objlib> ...)\n"
+      "  add_executable(... $<TARGET_OBJECTS:objlib> ...)\n"
+      "will include objlib's object files in a library and an executable "
+      "along with those compiled from their own sources.  "
+      "Object libraries may contain only sources (and headers) that compile "
+      "to object files.  "
+      "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."
       ;
     }