install

指定在安装时运行的规则。

概要

install(TARGETS <target>... [...])
install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
install({FILES | PROGRAMS} <file>... [...])
install(DIRECTORY <dir>... [...])
install(SCRIPT <file> [...])
install(CODE <code> [...])
install(EXPORT <export-name> [...])
install(PACKAGE_INFO <package-name> [...])
install(RUNTIME_DEPENDENCY_SET <set-name> [...])

简介

此命令为项目生成安装规则。在源目录中通过调用 install() 命令指定的安装规则在安装期间按顺序执行。

在 3.14 版本中变更: 通过调用 add_subdirectory() 命令添加到子目录中的安装规则与父目录中的规则交错，并按照声明的顺序运行（参见策略 CMP0082）。

在 3.22 版本中变更: 环境变量 CMAKE_INSTALL_MODE 可以覆盖 install() 的默认复制行为。

在 3.31 版本中变更: 项目可以启用 INSTALL_PARALLEL 以启用并行安装。当使用并行安装时，通过调用 add_subdirectory() 命令添加的子目录将独立安装，并且不能保证在不同子目录中添加的安装规则的运行顺序。

此命令有多个签名。其中一些签名定义了文件和目标的安装选项。多个签名通用的选项在此处介绍，但它们仅对指定它们的签名有效。常用选项有

DESTINATION <dir>

指定磁盘上文件将被安装到的目录。<dir> 应该是一个相对路径。允许使用绝对路径，但不建议这样做。

当给定相对路径时，它会被解释为相对于 CMAKE_INSTALL_PREFIX 变量的值。前缀可以在安装时使用 DESTDIR 机制进行重定位，该机制在 CMAKE_INSTALL_PREFIX 变量文档中进行了解释。

由于绝对路径不适用于 cmake --install 命令的 --prefix 选项，或 cpack 安装程序生成器，因此强烈建议始终使用相对路径，以便获得软件包维护者的最佳支持。 特别是，没有必要通过预先添加 CMAKE_INSTALL_PREFIX 来使路径成为绝对路径；如果 DESTINATION 是相对路径，则默认使用此前缀。

如果给出了绝对路径（带有前导斜杠或驱动器号），则按原样使用。

在 3.31 版本中变更: <dir> 将根据与 cmake_path() 命令相同的 规范化规则 进行规范化。

PERMISSIONS <permission>...

指定已安装文件的权限。有效权限为 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, 和 SETGID。在某些平台上没有意义的权限在这些平台上将被忽略。

如果在单个调用中多次使用此选项，则其权限列表会累积。如果 install(TARGETS) 调用使用 <artifact-kind> 参数，则为每种构件类型累积单独的权限列表。

CONFIGURATIONS <config>...

指定安装规则适用的构建配置列表（Debug、Release 等）。

如果在单个调用中多次使用此选项，则其配置列表会累积。如果 install(TARGETS) 调用使用 <artifact-kind> 参数，则为每种构件类型累积单独的配置列表。

COMPONENT <component>

指定与安装规则关联的安装组件名称，例如 Runtime 或 Development。在组件特定的安装期间，仅执行与给定组件名称关联的安装规则。在完全安装期间，将安装所有组件，除非标记为 EXCLUDE_FROM_ALL。如果未提供 COMPONENT，则会创建一个默认组件“Unspecified”。默认组件名称可以通过 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME 变量进行控制。

安装组件可以被 cmake --install 命令的 --component 选项和 CPackComponent 模块使用。全局目标 list_install_components 列出所有可用的组件。

EXCLUDE_FROM_ALL

在 3.6 版本中添加。

指定该文件从完全安装中排除，仅作为组件特定安装的一部分安装

OPTIONAL

指定如果要安装的文件不存在，则不是错误。

在 3.1 版本中添加: 安装文件的命令签名可能会在安装期间打印消息。使用 CMAKE_INSTALL_MESSAGE 变量来控制打印哪些消息。

在 3.11 版本中添加: 许多 install() 变体隐式创建包含已安装文件的目录。如果设置了 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS，则将使用指定的权限创建这些目录。否则，它们将根据类 Unix 平台上的 uname 规则创建。Windows 平台不受影响。

签名

install(TARGETS <target>... [...])

安装目标 输出构件 和关联文件

install(TARGETS <target>... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
        [<artifact-option>...]
        [<artifact-kind> <artifact-option>...]...
        [INCLUDES DESTINATION [<dir> ...]]
        )

其中 <artifact-option>... 组可能包含

[DESTINATION <dir>]
[PERMISSIONS <permission>...]
[CONFIGURATIONS <config>...]
[COMPONENT <component>]
[NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP]

第一个 <artifact-option>... 组适用于没有在同一调用中稍后指定专用组的目标 输出构件。

每个 <artifact-kind> <artifact-option>... 组适用于指定构件类型的 输出构件

ARCHIVE

