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