Source/cmInstallCommand.h

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   8   This software is distributed WITHOUT ANY WARRANTY; without even the
   9   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10   See the License for more information.
  11 ============================================================================*/
  12 #ifndef cmInstallCommand_h
  13 #define cmInstallCommand_h
  14
  15 #include "cmCommand.h"
  16
  17 /** \class cmInstallCommand
  18  * \brief Specifies where to install some files
  19  *
  20  * cmInstallCommand is a general-purpose interface command for
  21  * specifying install rules.
  22  */
  23 class cmInstallCommand : public cmCommand
  24 {
  25 public:
  26   /**
  27    * This is a virtual constructor for the command.
  28    */
  29   virtual cmCommand* Clone()
  30     {
  31     return new cmInstallCommand;
  32     }
  33
  34   /**
  35    * This is called when the command is first encountered in
  36    * the CMakeLists.txt file.
  37    */
  38   virtual bool InitialPass(std::vector<std::string> const& args,
  39                            cmExecutionStatus &status);
  40
  41   /**
  42    * The name of the command as specified in CMakeList.txt.
  43    */
  44   virtual const char* GetName() const { return "install";}
  45
  46   /**
  47    * Succinct documentation.
  48    */
  49   virtual const char* GetTerseDocumentation() const
  50     {
  51     return "Specify rules to run at install time.";
  52     }
  53
  54   /**
  55    * More documentation.
  56    */
  57   virtual const char* GetFullDocumentation() const
  58     {
  59     return
  60       "This command generates installation rules for a project.  "
  61       "Rules specified by calls to this command within a source directory "
  62       "are executed in order during installation.  "
  63       "The order across directories is not defined."
  64       "\n"
  65       "There are multiple signatures for this command.  Some of them define "
  66       "installation properties for files and targets.  Properties common to "
  67       "multiple signatures are covered here but they are valid only for "
  68       "signatures that specify them.\n"
  69       "DESTINATION arguments specify "
  70       "the directory on disk to which a file will be installed.  "
  71       "If a full path (with a leading slash or drive letter) is given it "
  72       "is used directly.  If a relative path is given it is interpreted "
  73       "relative to the value of CMAKE_INSTALL_PREFIX.\n"
  74       "PERMISSIONS arguments specify permissions for installed files.  "
  75       "Valid permissions are "
  76       "OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, "
  77       "GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, "
  78       "WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, "
  79       "SETUID, and SETGID.  "
  80       "Permissions that do not make sense on certain platforms are ignored "
  81       "on those platforms.\n"
  82       "The CONFIGURATIONS argument specifies a list of build configurations "
  83       "for which the install rule applies (Debug, Release, etc.).\n"
  84       "The COMPONENT argument specifies an installation component name "
  85       "with which the install rule is associated, such as \"runtime\" or "
  86       "\"development\".  During component-specific installation only "
  87       "install rules associated with the given component name will be "
  88       "executed.  During a full installation all components are installed."
  89       " If COMPONENT is not provided a default component \"Unspecified\" is"
  90       " created. The default component name may be controlled with the "
  91       "CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.\n"
  92       "The RENAME argument specifies a name for an installed file that "
  93       "may be different from the original file.  Renaming is allowed only "
  94       "when a single file is installed by the command.\n"
  95       "The OPTIONAL argument specifies that it is not an error if the "
  96       "file to be installed does not exist.  "
  97       "\n"
  98       "The TARGETS signature:\n"
  99       "  install(TARGETS targets... [EXPORT <export-name>]\n"
 100       "          [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|\n"
 101       "            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]\n"
 102       "           [DESTINATION <dir>]\n"
 103       "           [PERMISSIONS permissions...]\n"
 104       "           [CONFIGURATIONS [Debug|Release|...]]\n"
 105       "           [COMPONENT <component>]\n"
 106       "           [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]\n"
 107       "          ] [...])\n"
 108       "The TARGETS form specifies rules for installing targets from a "
 109       "project.  There are five kinds of target files that may be "
 110       "installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.  "
 111
 112       "Executables are treated as RUNTIME targets, except that those "
 113       "marked with the MACOSX_BUNDLE property are treated as BUNDLE "
 114       "targets on OS X. "
 115       "Static libraries are always treated as ARCHIVE targets. "
 116       "Module libraries are always treated as LIBRARY targets. "
 117       "For non-DLL platforms shared libraries are treated as LIBRARY "
 118       "targets, except that those marked with the FRAMEWORK property "
 119       "are treated as FRAMEWORK targets on OS X.  "
 120       "For DLL platforms the DLL part of a shared library is treated as "
 121       "a RUNTIME target and the corresponding import library is treated as "
 122       "an ARCHIVE target. "
 123       "All Windows-based systems including Cygwin are DLL platforms. "
 124       "The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK "
 125       "arguments change the type of target to which the subsequent "
 126       "properties "
 127       "apply.  If none is given the installation properties apply to "
 128       "all target types.  If only one is given then only targets of that "
 129       "type will be installed (which can be used to install just a DLL or "
 130       "just an import library)."
 131       "\n"
 132       "The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause "
 133       "subsequent properties to be applied to installing a FRAMEWORK "
 134       "shared library target's associated files on non-Apple platforms.  "
 135       "Rules defined by these arguments are ignored on Apple platforms "
 136       "because the associated files are installed into the appropriate "
 137       "locations inside the framework folder.  "
 138       "See documentation of the PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE "
 139       "target properties for details."
 140       "\n"
 141       "Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a LIBRARY "
 142       "option.  "
 143       "On some platforms a versioned shared library has a symbolic link "
 144       "such as\n"
 145       "  lib<name>.so -> lib<name>.so.1\n"
 146       "where \"lib<name>.so.1\" is the soname of the library and "
 147       "\"lib<name>.so\" is a \"namelink\" allowing linkers to find the "
 148       "library when given \"-l<name>\".  "
 149       "The NAMELINK_ONLY option causes installation of only the namelink "
 150       "when a library target is installed.  "
 151       "The NAMELINK_SKIP option causes installation of library files other "
 152       "than the namelink when a library target is installed.  "
 153       "When neither option is given both portions are installed.  "
 154       "On platforms where versioned shared libraries do not have namelinks "
 155       "or when a library is not versioned the NAMELINK_SKIP option installs "
 156       "the library and the NAMELINK_ONLY option installs nothing.  "
 157       "See the VERSION and SOVERSION target properties for details on "
 158       "creating versioned shared libraries."
 159       "\n"
 160       "One or more groups of properties may be specified in a single call "
 161       "to the TARGETS form of this command.  A target may be installed more "
 162       "than once to different locations.  Consider hypothetical "
 163       "targets \"myExe\", \"mySharedLib\", and \"myStaticLib\".  The code\n"
 164       "    install(TARGETS myExe mySharedLib myStaticLib\n"
 165       "            RUNTIME DESTINATION bin\n"
 166       "            LIBRARY DESTINATION lib\n"
 167       "            ARCHIVE DESTINATION lib/static)\n"
 168       "    install(TARGETS mySharedLib DESTINATION /some/full/path)\n"
 169       "will install myExe to <prefix>/bin and myStaticLib to "
 170       "<prefix>/lib/static.  "
 171       "On non-DLL platforms mySharedLib will be installed to <prefix>/lib "
 172       "and /some/full/path.  On DLL platforms the mySharedLib DLL will be "
 173       "installed to <prefix>/bin and /some/full/path and its import library "
 174       "will be installed to <prefix>/lib/static and /some/full/path."
 175       "\n"
 176       "The EXPORT option associates the installed target files with an "
 177       "export called <export-name>.  "
 178       "It must appear before any RUNTIME, LIBRARY, or ARCHIVE options.  "
 179       "To actually install the export file itself, call install(EXPORT).  "
 180       "See documentation of the install(EXPORT ...) signature below for "
 181       "details."
 182       "\n"
 183       "Installing a target with EXCLUDE_FROM_ALL set to true has "
 184       "undefined behavior."
 185       "\n"
 186       "The FILES signature:\n"
 187       "  install(FILES files... DESTINATION <dir>\n"
 188       "          [PERMISSIONS permissions...]\n"
 189       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 190       "          [COMPONENT <component>]\n"
 191       "          [RENAME <name>] [OPTIONAL])\n"
 192       "The FILES form specifies rules for installing files for a "
 193       "project.  File names given as relative paths are interpreted with "
 194       "respect to the current source directory.  Files installed by this "
 195       "form are by default given permissions OWNER_WRITE, OWNER_READ, "
 196       "GROUP_READ, and WORLD_READ if no PERMISSIONS argument is given."
 197       "\n"
 198       "The PROGRAMS signature:\n"
 199       "  install(PROGRAMS files... DESTINATION <dir>\n"
 200       "          [PERMISSIONS permissions...]\n"
 201       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 202       "          [COMPONENT <component>]\n"
 203       "          [RENAME <name>] [OPTIONAL])\n"
 204       "The PROGRAMS form is identical to the FILES form except that the "
 205       "default permissions for the installed file also include "
 206       "OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE.  "
 207       "This form is intended to install programs that are not targets, "
 208       "such as shell scripts.  Use the TARGETS form to install targets "
 209       "built within the project."
 210       "\n"
 211       "The DIRECTORY signature:\n"
 212       "  install(DIRECTORY dirs... DESTINATION <dir>\n"
 213       "          [FILE_PERMISSIONS permissions...]\n"
 214       "          [DIRECTORY_PERMISSIONS permissions...]\n"
 215       "          [USE_SOURCE_PERMISSIONS] [OPTIONAL]\n"
 216       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 217       "          [COMPONENT <component>] [FILES_MATCHING]\n"
 218       "          [[PATTERN <pattern> | REGEX <regex>]\n"
 219       "           [EXCLUDE] [PERMISSIONS permissions...]] [...])\n"
 220       "The DIRECTORY form installs contents of one or more directories "
 221       "to a given destination.  "
 222       "The directory structure is copied verbatim to the destination.  "
 223       "The last component of each directory name is appended to the "
 224       "destination directory but a trailing slash may be used to "
 225       "avoid this because it leaves the last component empty.  "
 226       "Directory names given as relative paths are interpreted with "
 227       "respect to the current source directory.  "
 228       "If no input directory names are given the destination directory "
 229       "will be created but nothing will be installed into it.  "
 230       "The FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify "
 231       "permissions given to files and directories in the destination.  "
 232       "If USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not, "
 233       "file permissions will be copied from the source directory structure.  "
 234       "If no permissions are specified files will be given the default "
 235       "permissions specified in the FILES form of the command, and the "
 236       "directories will be given the default permissions specified in the "
 237       "PROGRAMS form of the command.\n"
 238
 239       "Installation of directories may be controlled with fine granularity "
 240       "using the PATTERN or REGEX options.  These \"match\" options specify a "
 241       "globbing pattern or regular expression to match directories or files "
 242       "encountered within input directories.  They may be used to apply "
 243       "certain options (see below) to a subset of the files and directories "
 244       "encountered.  "
 245       "The full path to each input file or directory "
 246       "(with forward slashes) is matched against the expression.  "
 247       "A PATTERN will match only complete file names: the portion of the "
 248       "full path matching the pattern must occur at the end of the file name "
 249       "and be preceded by a slash.  "
 250       "A REGEX will match any portion of the full path but it may use "
 251       "'/' and '$' to simulate the PATTERN behavior.  "
 252       "By default all files and directories are installed whether "
 253       "or not they are matched.  "
 254       "The FILES_MATCHING option may be given before the first match option "
 255       "to disable installation of files (but not directories) not matched by "
 256       "any expression.  For example, the code\n"
 257       "  install(DIRECTORY src/ DESTINATION include/myproj\n"
 258       "          FILES_MATCHING PATTERN \"*.h\")\n"
 259       "will extract and install header files from a source tree.\n"
 260       "Some options may follow a PATTERN or REGEX expression and are "
 261       "applied only to files or directories matching them.  "
 262       "The EXCLUDE option will skip the matched file or directory.  "
 263       "The PERMISSIONS option overrides the permissions setting for the "
 264       "matched file or directory.  "
 265       "For example the code\n"
 266       "  install(DIRECTORY icons scripts/ DESTINATION share/myproj\n"
 267       "          PATTERN \"CVS\" EXCLUDE\n"
 268       "          PATTERN \"scripts/*\"\n"
 269       "          PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ\n"
 270       "                      GROUP_EXECUTE GROUP_READ)\n"
 271       "will install the icons directory to share/myproj/icons and the "
 272       "scripts directory to share/myproj.  The icons will get default file "
 273       "permissions, the scripts will be given specific permissions, and "
 274       "any CVS directories will be excluded."
 275       "\n"
 276       "The SCRIPT and CODE signature:\n"
 277       "  install([[SCRIPT <file>] [CODE <code>]] [...])\n"
 278       "The SCRIPT form will invoke the given CMake script files during "
 279       "installation.  If the script file name is a relative path "
 280       "it will be interpreted with respect to the current source directory.  "
 281       "The CODE form will invoke the given CMake code during installation.  "
 282       "Code is specified as a single argument inside a double-quoted string. "
 283       "For example, the code\n"
 284       "  install(CODE \"MESSAGE(\\\"Sample install message.\\\")\")\n"
 285       "will print a message during installation.\n"
 286       ""
 287       "The EXPORT signature:\n"
 288       "  install(EXPORT <export-name> DESTINATION <dir>\n"
 289       "          [NAMESPACE <namespace>] [FILE <name>.cmake]\n"
 290       "          [PERMISSIONS permissions...]\n"
 291       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 292       "          [COMPONENT <component>])\n"
 293       "The EXPORT form generates and installs a CMake file containing code "
 294       "to import targets from the installation tree into another project.  "
 295       "Target installations are associated with the export <export-name> "
 296       "using the EXPORT option of the install(TARGETS ...) signature "
 297       "documented above.  The NAMESPACE option will prepend <namespace> to "
 298       "the target names as they are written to the import file.  "
 299       "By default the generated file will be called <export-name>.cmake but "
 300       "the FILE option may be used to specify a different name.  The value "
 301       "given to the FILE option must be a file name with the \".cmake\" "
 302       "extension.  "
 303       "If a CONFIGURATIONS option is given then the file will only be "
 304       "installed when one of the named configurations is installed.  "
 305       "Additionally, the generated import file will reference only the "
 306       "matching target configurations.  "
 307       "If a COMPONENT option is specified that does not match that given "
 308       "to the targets associated with <export-name> the behavior is "
 309       "undefined.  "
 310       "If a library target is included in the export but "
 311       "a target to which it links is not included the behavior is "
 312       "unspecified."
 313       "\n"
 314       "The EXPORT form is useful to help outside projects use targets built "
 315       "and installed by the current project.  For example, the code\n"
 316       "  install(TARGETS myexe EXPORT myproj DESTINATION bin)\n"
 317       "  install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)\n"
 318       "will install the executable myexe to <prefix>/bin and code to import "
 319       "it in the file \"<prefix>/lib/myproj/myproj.cmake\".  "
 320       "An outside project may load this file with the include command "
 321       "and reference the myexe executable from the installation tree using "
 322       "the imported target name mp_myexe as if the target were built "
 323       "in its own tree."
 324       "\n"
 325       "NOTE: This command supercedes the INSTALL_TARGETS command and the "
 326       "target properties PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT.  "
 327       "It also replaces the FILES forms of the INSTALL_FILES and "
 328       "INSTALL_PROGRAMS commands.  "
 329       "The processing order of these install rules relative to those "
 330       "generated by INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS "
 331       "commands is not defined.\n"
 332       ;
 333     }
 334
 335   cmTypeMacro(cmInstallCommand, cmCommand);
 336
 337 private:
 338   bool HandleScriptMode(std::vector<std::string> const& args);
 339   bool HandleTargetsMode(std::vector<std::string> const& args);
 340   bool HandleFilesMode(std::vector<std::string> const& args);
 341   bool HandleDirectoryMode(std::vector<std::string> const& args);
 342   bool HandleExportMode(std::vector<std::string> const& args);
 343   bool MakeFilesFullPath(const char* modeName,
 344                          const std::vector<std::string>& relFiles,
 345                          std::vector<std::string>& absFiles);
 346   bool CheckCMP0006(bool& failure);
 347
 348   std::string DefaultComponentName;
 349 };
 350
 351
 352 #endif