这种类型的目标构件包括

  • 静态库（在 macOS 上标记为 FRAMEWORK 时除外，见下文）；

  • DLL 导入库（在包括 Cygwin 在内的所有基于 Windows 的系统上；它们的扩展名为 .lib，与进入 RUNTIME 的 .dll 库相反）；

  • 在 AIX 上，为启用 ENABLE_EXPORTS 的可执行文件创建的链接器导入文件。

  • 在 macOS 上，为启用 ENABLE_EXPORTS 的共享库创建的链接器导入文件（标记为 FRAMEWORK 时除外，见下文）。

LIBRARY

这种类型的目标构件包括

  • 共享库，除了

    • DLL（这些进入 RUNTIME，见下文），

    • 在 macOS 上标记为 FRAMEWORK 时（见下文）。

RUNTIME

这种类型的目标构件包括

  • 可执行文件（在 macOS 上标记为 MACOSX_BUNDLE 时除外，参见下面的 BUNDLE）；

  • DLL（在包括 Cygwin 在内的所有基于 Windows 的系统上；请注意，随附的导入库是 ARCHIVE 类型）。

OBJECTS

在 3.9 版本中添加。

与对象库关联的目标文件。

FRAMEWORK

标记有 FRAMEWORK 属性的静态库和共享库在 macOS 上都被视为 FRAMEWORK 目标。

BUNDLE

标记有 MACOSX_BUNDLE 属性的可执行文件在 macOS 上被视为 BUNDLE 目标。

PUBLIC_HEADER

与库关联的任何 PUBLIC_HEADER 文件都安装在非 Apple 平台上 PUBLIC_HEADER 参数指定的目的地中。由此参数定义的规则对于 Apple 平台上的 FRAMEWORK 库将被忽略，因为关联的文件安装到框架文件夹内的相应位置。 有关详细信息，请参阅 PUBLIC_HEADER。

PRIVATE_HEADER

类似于 PUBLIC_HEADER，但用于 PRIVATE_HEADER 文件。有关详细信息，请参阅 PRIVATE_HEADER。

RESOURCE

类似于 PUBLIC_HEADER 和 PRIVATE_HEADER，但用于 RESOURCE 文件。有关详细信息，请参阅 RESOURCE。

FILE_SET <set-name>

在 3.23 版本中添加。

文件集由 target_sources(FILE_SET) 命令定义。如果文件集 <set-name> 存在且为 PUBLIC 或 INTERFACE，则该集合中的任何文件都将安装在目标位置（见下文）下。相对于文件集基本目录的目录结构将被保留。例如，以 /blah/include/myproj/here.h 形式添加到文件集的文件，且基本目录为 /blah/include，将被安装到目标位置下的 myproj/here.h。

CXX_MODULES_BMI

在 3.28 版本中添加。

来自 CXX_MODULES 类型的文件集中的 PUBLIC 源的任何 C++ 模块的模块文件都将安装到给定的 DESTINATION。所有模块都直接放置在目标位置，因为没有目录结构从模块名称派生而来。可以使用空的 DESTINATION 来禁止安装这些文件（用于通用代码）。

对于常规可执行文件、静态库和共享库，DESTINATION 参数不是必需的。对于这些目标类型，当省略 DESTINATION 时，默认目标位置将从 GNUInstallDirs 中的相应变量获取，如果该变量未定义，则设置为内置默认值。文件集以及通过 PUBLIC_HEADER 和 PRIVATE_HEADER 目标属性与已安装目标关联的公共和私有标头也是如此。必须始终为模块库、Apple bundle 和框架提供目标位置。可以省略接口库和对象库的目标位置，但它们的处理方式不同（请参阅本节末尾对此主题的讨论）。

对于 DLL 平台上的共享库，如果未指定 RUNTIME 和 ARCHIVE 目标位置，则 RUNTIME 和 ARCHIVE 组件都将安装到其默认目标位置。如果指定了 RUNTIME 或 ARCHIVE 目标位置，则组件将安装到该目标位置，而另一个组件将不安装。如果同时指定了 RUNTIME 和 ARCHIVE 目标位置，则两个组件都将安装到各自的目标位置。

下表显示了目标类型及其关联的变量和内置默认值，这些变量和内置默认值在未给出目标位置时适用

目标类型

GNUInstallDirs 变量

内置默认值

RUNTIME

${CMAKE_INSTALL_BINDIR}

bin

LIBRARY

${CMAKE_INSTALL_LIBDIR}

lib

ARCHIVE

${CMAKE_INSTALL_LIBDIR}

lib

PRIVATE_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

PUBLIC_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

FILE_SET (类型 HEADERS)

${CMAKE_INSTALL_INCLUDEDIR}

include

希望遵循将标头安装到项目特定子目录的常见做法的项目可能更喜欢使用具有适当路径和基本目录的文件集。否则，他们必须提供 DESTINATION，而不是能够依赖上述内容（请参阅下面的下一个示例）。

为了使软件包符合发行版文件系统布局策略，如果项目必须指定 DESTINATION，则强烈建议他们使用以适当的相对 GNUInstallDirs 变量开头的路径。这允许软件包维护者通过设置适当的缓存变量来控制安装目标位置。以下示例显示了静态库被安装到 GNUInstallDirs 提供的默认目标位置，但其标头安装到项目特定的子目录中，而未使用文件集

