Convert builtin help to reStructuredText source files

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

1 files changed, 316 insertions, 0 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
new file mode 100644
index 0000000..9b27cae
--- /dev/null
+++ b/Help/command/install.rst
@@ -0,0 +1,316 @@
+install
+-------
+
+Specify rules to run at install time.
+
+This command generates installation rules for a project.  Rules
+specified by calls to this command within a source directory are
+executed in order during installation.  The order across directories
+is not defined.
+
+There are multiple signatures for this command.  Some of them define
+installation properties for files and targets.  Properties common to
+multiple signatures are covered here but they are valid only for
+signatures that specify them.
+
+DESTINATION arguments specify the directory on disk to which a file
+will be installed.  If a full path (with a leading slash or drive
+letter) is given it is used directly.  If a relative path is given it
+is interpreted relative to the value of CMAKE_INSTALL_PREFIX.  The
+prefix can be relocated at install time using DESTDIR mechanism
+explained in the CMAKE_INSTALL_PREFIX variable documentation.
+
+PERMISSIONS arguments specify permissions for installed files.  Valid
+permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ,
+GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE,
+SETUID, and SETGID.  Permissions that do not make sense on certain
+platforms are ignored on those platforms.
+
+The CONFIGURATIONS argument specifies a list of build configurations
+for which the install rule applies (Debug, Release, etc.).
+
+The COMPONENT argument specifies an installation component name with
+which the install rule is associated, such as "runtime" or
+"development".  During component-specific installation only install
+rules associated with the given component name will be executed.
+During a full installation all components are installed.  If COMPONENT
+is not provided a default component "Unspecified" is created.  The
+default component name may be controlled with the
+CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
+
+The RENAME argument specifies a name for an installed file that may be
+different from the original file.  Renaming is allowed only when a
+single file is installed by the command.
+
+The OPTIONAL argument specifies that it is not an error if the file to
+be installed does not exist.
+
+The TARGETS signature:
+
+::
+
+  install(TARGETS targets... [EXPORT <export-name>]
+          [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
+            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
+           [DESTINATION <dir>]
+           [INCLUDES DESTINATION [<dir> ...]]
+           [PERMISSIONS permissions...]
+           [CONFIGURATIONS [Debug|Release|...]]
+           [COMPONENT <component>]
+           [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
+          ] [...])
+
+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 targets on OS X.  Static
+libraries are always treated as ARCHIVE targets.  Module libraries are
+always treated as LIBRARY targets.  For non-DLL platforms shared
+libraries are treated as LIBRARY 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
+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).The INCLUDES DESTINATION specifies a list of directories
+which will be added to the INTERFACE_INCLUDE_DIRECTORIES of the
+<targets> when exported by install(EXPORT).  If a relative path is
+specified, it is treated as relative to the $<INSTALL_PREFIX>.
+
+The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
+subsequent properties to be applied to installing a FRAMEWORK shared
+library target's associated files on non-Apple platforms.  Rules
+defined by these arguments are ignored on Apple platforms because the
+associated files are installed into the appropriate locations inside
+the framework folder.  See documentation of the PRIVATE_HEADER,
+PUBLIC_HEADER, and RESOURCE target properties for details.
+
+Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a LIBRARY
+option.  On some platforms a versioned shared library has a symbolic
+link such as
+
+::
+
+  lib<name>.so -> lib<name>.so.1
+
+where "lib<name>.so.1" is the soname of the library and "lib<name>.so"
+is a "namelink" allowing linkers to find the library when given
+"-l<name>".  The NAMELINK_ONLY option causes installation of only the
+namelink when a library target is installed.  The NAMELINK_SKIP option
+causes installation of library files other than the namelink when a
+library target is installed.  When neither option is given both
+portions are installed.  On platforms where versioned shared libraries
+do not have namelinks or when a library is not versioned the
+NAMELINK_SKIP option installs the library and the NAMELINK_ONLY option
+installs nothing.  See the VERSION and SOVERSION target properties for
+details on creating versioned shared libraries.
+
+One or more groups of properties may be specified in a single call to
+the TARGETS form of this command.  A target may be installed more than
+once to different locations.  Consider hypothetical targets "myExe",
+"mySharedLib", and "myStaticLib".  The code
+
+::
+
+    install(TARGETS myExe mySharedLib myStaticLib
+            RUNTIME DESTINATION bin
+            LIBRARY DESTINATION lib
+            ARCHIVE DESTINATION lib/static)
+    install(TARGETS mySharedLib DESTINATION /some/full/path)
+
+will install myExe to <prefix>/bin and myStaticLib to
+<prefix>/lib/static.  On non-DLL platforms mySharedLib will be
+installed to <prefix>/lib and /some/full/path.  On DLL platforms the
+mySharedLib DLL will be installed to <prefix>/bin and /some/full/path
+and its import library will be installed to <prefix>/lib/static and
+/some/full/path.
+
+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).  See documentation of the install(EXPORT ...)
+signature below for details.
+
+Installing a target with EXCLUDE_FROM_ALL set to true has undefined
+behavior.
+
+The FILES signature:
+
+::
+
+  install(FILES files... DESTINATION <dir>
+          [PERMISSIONS permissions...]
+          [CONFIGURATIONS [Debug|Release|...]]
+          [COMPONENT <component>]
+          [RENAME <name>] [OPTIONAL])
+
+The FILES form specifies rules for installing files for a project.
+File names given as relative paths are interpreted with respect to the
+current source directory.  Files installed by this form are by default
+given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
+if no PERMISSIONS argument is given.
+
+The PROGRAMS signature:
+
+::
+
+  install(PROGRAMS files... DESTINATION <dir>
+          [PERMISSIONS permissions...]
+          [CONFIGURATIONS [Debug|Release|...]]
+          [COMPONENT <component>]
+          [RENAME <name>] [OPTIONAL])
+
+The PROGRAMS form is identical to the FILES form except that the
+default permissions for the installed file also include OWNER_EXECUTE,
+GROUP_EXECUTE, and WORLD_EXECUTE.  This form is intended to install
+programs that are not targets, such as shell scripts.  Use the TARGETS
+form to install targets built within the project.
+
+The DIRECTORY signature:
+
+::
+
+  install(DIRECTORY dirs... DESTINATION <dir>
+          [FILE_PERMISSIONS permissions...]
+          [DIRECTORY_PERMISSIONS permissions...]
+          [USE_SOURCE_PERMISSIONS] [OPTIONAL]
+          [CONFIGURATIONS [Debug|Release|...]]
+          [COMPONENT <component>] [FILES_MATCHING]
+          [[PATTERN <pattern> | REGEX <regex>]
+           [EXCLUDE] [PERMISSIONS permissions...]] [...])
+
+The DIRECTORY form installs contents of one or more directories to a
+given destination.  The directory structure is copied verbatim to the
+destination.  The last component of each directory name is appended to
+the destination directory but a trailing slash may be used to avoid
+this because it leaves the last component empty.  Directory names
+given as relative paths are interpreted with respect to the current
+source directory.  If no input directory names are given the
+destination directory will be created but nothing will be installed
+into it.  The FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options
+specify permissions given to files and directories in the destination.
+If USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
+file permissions will be copied from the source directory structure.
+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.
+
+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.  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
+
+::
+
+  install(DIRECTORY src/ DESTINATION include/myproj
+          FILES_MATCHING PATTERN "*.h")
+
+will extract and install header files from a source tree.
+
+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.  For
+example the code
+
+::
+
+  install(DIRECTORY icons scripts/ DESTINATION share/myproj
+          PATTERN "CVS" EXCLUDE
+          PATTERN "scripts/*"
+          PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
+                      GROUP_EXECUTE GROUP_READ)
+
+will install the icons directory to share/myproj/icons and the scripts
+directory to share/myproj.  The icons will get default file
+permissions, the scripts will be given specific permissions, and any
+CVS directories will be excluded.
+
+The SCRIPT and CODE signature:
+
+::
+
+  install([[SCRIPT <file>] [CODE <code>]] [...])
+
+The SCRIPT form will invoke the given CMake script files during
+installation.  If the script file name is a relative path it will be
+interpreted with respect to the current source directory.  The CODE
+form will invoke the given CMake code during installation.  Code is
+specified as a single argument inside a double-quoted string.  For
+example, the code
+
+::
+
+  install(CODE "MESSAGE(\"Sample install message.\")")
+
+will print a message during installation.
+
+The EXPORT signature:
+
+::
+
+  install(EXPORT <export-name> DESTINATION <dir>
+          [NAMESPACE <namespace>] [FILE <name>.cmake]
+          [PERMISSIONS permissions...]
+          [CONFIGURATIONS [Debug|Release|...]]
+          [EXPORT_LINK_INTERFACE_LIBRARIES]
+          [COMPONENT <component>])
+
+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.  The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if
+present, causes the contents of the properties matching
+(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
+policy CMP0022 is NEW.  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.
+
+The EXPORT form is useful to help outside projects use targets built
+and installed by the current project.  For example, the code
+
+::
+
+  install(TARGETS myexe EXPORT myproj DESTINATION bin)
+  install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
+
+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.
+
+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 INSTALL_PROGRAMS
+commands.  The processing order of these install rules relative to
+those generated by INSTALL_TARGETS, INSTALL_FILES, and
+INSTALL_PROGRAMS commands is not defined.