汤一白君1. 先拆解这条 CMake 指令的字面结构
1.1 三个参数分别意味着什么
我第一次看到 target_compile_definitions(gen_img_component PRIVATE "COMPOSITION_BUILDING_DLL") 这条指令时，是在排查一个 Windows 下 DLL 导出符号缺失的链接问题。当时第一反应是：这不就是给目标加个宏？但实际上，围绕这条指令的项目实践远比表面复杂，涉及编译期定义、目标作用域以及 DLL 导出/导入的整套约定。这篇文章就以它为核心，把一个看似平常的构建指令讲透。
先看命令结构。CMake 里 target_compile_definitions 的完整签名是：
cmake复制target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...])
这里的 <target> 就是 gen_img_component，它必须是通过 add_library 或 add_executable 已经创建出来的目标名称。第二个参数是 PRIVATE，它决定了这个编译定义会作用的范围。第三个参数是 "COMPOSITION_BUILDING_DLL"，这就是要添加到编译命令行里的预处理器宏名。
很多初学者会把这条指令理解成“给 gen_img_component 这个库添加一个 CMake 里的变量”，这是不对的。宏定义不进入构建系统的变量空间，而是直接作用到所有参与构建该目标的源文件上。编译器在编译这些源文件时，就相当于在每个源文件的开头自动加了一行：
cpp复制#define COMPOSITION_BUILDING_DLL
注意，这里宏后面没有赋值，所以它只是一个“被定义”的宏。代码里可以用 #if defined(COMPOSITION_BUILDING_DLL) 或者 #ifdef COMPOSITION_BUILDING_DLL 来检测它是否存在。空值宏在绝大多数场景下都是够用的，因为它本来就是当作开关来用。
为什么写法上带了引号？因为目标是告诉 CMake：“这个字符串整体是一个定义项，空格或者特殊字符不要被拆开”。在 COMPOSITION_BUILDING_DLL 这种纯大写下划线组成的宏名上没有空格，写不写引号都能正常工作。但如果宏定义带值，比如 COMPOSITION_BUILDING_DLL=1，那不带引号也通常没问题；如果值里带了空格或者分号，引号就变得非常重要。
1.2 编译器命令行里发生了什么
这一行配置最终不会直接出现在 CMake 的输出里，而是被转换成对应平台编译器的预处理器参数。理解这一步，后面排查问题才会快。
在 Makefile 或 Ninja 这套构建体系下，宏会变成 -D 参数，例如：
bash复制-DCOMPOSITION_BUILDING_DLL
如果你用 IDE 工程生成器，比如 Windows 上常见的 VS 风格工程，这个宏会被塞到工程文件里，显示为预处理定义 COMPOSITION_BUILDING_DLL。工程设置里那一栏就是把这类东西管理起来。
如果你开启了编译命令导出，也就是设置了 CMAKE_EXPORT_COMPILE_COMMANDS=ON，或者直接使用 Ninja 生成器，构建目录下会生成一个 compile_commands.json。打开它，搜索目标名 gen_img_component，能看到该目标每个源文件对应的完整编译命令。命令里应该包含 -DCOMPOSITION_BUILDING_DLL。这是验证这行配置是否生效最直接的手段。
比较反直觉的一点：这条指令只影响 gen_img_component 目标自己的源文件。和它链接的其他目标，不会因为这个目标上写了 PRIVATE 定义而自动获得同样的宏。这正是“PRIVATE”这个关键字的核心作用。
1.3 为什么现在推荐 target_compile_definitions 而不是 add_definitions
老项目里经常能看到这种写法：
cmake复制add_definitions(-DCOMPOSITION_BUILDING_DLL)
add_definitions 从很老版本的 CMake 就开始有了，它的问题是作用域太粗。这条命令设置的是“当前 CMakeLists.txt 所在目录以及它以下所有子目录”的全局编译定义。假设你的目录树下同时存在 gen_img_component 和另一个完全不相干的工具库，只要它们共享了某个 CMakeLists 层级，就会一起收到这个宏。
这在 DLL 导出场景下是灾难级别的隐患。一个库如果收到了不属于自己的 XXX_BUILDING_DLL 宏，它公共头文件里的条件编译就可能错误地走“导出”分支，把 __declspec(dllexport) 标记到完全不应该导出的类上，或者更隐蔽地，让使用方也收到了这个宏，导致符号声明的导入/导出方向错乱。
target_compile_definitions 是 CMake 2.8.11 引入的按目标（target）管理的编译定义接口。它把一个宏精确地绑定到某一个 build target 上，干净、可控、不会污染邻居。新的项目应该默认使用它。
另外，别把 target_compile_options 和它混为一谈。target_compile_options 是添加编译器标志，比如 -Wall、/EHsc 这类，虽然也能间接加宏，但它不会帮你管理宏约束，也不适合表达“这个 target 是否处于构建 DLL 状态”这种语义。宏定义就应该用 target_compile_definitions 来表达。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. PRIVATE 不是语法点缀，它决定宏会不会传染给下游
2.1 三对作用域规则
CMake 目标之间发生依赖时，最常见的表达方式是 target_link_libraries。一个目标 A 链接了目标 B，那么 B 身上的某些属性可以被 A 继承，哪些继承、哪些不继承，就要看这些属性是 PRIVATE、PUBLIC 还是 INTERFACE。
target_compile_definitions 对应的目标属性是 COMPILE_DEFINITIONS。同时，每个目标还有一个 INTERFACE_COMPILE_DEFINITIONS 属性，专门存储“需要传递给链接到本目标的下游目标”的编译定义。三个关键字的实际行为如下：
| 关键字 | 写入自身 COMPILE_DEFINITIONS | 写入 INTERFACE_COMPILE_DEFINITIONS | 下游目标是否收到定义 | 典型用途 |
|---|---|---|---|---|
| PRIVATE | 是 | 否 | 不会收到 | 实现细节、DLL 导出宏 |
| PUBLIC | 是 | 是 | 会收到 | 公共头文件需要使用的宏 |
| INTERFACE | 否 | 是 | 会收到，但仅作为接口传递 | 纯头文件库、显式传递宏给消费者 |
举个例子。如果写了：
cmake复制target_compile_definitions(gen_img_component PRIVATE COMPOSITION_BUILDING_DLL)
add_executable(img_demo main.cpp)
target_link_libraries(img_demo PRIVATE gen_img_component)
那么 img_demo 的源文件在编译时不会带上 COMPOSITION_BUILDING_DLL。编译命令里只有 gen_img_component 自身的源文件带。
反过来，如果把 PRIVATE 改成 PUBLIC，那么 img_demo 的编译命令里也会出现这个宏。这通常不是我们想要的，后面我会详细解释原因。
2.2 为什么 DLL 导出宏必须用 PRIVATE
COMPOSITION_BUILDING_DLL 这个宏名本身就在传达一个信息：COMPOSITION 这个模块当前正处于“正在构建 DLL 模块”的编译状态。也就是说，这个宏的服务对象是“DLL 自身的源文件”。
我们通常会写一个公共导出宏头文件，里面根据这个宏决定某个类或函数是 __declspec(dllexport) 还是 __declspec(dllimport)。逻辑类似这样：
cpp复制#if defined(COMPOSITION_BUILDING_DLL)
#define COMPOSITION_API __declspec(dllexport)
#else
#define COMPOSITION_API __declspec(dllimport)
#endif
当编译器处理 gen_img_component 这个 DLL 自己的 composition.cpp 时，我们希望它走 dllexport 分支，把实现导出到 DLL 里。而当编译器处理外部程序 main.cpp 时，我们希望它走 dllimport 分支，告诉链接器“这个符号来自那个 DLL”。
如果 PRIVATE 被换成 PUBLIC，会发生什么？gen_img_component 自身得到宏，这没问题；但 img_demo 作为下游也会得到宏，于是 main.cpp 里也走了 dllexport 分支。也就是说，一个普通的可执行文件在声明外部类的头文件时，用了“导出”而不是“导入”，链接器自然找不到 __imp_ 开头的导入符号，报出一堆 unresolved external symbol 错误。
我见过不少新人因为想“让宏传递得广一点”，随手把 DLL 导出宏写成 PUBLIC，结果编译全绿、链接全红。反过来，为了排错把宏改成 PRIVATE，问题瞬间消失。这个现象在 Windows 平台尤其明显。
如果目标不是 DLL，而是静态库，使用 PRIVATE 还是 PUBLIC 影响没那么大，因为静态库没有导入/导出的符号语义。但从纪律角度，还是建议所有“构建状态类宏”都用 PRIVATE，避免项目从静态库改成动态库时留下隐雷。
2.3 什么情况下才值得用 PUBLIC 或 INTERFACE
PUBLIC 和 INTERFACE 编译定义也有自己的用武之地。
最常见场景是“公共头文件需要”的宏。比如你的库提倡用户在包含头文件时启用某个特性：
cpp复制#ifdef COMPOSITION_ENABLE_GPU
void composition_enable_gpu();
#endif
如果头文件是公共的，而该宏需要在所有使用方看到，你就可以：
cmake复制target_compile_definitions(gen_img_component PUBLIC COMPOSITION_ENABLE_GPU=1)
这样不仅库自身编译时能看到这个宏，下游目标只要链接了 gen_img_component，也会自动带上。这是很典型的 PUBLIC 用法。
还有一种场景是纯接口库。项目里的某个目标并不生成真正的二进制文件，只想给多个 DLL 目标统一传递某个宏，比如一个统一导出宏的辅助目标：
cmake复制add_library(composition_export_headers INTERFACE)
target_compile_definitions(composition_export_headers INTERFACE COMPOSITION_USING_DLL=1)
下游链接了这个 INTERFACE 库，就会收到 COMPOSITION_USING_DLL，适合那些需要明确“我正在消费外部 DLL”的场景。这就是 INTERFACE 的舞台。
3. COMPOSITION_BUILDING_DLL 背后是 Windows DLL 的符号导出约定
3.1 为什么 Windows DLL 要被“标记”才会导出
在 Windows 上构建动态库，并不像 Linux 那样默认把所有非静态符号都导到动态库符号表里。DLL 是一个可执行镜像，外部模块只能访问显式导出的符号。如果你只是写了一个普通类和一个普通函数，不加任何导出标记，链接器不会自动把它们放进 DLL 的导出表。
要让符号能被外部使用，主流做法有三种：在声明里写 __declspec(dllexport)、用 .def 文件罗列导出符号、或者开启 CMake 的 WINDOWS_EXPORT_ALL_SYMBOLS 属性。前两种属于精细化控制，第三种是给“懒得标记”的项目兜底用的，缺点是你无法精确控制哪些内部符号不应该暴露。
当你的项目决定用 __declspec(dllexport) 来标记导出符号时，就会遇到一个问题：同一个头文件，既要在 DLL 构建时被编译，导出实现；又要在调用方编译时被包含，告诉编译器“这些符号来自外部 DLL”。前者要用 dllexport，后者要用 dllimport，编译器在识别两种状态时的行为不同，最佳实践就是用一个条件编译开关。
3.2 一份典型的导出宏头文件长什么样
实际工程里，COMPOSITION_BUILDING_DLL 这类宏一般搭配一个专门的导出宏头文件使用。下面这个模板可以直接抄：
cpp复制// composition_export.h
#pragma once
#if defined(_WIN32) || defined(__CYGWIN__)
# if defined(COMPOSITION_BUILDING_DLL)
# define COMPOSITION_API __declspec(dllexport)
# elif defined(COMPOSITION_USING_DLL)
# define COMPOSITION_API __declspec(dllimport)
# else
# define COMPOSITION_API
# endif
#else
# define COMPOSITION_API
#endif
这个头文件划分了三个状态：
第一，COMPOSITION_BUILDING_DLL 被定义，说明当前翻译单元属于 DLL 模块自身。这时所有用 COMPOSITION_API 标记的类、函数、变量都会被导出。
第二，COMPOSITION_USING_DLL 被定义，说明当前翻译单元属于 DLL 的消费者。这时声明会被标记为导入，链接器去导入库里找符号。
第三，两个宏都没有定义。这种情况一般出现在静态库场景，或者非 Windows 平台。此时导出宏为空，不影响正常编译。
建议大家把 COMPOSITION_API 标记在类名、函数名前而不是后面。类导出时，标记写在类名前面：
cpp复制class COMPOSITION_API Composition {
public:
int version() const;
};
函数导出时，标记写在返回类型和函数名之间的位置比较稳妥：
cpp复制COMPOSITION_API int composition_version();
像 COMPOSITION_BUILDING_DLL 这种宏，本质上只是整个约定的一个启动开关。它本身不会让编译器做任何事，真正干活的还是后面那段条件编译。这就是为什么 target_compile_definitions 这一个命令看起来那么不起眼，却能在大型工程里推动整个 DLL 导出体系正常运转。
3.3 为什么宏名前要带模块前缀
名字里带 COMPOSITION 不是没理由的。一个项目可能会有多个 DLL 模块共存：图像处理模块、音频解码模块、网络通信模块……每个模块都会有自己独立的 XXX_BUILDING_DLL 宏，例如 COMPOSITION_BUILDING_DLL、AUDIO_BUILDING_DLL、NETWORK_BUILDING_DLL。
如果所有模块共用同一个 BUILDING_DLL 宏，整个工程同时编译多个模块时，很可能一个编译单元既在编译图像模块，又包含了音频模块的公共头文件。此时宏的语义已经分不清到底在构建谁，条件编译就会错乱，有的导出分支对了，有的错了，最后表现成毫无规律可言的链接错误。
所以，宏名一定要按模块隔离。gen_img_component 这个目标名称和 COMPOSITION_BUILDING_DLL 宏名，本质上是一个命名空间概念：它把“构建态”明确限定在 COMPOSITION 这个模块上下文里。
3.4 与 Linux/macOS 平台行为的差异
这里顺带补充一个跨平台细节。在 Linux 和 macOS 上，构建动态库（so/dylib）时，默认可见性往往是全部导出的，除非你特意加了 -fvisibility=hidden。所以同一份代码在 Windows 上有 COMPOSITION_API 导出宏，在 Linux 上只要那个宏展开为空无所谓。
如果项目有比较大的符号可见性控制需求，可以给非 Windows 分支也安排一个可见性宏：
cpp复制#if defined(_WIN32)
# if defined(COMPOSITION_BUILDING_DLL)
# define COMPOSITION_API __declspec(dllexport)
# elif defined(COMPOSITION_USING_DLL)
# define COMPOSITION_API __declspec(dllimport)
# else
# define COMPOSITION_API
# endif
#elif defined(__GNUC__) && defined(COMPOSITION_BUILDING_DLL)
# define COMPOSITION_API __attribute__((visibility("default")))
#else
# define COMPOSITION_API
#endif
不过对多数项目来说，第一部分模板已经够用。重点是理解宏的条件编译链路，而不是把平台差异写得太花哨。
4. 搭一个可复现的示例：gen_img_component 动态库全流程
4.1 工程目录结构
理论说得再多，不如直接跑一遍。下面我们就搭一个最小但完整的示例工程，把 target_compile_definitions(gen_img_component PRIVATE COMPOSITION_BUILDING_DLL) 放到真实场景里验证。
假设目录结构如下：
text复制composition_demo/
├── CMakeLists.txt
├── include/
│ └── composition/
│ ├── composition.h
│ └── composition_export.h
├── src/
│ └── composition.cpp
└── app/
└── main.cpp
include 目录放公共头文件，src 目录放 DLL 实现，app 目录放一个可执行程序来消费这个 DLL。
4.2 CMakeLists.txt 的完整写法
cmake复制cmake_minimum_required(VERSION 3.16)
project(CompositionDemo LANGUAGES CXX)
add_library(gen_img_component SHARED
src/composition.cpp
)
target_include_directories(gen_img_component
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
)
target_compile_definitions(gen_img_component
PRIVATE
COMPOSITION_BUILDING_DLL
)
add_executable(img_demo
app/main.cpp
)
target_link_libraries(img_demo
PRIVATE
gen_img_component
)
这里最核心的就是那行 target_compile_definitions(gen_img_component PRIVATE COMPOSITION_BUILDING_DLL)。要注意，由于是 PRIVATE，下游的 img_demo 不会继承这个宏。这正是我们要的效果：DLL 自身构建时代理头文件走 dllexport 分支，消费可执行文件则自动走 dllimport 分支。
为什么 target_include_directories 用了 $<BUILD_INTERFACE:...>？因为在这个演示工程里，头文件路径只在本工程内部构建时有用。如果你后续要做安装和打包，可以把 include 目录改成 INSTALL_INTERFACE 对应的路径。现在保持一个小示例的完整正确性就够。
4.3 导出宏头文件与类实现
先写 include/composition/composition_export.h：
cpp复制#pragma once
#if defined(_WIN32) || defined(__CYGWIN__)
# if defined(COMPOSITION_BUILDING_DLL)
# define COMPOSITION_API __declspec(dllexport)
# elif defined(COMPOSITION_USING_DLL)
# define COMPOSITION_API __declspec(dllimport)
# else
# define COMPOSITION_API
# endif
#else
# define COMPOSITION_API
#endif
再写 include/composition/composition.h：
cpp复制#pragma once
#include "composition_export.h"
class COMPOSITION_API Composition {
public:
int version() const;
};
然后写 src/composition.cpp：
cpp复制#include "composition/composition.h"
int Composition::version() const {
return 1;
}
最后写 app/main.cpp：
cpp复制#include <iostream>
#include "composition/composition.h"
int main() {
Composition composition;
std::cout << composition.version() << std::endl;
return 0;
}
这里有一个容易被忽略的小细节：composition.h 所在的目录是 include/composition，而 src/composition.cpp 里用的是 #include "composition/composition.h"。所以工程里必须有一个 include 目录被暴露出去，否则要么源文件找不到头文件，要么消费端找不到公共头文件。target_include_directories 的公共传递在这里起了很大作用。
4.4 构建、运行与验证宏是否生效
构建命令非常常规：
bash复制cmake -S . -B build
cmake --build build
在 Windows 上，构建完成后会看到 gen_img_component.dll、导入库 gen_img_component.lib 以及可执行文件 img_demo.exe。运行 img_demo.exe，如果输出 1，说明整个 DLL 构建、导入、链接链条是通的。
那么如何确认 COMPOSITION_BUILDING_DLL 真的只在 DLL 目标上生效？有三个办法：
第一，打开 build 目录下的 compile_commands.json。用 Ninja 生成器时默认会生成这个文件；用 Makefile 生成器时，可以加上 CMAKE_EXPORT_COMPILE_COMMANDS=ON 再配置一次。然后搜索 gen_img_component，对应的编译命令里会出现 -DCOMPOSITION_BUILDING_DLL；再搜索 img_demo，那条命令里不会出现它。
第二，在 IDE 工程生成器下，右键 gen_img_component 项目，查看预处理定义列表，可以看到 COMPOSITION_BUILDING_DLL；再看 img_demo 项目，它没有。
第三，临时在 composition_export.h 里加一行编译期输出，比如在不支持空宏转字符串的编译器上，可以改成：
cpp复制#if defined(COMPOSITION_BUILDING_DLL)
# pragma message("composition: building dll")
#endif
也可以把宏的默认定义改成带值的写法：
cmake复制target_compile_definitions(gen_img_component PRIVATE COMPOSITION_BUILDING_DLL=1)
然后在头文件里：
cpp复制#if COMPOSITION_BUILDING_DLL
# pragma message("composition: building with macro value 1")
#endif
这样能直观看到不同目标的编译分支走了哪条路。验证完了，再改回不带值的宏定义，就不会有别的隐患。
4.5 出问题时的排查链路
我在实际项目中总结过一套 DLL 宏问题的排查顺序，在这里分享出来。
第一类错误，链接时报 unresolved external symbol，且符号前面带 __imp_。这通常意味着消费端 img_demo 在使用 dllimport 声明，但 DLL 侧没有对应的导出符号。先检查 gen_img_component 的源文件是否真的被编译进 DLL，再检查类或函数声明上有没有 COMPOSITION_API，最后检查 COMPOSITION_BUILDING_DLL 是否真的出现在 DLL 目标的编译命令里。很多人忘了给类标记导出宏，只写了一个空的 __declspec(dllexport)，等于没导出。
第二类错误，编译时报宏重定义或告警。例如源文件里手动写了 #define COMPOSITION_BUILDING_DLL，而 CMake 又在命令行传入了同样的宏。MSVC 会报 C4005 之类的宏重定义告警。处理方式不是加 #undef，那是掩耳盗铃。应该删除源文件里的手动定义，让宏统一由构建系统管理。
第三类错误，构建出来是 DLL 但是调用方找不到函数导出。查看导出表是否真的有这个符号。Windows 上可以用工具导出 DLL 符号列表。如果没有导出，基本可以判断是导出宏分支没走对。此时把 COMPOSITION_BUILDING_DLL 临时改成带值版本，并配合 #pragma message 验证分支，是最快的方法。
第四类错误，如果混淆了 PRIVATE 和 PUBLIC，img_demo 可能也会收到 COMPOSITION_BUILDING_DLL，然后 main.cpp 里的 COMPOSITION_API 被展开成 __declspec(dllexport)。这种错误最隐蔽，因为编译完全不报错，链接时才会出现一堆 unresolved external symbol。排查时第一件事就是检查消费目标的编译命令是否被错误的宏污染。
5. 再多说几句：进阶写法和容易忽略的坑
5.1 用 CMake 的 GenerateExportHeader 模块自动生成导出宏
既然导出宏头文件的写法如此固定，CMake 也提供了一个官方模块来减少手写工作量：GenerateExportHeader。用法很简单：
cmake复制include(GenerateExportHeader)
add_library(gen_img_component SHARED src/composition.cpp)
generate_export_header(gen_img_component
BASE_NAME COMPOSITION
)
运行配置后，CMake 会生成一个 gen_img_component_export.h 头文件，里面定义了 COMPOSITION_EXPORT、COMPOSITION_NO_EXPORT、COMPOSITION_DEPRECATED 等宏。你只需要在公共头文件里包含这个自动生成的头文件，然后用 COMPOSITION_EXPORT 标记要导出的类或函数。
这个模块背后的逻辑和我上面手写模板是同一套：正常情况下根据当前目标是否定义了 COMPOSITION_EXPORTS（注意这里是 EXPORTS 不是 BUILDING_DLL）来决定走导出还是导入分支。配套的在 CMake 里仍然要定义一个编译宏，但名字可能是 COMPOSITION_EXPORTS 而不是我们标题里的 COMPOSITION_BUILDING_DLL：
cmake复制target_compile_definitions(gen_img_component PRIVATE COMPOSITION_EXPORTS)
为什么还要再提一个名字带 EXPORTS 的宏？因为 GenerateExportHeader 有自己的约定。如果你的工程底子里一直在用 COMPOSITION_BUILDING_DLL，完全可以不切到这个模块，继续把手写的 composition_export.h 用到底。两者没有谁一定更对，就看项目更依赖哪种惯例。
但如果你要维护一个大型多模块工程，我个人偏好在旧代码里继续保留原来的宏，新模块直接使用 GenerateExportHeader。这样既避免了改动老模块头文件的风险，又能在新模块里少写一堆条件编译判断。
5.2 静态库与动态库切换时的宏管理
项目开发过程中，模块形态经常变化。一个库可能先以静态库形式集成，后来又切成动态库，或者反过来。这种切换对 DLL 导出宏的影响很容易被忽略。
静态库不需要 COMPOSITION_BUILDING_DLL 宏。如果静态库的源文件里包含了 composition_export.h，由于宏未定义，COMPOSITION_API 可能展开为空或者变成 dllimport。这就会出现一种尴尬局面：静态库的类声明带了 dllimport 标记，但链接静态库时其实不需要导入。某些编译器会给出警告，甚至在某些组合下编译报错。
切换成动态库时，第一件事就是检查目标定义里有没有加 target_compile_definitions(... PRIVATE COMPOSITION_BUILDING_DLL)。漏了它，DLL 构建时导出宏不会生效，链接其他使用方时就找不到符号。补上它，通常就恢复正常。
我见过一个项目从“静态库 + PUBLIC include”平滑迁移到“动态库 + PRIVATE 导出宏”，结果因为一个目标漏了宏，整个上层应用链接失败。这种问题往往不是逻辑复杂，而是分散在几十个 CMakeLists 里的宏管理没有系统化。建议在每个库目标的定义旁边，用注释标明当前模块形态，例如：
cmake复制# 当前 gen_img_component 以动态库形态构建
add_library(gen_img_component SHARED ...)
target_compile_definitions(gen_img_component PRIVATE COMPOSITION_BUILDING_DLL)
如果后续切回静态库，把这个 PRIVATE 定义连同 SHARED 关键字一起注释掉，两行是一对，不容易漏。
5.3 编译定义里的生成器表达式
target_compile_definitions 支持生成器表达式，这点很有用。例如，如果你想只在 Windows 平台给目标加一个宏：
cmake复制target_compile_definitions(gen_img_component PRIVATE
$<$<PLATFORM_ID:Windows>:COMPOSITION_WIN32_BUILDING_DLL>
)
但要注意，DLL 导出宏和平台宏不一样。COMPOSITION_BUILDING_DLL 描述的是“编译这个目标时的模块身份”，跟平台没有必然关系。生成器表达式更适合“某个编译器、某个构建类型、某个平台下才需要的开关”。所以不要把所有宏统统塞进生成器表达式里，尤其在涉及 PUBLIC/INTERFACE 传递时，表达式求值发生在生成阶段，一旦表达式写复杂，生成的工程难以阅读。
另一个常见的进阶用法是配合 $<BUILD_INTERFACE:> 表达式做安装导出。比如把库安装到系统后，你希望下游消费者使用 COMPOSITION_USING_DLL 宏，但是不希望这个宏污染本工程构建：
cmake复制target_compile_definitions(gen_img_component INTERFACE
$<BUILD_INTERFACE:COMPOSITION_USING_DLL>
)
这种写法适合做成“显式消费宏”的库。它保证了本工程构建时不被 USING_DLL 干扰，但一旦被安装并被下游链接，下游就会看到这个宏。
这一点在产品级工程里非常实用：你可以在同一个公共头文件里区分“正在构建这个库”、“正在使用这个动态库”、“静态库场景”三种状态，每一方的宏都由对应的 CMake 目标声明清楚，彻底告别混乱。
5.4 预编译头与统一构建模式下的宏一致性问题
引入预编译头（PCH）或 unity build 之后，宏作用域的表现会有一些新变化，但不是大问题。
在普通构建模式下，每个源文件独立编译，只要目标上定义了 COMPOSITION_BUILDING_DLL，参与该目标的所有源文件都会拿到这个宏。预编译头本身并不改变这一点，因为 PCH 的生成也发生在同一个目标的编译上下文中，宏会带进去。
但在 unity build 模式下，多个源文件会被拼接到同一个翻译单元里一起编译。如果这些源文件分别属于不同目标，CMake 会确保它们仍然使用各自目标的编译定义，不会发生跨目标串宏。所以只要你用的是 target_compile_definitions 而不是全局 add_definitions，即便开启 unity build，宏也不会互相污染。
真正值得注意的反而是源文件级覆盖。CMake 允许你用 set_source_files_properties 给某个源文件单独设置编译定义，这时候同一个目标里不同源文件的宏就可能不一致。这种用法极其少见，但一旦出现，定位起来会很痛苦。所以一般工程不建议对 DLL 导出宏做源文件级差异化，保持目标级一致是最好的纪律。
5.5 修改宏之后为什么没有生效
最后补充一个很常见的问题：改了 CMake 里 target_compile_definitions 的定义，重新构建，为什么看起来宏没有变化？
原因多半是增量构建没有意识到编译命令变了，或者某些源文件没有被强制重新编译。CMake 在配置阶段感知到编译定义变化后，一般会触发受影响目标的重新编译，但如果构建系统本身缓存了旧的命令，还是可能出现漏编。
我的做法是在改动宏定义后，先做一次干净的重新构建：
bash复制cmake --build build --target clean
cmake --build build
或者直接删除 build 目录重新配置。这一步虽然浪费一点时间，但能最大限度避免“宏没生效”的误判。
在 IDE 工程里，如果改了 CMakeLists 但只重新编译不重新生成工程，宏定义也可能停留在旧状态。记得强制“重新生成工程”再进行构建。很多所谓“宏改了没用”的问题，最后都出在这里。
最后再分享一个我自己的习惯。最初我也在几个目标上都用过 PRIVATE COMPOSITION_BUILDING_DLL 这种写法，后来发现一旦目标从动态库改成静态库，或者从 Windows 移植到其他平台，这类手写宏就要跟着改。我现在通常把导出宏的声明独立成一个 export 头文件，CMake 里只保留一行 PRIVATE 定义，而头文件用三层条件判断（构建 DLL、使用 DLL、其他平台）。这样哪怕作用域写错了，在编译错误里也能很快看出来。还有一个快速验证宏是否生效的技巧：临时把定义写成 COMPOSITION_BUILDING_DLL=1，在想要验证的源文件里加一句 #if COMPOSITION_BUILDING_DLL 的分支，通过编译日志就能确认分支走对了。确认无误后，再改回不带值的写法。这行看似简单的 CMake 指令，背后是整套 DLL 符号管理约定，理解它，比背住十个 CMake 命令更有价值。