add_library(mylib STATIC ...)
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
include(GNUInstallDirs)
install(TARGETS mylib
        PUBLIC_HEADER
          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)

除了上面列出的 通用选项 外，每个目标还可以接受以下附加参数

NAMELINK_COMPONENT

在 3.12 版本中添加。

在某些平台上，版本化的共享库具有符号链接，例如

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

其中 lib<name>.so.1 是库的 soname，lib<name>.so 是“namelink”，允许链接器在给定 -l<name> 时找到库。NAMELINK_COMPONENT 选项类似于 COMPONENT 选项，但如果生成了共享库 namelink，它会更改共享库 namelink 的安装组件。如果未指定，则默认为 COMPONENT 的值。在 LIBRARY 块之外使用此参数是错误的。

在 3.27 版本中变更: 此参数也可用于 ARCHIVE 块，以管理在 macOS 上为启用 ENABLE_EXPORTS 的共享库创建的链接器导入文件。

有关使用 NAMELINK_COMPONENT 的示例，请参阅 示例：使用每个构件组件安装目标。

此选项通常用于具有单独运行时和开发包的软件包管理器。例如，在 Debian 系统上，库应位于运行时包中，而标头和 namelink 应位于开发包中。

有关创建版本化共享库的详细信息，请参阅 VERSION 和 SOVERSION 目标属性。

NAMELINK_ONLY

当安装库目标时，此选项仅安装 namelink。在版本化的共享库没有 namelink 的平台或库未版本化时，NAMELINK_ONLY 选项不安装任何内容。在 LIBRARY 块之外使用此参数是错误的。

在 3.27 版本中变更: 此参数也可用于 ARCHIVE 块，以管理在 macOS 上为启用 ENABLE_EXPORTS 的共享库创建的链接器导入文件。

当给定 NAMELINK_ONLY 时，可以使用 NAMELINK_COMPONENT 或 COMPONENT 来指定 namelink 的安装组件，但通常应首选 COMPONENT。

NAMELINK_SKIP

类似于 NAMELINK_ONLY，但效果相反：当安装库目标时，它会导致安装 namelink 以外的库文件。当既未给出 NAMELINK_ONLY 也未给出 NAMELINK_SKIP 时，两个部分都将安装。在版本化的共享库没有符号链接的平台或库未版本化时，NAMELINK_SKIP 安装库。在 LIBRARY 块之外使用此参数是错误的。

在 3.27 版本中变更: 此参数也可用于 ARCHIVE 块，以管理在 macOS 上为启用 ENABLE_EXPORTS 的共享库创建的链接器导入文件。

如果指定了 NAMELINK_SKIP，则 NAMELINK_COMPONENT 无效。不建议将 NAMELINK_SKIP 与 NAMELINK_COMPONENT 结合使用。

install(TARGETS) 命令还可以在顶层接受以下选项

EXPORT

此选项将已安装的目标文件与名为 <export-name> 的导出关联。它必须出现在任何目标选项之前。要实际安装导出文件本身，请调用 install(EXPORT)，如下所述。请参阅 EXPORT_NAME 目标属性的文档以更改导出的目标的名称。

如果使用了 EXPORT 并且目标包括 PUBLIC 或 INTERFACE 文件集，则所有这些文件集都必须使用 FILE_SET 参数指定。与目标关联的所有 PUBLIC 或 INTERFACE 文件集都包含在导出中。

INCLUDES DESTINATION

此选项指定目录列表，这些目录将添加到通过 install(EXPORT) 命令导出 <targets> 时的 INTERFACE_INCLUDE_DIRECTORIES 目标属性中。如果指定了相对路径，则将其视为相对于 $<INSTALL_PREFIX>。

与各种 install() 子命令的其他 DESTINATION 参数不同，在 INCLUDES DESTINATION 之后给出的路径按原样使用。它们未被规范化，也不假定已被规范化，尽管建议以规范化形式给出它们（请参阅 规范化）。

RUNTIME_DEPENDENCY_SET <set-name>

在 3.21 版本中添加。

此选项使已安装的可执行文件、共享库和模块目标的所有运行时依赖项都添加到指定的运行时依赖项集中。然后可以使用 install(RUNTIME_DEPENDENCY_SET) 命令安装此集合。

此关键字和 RUNTIME_DEPENDENCIES 关键字互斥。

RUNTIME_DEPENDENCIES <arg>...

在 3.21 版本中添加。

此选项使已安装的可执行文件、共享库和模块目标的所有运行时依赖项与目标本身一起安装。RUNTIME、LIBRARY、FRAMEWORK 和通用参数用于确定这些依赖项安装的属性（DESTINATION、COMPONENT 等）。

RUNTIME_DEPENDENCIES 在语义上等效于以下一对调用

install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
install(RUNTIME_DEPENDENCY_SET <set-name> <arg>...)

