CMake 怎么只构建指定 target

如果项目已经生成过 CMake 构建目录，想只编译其中一个库或可执行文件，核心命令就是 cmake --build --target 。--target 会把构建目标从默认目标切换成指定目标；目标自身需要的依赖仍可能一起构建，但没有被选中的无关目标不会因为这次命令自动加入。

官方地址：https://cmake.org/cmake/help/latest/manual/cmake.1.html

本文按一个常见场景推进：项目里同时有 core_lib、app_cli 和 docs，开发者只想快速重编 app_cli。重点是已生成的 build 目录和目标选择，不展开生成器配置。

最小可用写法是 cmake --build build --target app_cli；需要加速时再追加 --parallel 8，多配置生成器则补上 --config Release。

准备已经生成的构建目录

--target 属于构建阶段选项，前提是 build 已经由 CMake 配置并生成过。它不会替代 cmake -S ... -B ... 的配置步骤，也不会改变项目里声明的目标依赖关系。把两个阶段分开，后面排查“目标不存在”和“配置没有更新”会更容易。

先确认当前目录下确实有项目的构建目录；如果项目习惯使用 out/build、cmake-build-debug 等名字，就把命令里的目录替换为实际路径。这里不需要进入构建目录，--build 后面直接传它即可。

# 第一次配置项目时生成构建树；已有可用 build 目录时不要重复执行
cmake -S . -B build

# 构建阶段直接指定已有的二进制目录
cmake --build build

如果刚修改了 CMakeLists.txt、工具链或缓存选项，先按项目流程重新配置，再选择目标。本文后面的命令都假定构建树已经可用。

从构建目录选择要构建的 target

把目标名当成构建任务的最小单位：库可以是 core_lib，可执行文件可以是 app_cli，也可以是项目自定义的 docs 或其他 target。名称必须与项目生成的目标名完全一致，不能把源文件名、输出文件名或目录名当成目标名。

下面这张原创界面说明图用静态工作台展示目标列表与命令预览，帮助对照“选中的目标”和命令里的 --target 值；它不是 CMake 或 IDE 的真实截图，也不是运行证据。

如果只想构建命令行程序，最直接的写法如下：

# 只请求 app_cli 这个目标；它需要的依赖仍由构建系统按关系处理
cmake --build build --target app_cli

CMake 官方命令行文档将 --build

提交目标构建并控制并行度

目标确认后再提交构建命令。对编译时间较长的目标，可以用 --parallel 或简写 -j 控制并发进程数；这只改变构建调度，不会把其他无关 target 加入构建请求。

# 用 8 个并行进程构建 app_cli，数值按机器资源调整
cmake --build build --target app_cli --parallel 8

# 同一次请求也可以列出多个明确目标，空格分隔
cmake --build build --target core_lib app_cli --parallel 8

如果依赖目标已经是最新状态，构建工具通常会跳过无需重建的部分；如果源码或生成文件发生变化，指定目标所依赖的受影响对象可能重新编译。这是增量构建的正常表现，不等于 CMake 忽略了 --target。

多配置生成器要补充构建配置

使用 Visual Studio、Xcode 等多配置生成器时，同一个构建目录里可能同时存在 Debug 和 Release。此时目标名仍然放在 --target 后面，但还要用 --config 明确这次要构建哪一种配置。

# 多配置构建目录中，只构建 Release 配置的 app_cli
cmake --build build --config Release --target app_cli

# 调试阶段改为 Debug；不要把配置名误写成 target 名
cmake --build build --config Debug --target app_cli

单配置生成器通常在配置阶段已经确定构建类型，命令里未必需要 --config。如果你不确定当前生成器属于哪一类，先查看项目约定或 CMake 配置输出，再决定是否补这个参数。

核对提交结果和依赖范围

提交后按三层结果核对。第一层看命令是否以成功状态结束；第二层看目标产物或目标对应的输出是否更新；第三层看输出中是否出现了必要依赖的构建，而不是大量无关目标。指定 target 不承诺“只执行一条编译命令”，它承诺的是以该目标为构建入口。

下面这张原创结果说明图展示了目标完成、必要依赖完成和未选目标保持未构建三种状态，图中的状态是帮助理解验收位置的静态示意，不代表某次真实运行结果。

常见问题和恢复路径

提示目标不存在：先确认传入的是 CMake target 名，不是文件名。目标可能由子目录声明，也可能只在某个生成条件成立时出现；需要回到项目配置和生成器输出确认。

指定了目标却编译了其他内容：先区分“必要依赖”和“无关目标”。目标依赖链中的库或生成步骤可以被一起执行；如果完全不相关的模块也被触发，再检查是否调用了封装脚本、总目标或自定义构建步骤。

修改后仍像旧代码：选择 target 只控制构建请求，不会自动替代重新配置。检查是否改动了会影响生成结果的 CMakeLists.txt、工具链或缓存变量；必要时重新生成构建树，再回到单目标命令。

Debug 和 Release 搞混：多配置生成器明确写 --config，并在产物路径或构建输出中核对配置名；单配置生成器则遵循配置阶段的构建类型。

相关问题

--target 能不能一次写多个目标？可以，按空格列出多个目标；如果只想处理一个目标，保持命令短一些更利于定位输出。

指定目标后为什么还会构建依赖库？因为依赖是目标可构建性的前置条件。选择 target 限定的是构建入口，不是删除依赖关系。

只构建目标和只安装目标是一回事吗？不是。--target 负责构建目标；安装属于另一阶段，是否安装以及安装哪些组件由项目的安装规则决定。