<!DOCTYPE html> | |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> | |
<head> | |
<meta charset="utf-8" /> | |
<title>install — CMake 3.23.1 Documentation</title> | |
<link rel="stylesheet" href="../_static/cmake.css" type="text/css" /> | |
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> | |
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> | |
<script type="text/javascript" src="../_static/jquery.js"></script> | |
<script type="text/javascript" src="../_static/underscore.js"></script> | |
<script type="text/javascript" src="../_static/doctools.js"></script> | |
<script type="text/javascript" src="../_static/language_data.js"></script> | |
<link rel="shortcut icon" href="../_static/cmake-favicon.ico"/> | |
<link rel="index" title="Index" href="../genindex.html" /> | |
<link rel="search" title="Search" href="../search.html" /> | |
<link rel="next" title="link_directories" href="link_directories.html" /> | |
<link rel="prev" title="include_regular_expression" href="include_regular_expression.html" /> | |
</head><body> | |
<div class="related" role="navigation" aria-label="related navigation"> | |
<h3>Navigation</h3> | |
<ul> | |
<li class="right" style="margin-right: 10px"> | |
<a href="../genindex.html" title="General Index" | |
accesskey="I">index</a></li> | |
<li class="right" > | |
<a href="link_directories.html" title="link_directories" | |
accesskey="N">next</a> |</li> | |
<li class="right" > | |
<a href="include_regular_expression.html" title="include_regular_expression" | |
accesskey="P">previous</a> |</li> | |
<li> | |
<img src="../_static/cmake-logo-16.png" alt="" | |
style="vertical-align: middle; margin-top: -2px" /> | |
</li> | |
<li> | |
<a href="https://cmake.org/">CMake</a> » | |
</li> | |
<li> | |
<a href="../index.html">3.23.1 Documentation</a> » | |
</li> | |
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" accesskey="U">cmake-commands(7)</a> »</li> | |
</ul> | |
</div> | |
<div class="document"> | |
<div class="documentwrapper"> | |
<div class="bodywrapper"> | |
<div class="body" role="main"> | |
<div class="section" id="install"> | |
<span id="command:install"></span><h1>install<a class="headerlink" href="#install" title="Permalink to this headline">¶</a></h1> | |
<p>Specify rules to run at install time.</p> | |
<div class="section" id="synopsis"> | |
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> | |
<pre class="literal-block">install(<a class="reference internal" href="#targets">TARGETS</a> <target>... [...]) | |
install(<a class="reference internal" href="#imported-runtime-artifacts">IMPORTED_RUNTIME_ARTIFACTS</a> <target>... [...]) | |
install({<a class="reference internal" href="#files">FILES</a> | <a class="reference internal" href="#programs">PROGRAMS</a>} <file>... [...]) | |
install(<a class="reference internal" href="#directory">DIRECTORY</a> <dir>... [...]) | |
install(<a class="reference internal" href="#script">SCRIPT</a> <file> [...]) | |
install(<a class="reference internal" href="#code">CODE</a> <code> [...]) | |
install(<a class="reference internal" href="#export">EXPORT</a> <export-name> [...]) | |
install(<a class="reference internal" href="#runtime-dependency-set">RUNTIME_DEPENDENCY_SET</a> <set-name> [...])</pre> | |
</div> | |
<div class="section" id="introduction"> | |
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> | |
<p>This command generates installation rules for a project. Install rules | |
specified by calls to the <code class="docutils literal notranslate"><span class="pre">install()</span></code> command within a source directory | |
are executed in order during installation.</p> | |
<div class="versionchanged"> | |
<p><span class="versionmodified changed">Changed in version 3.14: </span>Install rules in subdirectories | |
added by calls to the <span class="target" id="index-0-command:add_subdirectory"></span><a class="reference internal" href="add_subdirectory.html#command:add_subdirectory" title="add_subdirectory"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">add_subdirectory()</span></code></a> command are interleaved | |
with those in the parent directory to run in the order declared (see | |
policy <span class="target" id="index-0-policy:CMP0082"></span><a class="reference internal" href="../policy/CMP0082.html#policy:CMP0082" title="CMP0082"><code class="xref cmake cmake-policy docutils literal notranslate"><span class="pre">CMP0082</span></code></a>).</p> | |
</div> | |
<div class="versionchanged"> | |
<p><span class="versionmodified changed">Changed in version 3.22: </span>The environment variable <span class="target" id="index-0-envvar:CMAKE_INSTALL_MODE"></span><a class="reference internal" href="../envvar/CMAKE_INSTALL_MODE.html#envvar:CMAKE_INSTALL_MODE" title="CMAKE_INSTALL_MODE"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">CMAKE_INSTALL_MODE</span></code></a> can override the | |
default copying behavior of <span class="target" id="index-0-command:install"></span><a class="reference internal" href="#command:install" title="install"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install()</span></code></a>.</p> | |
</div> | |
<p>There are multiple signatures for this command. Some of them define | |
installation options for files and targets. Options common to | |
multiple signatures are covered here but they are valid only for | |
signatures that specify them. The common options are:</p> | |
<dl> | |
<dt><code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code></dt><dd><p>Specify the directory on disk to which a file will be installed. | |
Arguments can be relative or absolute paths.</p> | |
<p>If a relative path is given it is interpreted relative to the value | |
of the <span class="target" id="index-0-variable:CMAKE_INSTALL_PREFIX"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_PREFIX.html#variable:CMAKE_INSTALL_PREFIX" title="CMAKE_INSTALL_PREFIX"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code></a> variable. | |
The prefix can be relocated at install time using the <code class="docutils literal notranslate"><span class="pre">DESTDIR</span></code> | |
mechanism explained in the <span class="target" id="index-1-variable:CMAKE_INSTALL_PREFIX"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_PREFIX.html#variable:CMAKE_INSTALL_PREFIX" title="CMAKE_INSTALL_PREFIX"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code></a> variable | |
documentation.</p> | |
<p>If an absolute path (with a leading slash or drive letter) is given | |
it is used verbatim.</p> | |
<p>As absolute paths are not supported by <span class="target" id="index-0-manual:cpack(1)"></span><a class="reference internal" href="../manual/cpack.1.html#manual:cpack(1)" title="cpack(1)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cpack</span></code></a> installer | |
generators, it is preferable to use relative paths throughout. | |
In particular, there is no need to make paths absolute by prepending | |
<span class="target" id="index-2-variable:CMAKE_INSTALL_PREFIX"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_PREFIX.html#variable:CMAKE_INSTALL_PREFIX" title="CMAKE_INSTALL_PREFIX"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code></a>; this prefix is used by default if | |
the DESTINATION is a relative path.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">PERMISSIONS</span></code></dt><dd><p>Specify permissions for installed files. Valid permissions are | |
<code class="docutils literal notranslate"><span class="pre">OWNER_READ</span></code>, <code class="docutils literal notranslate"><span class="pre">OWNER_WRITE</span></code>, <code class="docutils literal notranslate"><span class="pre">OWNER_EXECUTE</span></code>, <code class="docutils literal notranslate"><span class="pre">GROUP_READ</span></code>, | |
<code class="docutils literal notranslate"><span class="pre">GROUP_WRITE</span></code>, <code class="docutils literal notranslate"><span class="pre">GROUP_EXECUTE</span></code>, <code class="docutils literal notranslate"><span class="pre">WORLD_READ</span></code>, <code class="docutils literal notranslate"><span class="pre">WORLD_WRITE</span></code>, | |
<code class="docutils literal notranslate"><span class="pre">WORLD_EXECUTE</span></code>, <code class="docutils literal notranslate"><span class="pre">SETUID</span></code>, and <code class="docutils literal notranslate"><span class="pre">SETGID</span></code>. Permissions that do | |
not make sense on certain platforms are ignored on those platforms.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">CONFIGURATIONS</span></code></dt><dd><p>Specify a list of build configurations for which the install rule | |
applies (Debug, Release, etc.). Note that the values specified for | |
this option only apply to options listed AFTER the <code class="docutils literal notranslate"><span class="pre">CONFIGURATIONS</span></code> | |
option. For example, to set separate install paths for the Debug and | |
Release configurations, do the following:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">target</span><span class="w"></span> | |
<span class="w"> </span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="nb">Debug</span><span class="w"></span> | |
<span class="w"> </span><span class="no">RUNTIME</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">Debug/bin</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">target</span><span class="w"></span> | |
<span class="w"> </span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="nb">Release</span><span class="w"></span> | |
<span class="w"> </span><span class="no">RUNTIME</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">Release/bin</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>Note that <code class="docutils literal notranslate"><span class="pre">CONFIGURATIONS</span></code> appears BEFORE <code class="docutils literal notranslate"><span class="pre">RUNTIME</span> <span class="pre">DESTINATION</span></code>.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code></dt><dd><p>Specify an installation component name with which the install rule | |
is associated, such as "runtime" or "development". During | |
component-specific installation only install rules associated with | |
the given component name will be executed. During a full installation | |
all components are installed unless marked with <code class="docutils literal notranslate"><span class="pre">EXCLUDE_FROM_ALL</span></code>. | |
If <code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> is not provided a default component "Unspecified" is | |
created. The default component name may be controlled with the | |
<span class="target" id="index-0-variable:CMAKE_INSTALL_DEFAULT_COMPONENT_NAME"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.html#variable:CMAKE_INSTALL_DEFAULT_COMPONENT_NAME" title="CMAKE_INSTALL_DEFAULT_COMPONENT_NAME"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_DEFAULT_COMPONENT_NAME</span></code></a> variable.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">EXCLUDE_FROM_ALL</span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.6.</span></p> | |
</div> | |
<p>Specify that the file is excluded from a full installation and only | |
installed as part of a component-specific installation</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">RENAME</span></code></dt><dd><p>Specify 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.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">OPTIONAL</span></code></dt><dd><p>Specify that it is not an error if the file to be installed does | |
not exist.</p> | |
</dd> | |
</dl> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.1: </span>Command signatures that install files may print messages during | |
installation. Use the <span class="target" id="index-0-variable:CMAKE_INSTALL_MESSAGE"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_MESSAGE.html#variable:CMAKE_INSTALL_MESSAGE" title="CMAKE_INSTALL_MESSAGE"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_MESSAGE</span></code></a> variable | |
to control which messages are printed.</p> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.11: </span>Many of the <code class="docutils literal notranslate"><span class="pre">install()</span></code> variants implicitly create the directories | |
containing the installed files. If | |
<span class="target" id="index-0-variable:CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS"></span><a class="reference internal" href="../variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.html#variable:CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS" title="CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS</span></code></a> is set, these | |
directories will be created with the permissions specified. Otherwise, | |
they will be created according to the uname rules on Unix-like platforms. | |
Windows platforms are unaffected.</p> | |
</div> | |
</div> | |
<div class="section" id="installing-targets"> | |
<h2>Installing Targets<a class="headerlink" href="#installing-targets" title="Permalink to this headline">¶</a></h2> | |
<div class="highlight-cmake notranslate" id="targets"><span id="install-targets"></span><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">targets...</span><span class="w"> </span><span class="p">[</span><span class="no">EXPORT</span><span class="w"> </span><span class="nv"><export-name></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">RUNTIME_DEPENDENCIES</span><span class="w"> </span><span class="nb">args...</span><span class="p">|</span><span class="no">RUNTIME_DEPENDENCY_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[[</span><span class="no">ARCHIVE</span><span class="p">|</span><span class="no">LIBRARY</span><span class="p">|</span><span class="no">RUNTIME</span><span class="p">|</span><span class="no">OBJECTS</span><span class="p">|</span><span class="no">FRAMEWORK</span><span class="p">|</span><span class="no">BUNDLE</span><span class="p">|</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PRIVATE_HEADER</span><span class="p">|</span><span class="no">PUBLIC_HEADER</span><span class="p">|</span><span class="no">RESOURCE</span><span class="p">|</span><span class="no">FILE_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">NAMELINK_COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">OPTIONAL</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">NAMELINK_ONLY</span><span class="p">|</span><span class="no">NAMELINK_SKIP</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">[...]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">INCLUDES</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="p">[</span><span class="nv"><dir></span><span class="w"> </span><span class="p">...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">TARGETS</span></code> form specifies rules for installing targets from a | |
project. There are several kinds of target <a class="reference internal" href="../manual/cmake-buildsystem.7.html#output-artifacts"><span class="std std-ref">Output Artifacts</span></a> | |
that may be installed:</p> | |
<dl> | |
<dt><code class="docutils literal notranslate"><span class="pre">ARCHIVE</span></code></dt><dd><p>Target artifacts of this kind include:</p> | |
<ul class="simple"> | |
<li><p><em>Static libraries</em> | |
(except on macOS when marked as <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code>, see below);</p></li> | |
<li><p><em>DLL import libraries</em> | |
(on all Windows-based systems including Cygwin; they have extension | |
<code class="docutils literal notranslate"><span class="pre">.lib</span></code>, in contrast to the <code class="docutils literal notranslate"><span class="pre">.dll</span></code> libraries that go to <code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code>);</p></li> | |
<li><p>On AIX, the <em>linker import file</em> created for executables with | |
<span class="target" id="index-0-prop_tgt:ENABLE_EXPORTS"></span><a class="reference internal" href="../prop_tgt/ENABLE_EXPORTS.html#prop_tgt:ENABLE_EXPORTS" title="ENABLE_EXPORTS"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">ENABLE_EXPORTS</span></code></a> enabled.</p></li> | |
</ul> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code></dt><dd><p>Target artifacts of this kind include:</p> | |
<ul class="simple"> | |
<li><p><em>Shared libraries</em>, except</p> | |
<ul> | |
<li><p>DLLs (these go to <code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code>, see below),</p></li> | |
<li><p>on macOS when marked as <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code> (see below).</p></li> | |
</ul> | |
</li> | |
</ul> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code></dt><dd><p>Target artifacts of this kind include:</p> | |
<ul class="simple"> | |
<li><p><em>Executables</em> | |
(except on macOS when marked as <code class="docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code>, see <code class="docutils literal notranslate"><span class="pre">BUNDLE</span></code> below);</p></li> | |
<li><p>DLLs (on all Windows-based systems including Cygwin; note that the | |
accompanying import libraries are of kind <code class="docutils literal notranslate"><span class="pre">ARCHIVE</span></code>).</p></li> | |
</ul> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">OBJECTS</span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.9.</span></p> | |
</div> | |
<p>Object files associated with <em>object libraries</em>.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code></dt><dd><p>Both static and shared libraries marked with the <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code> | |
property are treated as <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code> targets on macOS.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">BUNDLE</span></code></dt><dd><p>Executables marked with the <span class="target" id="index-0-prop_tgt:MACOSX_BUNDLE"></span><a class="reference internal" href="../prop_tgt/MACOSX_BUNDLE.html#prop_tgt:MACOSX_BUNDLE" title="MACOSX_BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code></a> property are treated as | |
<code class="docutils literal notranslate"><span class="pre">BUNDLE</span></code> targets on macOS.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code></dt><dd><p>Any <span class="target" id="index-0-prop_tgt:PUBLIC_HEADER"></span><a class="reference internal" href="../prop_tgt/PUBLIC_HEADER.html#prop_tgt:PUBLIC_HEADER" title="PUBLIC_HEADER"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code></a> files associated with a library are installed in | |
the destination specified by the <code class="docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code> argument on non-Apple | |
platforms. Rules defined by this argument are ignored for <span class="target" id="index-0-prop_tgt:FRAMEWORK"></span><a class="reference internal" href="../prop_tgt/FRAMEWORK.html#prop_tgt:FRAMEWORK" title="FRAMEWORK"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">FRAMEWORK</span></code></a> | |
libraries on Apple platforms because the associated files are installed | |
into the appropriate locations inside the framework folder. See | |
<span class="target" id="index-1-prop_tgt:PUBLIC_HEADER"></span><a class="reference internal" href="../prop_tgt/PUBLIC_HEADER.html#prop_tgt:PUBLIC_HEADER" title="PUBLIC_HEADER"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code></a> for details.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code></dt><dd><p>Similar to <code class="docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code>, but for <code class="docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code> files. See | |
<span class="target" id="index-0-prop_tgt:PRIVATE_HEADER"></span><a class="reference internal" href="../prop_tgt/PRIVATE_HEADER.html#prop_tgt:PRIVATE_HEADER" title="PRIVATE_HEADER"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code></a> for details.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">RESOURCE</span></code></dt><dd><p>Similar to <code class="docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code> and <code class="docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code>, but for | |
<code class="docutils literal notranslate"><span class="pre">RESOURCE</span></code> files. See <span class="target" id="index-0-prop_tgt:RESOURCE"></span><a class="reference internal" href="../prop_tgt/RESOURCE.html#prop_tgt:RESOURCE" title="RESOURCE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">RESOURCE</span></code></a> for details.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">FILE_SET</span> <span class="pre"><set></span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.23.</span></p> | |
</div> | |
<p>File sets are defined by the <span class="target" id="index-0-command:target_sources"></span><a class="reference internal" href="target_sources.html#command:target_sources" title="target_sources"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">target_sources(FILE_SET)</span></code></a> command. | |
If the file set <code class="docutils literal notranslate"><span class="pre"><set></span></code> exists and is <code class="docutils literal notranslate"><span class="pre">PUBLIC</span></code> or <code class="docutils literal notranslate"><span class="pre">INTERFACE</span></code>, any | |
files in the set are installed under the destination (see below). | |
The directory structure relative to the file set's base directories is | |
preserved. For example, a file added to the file set as | |
<code class="docutils literal notranslate"><span class="pre">/blah/include/myproj/here.h</span></code> with a base directory <code class="docutils literal notranslate"><span class="pre">/blah/include</span></code> | |
would be installed to <code class="docutils literal notranslate"><span class="pre">myproj/here.h</span></code> below the destination.</p> | |
</dd> | |
</dl> | |
<p>For each of these arguments given, the arguments following them only apply | |
to the target or file type specified in the argument. If none is given, the | |
installation properties apply to all target types. If only one is given then | |
only targets of that type will be installed (which can be used to install | |
just a DLL or just an import library.)</p> | |
<p>For regular executables, static libraries and shared libraries, the | |
<code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument is not required. For these target types, when | |
<code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> is omitted, a default destination will be taken from the | |
appropriate variable from <span class="target" id="index-0-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a>, or set to a built-in | |
default value if that variable is not defined. The same is true for file | |
sets, and the public and private headers associated with the installed | |
targets through the <span class="target" id="index-2-prop_tgt:PUBLIC_HEADER"></span><a class="reference internal" href="../prop_tgt/PUBLIC_HEADER.html#prop_tgt:PUBLIC_HEADER" title="PUBLIC_HEADER"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code></a> and <span class="target" id="index-1-prop_tgt:PRIVATE_HEADER"></span><a class="reference internal" href="../prop_tgt/PRIVATE_HEADER.html#prop_tgt:PRIVATE_HEADER" title="PRIVATE_HEADER"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code></a> | |
target properties. A destination must always be provided for module libraries, | |
Apple bundles and frameworks. A destination can be omitted for interface and | |
object libraries, but they are handled differently (see the discussion of this | |
topic toward the end of this section).</p> | |
<p>The following table shows the target types with their associated variables and | |
built-in defaults that apply when no destination is given:</p> | |
<table class="docutils align-default"> | |
<colgroup> | |
<col style="width: 37%" /> | |
<col style="width: 37%" /> | |
<col style="width: 26%" /> | |
</colgroup> | |
<thead> | |
<tr class="row-odd"><th class="head"><p>Target Type</p></th> | |
<th class="head"><p>GNUInstallDirs Variable</p></th> | |
<th class="head"><p>Built-In Default</p></th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_BINDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">bin</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LIBDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">lib</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ARCHIVE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LIBDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">lib</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">PRIVATE_HEADER</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INCLUDEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">include</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">PUBLIC_HEADER</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INCLUDEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">include</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">FILE_SET</span></code> (type <code class="docutils literal notranslate"><span class="pre">HEADERS</span></code>)</p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INCLUDEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">include</span></code></p></td> | |
</tr> | |
</tbody> | |
</table> | |
<p>Projects wishing to follow the common practice of installing headers into a | |
project-specific subdirectory may prefer using file sets with appropriate | |
paths and base directories. Otherwise, they must provide a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> | |
instead of being able to rely on the above (see next example below).</p> | |
<p>To make packages compliant with distribution filesystem layout policies, if | |
projects must specify a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code>, it is recommended that they use a | |
path that begins with the appropriate <span class="target" id="index-1-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a> variable. | |
This allows package maintainers to control the install destination by setting | |
the appropriate cache variables. The following example shows a static library | |
being installed to the default destination provided by | |
<span class="target" id="index-2-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a>, but with its headers installed to a project-specific | |
subdirectory without using file sets:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">add_library(</span><span class="nb">mylib</span><span class="w"> </span><span class="no">STATIC</span><span class="w"> </span><span class="p">...</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set_target_properties(</span><span class="nb">mylib</span><span class="w"> </span><span class="no">PROPERTIES</span><span class="w"> </span><span class="no">PUBLIC_HEADER</span><span class="w"> </span><span class="nb">mylib.h</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">include(</span><span class="nb">GNUInstallDirs</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">mylib</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PUBLIC_HEADER</span><span class="w"></span> | |
<span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="o">${</span><span class="nt">CMAKE_INSTALL_INCLUDEDIR</span><span class="o">}</span><span class="na">/myproj</span><span class="w"></span> | |
<span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>In addition to the common options listed above, each target can accept | |
the following additional arguments:</p> | |
<dl> | |
<dt><code class="docutils literal notranslate"><span class="pre">NAMELINK_COMPONENT</span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.12.</span></p> | |
</div> | |
<p>On some platforms a versioned shared library has a symbolic link such | |
as:</p> | |
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>lib<name>.so -> lib<name>.so.1 | |
</pre></div> | |
</div> | |
<p>where <code class="docutils literal notranslate"><span class="pre">lib<name>.so.1</span></code> is the soname of the library and <code class="docutils literal notranslate"><span class="pre">lib<name>.so</span></code> | |
is a "namelink" allowing linkers to find the library when given | |
<code class="docutils literal notranslate"><span class="pre">-l<name></span></code>. The <code class="docutils literal notranslate"><span class="pre">NAMELINK_COMPONENT</span></code> option is similar to the | |
<code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> option, but it changes the installation component of a shared | |
library namelink if one is generated. If not specified, this defaults to the | |
value of <code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code>. It is an error to use this parameter outside of a | |
<code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code> block.</p> | |
<p>Consider the following example:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">mylib</span><span class="w"></span> | |
<span class="w"> </span><span class="no">LIBRARY</span><span class="w"></span> | |
<span class="w"> </span><span class="no">COMPONENT</span><span class="w"> </span><span class="nb">Libraries</span><span class="w"></span> | |
<span class="w"> </span><span class="no">NAMELINK_COMPONENT</span><span class="w"> </span><span class="nb">Development</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PUBLIC_HEADER</span><span class="w"></span> | |
<span class="w"> </span><span class="no">COMPONENT</span><span class="w"> </span><span class="nb">Development</span><span class="w"></span> | |
<span class="w"> </span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>In this scenario, if you choose to install only the <code class="docutils literal notranslate"><span class="pre">Development</span></code> | |
component, both the headers and namelink will be installed without the | |
library. (If you don't also install the <code class="docutils literal notranslate"><span class="pre">Libraries</span></code> component, the | |
namelink will be a dangling symlink, and projects that link to the library | |
will have build errors.) If you install only the <code class="docutils literal notranslate"><span class="pre">Libraries</span></code> component, | |
only the library will be installed, without the headers and namelink.</p> | |
<p>This option is typically used for package managers that have separate | |
runtime and development packages. For example, on Debian systems, the | |
library is expected to be in the runtime package, and the headers and | |
namelink are expected to be in the development package.</p> | |
<p>See the <span class="target" id="index-0-prop_tgt:VERSION"></span><a class="reference internal" href="../prop_tgt/VERSION.html#prop_tgt:VERSION" title="VERSION"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">VERSION</span></code></a> and <span class="target" id="index-0-prop_tgt:SOVERSION"></span><a class="reference internal" href="../prop_tgt/SOVERSION.html#prop_tgt:SOVERSION" title="SOVERSION"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">SOVERSION</span></code></a> target properties for | |
details on creating versioned shared libraries.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">NAMELINK_ONLY</span></code></dt><dd><p>This option causes the installation of only the namelink when a library | |
target is installed. On platforms where versioned shared libraries do not | |
have namelinks or when a library is not versioned, the <code class="docutils literal notranslate"><span class="pre">NAMELINK_ONLY</span></code> | |
option installs nothing. It is an error to use this parameter outside of a | |
<code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code> block.</p> | |
<p>When <code class="docutils literal notranslate"><span class="pre">NAMELINK_ONLY</span></code> is given, either <code class="docutils literal notranslate"><span class="pre">NAMELINK_COMPONENT</span></code> or | |
<code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> may be used to specify the installation component of the | |
namelink, but <code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> should generally be preferred.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">NAMELINK_SKIP</span></code></dt><dd><p>Similar to <code class="docutils literal notranslate"><span class="pre">NAMELINK_ONLY</span></code>, but it has the opposite effect: it causes the | |
installation of library files other than the namelink when a library target | |
is installed. When neither <code class="docutils literal notranslate"><span class="pre">NAMELINK_ONLY</span></code> or <code class="docutils literal notranslate"><span class="pre">NAMELINK_SKIP</span></code> are given, | |
both portions are installed. On platforms where versioned shared libraries | |
do not have symlinks or when a library is not versioned, <code class="docutils literal notranslate"><span class="pre">NAMELINK_SKIP</span></code> | |
installs the library. It is an error to use this parameter outside of a | |
<code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code> block.</p> | |
<p>If <code class="docutils literal notranslate"><span class="pre">NAMELINK_SKIP</span></code> is specified, <code class="docutils literal notranslate"><span class="pre">NAMELINK_COMPONENT</span></code> has no effect. It | |
is not recommended to use <code class="docutils literal notranslate"><span class="pre">NAMELINK_SKIP</span></code> in conjunction with | |
<code class="docutils literal notranslate"><span class="pre">NAMELINK_COMPONENT</span></code>.</p> | |
</dd> | |
</dl> | |
<p>The <a class="reference internal" href="#install-targets">install(TARGETS)</a> command can also accept the following options at the | |
top level:</p> | |
<dl> | |
<dt><code class="docutils literal notranslate"><span class="pre">EXPORT</span></code></dt><dd><p>This option associates the installed target files with an export called | |
<code class="docutils literal notranslate"><span class="pre"><export-name></span></code>. It must appear before any target options. To actually | |
install the export file itself, call <a class="reference internal" href="#install-export">install(EXPORT)</a>, documented below. | |
See documentation of the <span class="target" id="index-0-prop_tgt:EXPORT_NAME"></span><a class="reference internal" href="../prop_tgt/EXPORT_NAME.html#prop_tgt:EXPORT_NAME" title="EXPORT_NAME"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">EXPORT_NAME</span></code></a> target property to change | |
the name of the exported target.</p> | |
<p>If <code class="docutils literal notranslate"><span class="pre">EXPORT</span></code> is used and the targets include <code class="docutils literal notranslate"><span class="pre">PUBLIC</span></code> or <code class="docutils literal notranslate"><span class="pre">INTERFACE</span></code> | |
file sets, all of them must be specified with <code class="docutils literal notranslate"><span class="pre">FILE_SET</span></code> arguments. All | |
<code class="docutils literal notranslate"><span class="pre">PUBLIC</span></code> or <code class="docutils literal notranslate"><span class="pre">INTERFACE</span></code> file sets associated with a target are included | |
in the export.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">INCLUDES</span> <span class="pre">DESTINATION</span></code></dt><dd><p>This option specifies a list of directories which will be added to the | |
<span class="target" id="index-0-prop_tgt:INTERFACE_INCLUDE_DIRECTORIES"></span><a class="reference internal" href="../prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html#prop_tgt:INTERFACE_INCLUDE_DIRECTORIES" title="INTERFACE_INCLUDE_DIRECTORIES"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">INTERFACE_INCLUDE_DIRECTORIES</span></code></a> target property of the | |
<code class="docutils literal notranslate"><span class="pre"><targets></span></code> when exported by the <a class="reference internal" href="#install-export">install(EXPORT)</a> command. If a | |
relative path is specified, it is treated as relative to the | |
<code class="docutils literal notranslate"><span class="pre">$<INSTALL_PREFIX></span></code>.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCY_SET</span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.21.</span></p> | |
</div> | |
<p>This option causes all runtime dependencies of installed executable, shared | |
library, and module targets to be added to the specified runtime dependency | |
set. This set can then be installed with an | |
<a class="reference internal" href="#install-runtime-dependency-set">install(RUNTIME_DEPENDENCY_SET)</a> command.</p> | |
<p>This keyword and the <code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCIES</span></code> keyword are mutually | |
exclusive.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCIES</span></code></dt><dd><div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.21.</span></p> | |
</div> | |
<p>This option causes all runtime dependencies of installed executable, shared | |
library, and module targets to be installed along with the targets | |
themselves. The <code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code>, <code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code>, <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code>, and generic | |
arguments are used to determine the properties (<code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code>, | |
<code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code>, etc.) of the installation of these dependencies.</p> | |
<p><code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCIES</span></code> is semantically equivalent to the following pair | |
of calls:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="no">RUNTIME_DEPENDENCY_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">RUNTIME_DEPENDENCY_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="w"> </span><span class="nb">args...</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>where <code class="docutils literal notranslate"><span class="pre"><set-name></span></code> will be a randomly generated set name. | |
The <code class="docutils literal notranslate"><span class="pre">args...</span></code> may include any of the following keywords supported by | |
the <a class="reference internal" href="#install-runtime-dependency-set">install(RUNTIME_DEPENDENCY_SET)</a> command:</p> | |
<ul class="simple"> | |
<li><p><code class="docutils literal notranslate"><span class="pre">DIRECTORIES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">PRE_INCLUDE_REGEXES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">PRE_EXCLUDE_REGEXES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_INCLUDE_REGEXES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_EXCLUDE_REGEXES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_INCLUDE_FILES</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_EXCLUDE_FILES</span></code></p></li> | |
</ul> | |
<p>The <code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCIES</span></code> and <code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCY_SET</span></code> keywords are | |
mutually exclusive.</p> | |
</dd> | |
</dl> | |
<p>One or more groups of properties may be specified in a single call to | |
the <code class="docutils literal notranslate"><span class="pre">TARGETS</span></code> form of this command. A target may be installed more than | |
once to different locations. Consider hypothetical targets <code class="docutils literal notranslate"><span class="pre">myExe</span></code>, | |
<code class="docutils literal notranslate"><span class="pre">mySharedLib</span></code>, and <code class="docutils literal notranslate"><span class="pre">myStaticLib</span></code>. The code:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">myExe</span><span class="w"> </span><span class="nb">mySharedLib</span><span class="w"> </span><span class="nb">myStaticLib</span><span class="w"></span> | |
<span class="w"> </span><span class="no">RUNTIME</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nb">bin</span><span class="w"></span> | |
<span class="w"> </span><span class="no">LIBRARY</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nb">lib</span><span class="w"></span> | |
<span class="w"> </span><span class="no">ARCHIVE</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">lib/static</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">mySharedLib</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">/some/full/path</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>will install <code class="docutils literal notranslate"><span class="pre">myExe</span></code> to <code class="docutils literal notranslate"><span class="pre"><prefix>/bin</span></code> and <code class="docutils literal notranslate"><span class="pre">myStaticLib</span></code> to | |
<code class="docutils literal notranslate"><span class="pre"><prefix>/lib/static</span></code>. On non-DLL platforms <code class="docutils literal notranslate"><span class="pre">mySharedLib</span></code> will be | |
installed to <code class="docutils literal notranslate"><span class="pre"><prefix>/lib</span></code> and <code class="docutils literal notranslate"><span class="pre">/some/full/path</span></code>. On DLL platforms | |
the <code class="docutils literal notranslate"><span class="pre">mySharedLib</span></code> DLL will be installed to <code class="docutils literal notranslate"><span class="pre"><prefix>/bin</span></code> and | |
<code class="docutils literal notranslate"><span class="pre">/some/full/path</span></code> and its import library will be installed to | |
<code class="docutils literal notranslate"><span class="pre"><prefix>/lib/static</span></code> and <code class="docutils literal notranslate"><span class="pre">/some/full/path</span></code>.</p> | |
<p><a class="reference internal" href="../manual/cmake-buildsystem.7.html#interface-libraries"><span class="std std-ref">Interface Libraries</span></a> may be listed among the targets to install. | |
They install no artifacts but will be included in an associated <code class="docutils literal notranslate"><span class="pre">EXPORT</span></code>. | |
If <a class="reference internal" href="../manual/cmake-buildsystem.7.html#object-libraries"><span class="std std-ref">Object Libraries</span></a> are listed but given no destination for their | |
object files, they will be exported as <a class="reference internal" href="../manual/cmake-buildsystem.7.html#interface-libraries"><span class="std std-ref">Interface Libraries</span></a>. | |
This is sufficient to satisfy transitive usage requirements of other | |
targets that link to the object libraries in their implementation.</p> | |
<p>Installing a target with the <span class="target" id="index-0-prop_tgt:EXCLUDE_FROM_ALL"></span><a class="reference internal" href="../prop_tgt/EXCLUDE_FROM_ALL.html#prop_tgt:EXCLUDE_FROM_ALL" title="EXCLUDE_FROM_ALL"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">EXCLUDE_FROM_ALL</span></code></a> target property | |
set to <code class="docutils literal notranslate"><span class="pre">TRUE</span></code> has undefined behavior.</p> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.3: </span>An install destination given as a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument may | |
use "generator expressions" with the syntax <code class="docutils literal notranslate"><span class="pre">$<...></span></code>. See the | |
<span class="target" id="index-0-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions.</p> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.13: </span><a class="reference internal" href="#install-targets">install(TARGETS)</a> can install targets that were created in | |
other directories. When using such cross-directory install rules, running | |
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code> (or similar) from a subdirectory will not guarantee that | |
targets from other directories are up-to-date. You can use | |
<span class="target" id="index-0-command:target_link_libraries"></span><a class="reference internal" href="target_link_libraries.html#command:target_link_libraries" title="target_link_libraries"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">target_link_libraries()</span></code></a> or <span class="target" id="index-0-command:add_dependencies"></span><a class="reference internal" href="add_dependencies.html#command:add_dependencies" title="add_dependencies"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">add_dependencies()</span></code></a> | |
to ensure that such out-of-directory targets are built before the | |
subdirectory-specific install rules are run.</p> | |
</div> | |
</div> | |
<div class="section" id="installing-imported-runtime-artifacts"> | |
<h2>Installing Imported Runtime Artifacts<a class="headerlink" href="#installing-imported-runtime-artifacts" title="Permalink to this headline">¶</a></h2> | |
<div class="versionadded" id="imported-runtime-artifacts"> | |
<span id="install-imported-runtime-artifacts"></span><p><span class="versionmodified added">New in version 3.21.</span></p> | |
</div> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">IMPORTED_RUNTIME_ARTIFACTS</span><span class="w"> </span><span class="nb">targets...</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">RUNTIME_DEPENDENCY_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[[</span><span class="no">LIBRARY</span><span class="p">|</span><span class="no">RUNTIME</span><span class="p">|</span><span class="no">FRAMEWORK</span><span class="p">|</span><span class="no">BUNDLE</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">OPTIONAL</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">[...]</span><span class="w"></span> | |
<span class="w"> </span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">IMPORTED_RUNTIME_ARTIFACTS</span></code> form specifies rules for installing the | |
runtime artifacts of imported targets. Projects may do this if they want to | |
bundle outside executables or modules inside their installation. The | |
<code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code>, <code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code>, <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code>, and <code class="docutils literal notranslate"><span class="pre">BUNDLE</span></code> arguments have the | |
same semantics that they do in the <a class="reference internal" href="#targets">TARGETS</a> mode. Only the runtime artifacts | |
of imported targets are installed (except in the case of <span class="target" id="index-1-prop_tgt:FRAMEWORK"></span><a class="reference internal" href="../prop_tgt/FRAMEWORK.html#prop_tgt:FRAMEWORK" title="FRAMEWORK"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">FRAMEWORK</span></code></a> | |
libraries, <span class="target" id="index-1-prop_tgt:MACOSX_BUNDLE"></span><a class="reference internal" href="../prop_tgt/MACOSX_BUNDLE.html#prop_tgt:MACOSX_BUNDLE" title="MACOSX_BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code></a> executables, and <span class="target" id="index-0-prop_tgt:BUNDLE"></span><a class="reference internal" href="../prop_tgt/BUNDLE.html#prop_tgt:BUNDLE" title="BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">BUNDLE</span></code></a> | |
CFBundles.) For example, headers and import libraries associated with DLLs are | |
not installed. In the case of <span class="target" id="index-2-prop_tgt:FRAMEWORK"></span><a class="reference internal" href="../prop_tgt/FRAMEWORK.html#prop_tgt:FRAMEWORK" title="FRAMEWORK"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">FRAMEWORK</span></code></a> libraries, | |
<span class="target" id="index-2-prop_tgt:MACOSX_BUNDLE"></span><a class="reference internal" href="../prop_tgt/MACOSX_BUNDLE.html#prop_tgt:MACOSX_BUNDLE" title="MACOSX_BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code></a> executables, and <span class="target" id="index-1-prop_tgt:BUNDLE"></span><a class="reference internal" href="../prop_tgt/BUNDLE.html#prop_tgt:BUNDLE" title="BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">BUNDLE</span></code></a> CFBundles, the | |
entire directory is installed.</p> | |
<p>The <code class="docutils literal notranslate"><span class="pre">RUNTIME_DEPENDENCY_SET</span></code> option causes the runtime artifacts of the | |
imported executable, shared library, and module library <code class="docutils literal notranslate"><span class="pre">targets</span></code> to be | |
added to the <code class="docutils literal notranslate"><span class="pre"><set-name></span></code> runtime dependency set. This set can then be | |
installed with an <a class="reference internal" href="#install-runtime-dependency-set">install(RUNTIME_DEPENDENCY_SET)</a> command.</p> | |
</div> | |
<div class="section" id="installing-files"> | |
<h2>Installing Files<a class="headerlink" href="#installing-files" title="Permalink to this headline">¶</a></h2> | |
<div class="admonition note" id="programs"> | |
<span id="files"></span><span id="install-programs"></span><span id="install-files"></span><p class="admonition-title">Note</p> | |
<p>If installing header files, consider using file sets defined by | |
<span class="target" id="index-1-command:target_sources"></span><a class="reference internal" href="target_sources.html#command:target_sources" title="target_sources"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">target_sources(FILE_SET)</span></code></a> instead. File sets associate | |
headers with a target and they install as part of the target.</p> | |
</div> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="o"><</span><span class="no">FILES</span><span class="p">|</span><span class="no">PROGRAMS</span><span class="o">></span><span class="w"> </span><span class="nb">files...</span><span class="w"></span> | |
<span class="w"> </span><span class="no">TYPE</span><span class="w"> </span><span class="nv"><type></span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">RENAME</span><span class="w"> </span><span class="nv"><name></span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">OPTIONAL</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">FILES</span></code> form specifies rules for installing files for a project. | |
File names given as relative paths are interpreted with respect to the | |
current source directory. Files installed by this form are by default | |
given permissions <code class="docutils literal notranslate"><span class="pre">OWNER_WRITE</span></code>, <code class="docutils literal notranslate"><span class="pre">OWNER_READ</span></code>, <code class="docutils literal notranslate"><span class="pre">GROUP_READ</span></code>, and | |
<code class="docutils literal notranslate"><span class="pre">WORLD_READ</span></code> if no <code class="docutils literal notranslate"><span class="pre">PERMISSIONS</span></code> argument is given.</p> | |
<p>The <code class="docutils literal notranslate"><span class="pre">PROGRAMS</span></code> form is identical to the <code class="docutils literal notranslate"><span class="pre">FILES</span></code> form except that the | |
default permissions for the installed file also include <code class="docutils literal notranslate"><span class="pre">OWNER_EXECUTE</span></code>, | |
<code class="docutils literal notranslate"><span class="pre">GROUP_EXECUTE</span></code>, and <code class="docutils literal notranslate"><span class="pre">WORLD_EXECUTE</span></code>. This form is intended to install | |
programs that are not targets, such as shell scripts. Use the <code class="docutils literal notranslate"><span class="pre">TARGETS</span></code> | |
form to install targets built within the project.</p> | |
<p>The list of <code class="docutils literal notranslate"><span class="pre">files...</span></code> given to <code class="docutils literal notranslate"><span class="pre">FILES</span></code> or <code class="docutils literal notranslate"><span class="pre">PROGRAMS</span></code> may use | |
"generator expressions" with the syntax <code class="docutils literal notranslate"><span class="pre">$<...></span></code>. See the | |
<span class="target" id="index-1-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions. | |
However, if any item begins in a generator expression it must evaluate | |
to a full path.</p> | |
<p>Either a <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> or a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> must be provided, but not both. | |
A <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> argument specifies the generic file type of the files being | |
installed. A destination will then be set automatically by taking the | |
corresponding variable from <span class="target" id="index-3-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a>, or by using a | |
built-in default if that variable is not defined. See the table below for | |
the supported file types and their corresponding variables and built-in | |
defaults. Projects can provide a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument instead of a | |
file type if they wish to explicitly define the install destination.</p> | |
<table class="docutils align-default"> | |
<colgroup> | |
<col style="width: 28%" /> | |
<col style="width: 41%" /> | |
<col style="width: 30%" /> | |
</colgroup> | |
<thead> | |
<tr class="row-odd"><th class="head"><p><code class="docutils literal notranslate"><span class="pre">TYPE</span></code> Argument</p></th> | |
<th class="head"><p>GNUInstallDirs Variable</p></th> | |
<th class="head"><p>Built-In Default</p></th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BIN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_BINDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">bin</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SBIN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SBINDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">sbin</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LIB</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LIBDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">lib</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INCLUDE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INCLUDEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">include</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SYSCONF</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SYSCONFDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">etc</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SHAREDSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SHARESTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">com</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LOCALSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LOCALSTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">var</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RUNSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_RUNSTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><LOCALSTATE</span> <span class="pre">dir>/run</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DATA</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_DATADIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir></span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INFO</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INFODIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/info</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LOCALE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LOCALEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/locale</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">MAN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_MANDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/man</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DOC</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_DOCDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/doc</span></code></p></td> | |
</tr> | |
</tbody> | |
</table> | |
<p>Projects wishing to follow the common practice of installing headers into a | |
project-specific subdirectory will need to provide a destination rather than | |
rely on the above. Using file sets for headers instead of <code class="docutils literal notranslate"><span class="pre">install(FILES)</span></code> | |
would be even better (see <span class="target" id="index-2-command:target_sources"></span><a class="reference internal" href="target_sources.html#command:target_sources" title="target_sources"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">target_sources(FILE_SET)</span></code></a>).</p> | |
<p>Note that some of the types' built-in defaults use the <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> directory as | |
a prefix. The <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> prefix is calculated similarly to the types, with | |
<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_DATAROOTDIR</span></code> as the variable and <code class="docutils literal notranslate"><span class="pre">share</span></code> as the built-in | |
default. You cannot use <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> as a <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> parameter; please use | |
<code class="docutils literal notranslate"><span class="pre">DATA</span></code> instead.</p> | |
<p>To make packages compliant with distribution filesystem layout policies, if | |
projects must specify a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code>, it is recommended that they use a | |
path that begins with the appropriate <span class="target" id="index-4-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a> variable. | |
This allows package maintainers to control the install destination by setting | |
the appropriate cache variables. The following example shows how to follow | |
this advice while installing an image to a project-specific documentation | |
subdirectory:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">include(</span><span class="nb">GNUInstallDirs</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">FILES</span><span class="w"> </span><span class="nb">logo.png</span><span class="w"></span> | |
<span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="o">${</span><span class="nt">CMAKE_INSTALL_DOCDIR</span><span class="o">}</span><span class="na">/myproj</span><span class="w"></span> | |
<span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.4: </span>An install destination given as a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument may | |
use "generator expressions" with the syntax <code class="docutils literal notranslate"><span class="pre">$<...></span></code>. See the | |
<span class="target" id="index-2-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions.</p> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.20: </span>An install rename given as a <code class="docutils literal notranslate"><span class="pre">RENAME</span></code> argument may | |
use "generator expressions" with the syntax <code class="docutils literal notranslate"><span class="pre">$<...></span></code>. See the | |
<span class="target" id="index-3-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions.</p> | |
</div> | |
</div> | |
<div class="section" id="installing-directories"> | |
<h2>Installing Directories<a class="headerlink" href="#installing-directories" title="Permalink to this headline">¶</a></h2> | |
<div class="admonition note" id="directory"> | |
<span id="install-directory"></span><p class="admonition-title">Note</p> | |
<p>To install a directory sub-tree of headers, consider using file sets | |
defined by <span class="target" id="index-3-command:target_sources"></span><a class="reference internal" href="target_sources.html#command:target_sources" title="target_sources"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">target_sources(FILE_SET)</span></code></a> instead. File sets not only | |
preserve directory structure, they also associate headers with a target | |
and install as part of the target.</p> | |
</div> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="nb">dirs...</span><span class="w"></span> | |
<span class="w"> </span><span class="no">TYPE</span><span class="w"> </span><span class="nv"><type></span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">FILE_PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">DIRECTORY_PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">USE_SOURCE_PERMISSIONS</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">OPTIONAL</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">MESSAGE_NEVER</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">FILES_MATCHING</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[[</span><span class="no">PATTERN</span><span class="w"> </span><span class="nv"><pattern></span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="no">REGEX</span><span class="w"> </span><span class="nv"><regex></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]]</span><span class="w"> </span><span class="p">[...]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> form installs contents of one or more directories to a | |
given destination. The directory structure is copied verbatim to the | |
destination. The last component of each directory name is appended to | |
the destination directory but a trailing slash may be used to avoid | |
this because it leaves the last component empty. Directory names | |
given as relative paths are interpreted with respect to the current | |
source directory. If no input directory names are given the | |
destination directory will be created but nothing will be installed | |
into it. The <code class="docutils literal notranslate"><span class="pre">FILE_PERMISSIONS</span></code> and <code class="docutils literal notranslate"><span class="pre">DIRECTORY_PERMISSIONS</span></code> options | |
specify permissions given to files and directories in the destination. | |
If <code class="docutils literal notranslate"><span class="pre">USE_SOURCE_PERMISSIONS</span></code> is specified and <code class="docutils literal notranslate"><span class="pre">FILE_PERMISSIONS</span></code> is not, | |
file permissions will be copied from the source directory structure. | |
If no permissions are specified files will be given the default | |
permissions specified in the <code class="docutils literal notranslate"><span class="pre">FILES</span></code> form of the command, and the | |
directories will be given the default permissions specified in the | |
<code class="docutils literal notranslate"><span class="pre">PROGRAMS</span></code> form of the command.</p> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.1: </span>The <code class="docutils literal notranslate"><span class="pre">MESSAGE_NEVER</span></code> option disables file installation status output.</p> | |
</div> | |
<p>Installation of directories may be controlled with fine granularity | |
using the <code class="docutils literal notranslate"><span class="pre">PATTERN</span></code> or <code class="docutils literal notranslate"><span class="pre">REGEX</span></code> options. These "match" options specify a | |
globbing pattern or regular expression to match directories or files | |
encountered within input directories. They may be used to apply | |
certain options (see below) to a subset of the files and directories | |
encountered. The full path to each input file or directory (with | |
forward slashes) is matched against the expression. A <code class="docutils literal notranslate"><span class="pre">PATTERN</span></code> will | |
match only complete file names: the portion of the full path matching | |
the pattern must occur at the end of the file name and be preceded by | |
a slash. A <code class="docutils literal notranslate"><span class="pre">REGEX</span></code> will match any portion of the full path but it may | |
use <code class="docutils literal notranslate"><span class="pre">/</span></code> and <code class="docutils literal notranslate"><span class="pre">$</span></code> to simulate the <code class="docutils literal notranslate"><span class="pre">PATTERN</span></code> behavior. By default all | |
files and directories are installed whether or not they are matched. | |
The <code class="docutils literal notranslate"><span class="pre">FILES_MATCHING</span></code> option may be given before the first match option | |
to disable installation of files (but not directories) not matched by | |
any expression. For example, the code</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="na">src/</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">doc/myproj</span><span class="w"></span> | |
<span class="w"> </span><span class="no">FILES_MATCHING</span><span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="s">"*.png"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>will extract and install images from a source tree.</p> | |
<p>Some options may follow a <code class="docutils literal notranslate"><span class="pre">PATTERN</span></code> or <code class="docutils literal notranslate"><span class="pre">REGEX</span></code> expression as described | |
under <a class="reference internal" href="string.html#regex-specification"><span class="std std-ref">string(REGEX)</span></a> and are applied | |
only to files or directories matching them. The <code class="docutils literal notranslate"><span class="pre">EXCLUDE</span></code> option will | |
skip the matched file or directory. The <code class="docutils literal notranslate"><span class="pre">PERMISSIONS</span></code> option overrides | |
the permissions setting for the matched file or directory. For | |
example the code</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="nb">icons</span><span class="w"> </span><span class="na">scripts/</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">share/myproj</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="s">"CVS"</span><span class="w"> </span><span class="no">EXCLUDE</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PATTERN</span><span class="w"> </span><span class="s">"scripts/*"</span><span class="w"></span> | |
<span class="w"> </span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="no">OWNER_EXECUTE</span><span class="w"> </span><span class="no">OWNER_WRITE</span><span class="w"> </span><span class="no">OWNER_READ</span><span class="w"></span> | |
<span class="w"> </span><span class="no">GROUP_EXECUTE</span><span class="w"> </span><span class="no">GROUP_READ</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>will install the <code class="docutils literal notranslate"><span class="pre">icons</span></code> directory to <code class="docutils literal notranslate"><span class="pre">share/myproj/icons</span></code> and the | |
<code class="docutils literal notranslate"><span class="pre">scripts</span></code> directory to <code class="docutils literal notranslate"><span class="pre">share/myproj</span></code>. The icons will get default | |
file permissions, the scripts will be given specific permissions, and any | |
<code class="docutils literal notranslate"><span class="pre">CVS</span></code> directories will be excluded.</p> | |
<p>Either a <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> or a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> must be provided, but not both. | |
A <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> argument specifies the generic file type of the files within the | |
listed directories being installed. A destination will then be set | |
automatically by taking the corresponding variable from | |
<span class="target" id="index-5-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a>, or by using a built-in default if that variable | |
is not defined. See the table below for the supported file types and their | |
corresponding variables and built-in defaults. Projects can provide a | |
<code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument instead of a file type if they wish to explicitly | |
define the install destination.</p> | |
<table class="docutils align-default"> | |
<colgroup> | |
<col style="width: 28%" /> | |
<col style="width: 41%" /> | |
<col style="width: 30%" /> | |
</colgroup> | |
<thead> | |
<tr class="row-odd"><th class="head"><p><code class="docutils literal notranslate"><span class="pre">TYPE</span></code> Argument</p></th> | |
<th class="head"><p>GNUInstallDirs Variable</p></th> | |
<th class="head"><p>Built-In Default</p></th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">BIN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_BINDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">bin</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SBIN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SBINDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">sbin</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LIB</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LIBDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">lib</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INCLUDE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INCLUDEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">include</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SYSCONF</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SYSCONFDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">etc</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SHAREDSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_SHARESTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">com</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LOCALSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LOCALSTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">var</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">RUNSTATE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_RUNSTATEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><LOCALSTATE</span> <span class="pre">dir>/run</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DATA</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_DATADIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir></span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">INFO</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_INFODIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/info</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">LOCALE</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_LOCALEDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/locale</span></code></p></td> | |
</tr> | |
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">MAN</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_MANDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/man</span></code></p></td> | |
</tr> | |
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">DOC</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre">${CMAKE_INSTALL_DOCDIR}</span></code></p></td> | |
<td><p><code class="docutils literal notranslate"><span class="pre"><DATAROOT</span> <span class="pre">dir>/doc</span></code></p></td> | |
</tr> | |
</tbody> | |
</table> | |
<p>Note that some of the types' built-in defaults use the <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> directory as | |
a prefix. The <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> prefix is calculated similarly to the types, with | |
<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_DATAROOTDIR</span></code> as the variable and <code class="docutils literal notranslate"><span class="pre">share</span></code> as the built-in | |
default. You cannot use <code class="docutils literal notranslate"><span class="pre">DATAROOT</span></code> as a <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> parameter; please use | |
<code class="docutils literal notranslate"><span class="pre">DATA</span></code> instead.</p> | |
<p>To make packages compliant with distribution filesystem layout policies, if | |
projects must specify a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code>, it is recommended that they use a | |
path that begins with the appropriate <span class="target" id="index-6-module:GNUInstallDirs"></span><a class="reference internal" href="../module/GNUInstallDirs.html#module:GNUInstallDirs" title="GNUInstallDirs"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">GNUInstallDirs</span></code></a> variable. | |
This allows package maintainers to control the install destination by setting | |
the appropriate cache variables.</p> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.4: </span>An install destination given as a <code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> argument may | |
use "generator expressions" with the syntax <code class="docutils literal notranslate"><span class="pre">$<...></span></code>. See the | |
<span class="target" id="index-4-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions.</p> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.5: </span>The list of <code class="docutils literal notranslate"><span class="pre">dirs...</span></code> given to <code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> may use | |
"generator expressions" too.</p> | |
</div> | |
</div> | |
<div class="section" id="custom-installation-logic"> | |
<h2>Custom Installation Logic<a class="headerlink" href="#custom-installation-logic" title="Permalink to this headline">¶</a></h2> | |
<div class="highlight-cmake notranslate" id="script"><span id="code"></span><span id="install-script"></span><span id="install-code"></span><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="p">[[</span><span class="no">SCRIPT</span><span class="w"> </span><span class="nv"><file></span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">CODE</span><span class="w"> </span><span class="nv"><code></span><span class="p">]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">ALL_COMPONENTS</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="w"> </span><span class="p">[...]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">SCRIPT</span></code> form will invoke the given CMake script files during | |
installation. If the script file name is a relative path it will be | |
interpreted with respect to the current source directory. The <code class="docutils literal notranslate"><span class="pre">CODE</span></code> | |
form will invoke the given CMake code during installation. Code is | |
specified as a single argument inside a double-quoted string. For | |
example, the code</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">CODE</span><span class="w"> </span><span class="s">"MESSAGE(\"Sample install message.\")"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>will print a message during installation.</p> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.21: </span>When the <code class="docutils literal notranslate"><span class="pre">ALL_COMPONENTS</span></code> option is given, the custom installation | |
script code will be executed for every component of a component-specific | |
installation. This option is mutually exclusive with the <code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> | |
option.</p> | |
</div> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.14: </span><code class="docutils literal notranslate"><span class="pre"><file></span></code> or <code class="docutils literal notranslate"><span class="pre"><code></span></code> may use "generator expressions" with the syntax | |
<code class="docutils literal notranslate"><span class="pre">$<...></span></code> (in the case of <code class="docutils literal notranslate"><span class="pre"><file></span></code>, this refers to their use in the file | |
name, not the file's contents). See the | |
<span class="target" id="index-5-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake-generator-expressions(7)</span></code></a> manual for available expressions.</p> | |
</div> | |
</div> | |
<div class="section" id="installing-exports"> | |
<h2>Installing Exports<a class="headerlink" href="#installing-exports" title="Permalink to this headline">¶</a></h2> | |
<div class="highlight-cmake notranslate" id="export"><span id="install-export"></span><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">EXPORT</span><span class="w"> </span><span class="nv"><export-name></span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">NAMESPACE</span><span class="w"> </span><span class="nv"><namespace></span><span class="p">]</span><span class="w"> </span><span class="p">[[</span><span class="no">FILE</span><span class="w"> </span><span class="nv"><name></span><span class="p">.</span><span class="nb">cmake</span><span class="p">]|</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">EXPORT_LINK_INTERFACE_LIBRARIES</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">EXPORT_ANDROID_MK</span><span class="w"> </span><span class="nv"><export-name></span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="w"> </span><span class="p">[...]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">EXPORT</span></code> form generates and installs a CMake file containing code to | |
import targets from the installation tree into another project. | |
Target installations are associated with the export <code class="docutils literal notranslate"><span class="pre"><export-name></span></code> | |
using the <code class="docutils literal notranslate"><span class="pre">EXPORT</span></code> option of the <a class="reference internal" href="#install-targets">install(TARGETS)</a> signature | |
documented above. The <code class="docutils literal notranslate"><span class="pre">NAMESPACE</span></code> option will prepend <code class="docutils literal notranslate"><span class="pre"><namespace></span></code> to | |
the target names as they are written to the import file. By default | |
the generated file will be called <code class="docutils literal notranslate"><span class="pre"><export-name>.cmake</span></code> but the <code class="docutils literal notranslate"><span class="pre">FILE</span></code> | |
option may be used to specify a different name. The value given to | |
the <code class="docutils literal notranslate"><span class="pre">FILE</span></code> option must be a file name with the <code class="docutils literal notranslate"><span class="pre">.cmake</span></code> extension. | |
If a <code class="docutils literal notranslate"><span class="pre">CONFIGURATIONS</span></code> option is given then the file will only be installed | |
when one of the named configurations is installed. Additionally, the | |
generated import file will reference only the matching target | |
configurations. The <code class="docutils literal notranslate"><span class="pre">EXPORT_LINK_INTERFACE_LIBRARIES</span></code> keyword, if | |
present, causes the contents of the properties matching | |
<code class="docutils literal notranslate"><span class="pre">(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?</span></code> to be exported, when | |
policy <span class="target" id="index-0-policy:CMP0022"></span><a class="reference internal" href="../policy/CMP0022.html#policy:CMP0022" title="CMP0022"><code class="xref cmake cmake-policy docutils literal notranslate"><span class="pre">CMP0022</span></code></a> is <code class="docutils literal notranslate"><span class="pre">NEW</span></code>.</p> | |
<div class="admonition note"> | |
<p class="admonition-title">Note</p> | |
<p>The installed <code class="docutils literal notranslate"><span class="pre"><export-name>.cmake</span></code> file may come with additional | |
per-configuration <code class="docutils literal notranslate"><span class="pre"><export-name>-*.cmake</span></code> files to be loaded by | |
globbing. Do not use an export name that is the same as the package | |
name in combination with installing a <code class="docutils literal notranslate"><span class="pre"><package-name>-config.cmake</span></code> | |
file or the latter may be incorrectly matched by the glob and loaded.</p> | |
</div> | |
<p>When a <code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code> option is given, the listed <code class="docutils literal notranslate"><span class="pre"><component></span></code> implicitly | |
depends on all components mentioned in the export set. The exported | |
<code class="docutils literal notranslate"><span class="pre"><name>.cmake</span></code> file will require each of the exported components to be | |
present in order for dependent projects to build properly. For example, a | |
project may define components <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> and <code class="docutils literal notranslate"><span class="pre">Development</span></code>, with shared | |
libraries going into the <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> component and static libraries and | |
headers going into the <code class="docutils literal notranslate"><span class="pre">Development</span></code> component. The export set would also | |
typically be part of the <code class="docutils literal notranslate"><span class="pre">Development</span></code> component, but it would export | |
targets from both the <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> and <code class="docutils literal notranslate"><span class="pre">Development</span></code> components. Therefore, | |
the <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> component would need to be installed if the <code class="docutils literal notranslate"><span class="pre">Development</span></code> | |
component was installed, but not vice versa. If the <code class="docutils literal notranslate"><span class="pre">Development</span></code> component | |
was installed without the <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> component, dependent projects that try | |
to link against it would have build errors. Package managers, such as APT and | |
RPM, typically handle this by listing the <code class="docutils literal notranslate"><span class="pre">Runtime</span></code> component as a dependency | |
of the <code class="docutils literal notranslate"><span class="pre">Development</span></code> component in the package metadata, ensuring that the | |
library is always installed if the headers and CMake export file are present.</p> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.7: </span>In addition to cmake language files, the <code class="docutils literal notranslate"><span class="pre">EXPORT_ANDROID_MK</span></code> mode may be | |
used to specify an export to the android ndk build system. This mode | |
accepts the same options as the normal export mode. The Android | |
NDK supports the use of prebuilt libraries, both static and shared. This | |
allows cmake to build the libraries of a project and make them available | |
to an ndk build system complete with transitive dependencies, include flags | |
and defines required to use the libraries.</p> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">EXPORT</span></code> form is useful to help outside projects use targets built | |
and installed by the current project. For example, the code</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">TARGETS</span><span class="w"> </span><span class="nb">myexe</span><span class="w"> </span><span class="no">EXPORT</span><span class="w"> </span><span class="nb">myproj</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="nb">bin</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">EXPORT</span><span class="w"> </span><span class="nb">myproj</span><span class="w"> </span><span class="no">NAMESPACE</span><span class="w"> </span><span class="nb">mp_</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">lib/myproj</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">install(</span><span class="no">EXPORT_ANDROID_MK</span><span class="w"> </span><span class="nb">myproj</span><span class="w"> </span><span class="no">DESTINATION</span><span class="w"> </span><span class="na">share/ndk-modules</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>will install the executable <code class="docutils literal notranslate"><span class="pre">myexe</span></code> to <code class="docutils literal notranslate"><span class="pre"><prefix>/bin</span></code> and code to import | |
it in the file <code class="docutils literal notranslate"><span class="pre"><prefix>/lib/myproj/myproj.cmake</span></code> and | |
<code class="docutils literal notranslate"><span class="pre"><prefix>/share/ndk-modules/Android.mk</span></code>. An outside project | |
may load this file with the include command and reference the <code class="docutils literal notranslate"><span class="pre">myexe</span></code> | |
executable from the installation tree using the imported target name | |
<code class="docutils literal notranslate"><span class="pre">mp_myexe</span></code> as if the target were built in its own tree.</p> | |
<div class="admonition note"> | |
<p class="admonition-title">Note</p> | |
<p>This command supersedes the <span class="target" id="index-0-command:install_targets"></span><a class="reference internal" href="install_targets.html#command:install_targets" title="install_targets"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_targets()</span></code></a> command and | |
the <span class="target" id="index-0-prop_tgt:PRE_INSTALL_SCRIPT"></span><a class="reference internal" href="../prop_tgt/PRE_INSTALL_SCRIPT.html#prop_tgt:PRE_INSTALL_SCRIPT" title="PRE_INSTALL_SCRIPT"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">PRE_INSTALL_SCRIPT</span></code></a> and <span class="target" id="index-0-prop_tgt:POST_INSTALL_SCRIPT"></span><a class="reference internal" href="../prop_tgt/POST_INSTALL_SCRIPT.html#prop_tgt:POST_INSTALL_SCRIPT" title="POST_INSTALL_SCRIPT"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">POST_INSTALL_SCRIPT</span></code></a> | |
target properties. It also replaces the <code class="docutils literal notranslate"><span class="pre">FILES</span></code> forms of the | |
<span class="target" id="index-0-command:install_files"></span><a class="reference internal" href="install_files.html#command:install_files" title="install_files"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_files()</span></code></a> and <span class="target" id="index-0-command:install_programs"></span><a class="reference internal" href="install_programs.html#command:install_programs" title="install_programs"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_programs()</span></code></a> commands. | |
The processing order of these install rules relative to | |
those generated by <span class="target" id="index-1-command:install_targets"></span><a class="reference internal" href="install_targets.html#command:install_targets" title="install_targets"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_targets()</span></code></a>, | |
<span class="target" id="index-1-command:install_files"></span><a class="reference internal" href="install_files.html#command:install_files" title="install_files"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_files()</span></code></a>, and <span class="target" id="index-1-command:install_programs"></span><a class="reference internal" href="install_programs.html#command:install_programs" title="install_programs"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">install_programs()</span></code></a> commands | |
is not defined.</p> | |
</div> | |
</div> | |
<div class="section" id="installing-runtime-dependencies"> | |
<h2>Installing Runtime Dependencies<a class="headerlink" href="#installing-runtime-dependencies" title="Permalink to this headline">¶</a></h2> | |
<div class="versionadded" id="runtime-dependency-set"> | |
<span id="install-runtime-dependency-set"></span><p><span class="versionmodified added">New in version 3.21.</span></p> | |
</div> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">install(</span><span class="no">RUNTIME_DEPENDENCY_SET</span><span class="w"> </span><span class="nv"><set-name></span><span class="w"></span> | |
<span class="w"> </span><span class="p">[[</span><span class="no">LIBRARY</span><span class="p">|</span><span class="no">RUNTIME</span><span class="p">|</span><span class="no">FRAMEWORK</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">DESTINATION</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PERMISSIONS</span><span class="w"> </span><span class="nb">permissions...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">CONFIGURATIONS</span><span class="w"> </span><span class="p">[</span><span class="nb">Debug</span><span class="p">|</span><span class="nb">Release</span><span class="p">|...]]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">NAMELINK_COMPONENT</span><span class="w"> </span><span class="nv"><component></span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">OPTIONAL</span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="no">EXCLUDE_FROM_ALL</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">[...]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PRE_INCLUDE_REGEXES</span><span class="w"> </span><span class="nb">regexes...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">PRE_EXCLUDE_REGEXES</span><span class="w"> </span><span class="nb">regexes...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">POST_INCLUDE_REGEXES</span><span class="w"> </span><span class="nb">regexes...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">POST_EXCLUDE_REGEXES</span><span class="w"> </span><span class="nb">regexes...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">POST_INCLUDE_FILES</span><span class="w"> </span><span class="nb">files...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">POST_EXCLUDE_FILES</span><span class="w"> </span><span class="nb">files...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="p">[</span><span class="no">DIRECTORIES</span><span class="w"> </span><span class="nb">directories...</span><span class="p">]</span><span class="w"></span> | |
<span class="w"> </span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>Installs a runtime dependency set previously created by one or more | |
<a class="reference internal" href="#install-targets">install(TARGETS)</a> or <a class="reference internal" href="#install-imported-runtime-artifacts">install(IMPORTED_RUNTIME_ARTIFACTS)</a> commands. The | |
dependencies of targets belonging to a runtime dependency set are installed in | |
the <code class="docutils literal notranslate"><span class="pre">RUNTIME</span></code> destination and component on DLL platforms, and in the | |
<code class="docutils literal notranslate"><span class="pre">LIBRARY</span></code> destination and component on non-DLL platforms. macOS frameworks | |
are installed in the <code class="docutils literal notranslate"><span class="pre">FRAMEWORK</span></code> destination and component. | |
Targets built within the build tree will never be installed as runtime | |
dependencies, nor will their own dependencies, unless the targets themselves | |
are installed with <a class="reference internal" href="#install-targets">install(TARGETS)</a>.</p> | |
<p>The generated install script calls <span class="target" id="index-0-command:file"></span><a class="reference internal" href="file.html#command:file" title="file"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">file(GET_RUNTIME_DEPENDENCIES)</span></code></a> | |
on the build-tree files to calculate the runtime dependencies. The build-tree | |
executable files are passed as the <code class="docutils literal notranslate"><span class="pre">EXECUTABLES</span></code> argument, the build-tree | |
shared libraries as the <code class="docutils literal notranslate"><span class="pre">LIBRARIES</span></code> argument, and the build-tree modules as | |
the <code class="docutils literal notranslate"><span class="pre">MODULES</span></code> argument. On macOS, if one of the executables is a | |
<span class="target" id="index-3-prop_tgt:MACOSX_BUNDLE"></span><a class="reference internal" href="../prop_tgt/MACOSX_BUNDLE.html#prop_tgt:MACOSX_BUNDLE" title="MACOSX_BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code></a>, that executable is passed as the | |
<code class="docutils literal notranslate"><span class="pre">BUNDLE_EXECUTABLE</span></code> argument. At most one such bundle executable may be in | |
the runtime dependency set on macOS. The <span class="target" id="index-4-prop_tgt:MACOSX_BUNDLE"></span><a class="reference internal" href="../prop_tgt/MACOSX_BUNDLE.html#prop_tgt:MACOSX_BUNDLE" title="MACOSX_BUNDLE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">MACOSX_BUNDLE</span></code></a> property | |
has no effect on other platforms. Note that | |
<span class="target" id="index-1-command:file"></span><a class="reference internal" href="file.html#command:file" title="file"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">file(GET_RUNTIME_DEPENDENCIES)</span></code></a> only supports collecting the runtime | |
dependencies for Windows, Linux and macOS platforms, so | |
<code class="docutils literal notranslate"><span class="pre">install(RUNTIME_DEPENDENCY_SET)</span></code> has the same limitation.</p> | |
<p>The following sub-arguments are forwarded through as the corresponding | |
arguments to <span class="target" id="index-2-command:file"></span><a class="reference internal" href="file.html#command:file" title="file"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">file(GET_RUNTIME_DEPENDENCIES)</span></code></a> (for those that provide | |
a non-empty list of directories, regular expressions or files). They all | |
support <span class="target" id="index-6-manual:cmake-generator-expressions(7)"></span><a class="reference internal" href="../manual/cmake-generator-expressions.7.html#manual:cmake-generator-expressions(7)" title="cmake-generator-expressions(7)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">generator</span> <span class="pre">expressions</span></code></a>.</p> | |
<ul class="simple"> | |
<li><p><code class="docutils literal notranslate"><span class="pre">DIRECTORIES</span> <span class="pre"><directories></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">PRE_INCLUDE_REGEXES</span> <span class="pre"><regexes></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">PRE_EXCLUDE_REGEXES</span> <span class="pre"><regexes></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_INCLUDE_REGEXES</span> <span class="pre"><regexes></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_EXCLUDE_REGEXES</span> <span class="pre"><regexes></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_INCLUDE_FILES</span> <span class="pre"><files></span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">POST_EXCLUDE_FILES</span> <span class="pre"><files></span></code></p></li> | |
</ul> | |
</div> | |
<div class="section" id="generated-installation-script"> | |
<h2>Generated Installation Script<a class="headerlink" href="#generated-installation-script" title="Permalink to this headline">¶</a></h2> | |
<div class="admonition note"> | |
<p class="admonition-title">Note</p> | |
<p>Use of this feature is not recommended. Please consider using the | |
<code class="docutils literal notranslate"><span class="pre">--install</span></code> argument of <span class="target" id="index-0-manual:cmake(1)"></span><a class="reference internal" href="../manual/cmake.1.html#manual:cmake(1)" title="cmake(1)"><code class="xref cmake cmake-manual docutils literal notranslate"><span class="pre">cmake(1)</span></code></a> instead.</p> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">install()</span></code> command generates a file, <code class="docutils literal notranslate"><span class="pre">cmake_install.cmake</span></code>, inside | |
the build directory, which is used internally by the generated install target | |
and by CPack. You can also invoke this script manually with <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-P</span></code>. This | |
script accepts several variables:</p> | |
<dl class="simple"> | |
<dt><code class="docutils literal notranslate"><span class="pre">COMPONENT</span></code></dt><dd><p>Set this variable to install only a single CPack component as opposed to all | |
of them. For example, if you only want to install the <code class="docutils literal notranslate"><span class="pre">Development</span></code> | |
component, run <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-DCOMPONENT=Development</span> <span class="pre">-P</span> <span class="pre">cmake_install.cmake</span></code>.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">BUILD_TYPE</span></code></dt><dd><p>Set this variable to change the build type if you are using a multi-config | |
generator. For example, to install with the <code class="docutils literal notranslate"><span class="pre">Debug</span></code> configuration, run | |
<code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-DBUILD_TYPE=Debug</span> <span class="pre">-P</span> <span class="pre">cmake_install.cmake</span></code>.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">DESTDIR</span></code></dt><dd><p>This is an environment variable rather than a CMake variable. It allows you | |
to change the installation prefix on UNIX systems. See <span class="target" id="index-0-envvar:DESTDIR"></span><a class="reference internal" href="../envvar/DESTDIR.html#envvar:DESTDIR" title="DESTDIR"><code class="xref cmake cmake-envvar docutils literal notranslate"><span class="pre">DESTDIR</span></code></a> for | |
details.</p> | |
</dd> | |
</dl> | |
</div> | |
</div> | |
</div> | |
</div> | |
</div> | |
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> | |
<div class="sphinxsidebarwrapper"> | |
<h3><a href="../index.html">Table of Contents</a></h3> | |
<ul> | |
<li><a class="reference internal" href="#">install</a><ul> | |
<li><a class="reference internal" href="#synopsis">Synopsis</a></li> | |
<li><a class="reference internal" href="#introduction">Introduction</a></li> | |
<li><a class="reference internal" href="#installing-targets">Installing Targets</a></li> | |
<li><a class="reference internal" href="#installing-imported-runtime-artifacts">Installing Imported Runtime Artifacts</a></li> | |
<li><a class="reference internal" href="#installing-files">Installing Files</a></li> | |
<li><a class="reference internal" href="#installing-directories">Installing Directories</a></li> | |
<li><a class="reference internal" href="#custom-installation-logic">Custom Installation Logic</a></li> | |
<li><a class="reference internal" href="#installing-exports">Installing Exports</a></li> | |
<li><a class="reference internal" href="#installing-runtime-dependencies">Installing Runtime Dependencies</a></li> | |
<li><a class="reference internal" href="#generated-installation-script">Generated Installation Script</a></li> | |
</ul> | |
</li> | |
</ul> | |
<h4>Previous topic</h4> | |
<p class="topless"><a href="include_regular_expression.html" | |
title="previous chapter">include_regular_expression</a></p> | |
<h4>Next topic</h4> | |
<p class="topless"><a href="link_directories.html" | |
title="next chapter">link_directories</a></p> | |
<div role="note" aria-label="source link"> | |
<h3>This Page</h3> | |
<ul class="this-page-menu"> | |
<li><a href="../_sources/command/install.rst.txt" | |
rel="nofollow">Show Source</a></li> | |
</ul> | |
</div> | |
<div id="searchbox" style="display: none" role="search"> | |
<h3 id="searchlabel">Quick search</h3> | |
<div class="searchformwrapper"> | |
<form class="search" action="../search.html" method="get"> | |
<input type="text" name="q" aria-labelledby="searchlabel" /> | |
<input type="submit" value="Go" /> | |
</form> | |
</div> | |
</div> | |
<script type="text/javascript">$('#searchbox').show(0);</script> | |
</div> | |
</div> | |
<div class="clearer"></div> | |
</div> | |
<div class="related" role="navigation" aria-label="related navigation"> | |
<h3>Navigation</h3> | |
<ul> | |
<li class="right" style="margin-right: 10px"> | |
<a href="../genindex.html" title="General Index" | |
>index</a></li> | |
<li class="right" > | |
<a href="link_directories.html" title="link_directories" | |
>next</a> |</li> | |
<li class="right" > | |
<a href="include_regular_expression.html" title="include_regular_expression" | |
>previous</a> |</li> | |
<li> | |
<img src="../_static/cmake-logo-16.png" alt="" | |
style="vertical-align: middle; margin-top: -2px" /> | |
</li> | |
<li> | |
<a href="https://cmake.org/">CMake</a> » | |
</li> | |
<li> | |
<a href="../index.html">3.23.1 Documentation</a> » | |
</li> | |
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" >cmake-commands(7)</a> »</li> | |
</ul> | |
</div> | |
<div class="footer" role="contentinfo"> | |
© Copyright 2000-2022 Kitware, Inc. and Contributors. | |
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.1.2. | |
</div> | |
</body> | |
</html> |