ENH: Updated exporting and importing of targets to support libraries and configurations.

  - Created cmExportFileGenerator hierarchy to implement export file generation
  - Installed exports use per-config import files loaded by a central one.
  - Include soname of shared libraries in import information
  - Renamed PREFIX to NAMESPACE in INSTALL(EXPORT) and EXPORT() commands
  - Move addition of CMAKE_INSTALL_PREFIX to destinations to install generators
  - Import files compute the installation prefix relative to their location when loaded
  - Add mapping of importer configurations to importee configurations
  - Rename IMPORT targets to IMPORTED targets to distinguish from windows import libraries
  - Scope IMPORTED targets within directories to isolate them
  - Place all properties created by import files in the IMPORTED namespace
  - Document INSTALL(EXPORT) and EXPORT() commands.
  - Document IMPORTED signature of add_executable and add_library
  - Enable finding of imported targets in cmComputeLinkDepends

1 files changed, 46 insertions, 1 deletions

diff --git a/Source/cmInstallCommand.h b/Source/cmInstallCommand.h
index f0f69e0..0f5eb16 100644
--- a/Source/cmInstallCommand.h
+++ b/Source/cmInstallCommand.h
@@ -98,7 +98,7 @@ public:
       "file to be installed does not exist.  "
       "\n"
       "The TARGETS signature:\n"
-      "  install(TARGETS targets...\n"
+      "  install(TARGETS targets... [EXPORT <export-name>]\n"
       "          [[ARCHIVE|LIBRARY|RUNTIME]\n"
       "           [DESTINATION <dir>]\n"
       "           [PERMISSIONS permissions...]\n"
@@ -145,6 +145,12 @@ public:
       "On non-DLL platforms mySharedLib will be installed to <prefix>/lib "
       "and /some/full/path."
       "\n"
+      "The EXPORT option associates the installed target files with an "
+      "export called <export-name>.  "
+      "It must appear before any RUNTIME, LIBRARY, or ARCHIVE options.  "
+      "See documentation of the install(EXPORT ...) signature below for "
+      "details."
+      "\n"
       "Installing a target with EXCLUDE_FROM_ALL set to true has "
       "undefined behavior."
       "\n"
@@ -248,6 +254,45 @@ public:
       "For example, the code\n"
       "  install(CODE \"MESSAGE(\\\"Sample install message.\\\")\")\n"
       "will print a message during installation.\n"
+      ""
+      "The EXPORT signature:\n"
+      "  install(EXPORT <export-name> DESTINATION <dir>\n"
+      "          [NAMESPACE <namespace>] [FILE <name>.cmake]\n"
+      "          [PERMISSIONS permissions...]\n"
+      "          [CONFIGURATIONS [Debug|Release|...]]\n"
+      "          [COMPONENT <component>])\n"
+      "The EXPORT form generates and installs a CMake file containing code "
+      "to import targets from the installation tree into another project.  "
+      "Target installations are associated with the export <export-name> "
+      "using the EXPORT option of the install(TARGETS ...) signature "
+      "documented above.  The NAMESPACE option will prepend <namespace> to "
+      "the target names as they are written to the import file.  "
+      "By default the generated file will be called <export-name>.cmake but "
+      "the FILE option may be used to specify a different name.  The value "
+      "given to the FILE option must be a file name with the \".cmake\" "
+      "extension.  "
+      "If a CONFIGURATIONS option is given then the file will only be "
+      "installed when one of the named configurations is installed.  "
+      "Additionally, the generated import file will reference only the "
+      "matching target configurations.  "
+      "If a COMPONENT option is specified that does not match that given "
+      "to the targets associated with <export-name> the behavior is "
+      "undefined.  "
+      "If a library target is included in the export but "
+      "a target to which it links is not included the behavior is "
+      "unspecified."
+      "\n"
+      "The EXPORT form is useful to help outside projects use targets built "
+      "and installed by the current project.  For example, the code\n"
+      "  install(TARGETS myexe EXPORT myproj DESTINATION bin)\n"
+      "  install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)\n"
+      "will install the executable myexe to <prefix>/bin and code to import "
+      "it in the file \"<prefix>/lib/myproj/myproj.cmake\".  "
+      "An outside project may load this file with the include command "
+      "and reference the myexe executable from the installation tree using "
+      "the imported target name mp_myexe as if the target were built "
+      "in its own tree."
+      "\n"
       "NOTE: This command supercedes the INSTALL_TARGETS command and the "
       "target properties PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT.  "
       "It also replaces the FILES forms of the INSTALL_FILES and "