1install 2------- 3 4Specify rules to run at install time. 5 6Synopsis 7^^^^^^^^ 8 9.. parsed-literal:: 10 11 install(`TARGETS`_ <target>... [...]) 12 install(`IMPORTED_RUNTIME_ARTIFACTS`_ <target>... [...]) 13 install({`FILES`_ | `PROGRAMS`_} <file>... [...]) 14 install(`DIRECTORY`_ <dir>... [...]) 15 install(`SCRIPT`_ <file> [...]) 16 install(`CODE`_ <code> [...]) 17 install(`EXPORT`_ <export-name> [...]) 18 install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...]) 19 20Introduction 21^^^^^^^^^^^^ 22 23This command generates installation rules for a project. Install rules 24specified by calls to the ``install()`` command within a source directory 25are executed in order during installation. 26 27.. versionchanged:: 3.14 28 Install rules in subdirectories 29 added by calls to the :command:`add_subdirectory` command are interleaved 30 with those in the parent directory to run in the order declared (see 31 policy :policy:`CMP0082`). 32 33.. versionchanged:: 3.22 34 The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the 35 default copying behavior of :command:`install()`. 36 37There are multiple signatures for this command. Some of them define 38installation options for files and targets. Options common to 39multiple signatures are covered here but they are valid only for 40signatures that specify them. The common options are: 41 42``DESTINATION`` 43 Specify the directory on disk to which a file will be installed. 44 Arguments can be relative or absolute paths. 45 46 If a relative path is given it is interpreted relative to the value 47 of the :variable:`CMAKE_INSTALL_PREFIX` variable. 48 The prefix can be relocated at install time using the ``DESTDIR`` 49 mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable 50 documentation. 51 52 If an absolute path (with a leading slash or drive letter) is given 53 it is used verbatim. 54 55 As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer 56 generators, it is preferable to use relative paths throughout. 57 In particular, there is no need to make paths absolute by prepending 58 :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if 59 the DESTINATION is a relative path. 60 61``PERMISSIONS`` 62 Specify permissions for installed files. Valid permissions are 63 ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, 64 ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``, 65 ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do 66 not make sense on certain platforms are ignored on those platforms. 67 68``CONFIGURATIONS`` 69 Specify a list of build configurations for which the install rule 70 applies (Debug, Release, etc.). Note that the values specified for 71 this option only apply to options listed AFTER the ``CONFIGURATIONS`` 72 option. For example, to set separate install paths for the Debug and 73 Release configurations, do the following: 74 75 .. code-block:: cmake 76 77 install(TARGETS target 78 CONFIGURATIONS Debug 79 RUNTIME DESTINATION Debug/bin) 80 install(TARGETS target 81 CONFIGURATIONS Release 82 RUNTIME DESTINATION Release/bin) 83 84 Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``. 85 86``COMPONENT`` 87 Specify an installation component name with which the install rule 88 is associated, such as "runtime" or "development". During 89 component-specific installation only install rules associated with 90 the given component name will be executed. During a full installation 91 all components are installed unless marked with ``EXCLUDE_FROM_ALL``. 92 If ``COMPONENT`` is not provided a default component "Unspecified" is 93 created. The default component name may be controlled with the 94 :variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable. 95 96``EXCLUDE_FROM_ALL`` 97 .. versionadded:: 3.6 98 99 Specify that the file is excluded from a full installation and only 100 installed as part of a component-specific installation 101 102``RENAME`` 103 Specify a name for an installed file that may be different from the 104 original file. Renaming is allowed only when a single file is 105 installed by the command. 106 107``OPTIONAL`` 108 Specify that it is not an error if the file to be installed does 109 not exist. 110 111.. versionadded:: 3.1 112 Command signatures that install files may print messages during 113 installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable 114 to control which messages are printed. 115 116.. versionadded:: 3.11 117 Many of the ``install()`` variants implicitly create the directories 118 containing the installed files. If 119 :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these 120 directories will be created with the permissions specified. Otherwise, 121 they will be created according to the uname rules on Unix-like platforms. 122 Windows platforms are unaffected. 123 124Installing Targets 125^^^^^^^^^^^^^^^^^^ 126 127.. _`install(TARGETS)`: 128.. _TARGETS: 129 130.. code-block:: cmake 131 132 install(TARGETS targets... [EXPORT <export-name>] 133 [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>] 134 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| 135 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] 136 [DESTINATION <dir>] 137 [PERMISSIONS permissions...] 138 [CONFIGURATIONS [Debug|Release|...]] 139 [COMPONENT <component>] 140 [NAMELINK_COMPONENT <component>] 141 [OPTIONAL] [EXCLUDE_FROM_ALL] 142 [NAMELINK_ONLY|NAMELINK_SKIP] 143 ] [...] 144 [INCLUDES DESTINATION [<dir> ...]] 145 ) 146 147The ``TARGETS`` form specifies rules for installing targets from a 148project. There are several kinds of target :ref:`Output Artifacts` 149that may be installed: 150 151``ARCHIVE`` 152 Target artifacts of this kind include: 153 154 * *Static libraries* 155 (except on macOS when marked as ``FRAMEWORK``, see below); 156 * *DLL import libraries* 157 (on all Windows-based systems including Cygwin; they have extension 158 ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); 159 * On AIX, the *linker import file* created for executables with 160 :prop_tgt:`ENABLE_EXPORTS` enabled. 161 162``LIBRARY`` 163 Target artifacts of this kind include: 164 165 * *Shared libraries*, except 166 167 - DLLs (these go to ``RUNTIME``, see below), 168 - on macOS when marked as ``FRAMEWORK`` (see below). 169 170``RUNTIME`` 171 Target artifacts of this kind include: 172 173 * *Executables* 174 (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below); 175 * DLLs (on all Windows-based systems including Cygwin; note that the 176 accompanying import libraries are of kind ``ARCHIVE``). 177 178``OBJECTS`` 179 .. versionadded:: 3.9 180 181 Object files associated with *object libraries*. 182 183``FRAMEWORK`` 184 Both static and shared libraries marked with the ``FRAMEWORK`` 185 property are treated as ``FRAMEWORK`` targets on macOS. 186 187``BUNDLE`` 188 Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as 189 ``BUNDLE`` targets on macOS. 190 191``PUBLIC_HEADER`` 192 Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in 193 the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple 194 platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK` 195 libraries on Apple platforms because the associated files are installed 196 into the appropriate locations inside the framework folder. See 197 :prop_tgt:`PUBLIC_HEADER` for details. 198 199``PRIVATE_HEADER`` 200 Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See 201 :prop_tgt:`PRIVATE_HEADER` for details. 202 203``RESOURCE`` 204 Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for 205 ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. 206 207For each of these arguments given, the arguments following them only apply 208to the target or file type specified in the argument. If none is given, the 209installation properties apply to all target types. If only one is given then 210only targets of that type will be installed (which can be used to install 211just a DLL or just an import library.) 212 213For regular executables, static libraries and shared libraries, the 214``DESTINATION`` argument is not required. For these target types, when 215``DESTINATION`` is omitted, a default destination will be taken from the 216appropriate variable from :module:`GNUInstallDirs`, or set to a built-in 217default value if that variable is not defined. The same is true for the 218public and private headers associated with the installed targets through the 219:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. 220A destination must always be provided for module libraries, Apple bundles and 221frameworks. A destination can be omitted for interface and object libraries, 222but they are handled differently (see the discussion of this topic toward the 223end of this section). 224 225The following table shows the target types with their associated variables and 226built-in defaults that apply when no destination is given: 227 228================== =============================== ====================== 229 Target Type GNUInstallDirs Variable Built-In Default 230================== =============================== ====================== 231``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` 232``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` 233``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` 234``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` 235``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` 236================== =============================== ====================== 237 238Projects wishing to follow the common practice of installing headers into a 239project-specific subdirectory will need to provide a destination rather than 240rely on the above. 241 242To make packages compliant with distribution filesystem layout policies, if 243projects must specify a ``DESTINATION``, it is recommended that they use a 244path that begins with the appropriate :module:`GNUInstallDirs` variable. 245This allows package maintainers to control the install destination by setting 246the appropriate cache variables. The following example shows a static library 247being installed to the default destination provided by 248:module:`GNUInstallDirs`, but with its headers installed to a project-specific 249subdirectory that follows the above recommendation: 250 251.. code-block:: cmake 252 253 add_library(mylib STATIC ...) 254 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) 255 include(GNUInstallDirs) 256 install(TARGETS mylib 257 PUBLIC_HEADER 258 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj 259 ) 260 261In addition to the common options listed above, each target can accept 262the following additional arguments: 263 264``NAMELINK_COMPONENT`` 265 .. versionadded:: 3.12 266 267 On some platforms a versioned shared library has a symbolic link such 268 as:: 269 270 lib<name>.so -> lib<name>.so.1 271 272 where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` 273 is a "namelink" allowing linkers to find the library when given 274 ``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the 275 ``COMPONENT`` option, but it changes the installation component of a shared 276 library namelink if one is generated. If not specified, this defaults to the 277 value of ``COMPONENT``. It is an error to use this parameter outside of a 278 ``LIBRARY`` block. 279 280 Consider the following example: 281 282 .. code-block:: cmake 283 284 install(TARGETS mylib 285 LIBRARY 286 COMPONENT Libraries 287 NAMELINK_COMPONENT Development 288 PUBLIC_HEADER 289 COMPONENT Development 290 ) 291 292 In this scenario, if you choose to install only the ``Development`` 293 component, both the headers and namelink will be installed without the 294 library. (If you don't also install the ``Libraries`` component, the 295 namelink will be a dangling symlink, and projects that link to the library 296 will have build errors.) If you install only the ``Libraries`` component, 297 only the library will be installed, without the headers and namelink. 298 299 This option is typically used for package managers that have separate 300 runtime and development packages. For example, on Debian systems, the 301 library is expected to be in the runtime package, and the headers and 302 namelink are expected to be in the development package. 303 304 See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for 305 details on creating versioned shared libraries. 306 307``NAMELINK_ONLY`` 308 This option causes the installation of only the namelink when a library 309 target is installed. On platforms where versioned shared libraries do not 310 have namelinks or when a library is not versioned, the ``NAMELINK_ONLY`` 311 option installs nothing. It is an error to use this parameter outside of a 312 ``LIBRARY`` block. 313 314 When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or 315 ``COMPONENT`` may be used to specify the installation component of the 316 namelink, but ``COMPONENT`` should generally be preferred. 317 318``NAMELINK_SKIP`` 319 Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the 320 installation of library files other than the namelink when a library target 321 is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given, 322 both portions are installed. On platforms where versioned shared libraries 323 do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP`` 324 installs the library. It is an error to use this parameter outside of a 325 ``LIBRARY`` block. 326 327 If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It 328 is not recommended to use ``NAMELINK_SKIP`` in conjunction with 329 ``NAMELINK_COMPONENT``. 330 331The `install(TARGETS)`_ command can also accept the following options at the 332top level: 333 334``EXPORT`` 335 This option associates the installed target files with an export called 336 ``<export-name>``. It must appear before any target options. To actually 337 install the export file itself, call `install(EXPORT)`_, documented below. 338 See documentation of the :prop_tgt:`EXPORT_NAME` target property to change 339 the name of the exported target. 340 341``INCLUDES DESTINATION`` 342 This option specifies a list of directories which will be added to the 343 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the 344 ``<targets>`` when exported by the `install(EXPORT)`_ command. If a 345 relative path is specified, it is treated as relative to the 346 ``$<INSTALL_PREFIX>``. 347 348``RUNTIME_DEPENDENCY_SET`` 349 .. versionadded:: 3.21 350 351 This option causes all runtime dependencies of installed executable, shared 352 library, and module targets to be added to the specified runtime dependency 353 set. This set can then be installed with an 354 `install(RUNTIME_DEPENDENCY_SET)`_ command. 355 356 This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually 357 exclusive. 358 359``RUNTIME_DEPENDENCIES`` 360 .. versionadded:: 3.21 361 362 This option causes all runtime dependencies of installed executable, shared 363 library, and module targets to be installed along with the targets 364 themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic 365 arguments are used to determine the properties (``DESTINATION``, 366 ``COMPONENT``, etc.) of the installation of these dependencies. 367 368 ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair 369 of calls: 370 371 .. code-block:: cmake 372 373 install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>) 374 install(RUNTIME_DEPENDENCY_SET <set-name> args...) 375 376 where ``<set-name>`` will be a randomly generated set name. 377 The ``args...`` may include any of the following keywords supported by 378 the `install(RUNTIME_DEPENDENCY_SET)`_ command: 379 380 * ``DIRECTORIES`` 381 * ``PRE_INCLUDE_REGEXES`` 382 * ``PRE_EXCLUDE_REGEXES`` 383 * ``POST_INCLUDE_REGEXES`` 384 * ``POST_EXCLUDE_REGEXES`` 385 * ``POST_INCLUDE_FILES`` 386 * ``POST_EXCLUDE_FILES`` 387 388 The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are 389 mutually exclusive. 390 391One or more groups of properties may be specified in a single call to 392the ``TARGETS`` form of this command. A target may be installed more than 393once to different locations. Consider hypothetical targets ``myExe``, 394``mySharedLib``, and ``myStaticLib``. The code: 395 396.. code-block:: cmake 397 398 install(TARGETS myExe mySharedLib myStaticLib 399 RUNTIME DESTINATION bin 400 LIBRARY DESTINATION lib 401 ARCHIVE DESTINATION lib/static) 402 install(TARGETS mySharedLib DESTINATION /some/full/path) 403 404will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to 405``<prefix>/lib/static``. On non-DLL platforms ``mySharedLib`` will be 406installed to ``<prefix>/lib`` and ``/some/full/path``. On DLL platforms 407the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and 408``/some/full/path`` and its import library will be installed to 409``<prefix>/lib/static`` and ``/some/full/path``. 410 411:ref:`Interface Libraries` may be listed among the targets to install. 412They install no artifacts but will be included in an associated ``EXPORT``. 413If :ref:`Object Libraries` are listed but given no destination for their 414object files, they will be exported as :ref:`Interface Libraries`. 415This is sufficient to satisfy transitive usage requirements of other 416targets that link to the object libraries in their implementation. 417 418Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property 419set to ``TRUE`` has undefined behavior. 420 421.. versionadded:: 3.3 422 An install destination given as a ``DESTINATION`` argument may 423 use "generator expressions" with the syntax ``$<...>``. See the 424 :manual:`cmake-generator-expressions(7)` manual for available expressions. 425 426.. versionadded:: 3.13 427 `install(TARGETS)`_ can install targets that were created in 428 other directories. When using such cross-directory install rules, running 429 ``make install`` (or similar) from a subdirectory will not guarantee that 430 targets from other directories are up-to-date. You can use 431 :command:`target_link_libraries` or :command:`add_dependencies` 432 to ensure that such out-of-directory targets are built before the 433 subdirectory-specific install rules are run. 434 435Installing Imported Runtime Artifacts 436^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 437 438.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`: 439.. _IMPORTED_RUNTIME_ARTIFACTS: 440 441.. versionadded:: 3.21 442 443.. code-block:: cmake 444 445 install(IMPORTED_RUNTIME_ARTIFACTS targets... 446 [RUNTIME_DEPENDENCY_SET <set-name>] 447 [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] 448 [DESTINATION <dir>] 449 [PERMISSIONS permissions...] 450 [CONFIGURATIONS [Debug|Release|...]] 451 [COMPONENT <component>] 452 [OPTIONAL] [EXCLUDE_FROM_ALL] 453 ] [...] 454 ) 455 456The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the 457runtime artifacts of imported targets. Projects may do this if they want to 458bundle outside executables or modules inside their installation. The 459``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the 460same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts 461of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK` 462libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` 463CFBundles.) For example, headers and import libraries associated with DLLs are 464not installed. In the case of :prop_tgt:`FRAMEWORK` libraries, 465:prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the 466entire directory is installed. 467 468The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the 469imported executable, shared library, and module library ``targets`` to be 470added to the ``<set-name>`` runtime dependency set. This set can then be 471installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. 472 473Installing Files 474^^^^^^^^^^^^^^^^ 475 476.. _`install(FILES)`: 477.. _`install(PROGRAMS)`: 478.. _FILES: 479.. _PROGRAMS: 480 481.. code-block:: cmake 482 483 install(<FILES|PROGRAMS> files... 484 TYPE <type> | DESTINATION <dir> 485 [PERMISSIONS permissions...] 486 [CONFIGURATIONS [Debug|Release|...]] 487 [COMPONENT <component>] 488 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) 489 490The ``FILES`` form specifies rules for installing files for a project. 491File names given as relative paths are interpreted with respect to the 492current source directory. Files installed by this form are by default 493given permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and 494``WORLD_READ`` if no ``PERMISSIONS`` argument is given. 495 496The ``PROGRAMS`` form is identical to the ``FILES`` form except that the 497default permissions for the installed file also include ``OWNER_EXECUTE``, 498``GROUP_EXECUTE``, and ``WORLD_EXECUTE``. This form is intended to install 499programs that are not targets, such as shell scripts. Use the ``TARGETS`` 500form to install targets built within the project. 501 502The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use 503"generator expressions" with the syntax ``$<...>``. See the 504:manual:`cmake-generator-expressions(7)` manual for available expressions. 505However, if any item begins in a generator expression it must evaluate 506to a full path. 507 508Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. 509A ``TYPE`` argument specifies the generic file type of the files being 510installed. A destination will then be set automatically by taking the 511corresponding variable from :module:`GNUInstallDirs`, or by using a 512built-in default if that variable is not defined. See the table below for 513the supported file types and their corresponding variables and built-in 514defaults. Projects can provide a ``DESTINATION`` argument instead of a 515file type if they wish to explicitly define the install destination. 516 517======================= ================================== ========================= 518 ``TYPE`` Argument GNUInstallDirs Variable Built-In Default 519======================= ================================== ========================= 520``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` 521``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` 522``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` 523``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` 524``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` 525``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` 526``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` 527``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run`` 528``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>`` 529``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info`` 530``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` 531``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` 532``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` 533======================= ================================== ========================= 534 535Projects wishing to follow the common practice of installing headers into a 536project-specific subdirectory will need to provide a destination rather than 537rely on the above. 538 539Note that some of the types' built-in defaults use the ``DATAROOT`` directory as 540a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with 541``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in 542default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use 543``DATA`` instead. 544 545To make packages compliant with distribution filesystem layout policies, if 546projects must specify a ``DESTINATION``, it is recommended that they use a 547path that begins with the appropriate :module:`GNUInstallDirs` variable. 548This allows package maintainers to control the install destination by setting 549the appropriate cache variables. The following example shows how to follow 550this advice while installing headers to a project-specific subdirectory: 551 552.. code-block:: cmake 553 554 include(GNUInstallDirs) 555 install(FILES mylib.h 556 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj 557 ) 558 559.. versionadded:: 3.4 560 An install destination given as a ``DESTINATION`` argument may 561 use "generator expressions" with the syntax ``$<...>``. See the 562 :manual:`cmake-generator-expressions(7)` manual for available expressions. 563 564.. versionadded:: 3.20 565 An install rename given as a ``RENAME`` argument may 566 use "generator expressions" with the syntax ``$<...>``. See the 567 :manual:`cmake-generator-expressions(7)` manual for available expressions. 568 569Installing Directories 570^^^^^^^^^^^^^^^^^^^^^^ 571 572.. _`install(DIRECTORY)`: 573.. _DIRECTORY: 574 575.. code-block:: cmake 576 577 install(DIRECTORY dirs... 578 TYPE <type> | DESTINATION <dir> 579 [FILE_PERMISSIONS permissions...] 580 [DIRECTORY_PERMISSIONS permissions...] 581 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] 582 [CONFIGURATIONS [Debug|Release|...]] 583 [COMPONENT <component>] [EXCLUDE_FROM_ALL] 584 [FILES_MATCHING] 585 [[PATTERN <pattern> | REGEX <regex>] 586 [EXCLUDE] [PERMISSIONS permissions...]] [...]) 587 588The ``DIRECTORY`` form installs contents of one or more directories to a 589given destination. The directory structure is copied verbatim to the 590destination. The last component of each directory name is appended to 591the destination directory but a trailing slash may be used to avoid 592this because it leaves the last component empty. Directory names 593given as relative paths are interpreted with respect to the current 594source directory. If no input directory names are given the 595destination directory will be created but nothing will be installed 596into it. The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options 597specify permissions given to files and directories in the destination. 598If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not, 599file permissions will be copied from the source directory structure. 600If no permissions are specified files will be given the default 601permissions specified in the ``FILES`` form of the command, and the 602directories will be given the default permissions specified in the 603``PROGRAMS`` form of the command. 604 605.. versionadded:: 3.1 606 The ``MESSAGE_NEVER`` option disables file installation status output. 607 608Installation of directories may be controlled with fine granularity 609using the ``PATTERN`` or ``REGEX`` options. These "match" options specify a 610globbing pattern or regular expression to match directories or files 611encountered within input directories. They may be used to apply 612certain options (see below) to a subset of the files and directories 613encountered. The full path to each input file or directory (with 614forward slashes) is matched against the expression. A ``PATTERN`` will 615match only complete file names: the portion of the full path matching 616the pattern must occur at the end of the file name and be preceded by 617a slash. A ``REGEX`` will match any portion of the full path but it may 618use ``/`` and ``$`` to simulate the ``PATTERN`` behavior. By default all 619files and directories are installed whether or not they are matched. 620The ``FILES_MATCHING`` option may be given before the first match option 621to disable installation of files (but not directories) not matched by 622any expression. For example, the code 623 624.. code-block:: cmake 625 626 install(DIRECTORY src/ DESTINATION include/myproj 627 FILES_MATCHING PATTERN "*.h") 628 629will extract and install header files from a source tree. 630 631Some options may follow a ``PATTERN`` or ``REGEX`` expression as described 632under :ref:`string(REGEX) <Regex Specification>` and are applied 633only to files or directories matching them. The ``EXCLUDE`` option will 634skip the matched file or directory. The ``PERMISSIONS`` option overrides 635the permissions setting for the matched file or directory. For 636example the code 637 638.. code-block:: cmake 639 640 install(DIRECTORY icons scripts/ DESTINATION share/myproj 641 PATTERN "CVS" EXCLUDE 642 PATTERN "scripts/*" 643 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ 644 GROUP_EXECUTE GROUP_READ) 645 646will install the ``icons`` directory to ``share/myproj/icons`` and the 647``scripts`` directory to ``share/myproj``. The icons will get default 648file permissions, the scripts will be given specific permissions, and any 649``CVS`` directories will be excluded. 650 651Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. 652A ``TYPE`` argument specifies the generic file type of the files within the 653listed directories being installed. A destination will then be set 654automatically by taking the corresponding variable from 655:module:`GNUInstallDirs`, or by using a built-in default if that variable 656is not defined. See the table below for the supported file types and their 657corresponding variables and built-in defaults. Projects can provide a 658``DESTINATION`` argument instead of a file type if they wish to explicitly 659define the install destination. 660 661======================= ================================== ========================= 662 ``TYPE`` Argument GNUInstallDirs Variable Built-In Default 663======================= ================================== ========================= 664``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` 665``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` 666``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` 667``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` 668``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` 669``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` 670``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` 671``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run`` 672``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>`` 673``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info`` 674``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` 675``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` 676``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` 677======================= ================================== ========================= 678 679Note that some of the types' built-in defaults use the ``DATAROOT`` directory as 680a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with 681``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in 682default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use 683``DATA`` instead. 684 685To make packages compliant with distribution filesystem layout policies, if 686projects must specify a ``DESTINATION``, it is recommended that they use a 687path that begins with the appropriate :module:`GNUInstallDirs` variable. 688This allows package maintainers to control the install destination by setting 689the appropriate cache variables. 690 691.. versionadded:: 3.4 692 An install destination given as a ``DESTINATION`` argument may 693 use "generator expressions" with the syntax ``$<...>``. See the 694 :manual:`cmake-generator-expressions(7)` manual for available expressions. 695 696.. versionadded:: 3.5 697 The list of ``dirs...`` given to ``DIRECTORY`` may use 698 "generator expressions" too. 699 700Custom Installation Logic 701^^^^^^^^^^^^^^^^^^^^^^^^^ 702 703.. _`install(CODE)`: 704.. _`install(SCRIPT)`: 705.. _CODE: 706.. _SCRIPT: 707 708.. code-block:: cmake 709 710 install([[SCRIPT <file>] [CODE <code>]] 711 [ALL_COMPONENTS | COMPONENT <component>] 712 [EXCLUDE_FROM_ALL] [...]) 713 714The ``SCRIPT`` form will invoke the given CMake script files during 715installation. If the script file name is a relative path it will be 716interpreted with respect to the current source directory. The ``CODE`` 717form will invoke the given CMake code during installation. Code is 718specified as a single argument inside a double-quoted string. For 719example, the code 720 721.. code-block:: cmake 722 723 install(CODE "MESSAGE(\"Sample install message.\")") 724 725will print a message during installation. 726 727.. versionadded:: 3.21 728 When the ``ALL_COMPONENTS`` option is given, the custom installation 729 script code will be executed for every component of a component-specific 730 installation. This option is mutually exclusive with the ``COMPONENT`` 731 option. 732 733.. versionadded:: 3.14 734 ``<file>`` or ``<code>`` may use "generator expressions" with the syntax 735 ``$<...>`` (in the case of ``<file>``, this refers to their use in the file 736 name, not the file's contents). See the 737 :manual:`cmake-generator-expressions(7)` manual for available expressions. 738 739Installing Exports 740^^^^^^^^^^^^^^^^^^ 741 742.. _`install(EXPORT)`: 743.. _EXPORT: 744 745.. code-block:: cmake 746 747 install(EXPORT <export-name> DESTINATION <dir> 748 [NAMESPACE <namespace>] [[FILE <name>.cmake]| 749 [PERMISSIONS permissions...] 750 [CONFIGURATIONS [Debug|Release|...]] 751 [EXPORT_LINK_INTERFACE_LIBRARIES] 752 [COMPONENT <component>] 753 [EXCLUDE_FROM_ALL]) 754 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...]) 755 756The ``EXPORT`` form generates and installs a CMake file containing code to 757import targets from the installation tree into another project. 758Target installations are associated with the export ``<export-name>`` 759using the ``EXPORT`` option of the `install(TARGETS)`_ signature 760documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to 761the target names as they are written to the import file. By default 762the generated file will be called ``<export-name>.cmake`` but the ``FILE`` 763option may be used to specify a different name. The value given to 764the ``FILE`` option must be a file name with the ``.cmake`` extension. 765If a ``CONFIGURATIONS`` option is given then the file will only be installed 766when one of the named configurations is installed. Additionally, the 767generated import file will reference only the matching target 768configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if 769present, causes the contents of the properties matching 770``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when 771policy :policy:`CMP0022` is ``NEW``. 772 773.. note:: 774 The installed ``<export-name>.cmake`` file may come with additional 775 per-configuration ``<export-name>-*.cmake`` files to be loaded by 776 globbing. Do not use an export name that is the same as the package 777 name in combination with installing a ``<package-name>-config.cmake`` 778 file or the latter may be incorrectly matched by the glob and loaded. 779 780When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly 781depends on all components mentioned in the export set. The exported 782``<name>.cmake`` file will require each of the exported components to be 783present in order for dependent projects to build properly. For example, a 784project may define components ``Runtime`` and ``Development``, with shared 785libraries going into the ``Runtime`` component and static libraries and 786headers going into the ``Development`` component. The export set would also 787typically be part of the ``Development`` component, but it would export 788targets from both the ``Runtime`` and ``Development`` components. Therefore, 789the ``Runtime`` component would need to be installed if the ``Development`` 790component was installed, but not vice versa. If the ``Development`` component 791was installed without the ``Runtime`` component, dependent projects that try 792to link against it would have build errors. Package managers, such as APT and 793RPM, typically handle this by listing the ``Runtime`` component as a dependency 794of the ``Development`` component in the package metadata, ensuring that the 795library is always installed if the headers and CMake export file are present. 796 797.. versionadded:: 3.7 798 In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe 799 used to specify an export to the android ndk build system. This mode 800 accepts the same options as the normal export mode. The Android 801 NDK supports the use of prebuilt libraries, both static and shared. This 802 allows cmake to build the libraries of a project and make them available 803 to an ndk build system complete with transitive dependencies, include flags 804 and defines required to use the libraries. 805 806The ``EXPORT`` form is useful to help outside projects use targets built 807and installed by the current project. For example, the code 808 809.. code-block:: cmake 810 811 install(TARGETS myexe EXPORT myproj DESTINATION bin) 812 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) 813 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules) 814 815will install the executable ``myexe`` to ``<prefix>/bin`` and code to import 816it in the file ``<prefix>/lib/myproj/myproj.cmake`` and 817``<prefix>/share/ndk-modules/Android.mk``. An outside project 818may load this file with the include command and reference the ``myexe`` 819executable from the installation tree using the imported target name 820``mp_myexe`` as if the target were built in its own tree. 821 822.. note:: 823 This command supersedes the :command:`install_targets` command and 824 the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` 825 target properties. It also replaces the ``FILES`` forms of the 826 :command:`install_files` and :command:`install_programs` commands. 827 The processing order of these install rules relative to 828 those generated by :command:`install_targets`, 829 :command:`install_files`, and :command:`install_programs` commands 830 is not defined. 831 832Installing Runtime Dependencies 833^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 834 835.. _`install(RUNTIME_DEPENDENCY_SET)`: 836.. _RUNTIME_DEPENDENCY_SET: 837 838.. versionadded:: 3.21 839 840.. code-block:: cmake 841 842 install(RUNTIME_DEPENDENCY_SET <set-name> 843 [[LIBRARY|RUNTIME|FRAMEWORK] 844 [DESTINATION <dir>] 845 [PERMISSIONS permissions...] 846 [CONFIGURATIONS [Debug|Release|...]] 847 [COMPONENT <component>] 848 [NAMELINK_COMPONENT <component>] 849 [OPTIONAL] [EXCLUDE_FROM_ALL] 850 ] [...] 851 [PRE_INCLUDE_REGEXES regexes...] 852 [PRE_EXCLUDE_REGEXES regexes...] 853 [POST_INCLUDE_REGEXES regexes...] 854 [POST_EXCLUDE_REGEXES regexes...] 855 [POST_INCLUDE_FILES files...] 856 [POST_EXCLUDE_FILES files...] 857 [DIRECTORIES directories...] 858 ) 859 860Installs a runtime dependency set previously created by one or more 861`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The 862dependencies of targets belonging to a runtime dependency set are installed in 863the ``RUNTIME`` destination and component on DLL platforms, and in the 864``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks 865are installed in the ``FRAMEWORK`` destination and component. 866Targets built within the build tree will never be installed as runtime 867dependencies, nor will their own dependencies, unless the targets themselves 868are installed with `install(TARGETS)`_. 869 870The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` 871on the build-tree files to calculate the runtime dependencies. The build-tree 872executable files are passed as the ``EXECUTABLES`` argument, the build-tree 873shared libraries as the ``LIBRARIES`` argument, and the build-tree modules as 874the ``MODULES`` argument. On macOS, if one of the executables is a 875:prop_tgt:`MACOSX_BUNDLE`, that executable is passed as the 876``BUNDLE_EXECUTABLE`` argument. At most one such bundle executable may be in 877the runtime dependency set on macOS. The :prop_tgt:`MACOSX_BUNDLE` property 878has no effect on other platforms. Note that 879:command:`file(GET_RUNTIME_DEPENDENCIES)` only supports collecting the runtime 880dependencies for Windows, Linux and macOS platforms, so 881``install(RUNTIME_DEPENDENCY_SET)`` has the same limitation. 882 883The following sub-arguments are forwarded through as the corresponding 884arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide 885a non-empty list of directories, regular expressions or files). They all 886support :manual:`generator expressions <cmake-generator-expressions(7)>`. 887 888* ``DIRECTORIES <directories>`` 889* ``PRE_INCLUDE_REGEXES <regexes>`` 890* ``PRE_EXCLUDE_REGEXES <regexes>`` 891* ``POST_INCLUDE_REGEXES <regexes>`` 892* ``POST_EXCLUDE_REGEXES <regexes>`` 893* ``POST_INCLUDE_FILES <files>`` 894* ``POST_EXCLUDE_FILES <files>`` 895 896Generated Installation Script 897^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 898 899.. note:: 900 901 Use of this feature is not recommended. Please consider using the 902 ``--install`` argument of :manual:`cmake(1)` instead. 903 904The ``install()`` command generates a file, ``cmake_install.cmake``, inside 905the build directory, which is used internally by the generated install target 906and by CPack. You can also invoke this script manually with ``cmake -P``. This 907script accepts several variables: 908 909``COMPONENT`` 910 Set this variable to install only a single CPack component as opposed to all 911 of them. For example, if you only want to install the ``Development`` 912 component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``. 913 914``BUILD_TYPE`` 915 Set this variable to change the build type if you are using a multi-config 916 generator. For example, to install with the ``Debug`` configuration, run 917 ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``. 918 919``DESTDIR`` 920 This is an environment variable rather than a CMake variable. It allows you 921 to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for 922 details. 923