Installing Files
****************

Software is typically installed into a directory separate from the
source and build trees. This allows it to be distributed in a clean
form and isolates users from the details of the build process. CMake
provides the :command:`install` command to specify how a project is to be
installed. This command is invoked by a project in the CMakeLists file
and tells CMake how to generate installation scripts. The scripts are
executed at install time to perform the actual installation of
files. For Makefile generators (UNIX, NMake, MinGW, etc.),
the user simply runs ``make install`` (or ``nmake install``) and the
make tool will invoke CMake's installation module. With GUI based
systems (Visual Studio, Xcode, etc.), the user simply builds the
target called ``INSTALL``.

Each call to the :command:`install` command defines some installation
rules. Within one CMakeLists file (source directory), these rules will
be evaluated in the order that the corresponding commands are
invoked. The order across multiple directories changed in CMake 3.14.

The :command:`install` command has several signatures designed for common
installation use cases. A particular invocation of the command
specifies the signature as the first argument. The signatures are
``TARGETS``, ``FILES`` or ``PROGRAMS``, ``DIRECTORY``, ``SCRIPT``,
``CODE`` and ``EXPORT``.

**install(TARGETS ...)**
  Installs the binary files corresponding to targets built inside the
  project.

**install(FILES ...)**
  General-purpose file installation, which is typically used for
  header files, documentation, and data files required by your
  software.

