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>... [...])

安装目标 Output Artifacts 及相关文件

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>... 组适用于在同一调用中稍后没有专门组的特定目标 Output Artifacts。

每个 <artifact-kind> <artifact-option>... 组适用于指定类型的 Output Artifacts

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

标记为 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 包和框架必须始终提供目标位置。可以为接口库和对象库省略目标位置，但它们的处理方式不同（请参阅本节末尾关于此主题的讨论）。

对于 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_COMPONENT 选项类似于 COMPONENT 选项，但它会更改共享库名称链接的安装组件（如果生成了名称链接）。如果未指定，则默认为 COMPONENT 的值。在 LIBRARY 块之外使用此参数是错误的。

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

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

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

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

NAMELINK_ONLY

此选项在安装库目标时仅安装名称链接。在没有名称链接或库未带版本号的平台上，NAMELINK_ONLY 选项不安装任何内容。在 LIBRARY 块之外使用此参数是错误的。

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

当给出 NAMELINK_ONLY 时，可以使用 NAMELINK_COMPONENT 或 COMPONENT 来指定名称链接的安装组件，但通常应优先使用 COMPONENT。

NAMELINK_SKIP

类似于 NAMELINK_ONLY，但效果相反：它会在安装库目标时安装名称链接以外的库文件。在没有名称链接或库未带版本号的平台上，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> 时，这些目录将被添加到 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 是互斥的。

Interface Libraries 可以列在要安装的目标中。它们不安装任何工件，但将包含在相关的 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

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 <dir>...
        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]
        [<match-rule> <match-option>...]...
        )

DIRECTORY 形式将一个或多个目录的内容安装到给定的目标位置。目录结构将按原样复制到目标位置。

必须提供 TYPE 或 DESTINATION 中的一个，但不能同时提供。如果未提供权限，文件将获得命令的 FILES 形式中指定的默认权限，目录将获得命令的 PROGRAMS 形式中指定的默认权限。

选项包括

<dir>...

要安装的目录列表。

每个目录名称的最后一个组件将被附加到目标目录，但可以使用尾部斜杠来避免这种情况，因为它会使最后一个组件变为空。作为相对路径给出的目录名称将相对于当前源目录进行解释。如果未给出输入目录名称，则会创建目标目录，但不会向其中安装任何内容。

版本 3.5 中已添加： 源 <dir>... 列表可能使用“生成器表达式”，语法为 $<...>。有关可用表达式，请参阅 cmake-generator-expressions(7) 手册。

TYPE <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。

版本 3.31 中已更改： LIBEXEC 类型。

DESTINATION <dir>

目标目录，如 通用选项 中所述。

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

版本 3.4 中已添加： 目标 <dir> 可能使用“生成器表达式”，语法为 $<...>。有关可用表达式，请参阅 cmake-generator-expressions(7) 手册。

FILE_PERMISSIONS <permission>...

指定授予目标中文件的权限，其中 <permission> 名称在 通用选项 中有说明。

DIRECTORY_PERMISSIONS <permission>...

指定授予目标中目录的权限，其中 <permission> 名称在 通用选项 中有说明。

USE_SOURCE_PERMISSIONS

如果指定且未指定 FILE_PERMISSIONS，则文件权限将从源目录结构复制。

MESSAGE_NEVER

版本 3.1 中新增。

禁用文件安装状态输出。

FILES_MATCHING

可以在第一个 <match-rule> 之前提供此选项，以禁用未被任何表达式匹配的文件（但不包括目录）的安装。例如，以下代码

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

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

<match-rule> <match-option>...

可以使用规则来精细控制目录的安装，这些规则匹配输入目录中遇到的目录或文件。它们可用于将某些选项（见下文）应用于文件和目录的子集。所有文件和目录都将被安装，无论它们是否匹配，除非提供了上面的 FILES_MATCHING 选项。

每个输入文件或目录的完整路径（使用正斜杠）可以由 <match-rule> 匹配。

PATTERN <pattern>

使用 globbing 模式匹配完整文件名。匹配模式的完整路径部分必须出现在文件名末尾，并且前面有一个斜杠（该斜杠不属于模式）。