其中 <set-name> 将是随机生成的集合名称。<arg>... 可能包含 install(RUNTIME_DEPENDENCY_SET) 命令支持的以下任何关键字

  • DIRECTORIES

  • PRE_INCLUDE_REGEXES

  • PRE_EXCLUDE_REGEXES

  • POST_INCLUDE_REGEXES

  • POST_EXCLUDE_REGEXES

  • POST_INCLUDE_FILES

  • POST_EXCLUDE_FILES

RUNTIME_DEPENDENCIES 和 RUNTIME_DEPENDENCY_SET 关键字互斥。

可以将被安装目标列在接口库中。 它们不安装任何工件，但会包含在相关的 EXPORT 中。 如果对象库被列出，但没有为其对象文件指定目标位置，它们将被导出为接口库。 这足以满足链接到其实现中的对象库的其他目标的可传递使用要求。

安装目标时，如果目标的 EXCLUDE_FROM_ALL 属性设置为 TRUE，则行为未定义。

3.3 版本新增: 作为 DESTINATION 参数给定的安装目标位置可以使用“生成器表达式”，语法为 $<...>。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。

3.13 版本新增: install(TARGETS) 可以安装在其他目录中创建的目标。 当使用此类跨目录安装规则时，从子目录运行 make install （或类似命令）不能保证其他目录中的目标是最新的。 您可以使用 target_link_libraries() 或 add_dependencies() 来确保在运行特定于子目录的安装规则之前构建此类目录外的目标。

install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])

在 3.21 版本中添加。

安装导入目标的运行时工件

install(IMPORTED_RUNTIME_ARTIFACTS <target>...
        [RUNTIME_DEPENDENCY_SET <set-name>]
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        )

IMPORTED_RUNTIME_ARTIFACTS 形式指定了安装导入目标的运行时工件的规则。 如果项目希望将其外部可执行文件或模块捆绑在其安装中，则可以使用此形式。 LIBRARY、RUNTIME、FRAMEWORK 和 BUNDLE 参数具有与 TARGETS 模式中相同的语义。 仅安装导入目标的运行时工件（FRAMEWORK 库、MACOSX_BUNDLE 可执行文件和 BUNDLE CFBundle 除外）。 例如，与 DLL 关联的头文件和导入库不会被安装。 对于 FRAMEWORK 库、MACOSX_BUNDLE 可执行文件和 BUNDLE CFBundle，将安装整个目录。

RUNTIME_DEPENDENCY_SET 选项使导入的可执行文件、共享库和模块库 targets 的运行时工件被添加到 <set-name> 运行时依赖集中。 然后可以使用 install(RUNTIME_DEPENDENCY_SET) 命令安装此集合。

install(FILES <file>... [...])
install(PROGRAMS <program>... [...])

注意

如果要安装头文件，请考虑使用由 target_sources(FILE_SET) 定义的文件集。 文件集将头文件与目标关联，并作为目标的一部分安装。

安装文件或程序

install(<FILES|PROGRAMS> <file>...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

FILES 形式指定了安装项目文件的规则。 以相对路径给出的文件名相对于当前源目录进行解释。 默认情况下，如果未给出 PERMISSIONS 参数，则由此形式安装的文件将被赋予 OWNER_WRITE、OWNER_READ、GROUP_READ 和 WORLD_READ 权限。

PROGRAMS 形式与 FILES 形式相同，只是安装文件的默认权限还包括 OWNER_EXECUTE、GROUP_EXECUTE 和 WORLD_EXECUTE。 此形式旨在安装非目标程序的程序，例如 shell 脚本。 使用 TARGETS 形式安装在项目内构建的目标。

提供给 FILES 或 PROGRAMS 的 files... 列表可以使用“生成器表达式”，语法为 $<...>。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。 但是，如果任何项以生成器表达式开头，则它必须评估为完整路径。

可选的 RENAME <name> 参数用于为已安装的文件指定与原始文件名不同的名称。 仅当命令安装单个文件时才允许重命名。

必须提供 TYPE 或 DESTINATION，但不能同时提供两者。 TYPE 参数指定要安装的文件的通用文件类型。 然后将通过从 GNUInstallDirs 中获取相应的变量，或者在未定义该变量时使用内置默认值来自动设置目标位置。 请参阅下表，了解支持的文件类型及其对应的变量和内置默认值。 如果项目希望显式定义安装目标位置，则可以提供 DESTINATION 参数来代替文件类型。

TYPE 参数

GNUInstallDirs 变量

内置默认值

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

LIBEXEC

${CMAKE_INSTALL_LIBEXECDIR}

libexec

希望遵循将头文件安装到项目特定子目录的常见做法的项目，将需要提供目标位置，而不是依赖上述类型。 使用文件集来处理头文件而不是 install(FILES) 会更好（请参阅 target_sources(FILE_SET)）。

请注意，某些类型的内置默认值使用 DATAROOT 目录作为前缀。 DATAROOT 前缀的计算方式与类型类似，变量为 CMAKE_INSTALL_DATAROOTDIR，内置默认值为 share。 您不能将 DATAROOT 用作 TYPE 参数； 请改用 DATA。

为了使软件包符合发行版文件系统布局策略，如果项目必须指定 DESTINATION，强烈建议他们使用以适当的相对 GNUInstallDirs 变量开头的路径。 这允许软件包维护者通过设置适当的缓存变量来控制安装目标位置。 以下示例显示了如何在将图像安装到项目特定的文档子目录时遵循此建议

include(GNUInstallDirs)
install(FILES logo.png
        DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)

3.4 版本新增: 作为 DESTINATION 参数给定的安装目标位置可以使用“生成器表达式”，语法为 $<...>。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。

3.20 版本新增: 作为 RENAME 参数给定的安装重命名可以使用“生成器表达式”，语法为 $<...>。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。

3.31 版本新增: TYPE 参数现在支持类型 LIBEXEC。

install(DIRECTORY <dir>... [...])

注意

要安装头文件的目录子树，请考虑使用由 target_sources(FILE_SET) 定义的文件集。 文件集不仅保留目录结构，它们还将头文件与目标关联，并作为目标的一部分安装。

安装一个或多个目录的内容

install(DIRECTORY dirs...
        TYPE <type> | DESTINATION <dir>
        [FILE_PERMISSIONS <permission>...]
        [DIRECTORY_PERMISSIONS <permission>...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS <permission>...]] [...])

