1. 项目概述当游戏引擎遇上C26模块最近在重构一个内部自研游戏引擎的底层架构核心目标是把那个已经服役五年、依赖关系盘根错节的“面条式”代码库改造成一个清晰、高效、易于维护的现代化组件系统。这个引擎最初为了快速上线大量使用了传统的头文件包含#include和预编译头PCH随着项目规模膨胀到数百万行代码编译时间动辄半小时起步增量构建也慢得让人抓狂更别提跨团队协作时动一个基础头文件引发的“海啸式”重编译了。痛定思痛我们决定拥抱C20/26标准中最重要的特性之一模块Modules。这不仅仅是把#include换成import那么简单而是一次从源码组织、构建流程到团队协作范式的全面升级。我们最终的目标是实现一个基于C26模块虽然编译器支持还在追赶但设计上我们面向未来的纯组件化引擎架构并打通从开发、测试到自动化部署的全链路。如果你也在为大型C项目的编译速度、代码隔离和部署复杂度头疼那么这次从传统头文件到现代模块化组件体系的迁移实战或许能给你带来一些直接的参考。2. 架构升级的核心驱动力与设计选型2.1 为什么是C模块而不仅仅是更好的构建系统在决定方案前我们评估过几种路径优化现有的基于Makefile/CMake的构建脚本、引入更激进的分布式编译缓存如DistCC、icecc、或者全面转向模块化。前两者治标不治本它们能缓解但无法根除头文件包含机制带来的固有缺陷。传统#include的本质是文本替换它会将头文件内容“复制粘贴”到每一个翻译单元中。这意味着重复解析与编译vector这样的标准库头文件在成千上万个.cpp文件中会被重复解析成千上万次。脆弱的依赖隔离头文件中的宏定义、using声明会污染包含它的所有源文件容易引发难以察觉的命名冲突和副作用。编译防火墙失效即使使用PIMPL指针指向实现等模式头文件中仍然需要暴露私有成员的指针类型修改实现细节有时仍会触发广泛的重新编译。C模块则提供了一种逻辑封装的机制。一个模块是一个独立的编译单元它明确声明了哪些接口函数、类、模板对外可见export。编译器只需解析模块接口一次生成一个二进制接口文件BMI如.ifc、.pcm后续所有导入import该模块的翻译单元都直接使用这个BMI无需再次解析源码。这带来了几个立竿见影的好处编译速度飞跃特别是对于大型项目一次构建后模块接口的变更只会导致直接依赖它的单元重编译依赖关系是精确的、图状的而非头文件包含那种广播式的。强代码隔离模块内部实现细节完全隐藏真正的“编译防火墙”。只有export的内容才对导入者可见。消除宏污染模块接口不受导入处宏定义的影响反之亦然大大提升了代码的健壮性和可预测性。基于这些根本性优势我们认定面向未来C26将进一步稳定模块生态的架构升级必须围绕模块展开。2.2 组件化设计如何划分引擎的“积木块”确定了模块作为技术基石下一步就是如何用模块来构建我们的“组件”。这里的“组件”不是指Unity/Unreal中的Component实体而是指引擎中功能独立、可单独编译、可部署的子系统库例如“渲染核心”、“物理模拟”、“音频系统”、“资源管理器”、“网络层”等。我们的设计原则是“高内聚、低耦合”与“明确依赖层级”。核心层Core包含基础类型自定义的Vec3、Matrix4、内存管理、日志系统、配置文件读取等几乎所有其他组件都依赖的底层设施。它被设计为一个名为Engine.Core的模块。平台抽象层Platform封装窗口管理、输入处理、文件系统等操作系统相关功能形成Engine.Platform模块。它依赖Engine.Core。功能组件层这是主体。每个主要功能子系统成为一个独立模块。Engine.Rendering负责Vulkan/D3D12的封装、着色器管理、渲染管线。依赖Engine.Core和Engine.Platform用于窗口和输入。Engine.Physics物理引擎封装。依赖Engine.Core。Engine.Audio音频系统。依赖Engine.Core。Engine.Resource负责模型、纹理等资源的加载、缓存与生命周期管理。依赖Engine.Core和Engine.Rendering因为要知道纹理格式等。框架层与工具层在功能组件之上可以构建更上层的框架如实体组件系统ECS框架Engine.ECS它依赖多个底层组件。工具链如离线资源编译器、关卡编辑器则作为独立的可执行文件项目导入并使用上述模块。每个模块对应一个物理目录目录下包含module.ixx(或module.cppm)模块接口单元文件用于声明export的接口。module.impl.ixx(可选)模块实现单元用于放置那些不希望放在接口单元中的实现细节特别是大型函数体或模板特化。src/私有实现源文件.cpp。tests/该模块的单元测试。这种划分使得每个模块可以独立开发、测试甚至理论上可以独立版本化和发布。实操心得模块划分的粒度一开始我们倾向于划分得非常细比如把数学库单独成Math模块。但后来发现过度细分会导致模块数量爆炸管理成本增加且细粒度模块间的频繁import有时会抵消部分编译收益。我们的经验是将变更频率和功能紧密性作为首要划分依据。数学库非常稳定且被广泛使用放入Core是合理的。而像“渲染后端抽象”和“具体Vulkan实现”虽然功能相关但后者变动更频繁且可能希望替换如换用D3D12因此拆分为Rendering.API抽象接口和Rendering.Vulkan具体实现两个模块是更好的选择。3. 从零搭建基于模块的构建与开发环境3.1 工具链选型编译器与构建系统的抉择模块的支持程度直接取决于工具链。目前以当前时间点计的情况是MSVC (Visual Studio 2022 17.8): 对C20模块支持最为成熟和稳定其生成的BMI文件为.ifc。它是我们开发阶段的主力特别是在Windows平台。Clang (16): 支持也在快速跟进使用.pcm文件。在macOS和Linux上它是首选。对于跨平台项目需要确保代码在两种编译器下都能正确编译。GCC (13): 支持较晚且在某些边缘场景下可能不如前两者完善。对于追求最新稳定性的生产环境可能需要暂缓。构建系统方面CMake (3.28)是目前对模块支持最全面的主流选择。Ninja作为生成后端因其极快的速度成为不二之选。我们放弃了旧有的自定义Makefile全面转向CMake。一个典型的模块CMakeLists.txt看起来像这样# Engine.Core 模块的 CMakeLists.txt cmake_minimum_required(VERSION 3.28) project(Engine.Core LANGUAGES CXX) add_library(Engine.Core) # 关键设置C标准并启用模块 target_compile_features(Engine.Core PUBLIC cxx_std_23) # 我们使用C23作为基线为C26特性留空间 set_target_properties(Engine.Core PROPERTIES CXX_SCAN_FOR_MODULES ON # 让CMake扫描模块依赖 CXX_STANDARD_REQUIRED ON ) # 模块的接口源文件 target_sources(Engine.Core PUBLIC FILE_SET cxx_modules TYPE CXX_MODULES FILES src/core/module.ixx PRIVATE src/core/memory/allocator.cpp src/core/logging/logger.cpp # ... 其他私有实现文件 ) # 包含目录 target_include_directories(Engine.Core PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ) # 依赖这个核心模块可能依赖一些第三方库如fmt find_package(fmt REQUIRED) target_link_libraries(Engine.Core PUBLIC fmt::fmt)对于上层模块如Engine.Rendering其CMakeLists.txt需要声明对Engine.Core的依赖add_library(Engine.Rendering ...) target_link_libraries(Engine.Rendering PUBLIC Engine.Core) # CMake会自动处理模块依赖关系3.2 开发环境配置让VS Code和Visual Studio高效协作虽然我们主要使用Visual Studio进行开发和调试但很多同事习惯使用VS Code进行代码阅读和轻量编辑。因此配置一个统一的、支持模块的编辑体验很重要。对于Visual Studio 2022 确保安装时勾选了“使用C的桌面开发”和最新的MSVC工具集。在项目属性中“C/C” - “常规” - “扫描源以查找模块依赖”需设置为“是”。VS 2022对模块的IntelliSense支持已经相当好能够正确识别import语句并提供代码补全、跳转。对于VS Code 配置关键在于c_cpp_properties.json和CMake Tools扩展。通过CMake: Configure让CMake Tools生成编译数据库compile_commands.json。在c_cpp_properties.json中设置configurationProvider: ms-vscode.cmake-tools这样C/C扩展就能从CMake获取正确的包含路径和编译定义。对于模块Clang版本的IntelliSense需要额外配置。一个有效的配置片段如下{ configurations: [ { name: Win32, compileCommands: ${workspaceFolder}/build/compile_commands.json, compilerPath: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.xx.x/bin/Hostx64/x64/cl.exe, cStandard: c17, cppStandard: c23, intelliSenseMode: windows-msvc-x64, // 以下对于模块的IntelliSense支持很重要 compilerArgs: [ /experimental:module, /std:clatest // 或 /std:c20 ] } ], version: 4 }需要注意的是VS Code的C/C扩展对模块的完全支持仍在完善中对于复杂的模块依赖有时IntelliSense可能会滞后或报错尽管实际编译通过。这时信任编译器的报错信息更为可靠。踩坑实录CMake与模块扫描早期我们使用CMake 3.26时CXX_SCAN_FOR_MODULES的行为不太稳定有时无法正确捕获模块间的依赖关系导致构建顺序错误。升级到CMake 3.30后这个问题基本得到解决。我们的教训是务必使用CMake和编译器尽可能新的版本因为模块支持是仍在快速演进的特性。同时在CMakeLists.txt中确保模块接口文件.ixx通过FILE_SET的CXX_MODULES类型添加而不是普通的源文件这是CMake正确识别和处理模块依赖的关键。4. 模块接口与实现单元的设计实战4.1 编写模块接口单元.ixx文件模块接口单元是模块的“门面”。我们以Engine.Core模块的module.ixx为例// module.ixx export module Engine.Core; // 声明模块名 // 分区模块可选将大型模块接口分到不同文件 export import Engine.Core.Base; // 导入并重新导出基础类型分区 export import Engine.Core.Memory; // 导入并重新导出内存管理分区 // export import Engine.Core.Utils; // 工具函数分区 // 直接导出声明 export namespace Engine::Core { // 一个简单的日志器接口 class Logger { public: enum class Level { Debug, Info, Warn, Error }; virtual ~Logger() default; virtual void log(Level level, std::string_view message) 0; // 便捷方法 void debug(std::string_view msg) { log(Level::Debug, msg); } void info(std::string_view msg) { log(Level::Info, msg); } // ... 其他级别 }; // 获取全局日志器实例实现位于模块内部 export Logger getGlobalLogger(); // 一个基础配置类 export class Config { public: virtual ~Config() default; virtual std::optionalstd::string_view getString(std::string_view key) const 0; virtual std::optionalint getInt(std::string_view key) const 0; // ... 其他类型 }; } // 注意标准库头单元可以import这比#include高效得多 import string_view; import optional; import memory; // 虽然这里没直接用到但导入后模块内可用 // 全局模块片段GMF用于处理宏和遗留头文件 module; // 在GMF中可以包含一些必须用#include的代码比如某些第三方库的头文件 #include some_legacy_lib.h // 定义一些只在本模块内有效的宏 #define ENGINE_CORE_LOCAL_MACRO 1 export module Engine.Core; // GMF结束模块声明再次出现C20风格 // 现在开始是模块的“纯净”区域关键设计点export import用于组合模块分区或聚合子模块。它意味着“导入这个模块分区/子模块并将其接口全部作为本模块接口的一部分对外提供”。这是构建模块层级的关键。分区模块对于像Core这样的大型模块将其接口拆分到Engine.Core.Base、Engine.Core.Memory等分区中每个分区有自己的.ixx文件。这保持了代码的物理组织清晰同时逻辑上仍属于同一个模块编译器最终会合并为一个BMI。全局模块片段用于放置那些必须使用#include的内容如某些尚未模块化的第三方库或模块内部使用的宏。非常重要的一点在GMF中定义的宏其影响范围仅限于该模块单元内部不会泄漏给导入者这是模块解决宏污染的核心机制之一。导入标准库头单元使用import vector;而非#include vector。编译器会将其作为“标准库模块”处理编译效率更高。但需要注意编译器支持程度MSVC对标准库模块的支持较好。4.2 模块实现单元与私有实现不是所有代码都适合放在接口单元里。对于实现细节尤其是复杂的模板定义、大型内联函数或者纯粹的内部辅助函数我们使用模块实现单元module.impl.ixx或普通的.cpp文件。// module.impl.ixx - 模块实现单元 module Engine.Core; // 注意不是 export module 它不提供新接口只是实现接口单元中声明的实体。 import iostream; // 实现单元可以导入其他模块 import fstream; namespace Engine::Core { // 实现 getGlobalLogger() Logger getGlobalLogger() { static class DefaultLogger : public Logger { void log(Level level, std::string_view message) override { std::ostream os (level Level::Warn) ? std::cerr : std::cout; os [ static_castint(level) ] message \n; } } logger; return logger; } // 一个内部使用的辅助函数不导出 void internalHelper() { /* ... */ } }普通的私有.cpp文件则更简单它们只需要声明所属的模块// src/core/config/json_config.cpp module Engine.Core; // 声明这个.cpp文件是Engine.Core模块的一部分 import nlohmann/json.hpp; // 导入一个第三方JSON库假设它已模块化 import fstream; namespace Engine::Core { class JsonConfigImpl : public Config { nlohmann::json m_data; public: explicit JsonConfigImpl(const std::filesystem::path path) { std::ifstream file(path); m_data nlohmann::json::parse(file); } std::optionalstd::string_view getString(std::string_view key) const override { // ... 实现 } // ... 其他实现 }; // 这个工厂函数可能通过接口单元中导出的某个函数来调用但类本身可以不导出。 }注意事项接口与实现的分离策略保持接口精简接口单元只export绝对必要的类型和函数。将实现细节尽可能下放到实现单元或私有.cpp中。这减少了接口变更的几率从而减少了依赖它的模块需要重编译的次数。小心内联和模板被export的模板其定义通常必须放在接口单元中因为调用方需要实例化。对于复杂的模板考虑使用显式实例化并在接口中export这些实例将模板定义移入实现单元。例如// module.ixx export module MyLib.Templates; export templatetypename T class MyVector; // 前置声明 export extern template class MyVectorint; // 声明显式实例化 export extern template class MyVectorfloat;// module.impl.ixx module MyLib.Templates; templatetypename T class MyVector { /* 完整定义 */ }; template class MyVectorint; // 显式实例化定义 template class MyVectorfloat;这样MyVectorint的代码只在此处编译一次所有导入者共享减少了代码膨胀和编译时间。5. 依赖管理、构建优化与持续集成5.1 管理模块间与第三方依赖在组件化架构中清晰的依赖关系至关重要。我们使用CMake的target_link_libraries来声明依赖这不仅能传递链接库也能传递模块依赖信息。对于第三方库理想情况是它们也提供了模块接口.ixx文件。越来越多的现代C库开始支持例如{fmt}、spdlog等。对于这样的库我们直接使用import。对于尚未模块化的传统头文件库如许多C语言库或老式C库我们有几种选择封装模块为这个库创建一个薄薄的封装模块。在封装模块的GMF中#include该库的头文件然后export我们需要的类型和函数。这样外部代码通过import我们的封装模块来使用该库实现了隔离。// third_party/glfw.ixx module; #include GLFW/glfw3.h export module ThirdParty.GLFW; export using ::GLFWwindow; // 导出类型别名 export int glfwInit(); // 导出函数 // ... 导出其他需要的符号直接使用如果该库很小或者我们愿意接受其头文件包含的代价可以在需要使用它的模块的GMF或实现文件中直接#include。但这会破坏该模块的“纯净性”并可能带来宏污染。我们为项目建立了一个third_party目录使用CMake的FetchContent或find_package来管理这些依赖并为其中关键的、广泛使用的库创建了封装模块。5.2 构建缓存与分布式编译模块化本身能极大提升增量编译速度但对于完整的干净构建我们还需要其他手段。共享编译缓存我们引入了ccache。ccache可以缓存每个翻译单元的编译结果包括模块BMI的生成。当源文件未改变时直接使用缓存跳过编译。这对于频繁切换分支或清理构建非常有效。在CMake中集成很简单cmake -B build -DCMAKE_CXX_COMPILER_LAUNCHERccache分布式编译对于超大型项目我们使用了distcc或iceccIncredibuild的替代开源方案。它们可以将编译任务分发到网络中的多台机器上。关键点模块的BMI文件生成.ixx-.ifc/.pcm这一步通常无法有效分发因为BMI包含了模块的完整抽象语法树AST生成过程对编译器状态依赖很强。但模块实现单元和普通.cpp文件的编译可以很好地分布式进行。我们的策略是在性能强大的编译服务器上集中生成所有模块的BMI这一步相对较快然后将大量的.cpp编译任务分发出去。5.3 CI/CD流水线设计基于模块的组件化架构为我们的CI/CD带来了新的可能性和挑战。持续集成CI独立组件测试每个模块组件都是一个独立的CMake目标因此可以轻松地为每个组件单独运行单元测试。我们在GitLab CI中为每个模块配置了独立的测试任务只有该模块或其依赖的代码发生变更时才触发对应的测试大大缩短了CI反馈周期。模块接口兼容性检查我们编写了一个脚本在合并请求MR时对比目标分支与特性分支的模块接口.ixx文件。如果发现export的接口被移除或签名被不兼容地修改例如删除了一个公共函数CI会发出警告要求开发者提供迁移说明或否决合并。这有助于维护二进制兼容性如果以动态库形式发布。持续部署/交付CD 组件化的最终目的是实现独立部署。我们将每个核心功能模块如Engine.Rendering,Engine.Physics编译为独立的动态链接库DLL/.so。版本化每个组件DLL都带有版本号如Engine.Rendering-v1.2.0.dll。主引擎可执行文件声明其依赖的组件及版本范围。包管理我们搭建了一个简单的私有NuGet服务器对于Windows和Conan仓库对于跨平台将编译好的组件包包含DLL、导入库.lib、模块BMI文件.ifc以及头文件/模块接口文件发布上去。游戏项目集成具体的游戏项目不再需要从头编译整个引擎。它只需要在自己的CMakeLists.txt中通过find_package找到所需的引擎组件包然后import对应的模块即可。构建时CMake会确保使用正确版本的组件BMI和链接对应的DLL。# 游戏项目的CMakeLists.txt find_package(EngineRendering 1.2.0 REQUIRED) find_package(EnginePhysics 1.1.0 REQUIRED) add_executable(MyGame src/main.cpp) target_link_libraries(MyGame PRIVATE EngineRendering::Rendering EnginePhysics::Physics) # 现在在MyGame的源码中就可以直接 import Engine.Rendering; 了这种架构使得引擎团队可以独立于游戏项目迭代和发布某个组件比如升级物理引擎版本游戏项目可以选择性地集成更新降低了耦合度提升了协作效率。6. 迁移策略、常见问题与性能实测6.1 从传统头文件到模块的渐进式迁移将数百万行代码一次性重写为模块是不现实的。我们采用了渐进式迁移策略“底部向上”迁移从最底层、依赖最少的模块开始比如工具类库、数学库。先将其改造成模块。由于上层代码目前仍使用#include我们需要为这个新模块创建一个兼容层一个传统的头文件里面只包含import该模块的语句可能需要放在module;全局片段之后不对于纯头文件兼容层它本身不是模块单元。更常见的做法是在模块的接口单元中使用#ifdef来同时支持export和传统声明。// 不推荐维护两份接口很麻烦实际上更干净的做法是让新模块和旧头文件并存一段时间。新建Math.ixx模块同时保留旧的math.h但math.h的内容改为#include旧实现或转发到模块通过using。新代码逐步迁移到import Math;旧代码继续使用#include “math.h”直到所有依赖都升级完毕再删除旧头文件。依赖反转与接口稳定在迁移过程中我们优先迁移那些被广泛依赖但自身依赖少的“叶子”模块。对于处于依赖图中部的模块迁移前要确保其接口足够稳定因为一旦改为模块其BMI会成为二进制接口频繁改动会导致依赖它的所有模块重编译。构建系统双轨制在迁移过渡期CMake需要同时处理包含.ixx模块和传统.h/.cpp的混合项目。CMake 3.28对此支持良好。关键是为每个目标统一设置CXX_STANDARD和CXX_SCAN_FOR_MODULESCMake会自动处理混合情况。6.2 开发中遇到的典型问题与解决方案循环依赖模块不允许循环import。这是好事它强迫我们设计出更清晰的依赖层次。如果遇到看似循环的情况需要重构。常见解法提取公共接口将A和B共同依赖的部分提取到新模块C中A和B都导入C。前向声明与延迟依赖如果A只需要B的类型名进行声明而非定义可以在A的接口单元中只做前向声明class B;而不import B。将真正的import B放到需要B定义的A的实现单元中。回调与观察者模式用接口类解耦。BMI文件的管理编译器生成的.ifc或.pcm文件是二进制文件需要妥善管理。我们将其作为构建产物放在${CMAKE_CURRENT_BINARY_DIR}下的特定目录中。在CI和打包时需要将这些BMI文件连同头文件/模块接口文件一起发布因为其他项目导入模块时需要它们。与旧代码尤其是宏的交互这是最棘手的问题之一。模块内部定义的宏不会泄漏出去但外部定义的宏也不会影响模块接口的解析除了在GMF中。对于需要跨模块边界的配置宏例如ENGINE_DEBUG我们不再使用#define而是将其定义为export的常量或通过函数获取或者在编译引擎核心时将其定义作为编译器命令行参数/DENGINE_DEBUG统一传递所有模块在编译时都能看到相同的定义。调试信息与符号使用模块后调试体验和传统方式基本一致。编译器生成的PDBWindows或DWARFLinux调试信息仍然包含完整的源码信息。需要注意的是模块接口中的内联函数调试起来可能和以前略有不同但主流调试器VS GDB LLDB都在积极适配。6.3 性能提升实测数据迁移完成后我们对构建性能进行了量化对比在同一台高性能开发机上完全干净构建从原来的42分钟下降到28分钟。提升约33%。主要收益来自于标准库头单元import vector的重复编译被消除。增量构建修改一个核心基础头文件这是最大的胜利。原来需要重编译约80%的项目耗时约25分钟。现在如果只修改了某个模块的实现单元.cpp则只重编译该模块本身和直接依赖它的模块通常在1-3分钟内完成。如果只修改了模块接口.ixx重编译范围也远小于原来的头文件因为依赖关系是精确的。代码补全与IntelliSense响应在VS 2022中感觉更加流畅尤其是对于大型模板代码因为编辑器不再需要反复解析被包含的头文件。7. 总结与未来展望这次基于C26模块的引擎架构升级是一次彻底的“现代化手术”。初期在工具链、构建脚本和开发习惯上的适应成本确实不低但带来的长期收益是巨大的更快的编译速度、更坚固的代码边界、更清晰的工程结构以及为组件化独立部署铺平了道路。对于正在考虑类似迁移的团队我的建议是从小处着手选择一个相对独立、依赖关系简单的工具库开始模块化实践积累经验。投资工具链确保团队使用的编译器MSVC/Clang、CMake、IDE都是足够新的版本并统一开发环境。设计先行在写代码之前花时间用白板画出理想的模块依赖图明确层级避免循环依赖。拥抱变化C模块标准本身和编译器支持都在快速演进社区最佳实践也在形成中。保持关注并准备好调整你的构建脚本和代码组织方式。展望未来随着C26标准的最终落地和各编译器支持的进一步完善模块必将成为大型C项目的标配。我们下一步计划是探索如何更好地利用模块分区来组织超大型模块以及如何将我们的组件包更无缝地集成到外部游戏项目中真正实现“引擎即服务”的愿景。这条路还很长但第一步迈出后回望过去那种被编译时间支配的恐惧感觉一切都是值得的。
C++26模块化实战：重构游戏引擎架构，提升编译效率与代码隔离
1. 项目概述当游戏引擎遇上C26模块最近在重构一个内部自研游戏引擎的底层架构核心目标是把那个已经服役五年、依赖关系盘根错节的“面条式”代码库改造成一个清晰、高效、易于维护的现代化组件系统。这个引擎最初为了快速上线大量使用了传统的头文件包含#include和预编译头PCH随着项目规模膨胀到数百万行代码编译时间动辄半小时起步增量构建也慢得让人抓狂更别提跨团队协作时动一个基础头文件引发的“海啸式”重编译了。痛定思痛我们决定拥抱C20/26标准中最重要的特性之一模块Modules。这不仅仅是把#include换成import那么简单而是一次从源码组织、构建流程到团队协作范式的全面升级。我们最终的目标是实现一个基于C26模块虽然编译器支持还在追赶但设计上我们面向未来的纯组件化引擎架构并打通从开发、测试到自动化部署的全链路。如果你也在为大型C项目的编译速度、代码隔离和部署复杂度头疼那么这次从传统头文件到现代模块化组件体系的迁移实战或许能给你带来一些直接的参考。2. 架构升级的核心驱动力与设计选型2.1 为什么是C模块而不仅仅是更好的构建系统在决定方案前我们评估过几种路径优化现有的基于Makefile/CMake的构建脚本、引入更激进的分布式编译缓存如DistCC、icecc、或者全面转向模块化。前两者治标不治本它们能缓解但无法根除头文件包含机制带来的固有缺陷。传统#include的本质是文本替换它会将头文件内容“复制粘贴”到每一个翻译单元中。这意味着重复解析与编译vector这样的标准库头文件在成千上万个.cpp文件中会被重复解析成千上万次。脆弱的依赖隔离头文件中的宏定义、using声明会污染包含它的所有源文件容易引发难以察觉的命名冲突和副作用。编译防火墙失效即使使用PIMPL指针指向实现等模式头文件中仍然需要暴露私有成员的指针类型修改实现细节有时仍会触发广泛的重新编译。C模块则提供了一种逻辑封装的机制。一个模块是一个独立的编译单元它明确声明了哪些接口函数、类、模板对外可见export。编译器只需解析模块接口一次生成一个二进制接口文件BMI如.ifc、.pcm后续所有导入import该模块的翻译单元都直接使用这个BMI无需再次解析源码。这带来了几个立竿见影的好处编译速度飞跃特别是对于大型项目一次构建后模块接口的变更只会导致直接依赖它的单元重编译依赖关系是精确的、图状的而非头文件包含那种广播式的。强代码隔离模块内部实现细节完全隐藏真正的“编译防火墙”。只有export的内容才对导入者可见。消除宏污染模块接口不受导入处宏定义的影响反之亦然大大提升了代码的健壮性和可预测性。基于这些根本性优势我们认定面向未来C26将进一步稳定模块生态的架构升级必须围绕模块展开。2.2 组件化设计如何划分引擎的“积木块”确定了模块作为技术基石下一步就是如何用模块来构建我们的“组件”。这里的“组件”不是指Unity/Unreal中的Component实体而是指引擎中功能独立、可单独编译、可部署的子系统库例如“渲染核心”、“物理模拟”、“音频系统”、“资源管理器”、“网络层”等。我们的设计原则是“高内聚、低耦合”与“明确依赖层级”。核心层Core包含基础类型自定义的Vec3、Matrix4、内存管理、日志系统、配置文件读取等几乎所有其他组件都依赖的底层设施。它被设计为一个名为Engine.Core的模块。平台抽象层Platform封装窗口管理、输入处理、文件系统等操作系统相关功能形成Engine.Platform模块。它依赖Engine.Core。功能组件层这是主体。每个主要功能子系统成为一个独立模块。Engine.Rendering负责Vulkan/D3D12的封装、着色器管理、渲染管线。依赖Engine.Core和Engine.Platform用于窗口和输入。Engine.Physics物理引擎封装。依赖Engine.Core。Engine.Audio音频系统。依赖Engine.Core。Engine.Resource负责模型、纹理等资源的加载、缓存与生命周期管理。依赖Engine.Core和Engine.Rendering因为要知道纹理格式等。框架层与工具层在功能组件之上可以构建更上层的框架如实体组件系统ECS框架Engine.ECS它依赖多个底层组件。工具链如离线资源编译器、关卡编辑器则作为独立的可执行文件项目导入并使用上述模块。每个模块对应一个物理目录目录下包含module.ixx(或module.cppm)模块接口单元文件用于声明export的接口。module.impl.ixx(可选)模块实现单元用于放置那些不希望放在接口单元中的实现细节特别是大型函数体或模板特化。src/私有实现源文件.cpp。tests/该模块的单元测试。这种划分使得每个模块可以独立开发、测试甚至理论上可以独立版本化和发布。实操心得模块划分的粒度一开始我们倾向于划分得非常细比如把数学库单独成Math模块。但后来发现过度细分会导致模块数量爆炸管理成本增加且细粒度模块间的频繁import有时会抵消部分编译收益。我们的经验是将变更频率和功能紧密性作为首要划分依据。数学库非常稳定且被广泛使用放入Core是合理的。而像“渲染后端抽象”和“具体Vulkan实现”虽然功能相关但后者变动更频繁且可能希望替换如换用D3D12因此拆分为Rendering.API抽象接口和Rendering.Vulkan具体实现两个模块是更好的选择。3. 从零搭建基于模块的构建与开发环境3.1 工具链选型编译器与构建系统的抉择模块的支持程度直接取决于工具链。目前以当前时间点计的情况是MSVC (Visual Studio 2022 17.8): 对C20模块支持最为成熟和稳定其生成的BMI文件为.ifc。它是我们开发阶段的主力特别是在Windows平台。Clang (16): 支持也在快速跟进使用.pcm文件。在macOS和Linux上它是首选。对于跨平台项目需要确保代码在两种编译器下都能正确编译。GCC (13): 支持较晚且在某些边缘场景下可能不如前两者完善。对于追求最新稳定性的生产环境可能需要暂缓。构建系统方面CMake (3.28)是目前对模块支持最全面的主流选择。Ninja作为生成后端因其极快的速度成为不二之选。我们放弃了旧有的自定义Makefile全面转向CMake。一个典型的模块CMakeLists.txt看起来像这样# Engine.Core 模块的 CMakeLists.txt cmake_minimum_required(VERSION 3.28) project(Engine.Core LANGUAGES CXX) add_library(Engine.Core) # 关键设置C标准并启用模块 target_compile_features(Engine.Core PUBLIC cxx_std_23) # 我们使用C23作为基线为C26特性留空间 set_target_properties(Engine.Core PROPERTIES CXX_SCAN_FOR_MODULES ON # 让CMake扫描模块依赖 CXX_STANDARD_REQUIRED ON ) # 模块的接口源文件 target_sources(Engine.Core PUBLIC FILE_SET cxx_modules TYPE CXX_MODULES FILES src/core/module.ixx PRIVATE src/core/memory/allocator.cpp src/core/logging/logger.cpp # ... 其他私有实现文件 ) # 包含目录 target_include_directories(Engine.Core PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ) # 依赖这个核心模块可能依赖一些第三方库如fmt find_package(fmt REQUIRED) target_link_libraries(Engine.Core PUBLIC fmt::fmt)对于上层模块如Engine.Rendering其CMakeLists.txt需要声明对Engine.Core的依赖add_library(Engine.Rendering ...) target_link_libraries(Engine.Rendering PUBLIC Engine.Core) # CMake会自动处理模块依赖关系3.2 开发环境配置让VS Code和Visual Studio高效协作虽然我们主要使用Visual Studio进行开发和调试但很多同事习惯使用VS Code进行代码阅读和轻量编辑。因此配置一个统一的、支持模块的编辑体验很重要。对于Visual Studio 2022 确保安装时勾选了“使用C的桌面开发”和最新的MSVC工具集。在项目属性中“C/C” - “常规” - “扫描源以查找模块依赖”需设置为“是”。VS 2022对模块的IntelliSense支持已经相当好能够正确识别import语句并提供代码补全、跳转。对于VS Code 配置关键在于c_cpp_properties.json和CMake Tools扩展。通过CMake: Configure让CMake Tools生成编译数据库compile_commands.json。在c_cpp_properties.json中设置configurationProvider: ms-vscode.cmake-tools这样C/C扩展就能从CMake获取正确的包含路径和编译定义。对于模块Clang版本的IntelliSense需要额外配置。一个有效的配置片段如下{ configurations: [ { name: Win32, compileCommands: ${workspaceFolder}/build/compile_commands.json, compilerPath: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.xx.x/bin/Hostx64/x64/cl.exe, cStandard: c17, cppStandard: c23, intelliSenseMode: windows-msvc-x64, // 以下对于模块的IntelliSense支持很重要 compilerArgs: [ /experimental:module, /std:clatest // 或 /std:c20 ] } ], version: 4 }需要注意的是VS Code的C/C扩展对模块的完全支持仍在完善中对于复杂的模块依赖有时IntelliSense可能会滞后或报错尽管实际编译通过。这时信任编译器的报错信息更为可靠。踩坑实录CMake与模块扫描早期我们使用CMake 3.26时CXX_SCAN_FOR_MODULES的行为不太稳定有时无法正确捕获模块间的依赖关系导致构建顺序错误。升级到CMake 3.30后这个问题基本得到解决。我们的教训是务必使用CMake和编译器尽可能新的版本因为模块支持是仍在快速演进的特性。同时在CMakeLists.txt中确保模块接口文件.ixx通过FILE_SET的CXX_MODULES类型添加而不是普通的源文件这是CMake正确识别和处理模块依赖的关键。4. 模块接口与实现单元的设计实战4.1 编写模块接口单元.ixx文件模块接口单元是模块的“门面”。我们以Engine.Core模块的module.ixx为例// module.ixx export module Engine.Core; // 声明模块名 // 分区模块可选将大型模块接口分到不同文件 export import Engine.Core.Base; // 导入并重新导出基础类型分区 export import Engine.Core.Memory; // 导入并重新导出内存管理分区 // export import Engine.Core.Utils; // 工具函数分区 // 直接导出声明 export namespace Engine::Core { // 一个简单的日志器接口 class Logger { public: enum class Level { Debug, Info, Warn, Error }; virtual ~Logger() default; virtual void log(Level level, std::string_view message) 0; // 便捷方法 void debug(std::string_view msg) { log(Level::Debug, msg); } void info(std::string_view msg) { log(Level::Info, msg); } // ... 其他级别 }; // 获取全局日志器实例实现位于模块内部 export Logger getGlobalLogger(); // 一个基础配置类 export class Config { public: virtual ~Config() default; virtual std::optionalstd::string_view getString(std::string_view key) const 0; virtual std::optionalint getInt(std::string_view key) const 0; // ... 其他类型 }; } // 注意标准库头单元可以import这比#include高效得多 import string_view; import optional; import memory; // 虽然这里没直接用到但导入后模块内可用 // 全局模块片段GMF用于处理宏和遗留头文件 module; // 在GMF中可以包含一些必须用#include的代码比如某些第三方库的头文件 #include some_legacy_lib.h // 定义一些只在本模块内有效的宏 #define ENGINE_CORE_LOCAL_MACRO 1 export module Engine.Core; // GMF结束模块声明再次出现C20风格 // 现在开始是模块的“纯净”区域关键设计点export import用于组合模块分区或聚合子模块。它意味着“导入这个模块分区/子模块并将其接口全部作为本模块接口的一部分对外提供”。这是构建模块层级的关键。分区模块对于像Core这样的大型模块将其接口拆分到Engine.Core.Base、Engine.Core.Memory等分区中每个分区有自己的.ixx文件。这保持了代码的物理组织清晰同时逻辑上仍属于同一个模块编译器最终会合并为一个BMI。全局模块片段用于放置那些必须使用#include的内容如某些尚未模块化的第三方库或模块内部使用的宏。非常重要的一点在GMF中定义的宏其影响范围仅限于该模块单元内部不会泄漏给导入者这是模块解决宏污染的核心机制之一。导入标准库头单元使用import vector;而非#include vector。编译器会将其作为“标准库模块”处理编译效率更高。但需要注意编译器支持程度MSVC对标准库模块的支持较好。4.2 模块实现单元与私有实现不是所有代码都适合放在接口单元里。对于实现细节尤其是复杂的模板定义、大型内联函数或者纯粹的内部辅助函数我们使用模块实现单元module.impl.ixx或普通的.cpp文件。// module.impl.ixx - 模块实现单元 module Engine.Core; // 注意不是 export module 它不提供新接口只是实现接口单元中声明的实体。 import iostream; // 实现单元可以导入其他模块 import fstream; namespace Engine::Core { // 实现 getGlobalLogger() Logger getGlobalLogger() { static class DefaultLogger : public Logger { void log(Level level, std::string_view message) override { std::ostream os (level Level::Warn) ? std::cerr : std::cout; os [ static_castint(level) ] message \n; } } logger; return logger; } // 一个内部使用的辅助函数不导出 void internalHelper() { /* ... */ } }普通的私有.cpp文件则更简单它们只需要声明所属的模块// src/core/config/json_config.cpp module Engine.Core; // 声明这个.cpp文件是Engine.Core模块的一部分 import nlohmann/json.hpp; // 导入一个第三方JSON库假设它已模块化 import fstream; namespace Engine::Core { class JsonConfigImpl : public Config { nlohmann::json m_data; public: explicit JsonConfigImpl(const std::filesystem::path path) { std::ifstream file(path); m_data nlohmann::json::parse(file); } std::optionalstd::string_view getString(std::string_view key) const override { // ... 实现 } // ... 其他实现 }; // 这个工厂函数可能通过接口单元中导出的某个函数来调用但类本身可以不导出。 }注意事项接口与实现的分离策略保持接口精简接口单元只export绝对必要的类型和函数。将实现细节尽可能下放到实现单元或私有.cpp中。这减少了接口变更的几率从而减少了依赖它的模块需要重编译的次数。小心内联和模板被export的模板其定义通常必须放在接口单元中因为调用方需要实例化。对于复杂的模板考虑使用显式实例化并在接口中export这些实例将模板定义移入实现单元。例如// module.ixx export module MyLib.Templates; export templatetypename T class MyVector; // 前置声明 export extern template class MyVectorint; // 声明显式实例化 export extern template class MyVectorfloat;// module.impl.ixx module MyLib.Templates; templatetypename T class MyVector { /* 完整定义 */ }; template class MyVectorint; // 显式实例化定义 template class MyVectorfloat;这样MyVectorint的代码只在此处编译一次所有导入者共享减少了代码膨胀和编译时间。5. 依赖管理、构建优化与持续集成5.1 管理模块间与第三方依赖在组件化架构中清晰的依赖关系至关重要。我们使用CMake的target_link_libraries来声明依赖这不仅能传递链接库也能传递模块依赖信息。对于第三方库理想情况是它们也提供了模块接口.ixx文件。越来越多的现代C库开始支持例如{fmt}、spdlog等。对于这样的库我们直接使用import。对于尚未模块化的传统头文件库如许多C语言库或老式C库我们有几种选择封装模块为这个库创建一个薄薄的封装模块。在封装模块的GMF中#include该库的头文件然后export我们需要的类型和函数。这样外部代码通过import我们的封装模块来使用该库实现了隔离。// third_party/glfw.ixx module; #include GLFW/glfw3.h export module ThirdParty.GLFW; export using ::GLFWwindow; // 导出类型别名 export int glfwInit(); // 导出函数 // ... 导出其他需要的符号直接使用如果该库很小或者我们愿意接受其头文件包含的代价可以在需要使用它的模块的GMF或实现文件中直接#include。但这会破坏该模块的“纯净性”并可能带来宏污染。我们为项目建立了一个third_party目录使用CMake的FetchContent或find_package来管理这些依赖并为其中关键的、广泛使用的库创建了封装模块。5.2 构建缓存与分布式编译模块化本身能极大提升增量编译速度但对于完整的干净构建我们还需要其他手段。共享编译缓存我们引入了ccache。ccache可以缓存每个翻译单元的编译结果包括模块BMI的生成。当源文件未改变时直接使用缓存跳过编译。这对于频繁切换分支或清理构建非常有效。在CMake中集成很简单cmake -B build -DCMAKE_CXX_COMPILER_LAUNCHERccache分布式编译对于超大型项目我们使用了distcc或iceccIncredibuild的替代开源方案。它们可以将编译任务分发到网络中的多台机器上。关键点模块的BMI文件生成.ixx-.ifc/.pcm这一步通常无法有效分发因为BMI包含了模块的完整抽象语法树AST生成过程对编译器状态依赖很强。但模块实现单元和普通.cpp文件的编译可以很好地分布式进行。我们的策略是在性能强大的编译服务器上集中生成所有模块的BMI这一步相对较快然后将大量的.cpp编译任务分发出去。5.3 CI/CD流水线设计基于模块的组件化架构为我们的CI/CD带来了新的可能性和挑战。持续集成CI独立组件测试每个模块组件都是一个独立的CMake目标因此可以轻松地为每个组件单独运行单元测试。我们在GitLab CI中为每个模块配置了独立的测试任务只有该模块或其依赖的代码发生变更时才触发对应的测试大大缩短了CI反馈周期。模块接口兼容性检查我们编写了一个脚本在合并请求MR时对比目标分支与特性分支的模块接口.ixx文件。如果发现export的接口被移除或签名被不兼容地修改例如删除了一个公共函数CI会发出警告要求开发者提供迁移说明或否决合并。这有助于维护二进制兼容性如果以动态库形式发布。持续部署/交付CD 组件化的最终目的是实现独立部署。我们将每个核心功能模块如Engine.Rendering,Engine.Physics编译为独立的动态链接库DLL/.so。版本化每个组件DLL都带有版本号如Engine.Rendering-v1.2.0.dll。主引擎可执行文件声明其依赖的组件及版本范围。包管理我们搭建了一个简单的私有NuGet服务器对于Windows和Conan仓库对于跨平台将编译好的组件包包含DLL、导入库.lib、模块BMI文件.ifc以及头文件/模块接口文件发布上去。游戏项目集成具体的游戏项目不再需要从头编译整个引擎。它只需要在自己的CMakeLists.txt中通过find_package找到所需的引擎组件包然后import对应的模块即可。构建时CMake会确保使用正确版本的组件BMI和链接对应的DLL。# 游戏项目的CMakeLists.txt find_package(EngineRendering 1.2.0 REQUIRED) find_package(EnginePhysics 1.1.0 REQUIRED) add_executable(MyGame src/main.cpp) target_link_libraries(MyGame PRIVATE EngineRendering::Rendering EnginePhysics::Physics) # 现在在MyGame的源码中就可以直接 import Engine.Rendering; 了这种架构使得引擎团队可以独立于游戏项目迭代和发布某个组件比如升级物理引擎版本游戏项目可以选择性地集成更新降低了耦合度提升了协作效率。6. 迁移策略、常见问题与性能实测6.1 从传统头文件到模块的渐进式迁移将数百万行代码一次性重写为模块是不现实的。我们采用了渐进式迁移策略“底部向上”迁移从最底层、依赖最少的模块开始比如工具类库、数学库。先将其改造成模块。由于上层代码目前仍使用#include我们需要为这个新模块创建一个兼容层一个传统的头文件里面只包含import该模块的语句可能需要放在module;全局片段之后不对于纯头文件兼容层它本身不是模块单元。更常见的做法是在模块的接口单元中使用#ifdef来同时支持export和传统声明。// 不推荐维护两份接口很麻烦实际上更干净的做法是让新模块和旧头文件并存一段时间。新建Math.ixx模块同时保留旧的math.h但math.h的内容改为#include旧实现或转发到模块通过using。新代码逐步迁移到import Math;旧代码继续使用#include “math.h”直到所有依赖都升级完毕再删除旧头文件。依赖反转与接口稳定在迁移过程中我们优先迁移那些被广泛依赖但自身依赖少的“叶子”模块。对于处于依赖图中部的模块迁移前要确保其接口足够稳定因为一旦改为模块其BMI会成为二进制接口频繁改动会导致依赖它的所有模块重编译。构建系统双轨制在迁移过渡期CMake需要同时处理包含.ixx模块和传统.h/.cpp的混合项目。CMake 3.28对此支持良好。关键是为每个目标统一设置CXX_STANDARD和CXX_SCAN_FOR_MODULESCMake会自动处理混合情况。6.2 开发中遇到的典型问题与解决方案循环依赖模块不允许循环import。这是好事它强迫我们设计出更清晰的依赖层次。如果遇到看似循环的情况需要重构。常见解法提取公共接口将A和B共同依赖的部分提取到新模块C中A和B都导入C。前向声明与延迟依赖如果A只需要B的类型名进行声明而非定义可以在A的接口单元中只做前向声明class B;而不import B。将真正的import B放到需要B定义的A的实现单元中。回调与观察者模式用接口类解耦。BMI文件的管理编译器生成的.ifc或.pcm文件是二进制文件需要妥善管理。我们将其作为构建产物放在${CMAKE_CURRENT_BINARY_DIR}下的特定目录中。在CI和打包时需要将这些BMI文件连同头文件/模块接口文件一起发布因为其他项目导入模块时需要它们。与旧代码尤其是宏的交互这是最棘手的问题之一。模块内部定义的宏不会泄漏出去但外部定义的宏也不会影响模块接口的解析除了在GMF中。对于需要跨模块边界的配置宏例如ENGINE_DEBUG我们不再使用#define而是将其定义为export的常量或通过函数获取或者在编译引擎核心时将其定义作为编译器命令行参数/DENGINE_DEBUG统一传递所有模块在编译时都能看到相同的定义。调试信息与符号使用模块后调试体验和传统方式基本一致。编译器生成的PDBWindows或DWARFLinux调试信息仍然包含完整的源码信息。需要注意的是模块接口中的内联函数调试起来可能和以前略有不同但主流调试器VS GDB LLDB都在积极适配。6.3 性能提升实测数据迁移完成后我们对构建性能进行了量化对比在同一台高性能开发机上完全干净构建从原来的42分钟下降到28分钟。提升约33%。主要收益来自于标准库头单元import vector的重复编译被消除。增量构建修改一个核心基础头文件这是最大的胜利。原来需要重编译约80%的项目耗时约25分钟。现在如果只修改了某个模块的实现单元.cpp则只重编译该模块本身和直接依赖它的模块通常在1-3分钟内完成。如果只修改了模块接口.ixx重编译范围也远小于原来的头文件因为依赖关系是精确的。代码补全与IntelliSense响应在VS 2022中感觉更加流畅尤其是对于大型模板代码因为编辑器不再需要反复解析被包含的头文件。7. 总结与未来展望这次基于C26模块的引擎架构升级是一次彻底的“现代化手术”。初期在工具链、构建脚本和开发习惯上的适应成本确实不低但带来的长期收益是巨大的更快的编译速度、更坚固的代码边界、更清晰的工程结构以及为组件化独立部署铺平了道路。对于正在考虑类似迁移的团队我的建议是从小处着手选择一个相对独立、依赖关系简单的工具库开始模块化实践积累经验。投资工具链确保团队使用的编译器MSVC/Clang、CMake、IDE都是足够新的版本并统一开发环境。设计先行在写代码之前花时间用白板画出理想的模块依赖图明确层级避免循环依赖。拥抱变化C模块标准本身和编译器支持都在快速演进社区最佳实践也在形成中。保持关注并准备好调整你的构建脚本和代码组织方式。展望未来随着C26标准的最终落地和各编译器支持的进一步完善模块必将成为大型C项目的标配。我们下一步计划是探索如何更好地利用模块分区来组织超大型模块以及如何将我们的组件包更无缝地集成到外部游戏项目中真正实现“引擎即服务”的愿景。这条路还很长但第一步迈出后回望过去那种被编译时间支配的恐惧感觉一切都是值得的。
