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 变量的值进行解释。可以在安装期间使用 CMAKE_INSTALL_PREFIX 变量文档中说明的 DESTDIR 机制将此前缀重新定位。

由于绝对路径无法用于 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 变量控制默认组件名称。

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 导入库（在所有基于 Windows 的系统上（包括 Cygwin）；它们的扩展名为 .lib，与转到 RUNTIME 的 .dll 库不同）；

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

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

LIBRARY

此类目标工件包括

  • 共享库，但

    • DLL 除外（这些转到 RUNTIME，如下所示），

    • macOS 上标记为 FRAMEWORK 除外（如下所示）。

RUNTIME

此类目标工件包括

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

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

OBJECTS

在 3.9 版本中添加。

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

FRAMEWORK

在 macOS 上，用 FRAMEWORK 属性标记的静态和共享库都被视为 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 将文件 /blah/include/myproj/here.h 添加至文件集，则该文件将安装在目标位置下的 `myproj/here.h`。

CXX_MODULES_BMI

3.28 版中新增。

对于 `CXX_MODULES` 类型的文件集，源自 `PUBLIC` 来源的 C++ 模块中的所有模块文件都将被安装到给定的 `DESTINATION` 中。所有模块都直接放在目标位置，没有从模块名称来推导目录结构。空白 `{DESTINATION}` 可用于禁止安装这些文件（用于通用代码）。

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

对于 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 是允许链接器在给定 -l<name> 时找到库的“namelink”。NAMELINK_COMPONENT 选项与 COMPONENT 选项类似，但如果生成了共享库 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 之后给出的路径直接使用。它们不会规范化，不会假定已规范化，虽然建议以规范化形式给出（请参阅 Normalization）。

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中。如果Object Libraries 已列出，但没有针对其对象文件指定目标位置，则它们将作为 Interface Libraries 导出。这足以满足链接到其实现中的对象库的其他目标的传递使用要求。

安装具有 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 CFBundles 的情形）。例如，与 DLL 关联的头文件和导入库不会被安装。对于 FRAMEWORK 库，MACOSX_BUNDLE 可执行文件和 BUNDLE CFBundles，则整个目录都会被安装。

选项 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 表单指定项目的安装文件规则。以相对路径给出的文件名称相对于当前源目录进行解释。按此表单安装的文件默认被赋予权限 OWNER_WRITE、OWNER_READ、GROUP_READ 和 WORLD_READ，如果未给出 PERMISSIONS 参数的情况除外。

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

数据

${CMAKE_INSTALL_DATADIR}

<DATAROOT 目录>

信息

${CMAKE_INSTALL_INFODIR}

<DATAROOT 目录>/信息

区域设置

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT 目录>/区域设置

手册页

${CMAKE_INSTALL_MANDIR}

<DATAROOT 目录>/手册页

文档

${CMAKE_INSTALL_DOCDIR}

<DATAROOT 目录>/文档

LIBEXEC

${CMAKE_INSTALL_LIBEXECDIR}

libexec

希望遵循将头文件安装到特定于项目的子目录的惯例的项目将需要提供目标，而不是依赖于上述内容。最好使用头文件的文件集而不是 install(FILES) （请参阅 target_sources(FILE_SET)）。

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

为了使软件包与 distribution 文件系统布局策略兼容，如果项目必须指定 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 细化控制目录的安装。这些“匹配”选项指定 glob 模式或正则表达式，以匹配在输入目录中遇到的目录或文件。它们可用于将特定选项（见下文）应用到所遇到的文件和目录的一个子集。每个输入文件或目录的完整路径（带有正斜杠）与表达式进行匹配。 PATTERN 将只匹配完整的文件名：与模式匹配的完整路径部分必须出现在文件名末尾并以斜杠为前缀。 REGEX 将匹配完整路径的任何部分，但它可以使用 / 和 $ 来模拟 PATTERN 行为。默认情况下，所有文件和目录都会安装，无论是否匹配。在第一个匹配选项之前可以给出选项 FILES_MATCHING，以禁用未匹配任何表达式的文件（但不是目录）的安装。例如，代码

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

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

在 string(REGEX) 中所述，某些选项可能会在 PATTERN 或 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)

会在 share/myproj/icons 中安装 icons 目录，会在 share/myproj 中安装 scripts 目录。图标将获得默认的文件权限，脚本将获得特定的权限，并且任何 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

数据

${CMAKE_INSTALL_DATADIR}

<DATAROOT 目录>

信息

${CMAKE_INSTALL_INFODIR}

<DATAROOT 目录>/信息

区域设置

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT 目录>/区域设置

手册页

${CMAKE_INSTALL_MANDIR}

<DATAROOT 目录>/手册页

文档

${CMAKE_INSTALL_DOCDIR}

<DATAROOT 目录>/文档

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

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

注意

已安装的 <export-name>.cmake 文件可能附带其他按配置划分的 <export-name>-*.cmake 文件，这些文件可通过通配符加载。请勿使用与包名称相同的导出名称，同时安装 <package-name>-config.cmake 文件，否则通配符可能错误地匹配后者并加载后者。

给定 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 构建项目的库，并使它们连同使用库所需的传递依赖关系、include 标志和定义一起提供给 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) 来禁用此类软件包依赖项，则会通过目标的相应软件包名称、一个 REQUIRED 参数以及 export(SETUP) 的 EXTRA_ARGS 参数指定的所有其他参数来写入 find_dependency() 调用。尽管导出的目标不依赖于它们的任何目标，但也会添加通过将 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)

会在 <prefix>/bin 中安装可执行文件 myexe，并在文件 <prefix>/lib/myproj/myproj.cmake 和 <prefix>/share/ndk-modules/Android.mk 中安装导入此文件的代码。外部项目可以使用包含命令加载此文件，然后使用导入目标名称 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 表单会生成并安装 Common Package Specification 文件，此文件会描述已安装的目标，以便其他项目可以消耗这些目标。目标安装与导出的 <export-name> 关联，其中使用了上述 install(TARGETS) 签名的 EXPORT 选项。不同于 install(EXPORT)，此信息不是用 CMake 代码表示的，并且可以由 CMake 之外的其他工具使用。将此信息导入到另一个 CMake 项目后，导入目标前缀会被加为 <package-name>::。默认情况下，生成的文件将被命名为 <package-name>[-<appendix-name>].cps。如果给定了 LOWER_CASE_FILE，则磁盘上显示的包名称（在文件名和安装目标中）将首先转换为小写。

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

如果指定了 APPENDIX，则不会生成顶级软件包规范，而是会将指定的目标导出为命名软件包的附录。附录可用于将较少使用的目标（以及其外部依赖关系）与软件包的其余部分分隔开。这使用户能够忽略他们不使用的目标的传递性依赖关系，并且还允许将由多个构建树生成的人工制品组合成一个逻辑“软件包”。

附录不允许更改基本软件包元数据；因此，不能与 APPENDIX 结合使用 VERSION、COMPAT_VERSION、VERSION_SCHEMA、DEFAULT_TARGETS 或 DEFAULT_CONFIGURATIONS。此外，强烈建议在主软件包和任何附录之间一致使用 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)

我们可以调用install(TARGETS)与<artifact-kind>参数一起，以针对每种类型的工件指定不同的选项

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。

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

COMPONENT

设置此变量以仅安装一个 CPack 组件，而无需安装所有组件。例如，如果您只想安装 Development 组件，请运行 cmake -DCOMPONENT=Development -P cmake_install.cmake。

BUILD_TYPE

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

DESTDIR

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