ENH: Added FILES_MATCHING option to INSTALL(DIRECTORY). This will help install a tree of header files while ignoring non-headers.

1 files changed, 20 insertions, 7 deletions

diff --git a/Source/cmInstallCommand.h b/Source/cmInstallCommand.h
index d7b3f64e00..15332ae8ba 100644
--- a/Source/cmInstallCommand.h
+++ b/Source/cmInstallCommand.h
@@ -178,7 +178,7 @@ public:
       "          [DIRECTORY_PERMISSIONS permissions...]\n"
       "          [USE_SOURCE_PERMISSIONS]\n"
       "          [CONFIGURATIONS [Debug|Release|...]]\n"
-      "          [COMPONENT <component>]\n"
+      "          [COMPONENT <component>] [FILES_MATCHING]\n"
       "          [[PATTERN <pattern> | REGEX <regex>]\n"
       "           [EXCLUDE] [PERMISSIONS permissions...]] [...])\n"
       "The DIRECTORY form installs contents of one or more directories "
@@ -198,18 +198,31 @@ public:
       "If no permissions are specified files will be given the default "
       "permissions specified in the FILES form of the command, and the "
       "directories will be given the default permissions specified in the "
-      "PROGRAMS form of the command.  "
-      "The PATTERN and REGEX options specify a globbing pattern or regular "
-      "expression to match directories or files encountered during traversal "
-      "of an input directory.  The full path to an input file or directory "
+      "PROGRAMS form of the command.\n"
+
+      "Installation of directories may be controlled with fine granularity "
+      "using the PATTERN or REGEX options.  These \"match\" options specify a "
+      "globbing pattern or regular expression to match directories or files "
+      "encountered within input directories.  They may be used to apply "
+      "certain options (see below) to a subset of the files and directories "
+      "encountered.  "
+      "The full path to each input file or directory "
       "(with forward slashes) is matched against the expression.  "
       "A PATTERN will match only complete file names: the portion of the "
       "full path matching the pattern must occur at the end of the file name "
       "and be preceded by a slash.  "
       "A REGEX will match any portion of the full path but it may use "
       "'/' and '$' to simulate the PATTERN behavior.  "
-      "Options following one of these matching expressions "
-      "are applied only to files or directories matching them.  "
+      "By default all files and directories are installed whether "
+      "or not they are matched.  "
+      "The FILES_MATCHING option may be given before the first match option "
+      "to disable installation of files (but not directories) not matched by "
+      "any expression.  For example, the code\n"
+      "  install(DIRECTORY src/ DESTINATION include/myproj\n"
+      "          FILES_MATCHING PATTERN \"*.h\")\n"
+      "will extract and install header files from a source tree.\n"
+      "Some options may follow a PATTERN or REGEX expression and are "
+      "applied only to files or directories matching them.  "
       "The EXCLUDE option will skip the matched file or directory.  "
       "The PERMISSIONS option overrides the permissions setting for the "
       "matched file or directory.  "