DIRECTORY 形式将一个或多个目录的内容安装到给定的目标位置。 目录结构将原封不动地复制到目标位置。 每个目录名称的最后一个组成部分都会附加到目标目录，但可以使用尾部斜杠来避免这种情况，因为它会使最后一个组成部分为空。 以相对路径给出的目录名称相对于当前源目录进行解释。 如果未给出任何输入目录名称，则将创建目标目录，但不会在其中安装任何内容。 FILE_PERMISSIONS 和 DIRECTORY_PERMISSIONS 选项指定赋予目标位置中文件和目录的权限。 如果指定了 USE_SOURCE_PERMISSIONS 并且未指定 FILE_PERMISSIONS，则文件权限将从源目录结构复制。 如果未指定任何权限，则文件将获得命令的 FILES 形式中指定的默认权限，目录将获得命令的 PROGRAMS 形式中指定的默认权限。

3.1 版本新增: MESSAGE_NEVER 选项禁用文件安装状态输出。

可以使用 PATTERN 或 REGEX 选项精细地控制目录的安装。 这些“匹配”选项指定用于匹配输入目录中遇到的目录或文件的 globbing 模式或正则表达式。 它们可用于将某些选项（见下文）应用于遇到的文件和目录的子集。 每个输入文件或目录的完整路径（带有正斜杠）都将与表达式进行匹配。 PATTERN 将仅匹配完整的文件名：与模式匹配的完整路径部分必须出现在文件名的末尾，并且前面必须有一个斜杠。 REGEX 将匹配完整路径的任何部分，但它可以使用 / 和 $ 来模拟 PATTERN 行为。 默认情况下，无论是否匹配，所有文件和目录都会被安装。 可以在第一个匹配选项之前给出 FILES_MATCHING 选项，以禁用安装任何表达式未匹配的文件（但不包括目录）。 例如，代码

install(DIRECTORY src/ DESTINATION doc/myproj
        FILES_MATCHING PATTERN "*.png")

将从源树中提取并安装图像。

某些选项可以跟随 PATTERN 或 REGEX 表达式，如 string(REGEX) 下所述，并且仅应用于与它们匹配的文件或目录。 EXCLUDE 选项将跳过匹配的文件或目录。 PERMISSIONS 选项会覆盖匹配的文件或目录的权限设置。 例如，代码

install(DIRECTORY icons scripts/ DESTINATION share/myproj
        PATTERN "CVS" EXCLUDE
        PATTERN "scripts/*"
        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
                    GROUP_EXECUTE GROUP_READ)

会将 icons 目录安装到 share/myproj/icons，并将 scripts 目录安装到 share/myproj。 图标将获得默认文件权限，脚本将获得特定权限，并且任何 CVS 目录都将被排除。

必须提供 TYPE 或 DESTINATION，但不能同时提供两者。 TYPE 参数指定要安装的所列目录中的文件的通用文件类型。 然后将通过从 GNUInstallDirs 中获取相应的变量，或者在未定义该变量时使用内置默认值来自动设置目标位置。 请参阅下表，了解支持的文件类型及其对应的变量和内置默认值。 如果项目希望显式定义安装目标位置，则可以提供 DESTINATION 参数来代替文件类型。

TYPE 参数

GNUInstallDirs 变量

内置默认值

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

LIBEXEC

${CMAKE_INSTALL_LIBEXECDIR}

libexec

请注意，某些类型的内置默认值使用 DATAROOT 目录作为前缀。 DATAROOT 前缀的计算方式与类型类似，变量为 CMAKE_INSTALL_DATAROOTDIR，内置默认值为 share。 您不能将 DATAROOT 用作 TYPE 参数； 请改用 DATA。

为了使软件包符合发行版文件系统布局策略，如果项目必须指定 DESTINATION，强烈建议他们使用以适当的相对 GNUInstallDirs 变量开头的路径。 这允许软件包维护者通过设置适当的缓存变量来控制安装目标位置。

