Source/cmInstallCommand.h

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmInstallCommand.h,v $
   5   Language:  C++
   6   Date:      $Date: 2008-01-23 15:27:59 $
   7   Version:   $Revision: 1.24 $
   8
   9   Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
  10   See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
  11
  12      This software is distributed WITHOUT ANY WARRANTY; without even
  13      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14      PURPOSE.  See the above copyright notices for more information.
  15
  16 =========================================================================*/
  17 #ifndef cmInstallCommand_h
  18 #define cmInstallCommand_h
  19
  20 #include "cmCommand.h"
  21
  22 /** \class cmInstallCommand
  23  * \brief Specifies where to install some files
  24  *
  25  * cmInstallCommand is a general-purpose interface command for
  26  * specifying install rules.
  27  */
  28 class cmInstallCommand : public cmCommand
  29 {
  30 public:
  31   /**
  32    * This is a virtual constructor for the command.
  33    */
  34   virtual cmCommand* Clone()
  35     {
  36     return new cmInstallCommand;
  37     }
  38
  39   /**
  40    * This is called when the command is first encountered in
  41    * the CMakeLists.txt file.
  42    */
  43   virtual bool InitialPass(std::vector<std::string> const& args,
  44                            cmExecutionStatus &status);
  45
  46   /**
  47    * The name of the command as specified in CMakeList.txt.
  48    */
  49   virtual const char* GetName() { return "install";}
  50
  51   /**
  52    * Succinct documentation.
  53    */
  54   virtual const char* GetTerseDocumentation()
  55     {
  56     return "Specify rules to run at install time.";
  57     }
  58
  59   /**
  60    * More documentation.
  61    */
  62   virtual const char* GetFullDocumentation()
  63     {
  64     return
  65       "This command generates installation rules for a project.  "
  66       "Rules specified by calls to this command within a source directory "
  67       "are executed in order during installation.  "
  68       "The order across directories is not defined."
  69       "\n"
  70       "There are multiple signatures for this command.  Some of them define "
  71       "installation properties for files and targets.  Properties common to "
  72       "multiple signatures are covered here but they are valid only for "
  73       "signatures that specify them.\n"
  74       "DESTINATION arguments specify "
  75       "the directory on disk to which a file will be installed.  "
  76       "If a full path (with a leading slash or drive letter) is given it "
  77       "is used directly.  If a relative path is given it is interpreted "
  78       "relative to the value of CMAKE_INSTALL_PREFIX.\n"
  79       "PERMISSIONS arguments specify permissions for installed files.  "
  80       "Valid permissions are "
  81       "OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, "
  82       "GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, "
  83       "WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, "
  84       "SETUID, and SETGID.  "
  85       "Permissions that do not make sense on certain platforms are ignored "
  86       "on those platforms.\n"
  87       "The CONFIGURATIONS argument specifies a list of build configurations "
  88       "for which the install rule applies (Debug, Release, etc.).\n"
  89       "The COMPONENT argument specifies an installation component name "
  90       "with which the install rule is associated, such as \"runtime\" or "
  91       "\"development\".  During component-specific installation only "
  92       "install rules associated with the given component name will be "
  93       "executed.  During a full installation all components are installed.\n"
  94       "The RENAME argument specifies a name for an installed file that "
  95       "may be different from the original file.  Renaming is allowed only "
  96       "when a single file is installed by the command.\n"
  97       "The OPTIONAL argument specifies that it is not an error if the "
  98       "file to be installed does not exist.  "
  99       "\n"
 100       "The TARGETS signature:\n"
 101       "  install(TARGETS targets...\n"
 102       "          [[ARCHIVE|LIBRARY|RUNTIME]\n"
 103       "           [DESTINATION <dir>]\n"
 104       "           [PERMISSIONS permissions...]\n"
 105       "           [CONFIGURATIONS [Debug|Release|...]]\n"
 106       "           [COMPONENT <component>]\n"
 107       "           [OPTIONAL]\n"
 108       "          ] [...])\n"
 109       "The TARGETS form specifies rules for installing targets from a "
 110       "project.  There are three kinds of target files that may be "
 111       "installed: archive, library, and runtime.  "
 112
 113       "Executables are always treated as runtime targets. "
 114       "Static libraries are always treated as archive targets. "
 115       "Module libraries are always treated as library targets. "
 116       "For non-DLL platforms shared libraries are treated as library "
 117       "targets. "
 118       "For DLL platforms the DLL part of a shared library is treated as "
 119       "a runtime target and the corresponding import library is treated as "
 120       "an archive target. "
 121       "All Windows-based systems including Cygwin are DLL platforms. "
 122       "The ARCHIVE, LIBRARY, and RUNTIME "
 123       "arguments change the type of target to which the subsequent "
 124       "properties "
 125       "apply.  If none is given the installation properties apply to "
 126       "all target types.  If only one is given then only targets of that "
 127       "type will be installed (which can be used to install just a DLL or "
 128       "just an import library)."
 129       "\n"
 130       "One or more groups of properties may be specified in a single call "
 131       "to the TARGETS form of this command.  A target may be installed more "
 132       "than once to different locations.  Consider hypothetical "
 133       "targets \"myExe\", \"mySharedLib\", and \"myStaticLib\".  The code\n"
 134       "    install(TARGETS myExe mySharedLib myStaticLib\n"
 135       "            RUNTIME DESTINATION bin\n"
 136       "            LIBRARY DESTINATION lib\n"
 137       "            ARCHIVE DESTINATION lib/static)\n"
 138       "    install(TARGETS mySharedLib DESTINATION /some/full/path)\n"
 139       "will install myExe to <prefix>/bin and myStaticLib to "
 140       "<prefix>/lib/static.  "
 141       "On non-DLL platforms mySharedLib will be installed to <prefix>/lib "
 142       "and /some/full/path.  On DLL platforms the mySharedLib DLL will be "
 143       "installed to <prefix>/bin and /some/full/path and its import library "
 144       "will be installed to <prefix>/lib/static and /some/full/path. "
 145       "On non-DLL platforms mySharedLib will be installed to <prefix>/lib "
 146       "and /some/full/path."
 147       "\n"
 148       "Installing a target with EXCLUDE_FROM_ALL set to true has "
 149       "undefined behavior."
 150       "\n"
 151       "The FILES signature:\n"
 152       "  install(FILES files... DESTINATION <dir>\n"
 153       "          [PERMISSIONS permissions...]\n"
 154       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 155       "          [COMPONENT <component>]\n"
 156       "          [RENAME <name>] [OPTIONAL])\n"
 157       "The FILES form specifies rules for installing files for a "
 158       "project.  File names given as relative paths are interpreted with "
 159       "respect to the current source directory.  Files installed by this "
 160       "form are by default given permissions OWNER_WRITE, OWNER_READ, "
 161       "GROUP_READ, and WORLD_READ if no PERMISSIONS argument is given."
 162       "\n"
 163       "The PROGRAMS signature:\n"
 164       "  install(PROGRAMS files... DESTINATION <dir>\n"
 165       "          [PERMISSIONS permissions...]\n"
 166       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 167       "          [COMPONENT <component>]\n"
 168       "          [RENAME <name>] [OPTIONAL])\n"
 169       "The PROGRAMS form is identical to the FILES form except that the "
 170       "default permissions for the installed file also include "
 171       "OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE.  "
 172       "This form is intended to install programs that are not targets, "
 173       "such as shell scripts.  Use the TARGETS form to install targets "
 174       "built within the project."
 175       "\n"
 176       "The DIRECTORY signature:\n"
 177       "  install(DIRECTORY dirs... DESTINATION <dir>\n"
 178       "          [FILE_PERMISSIONS permissions...]\n"
 179       "          [DIRECTORY_PERMISSIONS permissions...]\n"
 180       "          [USE_SOURCE_PERMISSIONS]\n"
 181       "          [CONFIGURATIONS [Debug|Release|...]]\n"
 182       "          [COMPONENT <component>] [FILES_MATCHING]\n"
 183       "          [[PATTERN <pattern> | REGEX <regex>]\n"
 184       "           [EXCLUDE] [PERMISSIONS permissions...]] [...])\n"
 185       "The DIRECTORY form installs contents of one or more directories "
 186       "to a given destination.  "
 187       "The directory structure is copied verbatim to the destination.  "
 188       "The last component of each directory name is appended to the "
 189       "destination directory but a trailing slash may be used to "
 190       "avoid this because it leaves the last component empty.  "
 191       "Directory names given as relative paths are interpreted with "
 192       "respect to the current source directory.  "
 193       "If no input directory names are given the destination directory "
 194       "will be created but nothing will be installed into it.  "
 195       "The FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify "
 196       "permissions given to files and directories in the destination.  "
 197       "If USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not, "
 198       "file permissions will be copied from the source directory structure.  "
 199       "If no permissions are specified files will be given the default "
 200       "permissions specified in the FILES form of the command, and the "
 201       "directories will be given the default permissions specified in the "
 202       "PROGRAMS form of the command.\n"
 203
 204       "Installation of directories may be controlled with fine granularity "
 205       "using the PATTERN or REGEX options.  These \"match\" options specify a "
 206       "globbing pattern or regular expression to match directories or files "
 207       "encountered within input directories.  They may be used to apply "
 208       "certain options (see below) to a subset of the files and directories "
 209       "encountered.  "
 210       "The full path to each input file or directory "
 211       "(with forward slashes) is matched against the expression.  "
 212       "A PATTERN will match only complete file names: the portion of the "
 213       "full path matching the pattern must occur at the end of the file name "
 214       "and be preceded by a slash.  "
 215       "A REGEX will match any portion of the full path but it may use "
 216       "'/' and '$' to simulate the PATTERN behavior.  "
 217       "By default all files and directories are installed whether "
 218       "or not they are matched.  "
 219       "The FILES_MATCHING option may be given before the first match option "
 220       "to disable installation of files (but not directories) not matched by "
 221       "any expression.  For example, the code\n"
 222       "  install(DIRECTORY src/ DESTINATION include/myproj\n"
 223       "          FILES_MATCHING PATTERN \"*.h\")\n"
 224       "will extract and install header files from a source tree.\n"
 225       "Some options may follow a PATTERN or REGEX expression and are "
 226       "applied only to files or directories matching them.  "
 227       "The EXCLUDE option will skip the matched file or directory.  "
 228       "The PERMISSIONS option overrides the permissions setting for the "
 229       "matched file or directory.  "
 230       "For example the code\n"
 231       "  install(DIRECTORY icons scripts/ DESTINATION share/myproj\n"
 232       "          PATTERN \"CVS\" EXCLUDE\n"
 233       "          PATTERN \"scripts/*\"\n"
 234       "          PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ\n"
 235       "                      GROUP_EXECUTE GROUP_READ)\n"
 236       "will install the icons directory to share/myproj/icons and the "
 237       "scripts directory to share/myproj.  The icons will get default file "
 238       "permissions, the scripts will be given specific permissions, and "
 239       "any CVS directories will be excluded."
 240       "\n"
 241       "The SCRIPT and CODE signature:\n"
 242       "  install([[SCRIPT <file>] [CODE <code>]] [...])\n"
 243       "The SCRIPT form will invoke the given CMake script files during "
 244       "installation.  If the script file name is a relative path "
 245       "it will be interpreted with respect to the current source directory.  "
 246       "The CODE form will invoke the given CMake code during installation.  "
 247       "Code is specified as a single argument inside a double-quoted string. "
 248       "For example, the code\n"
 249       "  install(CODE \"MESSAGE(\\\"Sample install message.\\\")\")\n"
 250       "will print a message during installation.\n"
 251       "NOTE: This command supercedes the INSTALL_TARGETS command and the "
 252       "target properties PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT.  "
 253       "It also replaces the FILES forms of the INSTALL_FILES and "
 254       "INSTALL_PROGRAMS commands.  "
 255       "The processing order of these install rules relative to those "
 256       "generated by INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS "
 257       "commands is not defined.\n"
 258       ;
 259     }
 260
 261   cmTypeMacro(cmInstallCommand, cmCommand);
 262
 263 private:
 264   bool HandleScriptMode(std::vector<std::string> const& args);
 265   bool HandleTargetsMode(std::vector<std::string> const& args);
 266   bool HandleFilesMode(std::vector<std::string> const& args);
 267   bool HandleDirectoryMode(std::vector<std::string> const& args);
 268   bool HandleExportMode(std::vector<std::string> const& args);
 269   bool MakeFilesFullPath(const char* modeName,
 270                          const std::vector<std::string>& relFiles,
 271                          std::vector<std::string>& absFiles);
 272 };
 273
 274
 275 #endif