CMake 046：进阶目录安装

软件科学_郝学胜
0 阅读8分钟

玩 CMake 项目部署的小伙伴，大概率都踩过一个经典坑：批量安装项目目录资源时，要么全量拷贝冗余文件，要么手动写一堆文件列表，繁琐又低效。

日常开发中，我们经常需要部署整套资源目录、源码文件夹、网页静态资源等，这类目录往往嵌套多层子目录、包含数十个不同后缀的文件。如果沿用基础的 install(FILES) 逐个指定文件，不仅代码臃肿冗余，后续新增文件还需要手动维护，极其不灵活。

今天就给大家深度拆解 CMake 专属的目录安装神器：install(DIRECTORY)，手把手教大家实现「全量拷贝、按后缀精准筛选、排除冗余目录、组合过滤」四大核心能力，彻底告别手动罗列文件的低效操作，适配绝大多数项目部署场景💻。

Bilibili 同步视频

CMake 046：进阶目录安装

一、为什么要用目录安装？告别低效硬编码

先简单复盘 CMake 基础安装逻辑的痛点：

传统的文件安装指令 install(FILES)，有一个硬性限制：必须手动罗列每一个需要安装的文件路径。

如果是单个、少量文件，这种方式完全够用。但如果是一整个资源目录、源码目录，内部包含多层子目录、各类格式文件，逐个书写文件列表会出现两个致命问题：

  • 代码维护成本极高：目录新增/删除文件、子目录，必须同步修改 CMake 脚本，极易遗漏出错；

  • 无法批量适配动态文件：项目迭代中动态生成的文件，无法通过固定列表匹配。

而 install(DIRECTORY) 的诞生，就是为了完美解决目录批量部署问题，支持递归遍历子目录、自定义文件筛选、冗余内容排除，一键搞定整套目录安装，是项目打包、部署、发布的核心刚需语法。

二、install(DIRECTORY) 核心语法全解析

1. 基础语法结构

该指令整体逻辑简洁清晰，核心参数分为「源目录、目标路径、权限配置、过滤规则」四大模块，基础格式如下：

# CMake 目录安装基础语法
install(DIRECTORY 源目录路径
    [TYPE 系统预设类型 | DESTINATION 自定义目标路径]
    [FILE_PERMISSIONS 文件权限]
    [DIRECTORY_PERMISSIONS 目录权限]
    [FILES_MATCHING]
    [PATTERN 匹配规则]
    [EXCLUDE 排除规则]
)

2. 核心参数通俗解读

为了方便大家理解，我用通俗的语言拆解每个关键参数，避开晦涩官方文档：

  • 源目录路径：需要部署的本地项目目录，支持相对路径、绝对路径；

  • 目标路径二选一

    • TYPE 类型：沿用 CMake 预设路径，比如TYPE DOC 自动安装到文档目录，和基础文件安装规则完全一致，开箱即用；

    • DESTINATION 路径：自定义安装输出目录，灵活性更高，适配自定义部署场景；

  • 权限配置：文件和目录权限分开独立设置，支持自定义读写执行权限，也可直接继承源文件原始权限，完美适配服务器、嵌入式等权限严格的场景；

  • 默认特性：无过滤规则时，会递归拷贝整个目录，自动创建所有子目录，拷贝目录内全部文件。

三、三大核心实操场景（附完整可运行代码）

理论说完直接上干货！下面结合真实开发场景，从「全量拷贝」到「精准过滤」，层层递进演示核心用法，所有代码可直接复制运行。

场景一：完整目录全量安装（基础用法）

适用场景：需要完整部署静态资源、配置文件夹，目录内所有文件、子目录都需要保留。

我们提前创建测试目录 doc，内部包含 html 静态文件、cc/c 源码文件、多级子目录，通过以下脚本实现全量安装：

# CMakeLists.txt 完整目录全量安装
cmake_minimum_required(VERSION 3.10)
project(DirInstallDemo)

# 设置安装根路径
set(CMAKE_INSTALL_PREFIX ./build/install)

# 方式1：通过TYPE预设类型安装
install(DIRECTORY doc
    TYPE DOC
)

# 方式2：通过DESTINATION自定义路径安装
install(DIRECTORY doc
    DESTINATION doc2
)

运行效果：两种方式都会递归拷贝 doc 目录下所有文件、所有子目录，目录结构、文件内容完全保留，无任何遗漏。

场景二：按后缀筛选文件（精准提取指定资源）

适用场景：只需要部署指定类型文件，比如仅拷贝网页 html/htm 资源、仅导出 cc/c/h 源码文件，过滤掉日志、配置、临时文件等冗余内容。

核心关键字：FILES_MATCHING + PATTERN，支持多后缀同时匹配，灵活度极高。

# 仅筛选安装 html、htm 网页文件
install(DIRECTORY doc
    DESTINATION html_doc
    FILES_MATCHING
    # 匹配多种后缀文件
    PATTERN "*.html"
    PATTERN "*.htm"
)

关键特性解读（避坑重点❗）

