Help/command/install.rst

   1 install
   2 -------
   3
   4 Specify rules to run at install time.
   5
   6 Synopsis
   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
  20 Introduction
  21 ^^^^^^^^^^^^
  22
  23 This command generates installation rules for a project.  Install rules
  24 specified by calls to the ``install()`` command within a source directory
  25 are 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
  37 There are multiple signatures for this command.  Some of them define
  38 installation options for files and targets.  Options common to
  39 multiple signatures are covered here but they are valid only for
  40 signatures 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
 124 Installing 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|FILE_SET <set-name>|CXX_MODULES_BMI]
 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
 147 The ``TARGETS`` form specifies rules for installing targets from a
 148 project.  There are several kinds of target :ref:`Output Artifacts`
 149 that 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
 207 ``FILE_SET <set>``
 208   .. versionadded:: 3.23
 209
 210   File sets are defined by the :command:`target_sources(FILE_SET)` command.
 211   If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any
 212   files in the set are installed under the destination (see below).
 213   The directory structure relative to the file set's base directories is
 214   preserved. For example, a file added to the file set as
 215   ``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
 216   would be installed to ``myproj/here.h`` below the destination.
 217
 218 ``CXX_MODULES_BMI``
 219
 220   .. note ::
 221
 222     Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
 223
 224   Any module files from C++ modules from ``PUBLIC`` sources in a file set of
 225   type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All
 226   modules are placed directly in the destination as no directory structure is
 227   derived from the names of the modules. An empty ``DESTINATION`` may be used
 228   to suppress installing these files (for use in generic code).
 229
 230 For each of these arguments given, the arguments following them only apply
 231 to the target or file type specified in the argument. If none is given, the
 232 installation properties apply to all target types.
 233
 234 For regular executables, static libraries and shared libraries, the
 235 ``DESTINATION`` argument is not required.  For these target types, when
 236 ``DESTINATION`` is omitted, a default destination will be taken from the
 237 appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
 238 default value if that variable is not defined.  The same is true for file
 239 sets, and the public and private headers associated with the installed
 240 targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER`
 241 target properties. A destination must always be provided for module libraries,
 242 Apple bundles and frameworks.  A destination can be omitted for interface and
 243 object libraries, but they are handled differently (see the discussion of this
 244 topic toward the end of this section).
 245
 246 For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE``
 247 destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are
 248 installed to their default destinations. If either a ``RUNTIME`` or ``ARCHIVE``
 249 destination is specified, the component is installed to that destination, and
 250 the other component is not installed. If both ``RUNTIME`` and ``ARCHIVE``
 251 destinations are specified, then both components are installed to their
 252 respective destinations.
 253
 254 The following table shows the target types with their associated variables and
 255 built-in defaults that apply when no destination is given:
 256
 257 =============================== =============================== ======================
 258    Target Type                      GNUInstallDirs Variable        Built-In Default
 259 =============================== =============================== ======================
 260 ``RUNTIME``                     ``${CMAKE_INSTALL_BINDIR}``     ``bin``
 261 ``LIBRARY``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
 262 ``ARCHIVE``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
 263 ``PRIVATE_HEADER``              ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
 264 ``PUBLIC_HEADER``               ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
 265 ``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
 266 =============================== =============================== ======================
 267
 268 Projects wishing to follow the common practice of installing headers into a
 269 project-specific subdirectory may prefer using file sets with appropriate
 270 paths and base directories. Otherwise, they must provide a ``DESTINATION``
 271 instead of being able to rely on the above (see next example below).
 272
 273 To make packages compliant with distribution filesystem layout policies, if
 274 projects must specify a ``DESTINATION``, it is recommended that they use a
 275 path that begins with the appropriate :module:`GNUInstallDirs` variable.
 276 This allows package maintainers to control the install destination by setting
 277 the appropriate cache variables.  The following example shows a static library
 278 being installed to the default destination provided by
 279 :module:`GNUInstallDirs`, but with its headers installed to a project-specific
 280 subdirectory without using file sets:
 281
 282 .. code-block:: cmake
 283
 284   add_library(mylib STATIC ...)
 285   set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
 286   include(GNUInstallDirs)
 287   install(TARGETS mylib
 288           PUBLIC_HEADER
 289             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
 290   )
 291
 292 In addition to the common options listed above, each target can accept
 293 the following additional arguments:
 294
 295 ``NAMELINK_COMPONENT``
 296   .. versionadded:: 3.12
 297
 298   On some platforms a versioned shared library has a symbolic link such
 299   as::
 300
 301     lib<name>.so -> lib<name>.so.1
 302
 303   where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so``
 304   is a "namelink" allowing linkers to find the library when given
 305   ``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the
 306   ``COMPONENT`` option, but it changes the installation component of a shared
 307   library namelink if one is generated. If not specified, this defaults to the
 308   value of ``COMPONENT``. It is an error to use this parameter outside of a
 309   ``LIBRARY`` block.
 310
 311   Consider the following example:
 312
 313   .. code-block:: cmake
 314
 315     install(TARGETS mylib
 316             LIBRARY
 317               COMPONENT Libraries
 318               NAMELINK_COMPONENT Development
 319             PUBLIC_HEADER
 320               COMPONENT Development
 321            )
 322
 323   In this scenario, if you choose to install only the ``Development``
 324   component, both the headers and namelink will be installed without the
 325   library. (If you don't also install the ``Libraries`` component, the
 326   namelink will be a dangling symlink, and projects that link to the library
 327   will have build errors.) If you install only the ``Libraries`` component,
 328   only the library will be installed, without the headers and namelink.
 329
 330   This option is typically used for package managers that have separate
 331   runtime and development packages. For example, on Debian systems, the
 332   library is expected to be in the runtime package, and the headers and
 333   namelink are expected to be in the development package.
 334
 335   See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for
 336   details on creating versioned shared libraries.
 337
 338 ``NAMELINK_ONLY``
 339   This option causes the installation of only the namelink when a library
 340   target is installed. On platforms where versioned shared libraries do not
 341   have namelinks or when a library is not versioned, the ``NAMELINK_ONLY``
 342   option installs nothing. It is an error to use this parameter outside of a
 343   ``LIBRARY`` block.
 344
 345   When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or
 346   ``COMPONENT`` may be used to specify the installation component of the
 347   namelink, but ``COMPONENT`` should generally be preferred.
 348
 349 ``NAMELINK_SKIP``
 350   Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the
 351   installation of library files other than the namelink when a library target
 352   is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given,
 353   both portions are installed. On platforms where versioned shared libraries
 354   do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP``
 355   installs the library. It is an error to use this parameter outside of a
 356   ``LIBRARY`` block.
 357
 358   If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It
 359   is not recommended to use ``NAMELINK_SKIP`` in conjunction with
 360   ``NAMELINK_COMPONENT``.
 361
 362 The `install(TARGETS)`_ command can also accept the following options at the
 363 top level:
 364
 365 ``EXPORT``
 366   This option associates the installed target files with an export called
 367   ``<export-name>``.  It must appear before any target options.  To actually
 368   install the export file itself, call `install(EXPORT)`_, documented below.
 369   See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
 370   the name of the exported target.
 371
 372   If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE``
 373   file sets, all of them must be specified with ``FILE_SET`` arguments. All
 374   ``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included
 375   in the export.
 376
 377 ``INCLUDES DESTINATION``
 378   This option specifies a list of directories which will be added to the
 379   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
 380   ``<targets>`` when exported by the `install(EXPORT)`_ command. If a
 381   relative path is specified, it is treated as relative to the
 382   ``$<INSTALL_PREFIX>``.
 383
 384 ``RUNTIME_DEPENDENCY_SET``
 385   .. versionadded:: 3.21
 386
 387   This option causes all runtime dependencies of installed executable, shared
 388   library, and module targets to be added to the specified runtime dependency
 389   set. This set can then be installed with an
 390   `install(RUNTIME_DEPENDENCY_SET)`_ command.
 391
 392   This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually
 393   exclusive.
 394
 395 ``RUNTIME_DEPENDENCIES``
 396   .. versionadded:: 3.21
 397
 398   This option causes all runtime dependencies of installed executable, shared
 399   library, and module targets to be installed along with the targets
 400   themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic
 401   arguments are used to determine the properties (``DESTINATION``,
 402   ``COMPONENT``, etc.) of the installation of these dependencies.
 403
 404   ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair
 405   of calls:
 406
 407   .. code-block:: cmake
 408
 409     install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
 410     install(RUNTIME_DEPENDENCY_SET <set-name> args...)
 411
 412   where ``<set-name>`` will be a randomly generated set name.
 413   The ``args...`` may include any of the following keywords supported by
 414   the `install(RUNTIME_DEPENDENCY_SET)`_ command:
 415
 416   * ``DIRECTORIES``
 417   * ``PRE_INCLUDE_REGEXES``
 418   * ``PRE_EXCLUDE_REGEXES``
 419   * ``POST_INCLUDE_REGEXES``
 420   * ``POST_EXCLUDE_REGEXES``
 421   * ``POST_INCLUDE_FILES``
 422   * ``POST_EXCLUDE_FILES``
 423
 424   The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are
 425   mutually exclusive.
 426
 427 One or more groups of properties may be specified in a single call to
 428 the ``TARGETS`` form of this command.  A target may be installed more than
 429 once to different locations.  Consider hypothetical targets ``myExe``,
 430 ``mySharedLib``, and ``myStaticLib``.  The code:
 431
 432 .. code-block:: cmake
 433
 434   install(TARGETS myExe mySharedLib myStaticLib
 435           RUNTIME DESTINATION bin
 436           LIBRARY DESTINATION lib
 437           ARCHIVE DESTINATION lib/static)
 438   install(TARGETS mySharedLib DESTINATION /some/full/path)
 439
 440 will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to
 441 ``<prefix>/lib/static``.  On non-DLL platforms ``mySharedLib`` will be
 442 installed to ``<prefix>/lib`` and ``/some/full/path``.  On DLL platforms
 443 the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
 444 ``/some/full/path`` and its import library will be installed to
 445 ``<prefix>/lib/static`` and ``/some/full/path``.
 446
 447 :ref:`Interface Libraries` may be listed among the targets to install.
 448 They install no artifacts but will be included in an associated ``EXPORT``.
 449 If :ref:`Object Libraries` are listed but given no destination for their
 450 object files, they will be exported as :ref:`Interface Libraries`.
 451 This is sufficient to satisfy transitive usage requirements of other
 452 targets that link to the object libraries in their implementation.
 453
 454 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 455 set to ``TRUE`` has undefined behavior.
 456
 457 .. versionadded:: 3.3
 458   An install destination given as a ``DESTINATION`` argument may
 459   use "generator expressions" with the syntax ``$<...>``.  See the
 460   :manual:`cmake-generator-expressions(7)` manual for available expressions.
 461
 462 .. versionadded:: 3.13
 463   `install(TARGETS)`_ can install targets that were created in
 464   other directories.  When using such cross-directory install rules, running
 465   ``make install`` (or similar) from a subdirectory will not guarantee that
 466   targets from other directories are up-to-date.  You can use
 467   :command:`target_link_libraries` or :command:`add_dependencies`
 468   to ensure that such out-of-directory targets are built before the
 469   subdirectory-specific install rules are run.
 470
 471 Installing Imported Runtime Artifacts
 472 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 473
 474 .. _`install(IMPORTED_RUNTIME_ARTIFACTS)`:
 475 .. _IMPORTED_RUNTIME_ARTIFACTS:
 476
 477 .. versionadded:: 3.21
 478
 479 .. code-block:: cmake
 480
 481   install(IMPORTED_RUNTIME_ARTIFACTS targets...
 482           [RUNTIME_DEPENDENCY_SET <set-name>]
 483           [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
 484            [DESTINATION <dir>]
 485            [PERMISSIONS permissions...]
 486            [CONFIGURATIONS [Debug|Release|...]]
 487            [COMPONENT <component>]
 488            [OPTIONAL] [EXCLUDE_FROM_ALL]
 489           ] [...]
 490           )
 491
 492 The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the
 493 runtime artifacts of imported targets. Projects may do this if they want to
 494 bundle outside executables or modules inside their installation. The
 495 ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the
 496 same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts
 497 of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK`
 498 libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE`
 499 CFBundles.) For example, headers and import libraries associated with DLLs are
 500 not installed. In the case of :prop_tgt:`FRAMEWORK` libraries,
 501 :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the
 502 entire directory is installed.
 503
 504 The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the
 505 imported executable, shared library, and module library ``targets`` to be
 506 added to the ``<set-name>`` runtime dependency set. This set can then be
 507 installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command.
 508
 509 Installing Files
 510 ^^^^^^^^^^^^^^^^
 511
 512 .. _`install(FILES)`:
 513 .. _`install(PROGRAMS)`:
 514 .. _FILES:
 515 .. _PROGRAMS:
 516
 517 .. note::
 518
 519   If installing header files, consider using file sets defined by
 520   :command:`target_sources(FILE_SET)` instead. File sets associate
 521   headers with a target and they install as part of the target.
 522
 523 .. code-block:: cmake
 524
 525   install(<FILES|PROGRAMS> files...
 526           TYPE <type> | DESTINATION <dir>
 527           [PERMISSIONS permissions...]
 528           [CONFIGURATIONS [Debug|Release|...]]
 529           [COMPONENT <component>]
 530           [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
 531
 532 The ``FILES`` form specifies rules for installing files for a project.
 533 File names given as relative paths are interpreted with respect to the
 534 current source directory.  Files installed by this form are by default
 535 given permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and
 536 ``WORLD_READ`` if no ``PERMISSIONS`` argument is given.
 537
 538 The ``PROGRAMS`` form is identical to the ``FILES`` form except that the
 539 default permissions for the installed file also include ``OWNER_EXECUTE``,
 540 ``GROUP_EXECUTE``, and ``WORLD_EXECUTE``.  This form is intended to install
 541 programs that are not targets, such as shell scripts.  Use the ``TARGETS``
 542 form to install targets built within the project.
 543
 544 The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
 545 "generator expressions" with the syntax ``$<...>``.  See the
 546 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 547 However, if any item begins in a generator expression it must evaluate
 548 to a full path.
 549
 550 Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
 551 A ``TYPE`` argument specifies the generic file type of the files being
 552 installed.  A destination will then be set automatically by taking the
 553 corresponding variable from :module:`GNUInstallDirs`, or by using a
 554 built-in default if that variable is not defined.  See the table below for
 555 the supported file types and their corresponding variables and built-in
 556 defaults.  Projects can provide a ``DESTINATION`` argument instead of a
 557 file type if they wish to explicitly define the install destination.
 558
 559 ======================= ================================== =========================
 560    ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
 561 ======================= ================================== =========================
 562 ``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
 563 ``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
 564 ``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
 565 ``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
 566 ``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
 567 ``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
 568 ``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
 569 ``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
 570 ``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
 571 ``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
 572 ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
 573 ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
 574 ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
 575 ======================= ================================== =========================
 576
 577 Projects wishing to follow the common practice of installing headers into a
 578 project-specific subdirectory will need to provide a destination rather than
 579 rely on the above. Using file sets for headers instead of ``install(FILES)``
 580 would be even better (see :command:`target_sources(FILE_SET)`).
 581
 582 Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
 583 a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
 584 ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
 585 default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
 586 ``DATA`` instead.
 587
 588 To make packages compliant with distribution filesystem layout policies, if
 589 projects must specify a ``DESTINATION``, it is recommended that they use a
 590 path that begins with the appropriate :module:`GNUInstallDirs` variable.
 591 This allows package maintainers to control the install destination by setting
 592 the appropriate cache variables.  The following example shows how to follow
 593 this advice while installing an image to a project-specific documentation
 594 subdirectory:
 595
 596 .. code-block:: cmake
 597
 598   include(GNUInstallDirs)
 599   install(FILES logo.png
 600           DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
 601   )
 602
 603 .. versionadded:: 3.4
 604   An install destination given as a ``DESTINATION`` argument may
 605   use "generator expressions" with the syntax ``$<...>``.  See the
 606   :manual:`cmake-generator-expressions(7)` manual for available expressions.
 607
 608 .. versionadded:: 3.20
 609   An install rename given as a ``RENAME`` argument may
 610   use "generator expressions" with the syntax ``$<...>``.  See the
 611   :manual:`cmake-generator-expressions(7)` manual for available expressions.
 612
 613 Installing Directories
 614 ^^^^^^^^^^^^^^^^^^^^^^
 615
 616 .. _`install(DIRECTORY)`:
 617 .. _DIRECTORY:
 618
 619 .. note::
 620
 621   To install a directory sub-tree of headers, consider using file sets
 622   defined by :command:`target_sources(FILE_SET)` instead. File sets not only
 623   preserve directory structure, they also associate headers with a target
 624   and install as part of the target.
 625
 626 .. code-block:: cmake
 627
 628   install(DIRECTORY dirs...
 629           TYPE <type> | DESTINATION <dir>
 630           [FILE_PERMISSIONS permissions...]
 631           [DIRECTORY_PERMISSIONS permissions...]
 632           [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
 633           [CONFIGURATIONS [Debug|Release|...]]
 634           [COMPONENT <component>] [EXCLUDE_FROM_ALL]
 635           [FILES_MATCHING]
 636           [[PATTERN <pattern> | REGEX <regex>]
 637            [EXCLUDE] [PERMISSIONS permissions...]] [...])
 638
 639 The ``DIRECTORY`` form installs contents of one or more directories to a
 640 given destination.  The directory structure is copied verbatim to the
 641 destination.  The last component of each directory name is appended to
 642 the destination directory but a trailing slash may be used to avoid
 643 this because it leaves the last component empty.  Directory names
 644 given as relative paths are interpreted with respect to the current
 645 source directory.  If no input directory names are given the
 646 destination directory will be created but nothing will be installed
 647 into it.  The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options
 648 specify permissions given to files and directories in the destination.
 649 If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not,
 650 file permissions will be copied from the source directory structure.
 651 If no permissions are specified files will be given the default
 652 permissions specified in the ``FILES`` form of the command, and the
 653 directories will be given the default permissions specified in the
 654 ``PROGRAMS`` form of the command.
 655
 656 .. versionadded:: 3.1
 657   The ``MESSAGE_NEVER`` option disables file installation status output.
 658
 659 Installation of directories may be controlled with fine granularity
 660 using the ``PATTERN`` or ``REGEX`` options.  These "match" options specify a
 661 globbing pattern or regular expression to match directories or files
 662 encountered within input directories.  They may be used to apply
 663 certain options (see below) to a subset of the files and directories
 664 encountered.  The full path to each input file or directory (with
 665 forward slashes) is matched against the expression.  A ``PATTERN`` will
 666 match only complete file names: the portion of the full path matching
 667 the pattern must occur at the end of the file name and be preceded by
 668 a slash.  A ``REGEX`` will match any portion of the full path but it may
 669 use ``/`` and ``$`` to simulate the ``PATTERN`` behavior.  By default all
 670 files and directories are installed whether or not they are matched.
 671 The ``FILES_MATCHING`` option may be given before the first match option
 672 to disable installation of files (but not directories) not matched by
 673 any expression.  For example, the code
 674
 675 .. code-block:: cmake
 676
 677   install(DIRECTORY src/ DESTINATION doc/myproj
 678           FILES_MATCHING PATTERN "*.png")
 679
 680 will extract and install images from a source tree.
 681
 682 Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
 683 under :ref:`string(REGEX) <Regex Specification>` and are applied
 684 only to files or directories matching them.  The ``EXCLUDE`` option will
 685 skip the matched file or directory.  The ``PERMISSIONS`` option overrides
 686 the permissions setting for the matched file or directory.  For
 687 example the code
 688
 689 .. code-block:: cmake
 690
 691   install(DIRECTORY icons scripts/ DESTINATION share/myproj
 692           PATTERN "CVS" EXCLUDE
 693           PATTERN "scripts/*"
 694           PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
 695                       GROUP_EXECUTE GROUP_READ)
 696
 697 will install the ``icons`` directory to ``share/myproj/icons`` and the
 698 ``scripts`` directory to ``share/myproj``.  The icons will get default
 699 file permissions, the scripts will be given specific permissions, and any
 700 ``CVS`` directories will be excluded.
 701
 702 Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
 703 A ``TYPE`` argument specifies the generic file type of the files within the
 704 listed directories being installed.  A destination will then be set
 705 automatically by taking the corresponding variable from
 706 :module:`GNUInstallDirs`, or by using a built-in default if that variable
 707 is not defined.  See the table below for the supported file types and their
 708 corresponding variables and built-in defaults.  Projects can provide a
 709 ``DESTINATION`` argument instead of a file type if they wish to explicitly
 710 define the install destination.
 711
 712 ======================= ================================== =========================
 713    ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
 714 ======================= ================================== =========================
 715 ``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
 716 ``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
 717 ``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
 718 ``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
 719 ``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
 720 ``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
 721 ``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
 722 ``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
 723 ``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
 724 ``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
 725 ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
 726 ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
 727 ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
 728 ======================= ================================== =========================
 729
 730 Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
 731 a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
 732 ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
 733 default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
 734 ``DATA`` instead.
 735
 736 To make packages compliant with distribution filesystem layout policies, if
 737 projects must specify a ``DESTINATION``, it is recommended that they use a
 738 path that begins with the appropriate :module:`GNUInstallDirs` variable.
 739 This allows package maintainers to control the install destination by setting
 740 the appropriate cache variables.
 741
 742 .. versionadded:: 3.4
 743   An install destination given as a ``DESTINATION`` argument may
 744   use "generator expressions" with the syntax ``$<...>``.  See the
 745   :manual:`cmake-generator-expressions(7)` manual for available expressions.
 746
 747 .. versionadded:: 3.5
 748   The list of ``dirs...`` given to ``DIRECTORY`` may use
 749   "generator expressions" too.
 750
 751 Custom Installation Logic
 752 ^^^^^^^^^^^^^^^^^^^^^^^^^
 753
 754 .. _`install(CODE)`:
 755 .. _`install(SCRIPT)`:
 756 .. _CODE:
 757 .. _SCRIPT:
 758
 759 .. code-block:: cmake
 760
 761   install([[SCRIPT <file>] [CODE <code>]]
 762           [ALL_COMPONENTS | COMPONENT <component>]
 763           [EXCLUDE_FROM_ALL] [...])
 764
 765 The ``SCRIPT`` form will invoke the given CMake script files during
 766 installation.  If the script file name is a relative path it will be
 767 interpreted with respect to the current source directory.  The ``CODE``
 768 form will invoke the given CMake code during installation.  Code is
 769 specified as a single argument inside a double-quoted string.  For
 770 example, the code
 771
 772 .. code-block:: cmake
 773
 774   install(CODE "MESSAGE(\"Sample install message.\")")
 775
 776 will print a message during installation.
 777
 778 .. versionadded:: 3.21
 779   When the ``ALL_COMPONENTS`` option is given, the custom installation
 780   script code will be executed for every component of a component-specific
 781   installation.  This option is mutually exclusive with the ``COMPONENT``
 782   option.
 783
 784 .. versionadded:: 3.14
 785   ``<file>`` or ``<code>`` may use "generator expressions" with the syntax
 786   ``$<...>`` (in the case of ``<file>``, this refers to their use in the file
 787   name, not the file's contents).  See the
 788   :manual:`cmake-generator-expressions(7)` manual for available expressions.
 789
 790 Installing Exports
 791 ^^^^^^^^^^^^^^^^^^
 792
 793 .. _`install(EXPORT)`:
 794 .. _EXPORT:
 795
 796 .. code-block:: cmake
 797
 798   install(EXPORT <export-name> DESTINATION <dir>
 799           [NAMESPACE <namespace>] [FILE <name>.cmake]
 800           [PERMISSIONS permissions...]
 801           [CONFIGURATIONS [Debug|Release|...]
 802           [CXX_MODULES_DIRECTORY <directory>]
 803           [EXPORT_LINK_INTERFACE_LIBRARIES]
 804           [COMPONENT <component>]
 805           [EXCLUDE_FROM_ALL])
 806   install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
 807
 808 The ``EXPORT`` form generates and installs a CMake file containing code to
 809 import targets from the installation tree into another project.
 810 Target installations are associated with the export ``<export-name>``
 811 using the ``EXPORT`` option of the `install(TARGETS)`_ signature
 812 documented above.  The ``NAMESPACE`` option will prepend ``<namespace>`` to
 813 the target names as they are written to the import file.  By default
 814 the generated file will be called ``<export-name>.cmake`` but the ``FILE``
 815 option may be used to specify a different name.  The value given to
 816 the ``FILE`` option must be a file name with the ``.cmake`` extension.
 817 If a ``CONFIGURATIONS`` option is given then the file will only be installed
 818 when one of the named configurations is installed.  Additionally, the
 819 generated import file will reference only the matching target
 820 configurations.  The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if
 821 present, causes the contents of the properties matching
 822 ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
 823 policy :policy:`CMP0022` is ``NEW``.
 824
 825 .. note::
 826   The installed ``<export-name>.cmake`` file may come with additional
 827   per-configuration ``<export-name>-*.cmake`` files to be loaded by
 828   globbing.  Do not use an export name that is the same as the package
 829   name in combination with installing a ``<package-name>-config.cmake``
 830   file or the latter may be incorrectly matched by the glob and loaded.
 831
 832 When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly
 833 depends on all components mentioned in the export set. The exported
 834 ``<name>.cmake`` file will require each of the exported components to be
 835 present in order for dependent projects to build properly. For example, a
 836 project may define components ``Runtime`` and ``Development``, with shared
 837 libraries going into the ``Runtime`` component and static libraries and
 838 headers going into the ``Development`` component. The export set would also
 839 typically be part of the ``Development`` component, but it would export
 840 targets from both the ``Runtime`` and ``Development`` components. Therefore,
 841 the ``Runtime`` component would need to be installed if the ``Development``
 842 component was installed, but not vice versa. If the ``Development`` component
 843 was installed without the ``Runtime`` component, dependent projects that try
 844 to link against it would have build errors. Package managers, such as APT and
 845 RPM, typically handle this by listing the ``Runtime`` component as a dependency
 846 of the ``Development`` component in the package metadata, ensuring that the
 847 library is always installed if the headers and CMake export file are present.
 848
 849 .. versionadded:: 3.7
 850   In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode may be
 851   used to specify an export to the android ndk build system.  This mode
 852   accepts the same options as the normal export mode.  The Android
 853   NDK supports the use of prebuilt libraries, both static and shared. This
 854   allows cmake to build the libraries of a project and make them available
 855   to an ndk build system complete with transitive dependencies, include flags
 856   and defines required to use the libraries.
 857
 858 ``CXX_MODULES_DIRECTORY``
 859
 860   .. note ::
 861
 862     Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
 863
 864   Specify a subdirectory to store C++ module information for targets in the
 865   export set. This directory will be populated with files which add the
 866   necessary target property information to the relevant targets. Note that
 867   without this information, none of the C++ modules which are part of the
 868   targets in the export set will support being imported in consuming targets.
 869
 870 The ``EXPORT`` form is useful to help outside projects use targets built
 871 and installed by the current project.  For example, the code
 872
 873 .. code-block:: cmake
 874
 875   install(TARGETS myexe EXPORT myproj DESTINATION bin)
 876   install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
 877   install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
 878
 879 will install the executable ``myexe`` to ``<prefix>/bin`` and code to import
 880 it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
 881 ``<prefix>/share/ndk-modules/Android.mk``.  An outside project
 882 may load this file with the include command and reference the ``myexe``
 883 executable from the installation tree using the imported target name
 884 ``mp_myexe`` as if the target were built in its own tree.
 885
 886 .. note::
 887   This command supersedes the :command:`install_targets` command and
 888   the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT`
 889   target properties.  It also replaces the ``FILES`` forms of the
 890   :command:`install_files` and :command:`install_programs` commands.
 891   The processing order of these install rules relative to
 892   those generated by :command:`install_targets`,
 893   :command:`install_files`, and :command:`install_programs` commands
 894   is not defined.
 895
 896 Installing Runtime Dependencies
 897 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 898
 899 .. _`install(RUNTIME_DEPENDENCY_SET)`:
 900 .. _RUNTIME_DEPENDENCY_SET:
 901
 902 .. versionadded:: 3.21
 903
 904 .. code-block:: cmake
 905
 906   install(RUNTIME_DEPENDENCY_SET <set-name>
 907           [[LIBRARY|RUNTIME|FRAMEWORK]
 908            [DESTINATION <dir>]
 909            [PERMISSIONS permissions...]
 910            [CONFIGURATIONS [Debug|Release|...]]
 911            [COMPONENT <component>]
 912            [NAMELINK_COMPONENT <component>]
 913            [OPTIONAL] [EXCLUDE_FROM_ALL]
 914           ] [...]
 915           [PRE_INCLUDE_REGEXES regexes...]
 916           [PRE_EXCLUDE_REGEXES regexes...]
 917           [POST_INCLUDE_REGEXES regexes...]
 918           [POST_EXCLUDE_REGEXES regexes...]
 919           [POST_INCLUDE_FILES files...]
 920           [POST_EXCLUDE_FILES files...]
 921           [DIRECTORIES directories...]
 922           )
 923
 924 Installs a runtime dependency set previously created by one or more
 925 `install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The
 926 dependencies of targets belonging to a runtime dependency set are installed in
 927 the ``RUNTIME`` destination and component on DLL platforms, and in the
 928 ``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks
 929 are installed in the ``FRAMEWORK`` destination and component.
 930 Targets built within the build tree will never be installed as runtime
 931 dependencies, nor will their own dependencies, unless the targets themselves
 932 are installed with `install(TARGETS)`_.
 933
 934 The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)`
 935 on the build-tree files to calculate the runtime dependencies. The build-tree
 936 executable files are passed as the ``EXECUTABLES`` argument, the build-tree
 937 shared libraries as the ``LIBRARIES`` argument, and the build-tree modules as
 938 the ``MODULES`` argument. On macOS, if one of the executables is a
 939 :prop_tgt:`MACOSX_BUNDLE`, that executable is passed as the
 940 ``BUNDLE_EXECUTABLE`` argument. At most one such bundle executable may be in
 941 the runtime dependency set on macOS. The :prop_tgt:`MACOSX_BUNDLE` property
 942 has no effect on other platforms. Note that
 943 :command:`file(GET_RUNTIME_DEPENDENCIES)` only supports collecting the runtime
 944 dependencies for Windows, Linux and macOS platforms, so
 945 ``install(RUNTIME_DEPENDENCY_SET)`` has the same limitation.
 946
 947 The following sub-arguments are forwarded through as the corresponding
 948 arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide
 949 a non-empty list of directories, regular expressions or files).  They all
 950 support :manual:`generator expressions <cmake-generator-expressions(7)>`.
 951
 952 * ``DIRECTORIES <directories>``
 953 * ``PRE_INCLUDE_REGEXES <regexes>``
 954 * ``PRE_EXCLUDE_REGEXES <regexes>``
 955 * ``POST_INCLUDE_REGEXES <regexes>``
 956 * ``POST_EXCLUDE_REGEXES <regexes>``
 957 * ``POST_INCLUDE_FILES <files>``
 958 * ``POST_EXCLUDE_FILES <files>``
 959
 960 Generated Installation Script
 961 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 962
 963 .. note::
 964
 965   Use of this feature is not recommended. Please consider using the
 966   :option:`cmake --install` instead.
 967
 968 The ``install()`` command generates a file, ``cmake_install.cmake``, inside
 969 the build directory, which is used internally by the generated install target
 970 and by CPack. You can also invoke this script manually with
 971 :option:`cmake -P`. This script accepts several variables:
 972
 973 ``COMPONENT``
 974   Set this variable to install only a single CPack component as opposed to all
 975   of them. For example, if you only want to install the ``Development``
 976   component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``.
 977
 978 ``BUILD_TYPE``
 979   Set this variable to change the build type if you are using a multi-config
 980   generator. For example, to install with the ``Debug`` configuration, run
 981   ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``.
 982
 983 ``DESTDIR``
 984   This is an environment variable rather than a CMake variable. It allows you
 985   to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
 986   details.