3.4 版本新增: 作为 DESTINATION 参数给定的安装目标位置可以使用“生成器表达式”，语法为 $<...>。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。

3.5 版本新增: 提供给 DIRECTORY 的 dirs... 列表也可以使用“生成器表达式”。

3.31 版本新增: TYPE 参数现在支持类型 LIBEXEC。

install(SCRIPT <file> [...])
install(CODE <code> [...])

在安装期间调用 CMake 脚本或代码

install([[SCRIPT <file>] [CODE <code>]]
        [ALL_COMPONENTS | COMPONENT <component>]
        [EXCLUDE_FROM_ALL] [...])

SCRIPT 形式将在安装期间调用给定的 CMake 脚本文件。 如果脚本文件名是相对路径，则它将相对于当前源目录进行解释。 CODE 形式将在安装期间调用给定的 CMake 代码。 代码在双引号字符串中指定为单个参数。 例如，代码

install(CODE "message(\"Sample install message.\")")

将在安装期间打印一条消息。

3.21 版本新增: 当给出 ALL_COMPONENTS 选项时，自定义安装脚本代码将为组件特定的安装的每个组件执行。 此选项与 COMPONENT 选项互斥。

3.14 版本新增: <file> 或 <code> 可以使用“生成器表达式”，语法为 $<...>（对于 <file>，这是指它们在文件名中的使用，而不是文件的内容）。 请参阅 cmake-generator-expressions(7) 手册，了解可用的表达式。

install(EXPORT <export-name> [...])

安装 CMake 文件，导出目标以供依赖项目使用

install(EXPORT <export-name> DESTINATION <dir>
        [NAMESPACE <namespace>] [FILE <name>.cmake]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [CXX_MODULES_DIRECTORY <directory>]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL]
        [EXPORT_PACKAGE_DEPENDENCIES])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

EXPORT 形式生成并安装一个 CMake 文件，其中包含将安装树中的目标导入到另一个项目的代码。 目标安装使用上述 install(TARGETS) 签名的 EXPORT 选项与导出 <export-name> 关联。 NAMESPACE 选项会将 <namespace> 前置到写入导入文件的目标名称。 默认情况下，生成的文件将名为 <export-name>.cmake，但可以使用 FILE 选项指定不同的名称。 提供给 FILE 选项的值必须是带有 .cmake 扩展名的文件名。

如果给出了 CONFIGURATIONS 选项，则仅当安装了命名的配置之一时，才会安装该文件。 此外，生成的导入文件将仅引用匹配的目标配置。 请参阅 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> 变量，以将依赖项目的配置映射到已安装的配置。 如果存在 EXPORT_LINK_INTERFACE_LIBRARIES 关键字，则当策略 CMP0022 为 NEW 时，将导出与 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? 匹配的属性内容。

注意

安装的 <export-name>.cmake 文件可能带有附加的每个配置的 <export-name>-*.cmake 文件，这些文件将通过 globbing 加载。 请勿使用与软件包名称相同的导出名称，并结合安装 <package-name>-config.cmake 文件，否则后者可能会被 glob 错误地匹配并加载。

当给出 COMPONENT 选项时，列出的 <component> 隐式依赖于导出集中提到的所有组件。 导出的 <name>.cmake 文件将要求每个导出的组件都存在，以便依赖项目能够正确构建。 例如，一个项目可以定义组件 Runtime 和 Development，其中共享库进入 Runtime 组件，静态库和头文件进入 Development 组件。 导出集通常也是 Development 组件的一部分，但它将导出 Runtime 和 Development 组件的目标。 因此，如果安装了 Development 组件，则需要安装 Runtime 组件，反之则不然。 如果在没有 Runtime 组件的情况下安装了 Development 组件，则尝试链接到它的依赖项目将出现构建错误。 诸如 APT 和 RPM 之类的软件包管理器通常通过在软件包元数据中将 Runtime 组件列为 Development 组件的依赖项来处理此问题，从而确保在头文件和 CMake 导出文件存在时始终安装库。

3.7 版本新增: 除了 cmake 语言文件之外，EXPORT_ANDROID_MK 模式还可用于指定导出到 android ndk 构建系统。 此模式接受与普通导出模式相同的选项。 Android NDK 支持使用预构建库，包括静态库和共享库。 这允许 cmake 构建项目的库，并使它们可用于 ndk 构建系统，并提供使用库所需的传递依赖项、包含标志和宏定义。

CXX_MODULES_DIRECTORY

在 3.28 版本中添加。

指定一个子目录，用于存储导出集中目标的 C++ 模块信息。 此目录将填充文件，这些文件将必要的目标属性信息添加到相关目标。 请注意，如果没有此信息，导出集中目标的任何 C++ 模块都不支持在消费目标中导入。

EXPORT_PACKAGE_DEPENDENCIES

注意

实验性的。 受 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES 控制。