很多新手会误解过滤规则，这里重点划重点：

  1. 目录一定会保留：即使子目录内没有匹配的文件，系统依然会自动创建完整的目录结构；

  2. 文件精准过滤：仅拷贝匹配后缀的文件，其余格式文件直接跳过；

  3. 支持多规则叠加：可无限新增 PATTERN 匹配不同后缀，适配复杂资源场景。

场景三：排除冗余目录（过滤版本控制文件）

适用场景：项目打包发布、源码部署时，需要剔除 .git、.svn 等版本控制隐藏目录，避免冗余文件、隐私配置被打包发布。

核心关键字：EXCLUDE，命中规则的目录/文件会完全跳过，不创建、不拷贝。

# 安装目录并排除 git、svn 版本控制目录
install(DIRECTORY doc
    DESTINATION clean_doc
    PATTERN ".git" EXCLUDE
    PATTERN ".svn" EXCLUDE
)

运行效果：正常文件、子目录全部保留，唯独 .git、.svn 隐藏目录被彻底过滤，打包后的资源干净无冗余。

场景四：筛选+排除组合使用（高阶精准部署）

真实开发中，最常用的就是双重过滤组合：既要精准提取指定源码文件，又要排除版本控制冗余目录，实现极致精准的项目部署。

需求示例：仅拷贝项目 cc/c/h 源码文件，同时剔除 git、svn 版本目录，适配源码发布场景。

# 组合用法：筛选源码文件 + 排除版本目录
install(DIRECTORY src
    DESTINATION release_src
    FILES_MATCHING
    # 仅匹配源码后缀
    PATTERN "*.cc"
    PATTERN "*.c"
    PATTERN "*.h"
    # 排除版本控制冗余目录
    PATTERN ".git" EXCLUDE
    PATTERN ".svn" EXCLUDE
)

四、配套 C++ 测试代码（完整可落地）

为了让大家完整跑通整个流程，我补充一段简单的 C++ 测试代码，搭配目录安装脚本，可直接编译部署，验证整体效果。

新建 main.cc 测试程序：

#include <iostream>
using namespace std;

int main()
{
    cout << "CMake 目录安装测试程序运行成功！" << endl;
    cout << "已完成资源目录精准部署，过滤冗余文件！" << endl;
    return 0;
}

补充可编译、可安装的完整 CMake 脚本（整合所有功能）：

cmake_minimum_required(VERSION 3.10)
project(DirInstallTest)

# 设置C++标准
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 设置全局安装路径
set(CMAKE_INSTALL_PREFIX ./output)

# 编译可执行程序
add_executable(test main.cc)

# 1. 全量安装doc目录
install(DIRECTORY doc DESTINATION all_doc)

# 2. 仅安装网页资源
install(DIRECTORY doc DESTINATION html_doc
    FILES_MATCHING PATTERN "*.html" PATTERN "*.htm"
)

# 3. 过滤版本控制目录
install(DIRECTORY doc DESTINATION clean_doc
    PATTERN ".git" EXCLUDE PATTERN ".svn" EXCLUDE
)

# 4. 源码精准部署（筛选+排除）
install(DIRECTORY doc DESTINATION src_release
    FILES_MATCHING PATTERN "*.cc" PATTERN "*.c" PATTERN "*.h"
    PATTERN ".git" EXCLUDE PATTERN ".svn" EXCLUDE
)

# 安装可执行程序
install(TARGETS test RUNTIME DESTINATION bin)

五、完整编译部署指令

终端执行以下命令，一键完成编译、安装，查看最终部署效果：

# 创建构建目录
mkdir build && cd build

# 生成构建文件
cmake ..

# 编译项目
make -j4

# 执行安装（核心步骤）
cmake --install .

执行完成后，output 目录下会生成四类不同过滤规则的部署资源，清晰验证所有功能特性✅。

六、核心知识点总结（精华速记）

最后给大家整理一份极简速查表，方便日常开发直接复用：

  1. 基础特性：install(DIRECTORY) 默认递归拷贝所有子目录、文件，完美适配整目录部署；

  2. 文件筛选：搭配 FILES_MATCHING + PATTERN，精准提取指定后缀文件，目录结构完整保留；

  3. 目录排除：搭配 PATTERN + EXCLUDE，彻底剔除冗余、敏感目录，适配项目发布；

  4. 高阶组合：筛选+排除可叠加使用，实现「按需提取、精准过滤」的极致部署效果；

  5. 适用场景：静态资源部署、源码打包发布、嵌入式资源配置、项目迭代自动化部署。

七、写在最后

CMake 的目录安装功能，看似简单，实则是项目自动化部署、打包发布的核心刚需能力。很多小伙伴项目打包冗余、发布资源不干净、手动维护文件列表出错，本质都是没有用好这套过滤规则。

CMake 046：进阶目录安装

掌握「全量拷贝、后缀筛选、目录排除、组合过滤」这四种用法，就能覆盖 99% 的目录部署场景，彻底解放双手，让 CMake 项目部署更高效、更规范、更优雅✨。

avatar
文章
阅读
粉丝