**install(PROGRAMS ...)**
  Installs executable files not built by the project, such as shell
  scripts. This argument is identical to ``install(FILES)`` except
  that the default permissions of the installed file include the
  executable bit.`

**install(DIRECTORY ...)**
  This argument installs an entire directory tree. It may be used for
  installing directories with resources, such as icons and images.

**install(SCRIPT ...)**
  Specifies a user-provided CMake script file to be executed during
  installation. This is typically used to define pre-install or
  post-install actions for other rules.

**install(CODE ...)**
  Specifies user-provided CMake code to be executed during the
  installation. This is similar to ``install (SCRIPT)`` but the code
  is provided inline in the call as a string.

**install(EXPORT ...)**
  Generates and installs a CMake file containing code to import targets from
  the installation tree into another project.

The ``TARGETS``, ``FILES``, ``PROGRAMS``, and``DIRECTORY`` signatures are all
meant to create install rules for files. The targets, files, or directories
to be installed are listed immediately after the signature name argument.
Additional details can be specified using keyword arguments followed by
corresponding values. Keyword arguments provided by most of the signatures are as follows.

**DESTINATION**
  This argument specifies the location where the installation rule
  will place files, and must be followed by a directory path
  indicating the location. If the directory is specified as a full
  path, it will be evaluated at install time as an absolute path. If
  the directory is specified as a relative path, it will be evaluated
  at install time relative to the installation prefix. The prefix may
  be set by the user through the cache variable
  :variable:`CMAKE_INSTALL_PREFIX`. A platform-specific default is
  provided by CMake: ``/usr/local`` on UNIX, and
  "<SystemDrive>/``Program Files``/<ProjectName>" on Windows, where
  SystemDrive is along the lines of ``C:`` and ProjectName is the
  name given to the top-most :command:`project` command.

.. index::
   single: file ; permissions

**PERMISSIONS**
  This argument specifies file permissions to be set on the installed
  files. This option is needed only to override the default
  permissions selected by a particular :command:`install` command
  signature. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``,
  ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``,
  ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``,
  ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Some platforms do not
  support all of these permissions; on such platforms those permission
  names are ignored.

.. index::
   single: build ; configurations

**CONFIGURATIONS**
  This argument specifies a list of build configurations for which an
  installation rule applies (Debug, Release, etc.). For Makefile
  generators, the build configuration is specified by the
  :variable:`CMAKE_BUILD_TYPE` cache variable. For Visual Studio and Xcode
  generators, the configuration is selected when the :command:`install`
  target is built. An installation rule will be evaluated only if the
  current install configuration matches an entry in the list provided
  to this argument. Configuration name comparison is case-insensitive.

.. index::
   single: file ; component

**COMPONENT**
  This argument specifies the installation component for which the
  installation rule applies. Some projects divide their installations
  into multiple components for separate packaging. For example, a
  project may define a ``Runtime`` component that contains the files
  needed to run a tool; a ``Development`` component containing the
  files needed to build extensions to the tool; and a
  ``Documentation`` component containing the manual pages and other
  help files. The project may then package each component separately
  for distribution by installing only one component at a time. By
  default, all components are installed. Component-specific
  installation is an advanced feature intended for use by package
  maintainers. It requires manual invocation of the installation
  scripts with an argument defining the ``COMPONENT`` variable to name
  the desired component. Note that component names are not defined by
  CMake. Each project may define its own set of components.

.. index::
   single: file ; optional

**OPTIONAL**
  This argument specifies that it is not an error if the input file to
  be installed does not exist. If the input file exists, it will be
  installed as requested. If it does not exist, it will be silently
  not installed.

Installing Targets
------------------

Projects typically install some of the library and executable files
created during their build process. The :command:`install` command provides
the ``TARGETS`` signature for this purpose.

The ``TARGETS`` keyword is immediately followed by a list of the
targets created using :command:`add_executable` or :command:`add_library`,
which are to be installed. One or more files corresponding to each target will
be installed.

Files installed with this signature may be divided into
categories such as ``ARCHIVE``, ``LIBRARY``, or ``RUNTIME``. These
categories are designed to group target files by typical installation
destination. The corresponding keyword arguments are optional, but if
present, specify that other arguments following them apply only to
target files of that type. Target files are categorized as follows:

**executables - ``RUNTIME``**
 Created by :command:`add_executable` (.exe on Windows, no extension on UNIX)

**loadable modules - ``LIBRARY``**
 Created by :command:`add_library` with the ``MODULE`` option (.dll on
 Windows, .so on UNIX)

**shared libraries - ``LIBRARY``**
 Created by :command:`add_library` with the ``SHARED`` option on UNIX-like
 platforms (.so on most UNIX, .dylib on Mac)

**dynamic-link libraries - ``RUNTIME``**
 Created by :command:`add_library` with the ``SHARED`` option on Windows
 platforms (.dll)

**import libraries - ``ARCHIVE``**
 A linkable file created by a dynamic-link library that exports symbols
 (.lib on most Windows, .dll.a on Cygwin and MinGW).

**static libraries - ``ARCHIVE``**
 Created by :command:`add_library` with the ``STATIC`` option (.lib on
 Windows, .a on UNIX, Cygwin, and MinGW)

Consider a project that defines an executable, ``myExecutable``, which
links to a shared library ``mySharedLib``. It also provides a static
library ``myStaticLib`` and a plugin module to the executable called
``myPlugin`` that also links to the shared library. The executable,
static library, and plugin file may be installed individually using
the commands

.. code-block:: cmake

 install(TARGETS myExecutable DESTINATION bin)
 install(TARGETS myStaticLib DESTINATION lib/myproject)
 install(TARGETS myPlugin DESTINATION lib)

The executable will not be able to run from the installed location
until the shared library to it links to is also
installed. Installation of the library requires a bit more care in
order to support all platforms. It must be installed in a location
searched by the dynamic linker on each platform. On UNIX-like
platforms, the library is typically installed to ``lib``, while on
Windows it should be placed next to the executable in ``bin``. An
additional challenge is that the import library associated with the
shared library on Windows should be treated like the static library,
and installed to ``lib/myproject``. In other words, we have three
different kinds of files created with a single target name that must
be installed to three different destinations! Fortunately, this
problem can be solved using the category keyword arguments. The shared
library may be installed using the command:

.. code-block:: cmake

 install(TARGETS mySharedLib
         RUNTIME DESTINATION bin
         LIBRARY DESTINATION lib
         ARCHIVE DESTINATION lib/myproject)

This tells CMake that the ``RUNTIME`` file (.dll) should be installed
to ``bin``, the ``LIBRARY`` file (.so) should be installed to ``lib``,
and the ``ARCHIVE`` (.lib) file should be installed to
``lib/myproject``. On UNIX, the ``LIBRARY`` file will be installed; on
Windows, the ``RUNTIME`` and ``ARCHIVE`` files will be installed.

If the above sample project is to be packaged into separate run time
and development components, we must assign the appropriate component
to each target file installed. The executable, shared library, and
plugin are required in order to run the application, so they belong in
a ``Runtime`` component. Meanwhile, the import library (corresponding
to the shared library on Windows) and the static library are only
required to develop extensions to the application, and therefore
belong in a ``Development`` component.

Component assignments may be specified by adding the ``COMPONENT``
argument to each of the commands above. You may also combine all of
the installation rules into a single command invocation, which is
equivalent to all of the above commands with components added. The
files generated by each target are installed using the rule for their
category.

.. code-block:: cmake

 install(TARGETS myExecutable mySharedLib myStaticLib myPlugin
         RUNTIME DESTINATION bin           COMPONENT Runtime
         LIBRARY DESTINATION lib           COMPONENT Runtime
         ARCHIVE DESTINATION lib/myproject COMPONENT Development)

Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a
``LIBRARY`` option. On some platforms, a versioned shared library has
a symbolic link such as

::

 lib<name>.so -> lib<name>.so.1

where ``lib<name>.so.1`` is the soname of the library, and
``lib<name>.so`` is a "namelink" that helps linkers to find the
library when given ``-l<name>``. The ``NAMELINK_ONLY`` option results
in installation of only the namelink when a library target is
installed. The ``NAMELINK_SKIP`` option causes installation of library
files other than the namelink when a library target is installed. When
neither option is given, both portions are installed. On platforms
where versioned shared libraries do not have namelinks, or when a
library is not versioned, the ``NAMELINK_SKIP`` option installs the
library and the ``NAMELINK_ONLY`` option installs nothing. See the
:prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for details on
creating versioned, shared libraries.

Installing Files
----------------

Projects may install files other than those that are created with
:command:`add_executable` or :command:`add_library`, such as header files or
documentation. General-purpose installation of files is specified
using the ``FILES`` signature.

The ``FILES`` keyword is immediately followed by a list of files to be
installed. Relative paths are evaluated with respect to the current
source directory. Files will be installed to the given ``DESTINATION``
directory. For example, the command

.. code-block:: cmake

 install(FILES my-api.h ${CMAKE_CURRENT_BINARY_DIR}/my-config.h
         DESTINATION include)

installs the file ``my-api.h`` from the source tree, and the file
``my-config.h`` from the build tree into the include directory under
the installation prefix. By default installed files are given the
permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and
``WORLD_READ``, but this may be overridden by specifying the
``PERMISSIONS`` option. Consider cases in which users would want to
install a global configuration file on a UNIX system that is readable
only by its owner (such as root). We accomplish this with the command

.. code-block:: cmake

 install(FILES my-rc DESTINATION /etc
         PERMISSIONS OWNER_WRITE OWNER_READ)

which installs the file ``my-rc`` with owner read/write permission
into the absolute path ``/etc``.

.. index::
   single: file ; rename

The ``RENAME`` argument specifies a name for an installed file that
may be different from the original file. Renaming is allowed only when
a single file is installed by the command. For example, the command

.. code-block:: cmake

 install(FILES version.h DESTINATION include RENAME my-version.h)

will install the file ``version.h`` from the source directory to
``include/my-version.h`` under the installation prefix.

Installing Programs
-------------------

Projects may also install helper programs, such as shell scripts or
Python scripts that are not actually compiled as targets. These may be
installed with the ``FILES`` signature using the ``PERMISSIONS``
option to add execute permission. However, this case is common enough
to justify a simpler interface. CMake provides the ``PROGRAMS``
signature for this purpose.

The ``PROGRAMS`` keyword is immediately followed by a list of scripts
to be installed. This command is identical to the ``FILES`` signature,
except that the default permissions additionally include
``OWNER_EXECUTE``, ``GROUP_EXECUTE``, and ``WORLD_EXECUTE``. For
example, we may install a Python utility script with the command

.. code-block:: cmake

 install(PROGRAMS my-util.py DESTINATION bin)

which installs ``my-util.py`` to the ``bin`` directory under the
installation prefix and gives it owner, group, world read and execute
permissions, plus owner write.

.. index::
   single: directory installation

Installing Directories
----------------------

Projects may also provide an entire directory full of resource files,
such as icons or html documentation. An entire directory may be
installed using the ``DIRECTORY`` signature.

The ``DIRECTORY`` keyword is immediately followed by a list of
directories to be installed. Relative paths are evaluated with respect
to the current source directory. Each named directory is installed to
the destination directory. The last component of each input directory
name is appended to the destination directory as that directory is
copied. For example, the command

.. code-block:: cmake

 install(DIRECTORY data/icons DESTINATION share/myproject)

will install the ``data/icons`` directory from the source tree into
``share/myproject/icons`` under the installation prefix. A trailing
slash will leave the last component empty and install the contents of
the input directory to the destination. The command

.. code-block:: cmake

 install(DIRECTORY doc/html/ DESTINATION doc/myproject)

installs the contents of ``doc/html`` from the source directory into
``doc/myproject`` under the installation prefix. If no input directory
names are given, as in

.. code-block:: cmake

 install(DIRECTORY DESTINATION share/myproject/user)

the destination directory will be created but nothing will be
installed into it.

Files installed by the ``DIRECTORY`` signature are given the same
default permissions as the ``FILES`` signature. Directories installed
by the ``DIRECTORY`` signature are given the same default permissions
as the ``PROGRAMS`` signature. The ``FILE_PERMISSIONS`` and
``DIRECTORY_PERMISSIONS`` options may be used to override these
defaults. Consider a case in which a directory full of example shell
scripts is to be installed into a directory that is both owner and
group writable. We may use the command

.. code-block:: cmake

 install(DIRECTORY data/scripts DESTINATION share/myproject
         FILE_PERMISSIONS
           OWNER_READ OWNER_EXECUTE OWNER_WRITE
           GROUP_READ GROUP_EXECUTE
           WORLD_READ WORLD_EXECUTE
         DIRECTORY_PERMISSIONS
           OWNER_READ OWNER_EXECUTE OWNER_WRITE
           GROUP_READ GROUP_EXECUTE GROUP_WRITE
           WORLD_READ WORLD_EXECUTE
         )

which installs the directory ``data/scripts`` into
``share/myproject/scripts`` and sets the desired permissions. In some
cases, a fully-prepared input directory created by the project may
have the desired permissions already set. The
``USE_SOURCE_PERMISSIONS`` option tells CMake to use the file and
directory permissions from the input directory during installation. If
in the previous example the input directory were to have already been
prepared with correct permissions, the following command may have been
used instead:

.. code-block:: cmake

 install(DIRECTORY data/scripts DESTINATION share/myproject
         USE_SOURCE_PERMISSIONS)

If the input directory to be installed is under source management, there may
be extra subdirectories in the input that you do not wish to install. There
may also be specific files that should not be installed or be installed with
different permissions, while most files get the defaults. The ``PATTERN`` and
``REGEX`` options may be used for this purpose. A ``PATTERN`` option is
followed first by a globbing pattern and then by an ``EXCLUDE`` or
``PERMISSIONS`` option. A ``REGEX`` option is followed first by a regular
expression and then by ``EXCLUDE`` or ``PERMISSIONS``. The ``EXCLUDE`` option
skips installation of those files or directories matching the
preceding pattern or expression, while the ``PERMISSIONS`` option
assigns specific permissions to them.

Each input file and directory is tested against the pattern or regular
expression as a full path with forward slashes. A pattern will match
only complete file or directory names occurring at the end of the full
path, while a regular expression may match any portion. For example,
the pattern ``foo*`` will match ``.../foo.txt`` but not
``.../myfoo.txt`` or ``.../foo/bar.txt;`` however, the regular
expression ``foo`` will match all of them.

Returning to the above example of installing an icons directory,
consider the case in which the input directory is managed by git and
also contains some extra text files that we do not want to
install. The command

.. code-block:: cmake

 install(DIRECTORY data/icons DESTINATION share/myproject
         PATTERN ".git" EXCLUDE
         PATTERN "*.txt" EXCLUDE)

.. index::
   single: file ; regular expressions

installs the icons directory while ignoring any .git directory or text
file contained. The equivalent command using the ``REGEX`` option is

.. code-block:: cmake

 install(DIRECTORY data/icons DESTINATION share/myproject
         REGEX "/.git$" EXCLUDE
         REGEX "/[^/]*.txt$" EXCLUDE)

which uses '/' and '$' to constrain the match in the same way as the
patterns. Consider a similar case in which the input directory
contains shell scripts and text files that we wish to install with
different permissions than the other files. The command

.. code-block:: cmake

 install(DIRECTORY data/other/ DESTINATION share/myproject
         PATTERN ".git" EXCLUDE
         PATTERN "*.txt"
           PERMISSIONS OWNER_READ OWNER_WRITE
         PATTERN "*.sh"
           PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE)

will install the contents of ``data/other`` from the source directory
to ``share/myproject`` while ignoring .git directories and giving
specific permissions to ``.txt`` and ``.sh`` files.

.. index::
   single: installation scripts

Installing Scripts
------------------

Project installations may need to perform tasks other than just
placing files in the installation tree. Third-party packages may
provide their own mechanisms for registering new plugins that must be
invoked during project installation. The ``SCRIPT`` signature is
provided for this purpose.

The ``SCRIPT`` keyword is immediately followed by the name of a CMake
script. CMake will execute the script during installation. If the file
name given is a relative path, it will be evaluated with respect to
the current source directory. A simple use case is printing a message
during installation. We first write a ``message.cmake`` file
containing the code

.. code-block:: cmake

 message("Installing My Project")

and then reference this script using the command:

.. code-block:: cmake

 install(SCRIPT message.cmake)

Custom installation scripts are not executed during the main
CMakeLists file processing; they are executed during the installation
process itself. Variables and macros defined in the code containing
the ``install (SCRIPT)`` call will not be accessible from the
script. However, there are a few variables defined during the script
execution that may be used to get information about the
installation. The variable :variable:`CMAKE_INSTALL_PREFIX` is set to the
actual installation prefix. This may be different from the
corresponding cache variable value, because the installation scripts
may be executed by a packaging tool that uses a different prefix. An
environment variable ``ENV{DESTDIR}`` may be set by the user or
packaging tool. Its value is prepended to the installation prefix and
to absolute installation paths to determine the location where files
are installed. In order to reference an install location on disk,
custom script may use ``$ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}`` as the
top portion of the path. The variable ``CMAKE_INSTALL_CONFIG_NAME`` is
set to the name of the build configuration currently being installed
(Debug, Release, etc.). During component-specific installation, the
variable ``CMAKE_INSTALL_COMPONENT`` is set to the name of the current
component.

Installing Code
---------------

Custom installation scripts, as simple as the message above, are more
easily created with the script code placed inline in the call to the
:command:`install` command. The ``CODE`` signature is provided for this
purpose.

The ``CODE`` keyword is immediately followed by a string containing
the code to place in the installation script. An install-time message
may be created using the command

.. code-block:: cmake

 install(CODE "MESSAGE(\"Installing My Project\")")

which has the same effect as the ``message.cmake`` script but contains
the code inline.

.. index::
   single: libraries ; installing prerequisites

Installing Prerequisite Shared Libraries
----------------------------------------

Executables are frequently built using shared libraries as building
blocks. When you install such an executable, you must also install its
prerequisite shared libraries, called "prerequisites" because the
executable requires their presence in order to load and run
properly. The three main sources of shared libraries are the operating
system itself, the build products of your own project, and third party
libraries belonging to an external project. The ones from the
operating system may be relied upon to be present without installing
anything: they are on the base platform where your executable
runs. The build products in your own project presumably have
:command:`add_library` build rules in the CMakeLists files, and so it should
be straightforward to create CMake install rules for them. It is the
third party libraries that frequently become a high maintenance item
when there are more than a handful of them, or when the set of them
fluctuates from version-to-version of the third party
project. Libraries may be added, code may be reorganized, and the
third party shared libraries themselves may actually have additional
prerequisites that are not obvious at first glance.

.. index::
   single: Mac OS X ; relocatable applications
   single: Windows ; relocatable applications
   single: relocatable packages

CMake provides a module, :module:`BundleUtilities` to make it easier to deal
with required shared libraries. This module provides the ``fixup_bundle``
function to copy and fix prerequisite shared libraries using well-defined
locations relative to the executable. For Mac bundle applications, it embeds
the libraries inside the bundle, fixing them with ``install_name_tool`` to
make a self-contained unit. On Windows, it copies the libraries into
the same directory with the executable since executables will search
in their own directories for their required DLLs.

The ``fixup_bundle`` function helps you create relocatable install
trees. Mac users appreciate self-contained bundle applications: you
can drag them anywhere, double click them, and they still work. They
do not rely on anything being installed in a certain location other
than the operating system itself. Similarly, Windows users without
administrative privileges appreciate a relocatable install tree where
an executable and all required DLLs are installed in the same
directory, so that it works no matter where you install it. You can
even move things around after installing them and it will still work.

To use ``fixup_bundle``, first install one of your executable
targets. Then, configure a CMake script that can be called at install
time. Inside the configured CMake script, simply :command:`include`
:module:`BundleUtilities` and call the ``fixup_bundle`` function with
appropriate arguments.

In CMakeLists.txt

.. index::
   single: command ; configure_file
   single: command ; include
   single: command ; install
   single: command ; set

.. code-block:: cmake

 install(TARGETS myExecutable DESTINATION bin)

 # To install, for example, MSVC runtime libraries:
 include(InstallRequiredSystemLibraries)

 # To install other/non-system 3rd party required libraries:
 configure_file(
   ${CMAKE_CURRENT_SOURCE_DIR}/FixBundle.cmake.in
   ${CMAKE_CURRENT_BINARY_DIR}/FixBundle.cmake
   @ONLY
   )

 install(SCRIPT ${CMAKE_CURRENT_BINARY_DIR}/FixBundle.cmake)

In FixBundle.cmake.in:

.. code-block:: cmake

 include(BundleUtilities)

 # Set bundle to the full path name of the executable already
 # existing in the install tree:
 set(bundle
    "${CMAKE_INSTALL_PREFIX}/myExecutable@CMAKE_EXECUTABLE_SUFFIX@")

 # Set other_libs to a list of full path names to additional
 # libraries that cannot be reached by dependency analysis.
 # (Dynamically loaded PlugIns, for example.)
 set(other_libs "")

 # Set dirs to a list of directories where prerequisite libraries
 # may be found:
 set(dirs
    "@CMAKE_RUNTIME_OUTPUT_DIRECTORY@"
    "@CMAKE_LIBRARY_OUTPUT_DIRECTORY@"
    )

 fixup_bundle("${bundle}" "${other_libs}" "${dirs}")

You are responsible for verifying that you have permission to copy and
distribute the prerequisite shared libraries for your executable. Some
libraries may have restrictive software licenses that prohibit making
copies a la ``fixup_bundle``.
