ENH: Create file(COPY) command signature

The file(INSTALL) command has long been undocumented and used only to
implement install() scripts.  We now document it and provide a similar
file(COPY) signature which is useful in general-purpose scripts.  It
provides the capabilities of install(DIRECTORY) and install(FILES) but
operates immediately instead of contributing to install scripts.

1 files changed, 37 insertions, 1 deletions

diff --git a/Source/cmFileCommand.h b/Source/cmFileCommand.h
index 04bb661b9e..cadb1a9a94 100644
--- a/Source/cmFileCommand.h
+++ b/Source/cmFileCommand.h
@@ -157,7 +157,42 @@ public:
       "and the second element is a string value for the error. A 0 "
       "numeric error means no error in the operation. "
       "If TIMEOUT time is specified, the operation will "
-      "timeout after time seconds, time can be specified as a float.\n";
+      "timeout after time seconds, time can be specified as a float."
+      "\n"
+      "The file() command also provides COPY and INSTALL signatures:\n"
+      "  file(<COPY|INSTALL> files... DESTINATION <dir>\n"
+      "       [FILE_PERMISSIONS permissions...]\n"
+      "       [DIRECTORY_PERMISSIONS permissions...]\n"
+      "       [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]\n"
+      "       [FILES_MATCHING]\n"
+      "       [[PATTERN <pattern> | REGEX <regex>]\n"
+      "        [EXCLUDE] [PERMISSIONS permissions...]] [...])\n"
+      "The COPY signature copies files, directories, and symlinks to a "
+      "destination folder.  "
+      "Relative input paths are evaluated with respect to the current "
+      "source directory, and a relative destination is evaluated with "
+      "respect to the current build directory.  "
+      "Copying preserves input file timestamps, and optimizes out a file "
+      "if it exists at the destination with the same timestamp.  "
+      "Copying preserves input permissions unless explicit permissions or "
+      "NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PERMISSIONS).  "
+      "See the install(DIRECTORY) command for documentation of permissions, "
+      "PATTERN, REGEX, and EXCLUDE options.  "
+      "\n"
+      "The INSTALL signature differs slightly from COPY: "
+      "it prints status messages, and NO_SOURCE_PERMISSIONS is default.  "
+      "Installation scripts generated by the install() command use this "
+      "signature (with some undocumented options for internal use)."
+      // Undocumented INSTALL options:
+      //  - RENAME <name>
+      //  - OPTIONAL
+      //  - FILES keyword to re-enter files... list
+      //  - PERMISSIONS before REGEX is alias for FILE_PERMISSIONS
+      //  - DIR_PERMISSIONS is alias for DIRECTORY_PERMISSIONS
+      //  - TYPE <FILE|DIRECTORY|EXECUTABLE|PROGRAM|
+      //          STATIC_LIBRARY|SHARED_LIBRARY|MODULE>
+      //  - COMPONENTS, CONFIGURATIONS, PROPERTIES (ignored for compat)
+      ;
     }
 
   cmTypeMacro(cmFileCommand, cmCommand);
@@ -179,6 +214,7 @@ protected:
   bool HandleRPathRemoveCommand(std::vector<std::string> const& args);
   bool HandleDifferentCommand(std::vector<std::string> const& args);
 
+  bool HandleCopyCommand(std::vector<std::string> const& args);
   bool HandleInstallCommand(std::vector<std::string> const& args);
   bool HandleDownloadCommand(std::vector<std::string> const& args);
 };