指定应导出 find_dependency() 调用。如果指定此参数，CMake 将检查导出集中的所有目标，并收集它们的 INTERFACE 链接目标。如果任何此类目标是通过 find_package() 找到的，或者设置了 EXPORT_FIND_PACKAGE_NAME 属性，并且此类包依赖项未通过将 ENABLED OFF 传递给 export(SETUP) 禁用，则会写入一个 find_dependency() 调用，其中包含目标的相应包名称、REQUIRED 参数以及 export(SETUP) 的 EXTRA_ARGS 参数指定的任何其他参数。通过将 ENABLED ON 传递给 export(SETUP) 手动指定的任何包依赖项也会被添加，即使导出的目标不依赖于来自它们的任何目标。

find_dependency() 调用按以下顺序写入

  1. 在 export(SETUP) 中列出的任何包依赖项都按照它们首次指定的顺序写入，无论它们是否包含导出目标的 INTERFACE 依赖项。

  2. 任何包含导出目标的 INTERFACE 链接依赖项，并且从未在 export(SETUP) 中指定的包依赖项，都按照它们首次被发现的顺序写入。

EXPORT 形式对于帮助外部项目使用当前项目构建和安装的目标非常有用。例如，以下代码

install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)

会将可执行文件 myexe 安装到 <prefix>/bin，并将导入它的代码安装到文件 <prefix>/lib/myproj/myproj.cmake 和 <prefix>/share/ndk-modules/Android.mk 中。外部项目可以使用 include 命令加载此文件，并使用导入的目标名称 mp_myexe 从安装树引用 myexe 可执行文件，就好像该目标是在其自己的树中构建的一样。

install(PACKAGE_INFO <package-name> [...])

在版本 3.31 中添加。

注意

实验性的。由 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO 控制。

安装一个 通用包规范 文件，用于导出依赖项目的目标

install(PACKAGE_INFO <package-name> EXPORT <export-name>
        [APPENDIX <appendix-name>]
        [DESTINATION <dir>]
        [LOWER_CASE_FILE]
        [VERSION <version>
         [COMPAT_VERSION <version>]
         [VERSION_SCHEMA <string>]]
        [DEFAULT_TARGETS <target>...]
        [DEFAULT_CONFIGURATIONS <config>...]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])

PACKAGE_INFO 形式生成并安装一个通用包规范文件，该文件描述了已安装的目标，以便它们可以被另一个项目使用。目标安装使用上面记录的 install(TARGETS) 签名的 EXPORT 选项与导出 <export-name> 关联。与 install(EXPORT) 不同，此信息不是用 CMake 代码表达的，可以被 CMake 以外的工具使用。当导入到另一个 CMake 项目中时，导入的目标将以 <package-name>:: 为前缀。默认情况下，生成的文件将被称为 <package-name>[-<appendix-name>].cps。如果给定 LOWER_CASE_FILE，则磁盘上显示的包名称（在文件名和安装目标中）将首先转换为小写。

如果未指定 DESTINATION，则使用平台特定的默认值。

如果指定了 APPENDIX，则不是生成顶级包规范，而是将指定的目标导出为命名包的附录。附录可用于将不太常用的目标（及其外部依赖项）与包的其余部分分开。这使使用者可以忽略他们不使用的目标的传递依赖项，并且还允许单个逻辑“包”由多个构建树生成的工件组成。

附录不允许更改基本包元数据；因此，VERSION、COMPAT_VERSION、VERSION_SCHEMA、DEFAULT_TARGETS 或 DEFAULT_CONFIGURATIONS 都不得与 APPENDIX 组合使用。此外，强烈建议在主包和任何附录之间保持 LOWER_CASE_FILE 使用的一致性。

install(RUNTIME_DEPENDENCY_SET <set-name> [...])

在 3.21 版本中添加。

安装运行时依赖项集合