REGEX <regex>

使用 正则表达式 匹配文件完整路径的任何部分。可以使用 / 和 $ 来限制匹配到路径的末尾。

每个 <match-rule> 后面可以跟 <match-option> 参数。匹配选项适用于由规则匹配的文件或目录。匹配选项为：

EXCLUDE

从安装中排除匹配的文件或目录。

PERMISSIONS <permission>...

覆盖匹配的文件或目录的权限设置。

例如，以下代码：

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 目录将被排除。

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 组件，但反之则不然。如果安装了 Development 组件而未安装 Runtime 组件，则尝试链接它的依赖项目将导致构建错误。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 属性，并且通过向 export(SETUP) 传递 ENABLED OFF 禁用了此类包依赖项，那么将使用该目标的相应包名、REQUIRED 参数以及 export(SETUP) 的 EXTRA_ARGS 参数写入 find_dependency() 调用。即使导出的目标不依赖于它们中的任何目标，通过向 export(SETUP) 传递 ENABLED ON 手动指定的任何包依赖项也会被添加。

生成的 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 控制。

安装 Common Package Specification 文件，导出供依赖项目使用的目标

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

PACKAGE_INFO 形式生成并安装一个 Common Package Specification 文件，该文件描述已安装的目标，以便其他项目可以将其作为使用者。目标安装使用上面文档的 install(TARGETS) 签名的 EXPORT 选项与导出集 <export-name> 关联。与 install(EXPORT) 不同，此信息不以 CMake 代码形式表达，并且可以被 CMake 以外的工具使用。当导入到另一个 CMake 项目时，导入的目标将以 <package-name>:: 为前缀。默认情况下，生成的文件将命名为 <package-name>[-<appendix-name>].cps。如果指定了 LOWER_CASE_FILE，则磁盘上的包名（包括文件名和安装目标）将首先转换为小写。

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

可以使用多个选项来指定包元数据

VERSION <version>

包的版本。 <version> 应符合指定的模式。有关使用者请求包时如何使用包版本的信息，请参阅 版本选择 (CPS)。

COMPAT_VERSION <version>

包提供兼容性的最旧版本。

如果未指定，COMPAT_VERSION 将隐式等于包的 VERSION，也就是说，不提供向后兼容性。

VERSION_SCHEMA <schema>

包的版本号（包括 VERSION 和 COMPAT_VERSION）遵循的模式。虽然如果未提供此选项，则不会将任何模式写入 .cps 文件，但 CPS 指定在这种情况下假定模式为 simple。有关更多详细信息和官方支持的模式列表，请参阅 version_schema，但请注意，该规范可能包含 CMake 不支持的模式。有关 CMake 支持的模式列表，请参阅 版本选择 (CPS)。请参阅 版本选择 (CPS) 了解 find_package() 支持的模式列表。

DEFAULT_TARGETS <target>...

如果使用者请求链接到包名而不是特定组件，则使用的目标。

DEFAULT_CONFIGURATIONS <config>...

当消费者请求的配置与包的可用配置不完全匹配或未映射时，消费者应优先使用的配置的有序列表。如果未指定，CMake 将回退到以未指定顺序的包可用配置。

DESCRIPTION <project-description-string>

在 4.1 版本中新增。

项目的说明性描述。建议此描述为相对较短的字符串，通常不超过几个词。

HOMEPAGE_URL <url-string>

在 4.1 版本中新增。

项目的说明性规范主页 URL。

默认情况下，如果指定的 <package-name> 与当前的 CMake PROJECT_NAME 匹配，则包元数据将从项目继承。可以使用 PROJECT <project-name> 选项指定要从中继承元数据的不同项目。如果指定了 NO_PROJECT_METADATA，则将禁用包元数据的自动继承。在任何情况下，在 install 命令中指定的任何元数据值都将优先。

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

附加项不允许更改基本的包元数据；因此，不能将 PROJECT、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)（对于那些提供非空目录列表、正则表达式或文件的参数）。它们都支持 生成器表达式。

  • 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 “namelink”（符号链接）安装到 <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，该文件由生成的安装目标和 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。