CMAKE_INSTALL_MODE

3.22 版本新增。

这是一个 CMake 环境变量。其初始值取自调用进程环境。

CMAKE_INSTALL_MODE 环境变量允许用户以 file(INSTALL)install() 的替代模式操作 CMake。

安装的默认行为是将源文件从源目录复制到目标目录。然而,此环境变量允许用户覆盖此行为,使 CMake 转而创建符号链接。

使用场景

安装符号链接而不是复制文件可以通过以下方式提供帮助:

  • 节省存储空间,因为文件不必在磁盘上重复。

  • 符号链接源的更改会在安装目标处显示,而无需重新运行安装步骤。

  • 通过安装目标处的链接进行编辑将修改链接的源。这在处理 CMake 项目层次结构时可能很有用,例如使用 ExternalProject 并且需要在项目之间进行一致的源导航和重构时。

允许的值

以下值允许用于 CMAKE_INSTALL_MODE

COPY,空或未设置

在目标处复制文件。这是默认行为。

ABS_SYMLINK

在目标处创建源文件的*绝对*符号链接。如果无法创建链接,则报错并停止。

ABS_SYMLINK_OR_COPY

类似于 ABS_SYMLINK,但如果无法创建符号链接,则默默地回退到复制。

REL_SYMLINK

在目标处创建源文件的*相对*符号链接。如果无法创建链接,则报错并停止。

REL_SYMLINK_OR_COPY

类似于 REL_SYMLINK,但如果无法创建符号链接,则默默地回退到复制。

SYMLINK

尝试通过 REL_SYMLINK,如果无法使用相对路径表示引用的文件,则回退到 ABS_SYMLINK。如果无法创建链接,则报错并停止。

SYMLINK_OR_COPY

类似于 SYMLINK,但如果无法创建符号链接,则默默地回退到复制。

注意

符号链接由引用文件路径而不是其自身内容组成,因此有两种方式表达这种关系,即通过*相对*路径或*绝对*路径。

何时设置环境变量

为了使环境变量生效,它必须在正确的构建阶段设置。

  • 如果项目直接调用 file(INSTALL),则环境变量必须在配置阶段设置。

  • 为了应用于 install(),环境变量必须在安装期间设置。这可以在构建期间(如果使用 installpackage 构建目标)或独立于构建时(在调用安装或从命令行运行 cpack 时)进行。

  • 使用 ExternalProject 时,它可能在构建阶段需要,因为外部项目自身的配置、构建和安装步骤将在主项目的构建阶段执行。

鉴于上述情况,建议在所有阶段(配置、构建和安装)一致地设置环境变量。

注意事项

请谨慎使用此环境变量。以下强调了一些需要考虑的要点:

  • CMAKE_INSTALL_MODE 仅影响文件,不影响目录。

  • 并非所有平台都支持符号链接。

  • 此环境变量与 ExternalProject 的安装步骤的交互更为复杂。有关更多详细信息,请参阅该模块的文档。

  • 符号链接以持久的方式将目标与源绑定。写入两者中的任何一个都会影响两个文件系统对象。这与正常的安装行为形成对比,后者仅复制文件在安装时它们的样子,源和安装目标之间没有持久的关系。

  • 不支持将 CMAKE_INSTALL_MODEIOS_INSTALL_COMBINED 结合使用。

  • 更改 CMAKE_INSTALL_MODE 与之前运行时的值不同可能导致意外结果。从非符号链接模式切换到符号链接模式将丢弃目标处的任何先前文件,但反之则不然。一旦符号链接存在于目标处,即使您切换到非符号链接模式,该符号链接也将继续存在于目标处,并且不会被实际文件替换。