install(RUNTIME_DEPENDENCY_SET <set-name>
        [[LIBRARY|RUNTIME|FRAMEWORK]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        [PRE_INCLUDE_REGEXES <regex>...]
        [PRE_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_REGEXES <regex>...]
        [POST_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_FILES <file>...]
        [POST_EXCLUDE_FILES <file>...]
        [DIRECTORIES <dir>...]
        )

安装先前由一个或多个 install(TARGETS) 或 install(IMPORTED_RUNTIME_ARTIFACTS) 命令创建的运行时依赖项集合。属于运行时依赖项集合的目标的依赖项安装在 DLL 平台上的 RUNTIME 目标和组件中，以及非 DLL 平台上的 LIBRARY 目标和组件中。macOS 框架安装在 FRAMEWORK 目标和组件中。构建树中构建的目标永远不会作为运行时依赖项安装，它们自身的依赖项也不会，除非目标本身是通过 install(TARGETS) 安装的。

生成的安装脚本在构建树文件上调用 file(GET_RUNTIME_DEPENDENCIES)，以计算运行时依赖项。构建树可执行文件作为 EXECUTABLES 参数传递，构建树共享库作为 LIBRARIES 参数传递，构建树模块作为 MODULES 参数传递。在 macOS 上，如果其中一个可执行文件是 MACOSX_BUNDLE，则该可执行文件将作为 BUNDLE_EXECUTABLE 参数传递。在 macOS 上，运行时依赖项集合中最多可以有一个此类捆绑可执行文件。MACOSX_BUNDLE 属性在其他平台上无效。请注意，file(GET_RUNTIME_DEPENDENCIES) 仅支持收集 Windows、Linux 和 macOS 平台的运行时依赖项，因此 install(RUNTIME_DEPENDENCY_SET) 也具有相同的限制。

以下子参数作为 file(GET_RUNTIME_DEPENDENCIES) 的相应参数转发（对于那些提供非空目录列表、正则表达式或文件的参数）。它们都支持 generator expressions。

  • DIRECTORIES <dir>...

  • PRE_INCLUDE_REGEXES <regex>...

  • PRE_EXCLUDE_REGEXES <regex>...

  • POST_INCLUDE_REGEXES <regex>...

  • POST_EXCLUDE_REGEXES <regex>...

  • POST_INCLUDE_FILES <file>...

  • POST_EXCLUDE_FILES <file>...

注意

此命令取代了 install_targets() 命令以及 PRE_INSTALL_SCRIPT 和 POST_INSTALL_SCRIPT 目标属性。它还取代了 install_files() 和 install_programs() 命令的 FILES 形式。这些安装规则相对于由 install_targets()、install_files() 和 install_programs() 命令生成的规则的处理顺序未定义。

示例

示例：安装具有每个工件组件的目标

考虑一个项目，该项目定义了具有不同工件种类的目标

add_executable(myExe myExe.c)
add_library(myStaticLib STATIC myStaticLib.c)
target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
add_library(mySharedLib SHARED mySharedLib.c)
target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
set_property(TARGET mySharedLib PROPERTY SOVERSION 1)

我们可以使用带有 <artifact-kind> 参数的 install(TARGETS) 调用来为每种工件种类指定不同的选项

install(TARGETS
          myExe
          mySharedLib
          myStaticLib
        RUNTIME           # Following options apply to runtime artifacts.
          COMPONENT Runtime
        LIBRARY           # Following options apply to library artifacts.
          COMPONENT Runtime
          NAMELINK_COMPONENT Development
        ARCHIVE           # Following options apply to archive artifacts.
          COMPONENT Development
          DESTINATION lib/static
        FILE_SET HEADERS  # Following options apply to file set HEADERS.
          COMPONENT Development
        )

这将

  • 将 myExe 安装到 <prefix>/bin，默认的 RUNTIME 工件目标，作为 Runtime 组件的一部分。

  • 在非 DLL 平台上

    • 将 libmySharedLib.so.1 安装到 <prefix>/lib，默认的 LIBRARY 工件目标，作为 Runtime 组件的一部分。

    • 将 libmySharedLib.so “名称链接”（符号链接）安装到 <prefix>/lib，默认的 LIBRARY 工件目标，作为 Development 组件的一部分。

  • 在 DLL 平台上

    • 将 mySharedLib.dll 安装到 <prefix>/bin，默认的 RUNTIME 工件目标，作为 Runtime 组件的一部分。

    • 将 mySharedLib.lib 安装到 <prefix>/lib/static，指定的 ARCHIVE 工件目标，作为 Development 组件的一部分。

  • 将 myStaticLib 安装到 <prefix>/lib/static，指定的 ARCHIVE 工件目标，作为 Development 组件的一部分。

  • 将 mySharedLib.h 和 myStaticLib.h 安装到 <prefix>/include，类型为 HEADERS 的文件集的默认目标，作为 Development 组件的一部分。

示例：将目标安装到每个配置的目标

每个 install(TARGETS) 调用最多将给定的目标 输出工件 安装到一个 DESTINATION，但安装规则本身可能会被 CONFIGURATIONS 选项过滤。为了为每个配置安装到不同的目标，每个配置需要一个调用。例如，以下代码

install(TARGETS myExe
        CONFIGURATIONS Debug
        RUNTIME
          DESTINATION Debug/bin
        )
install(TARGETS myExe
        CONFIGURATIONS Release
        RUNTIME
          DESTINATION Release/bin
        )

将在 Debug 配置中将 myExe 安装到 <prefix>/Debug/bin，并在 Release 配置中安装到 <prefix>/Release/bin。

生成的安装脚本

注意

不建议使用此功能。请考虑改用 cmake --install。

install() 命令在构建目录内生成一个文件 cmake_install.cmake，该文件由生成的 install 目标和 CPack 在内部使用。您还可以使用 cmake -P 手动调用此脚本。此脚本接受几个变量

COMPONENT

设置此变量以仅安装单个 CPack 组件，而不是全部安装。例如，如果您只想安装 Development 组件，请运行 cmake -DCOMPONENT=Development -P cmake_install.cmake。

BUILD_TYPE

如果您使用的是多配置生成器，请设置此变量以更改构建类型。例如，要使用 Debug 配置进行安装，请运行 cmake -DBUILD_TYPE=Debug -P cmake_install.cmake。

DESTDIR

这是一个环境变量，而不是 CMake 变量。它允许您在 UNIX 系统上更改安装前缀。有关详细信息，请参阅 DESTDIR。