1. 项目概述为什么是GN和Ninja如果你在C或者Chromium相关的项目里摸爬滚打过一阵子大概率会听说过GN和Ninja这两个名字。它们不像CMake或Make那样“历史悠久”但在追求极致构建速度的大型项目尤其是像Chromium、Fuchsia这样的巨无霸中几乎成了标配。简单来说GN负责生成构建文件Ninja负责执行构建。这套组合拳的核心目标就一个快。为什么我们需要这套新工具想象一下你面对一个拥有数万甚至数十万个源文件的项目每次修改一两个文件传统的构建系统比如基于Make的可能因为依赖关系分析不够精细或者构建脚本本身解析缓慢导致增量构建也要等上几十秒甚至几分钟。这对于需要频繁编译、测试的开发流程来说简直是噩梦。GN和Ninja就是为了解决这个痛点而生的。GN的语法比CMake更简洁、声明式生成构建描述文件.ninja文件的速度极快而Ninja则是一个高度专注于速度的小型构建工具它只做一件事——以最快的速度执行GN生成的构建图。它的设计哲学是“不浪费时间”没有复杂的逻辑没有shell调用一切为了并行编译和最小化重建。所以当你看到“手把手使用GN和ninja构建编译过程”这个标题时它背后指向的是一套面向现代大型C/C项目的高效构建方法论。无论你是想深入理解Chromium的构建体系还是为自己庞大的个人项目寻找一个更快的构建方案掌握GN和Ninja都将是极具价值的一步。接下来我将以一个具体的示例项目为线索带你从零开始完整走通配置、生成、构建的全过程并分享那些官方文档里不会写的实操细节和避坑指南。2. 环境准备与工具链搭建在开始挥舞GN和Ninja之前我们需要先把“兵器”准备好。这个过程本身也是理解其生态的一部分。2.1 获取GN与Ninja首先明确Ninja是一个独立的构建执行器你需要单独安装它。而GN本身通常不作为一个独立工具分发它往往作为某个大型项目如Chromium源代码树的一部分存在。但为了方便学习和独立使用我们可以通过Chromium的源码库获取GN的独立版本。Ninja的安装Ninja的安装非常直接。它主要是一个用C写成的单二进制文件。Linux/macOS: 通常可以通过包管理器安装例如sudo apt-get install ninja-build(Ubuntu/Debian) 或brew install ninja(macOS)。Windows: 可以从其 GitHub发布页 下载预编译的ninja-win.zip解压后将ninja.exe放入你的系统PATH路径中。源码编译: 你也可以从上述GitHub仓库下载源码用./configure.py --bootstrap生成二进制文件。这本身就是一个有趣的练习因为它就是用Ninja构建自己的过程。验证安装在终端运行ninja --version应该能输出版本号。GN的获取与构建GN是用Python写的但其核心逻辑后来用C重写了以获得更好性能。我们通常需要从源码构建它。确保你已经安装了Python3和Git。获取Chromium的depot_tools工具包这是Google为管理大型源码仓库包括Chromium、GN而开发的一套工具集合。git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git将depot_tools目录添加到你的系统PATH环境变量最前面。在一个干净目录下获取GN的源码并编译# 创建一个工作目录 mkdir gn_standalone cd gn_standalone # 获取GN源码 fetch gn # 进入gn目录并编译 cd gn python build/gen.py ninja -C out gn # 这里就用到了我们刚安装的ninja编译完成后在gn/out/目录下会生成gnLinux/macOS或gn.exeWindows可执行文件。同样将其路径加入系统PATH。验证GN运行gn --version。注意depot_tools在首次使用时可能会自动下载一些依赖如特定版本的Python、Git并可能因网络环境导致较慢或失败。请确保你的网络可以访问相关资源。这是使用Google系开发工具的第一个常见“坑点”。2.2 理解核心概念BUILD.gn与.gn文件在GN的世界里有两个核心的配置文件.gn文件 这是项目的根配置文件通常位于项目源代码的根目录。它定义了整个构建的全局设置比如buildconfig指向一个定义默认工具链、配置等的核心脚本文件。root指定构建的根目录通常是包含.gn文件的目录。root_build_dir指定生成的.ninja构建文件和中间文件的输出目录默认为out。 一个最简单的.gn文件可能只有一行buildconfig //build/config/BUILDCONFIG.gn它引用了一个共享的配置。BUILD.gn文件 这是GN的模块定义文件相当于Makefile或CMakeLists.txt。你会在项目的各个子目录中创建它用来声明在那个目录下有哪些“目标”target需要被构建比如可执行文件、静态库、动态库等。GN会递归地读取这些BUILD.gn文件来构建整个依赖关系图。工具链Toolchain是另一个关键概念。它定义了用于编译、链接等一系列操作的具体命令如gcc、clang、msvc、标志flags和规则。GN允许你同时使用多个工具链例如同时编译主机和目标机代码。在.gn文件中指定的buildconfig通常会载入默认的工具链定义。3. 编写第一个BUILD.gn文件理论说得再多不如动手写一行。让我们从一个最简单的“Hello World”项目开始。3.1 项目结构规划假设我们有一个微型项目目录结构如下my_project/ ├── .gn ├── BUILD.gn └── src/ ├── BUILD.gn ├── main.cc └── utils/ ├── BUILD.gn └── logging.cc3.2 逐层解析BUILD.gn配置1. 项目根目录.gn文件# my_project/.gn # 指定构建配置文件的位置。“//”代表源代码根目录。 buildconfig //build/config/BUILDCONFIG.gn这里我们引用了一个相对路径的配置。在实际项目中这个文件可能包含更多全局变量设置。2. 创建构建配置目录和文件我们需要创建//build/config/BUILDCONFIG.gn文件以及一个简单的工具链定义。为了简化我们可以直接使用GN内置的默认配置。但为了理解我们创建一个最小化的版本。首先在my_project/build/config/下创建BUILDCONFIG.gn# my_project/build/config/BUILDCONFIG.gn # 声明默认的工具链。这里我们指向一个即将定义的工具链文件。 _default_toolchain //build/toolchains:gcc_toolchain # 设置默认的工具链为上面声明的。 set_default_toolchain(_default_toolchain)然后创建工具链定义my_project/build/toolchains/BUILD.gn# my_project/build/toolchains/BUILD.gn # 定义一个工具链模板 template(gcc_toolchain) { # toolchain() 是一个特殊的目标类型用于定义工具链 toolchain(target_name) { # 工具链的作用域这里我们简单地复用当前文件的目录 toolchain_args { current_cpu x64 current_os linux # 定义各种工具的命令 cc gcc cxx g ld g ar ar # 定义编译和链接标志 cflags [ -Wall, -Wextra, -stdc17 ] ldflags [ ] } } }这个工具链定义非常基础实际项目中如Chromium的工具链定义要复杂得多会处理各种平台、编译器变体、调试/发布模式等。3. 源代码目录的BUILD.gn文件现在我们来定义真正的构建目标。首先是工具库utils/logging.cc// my_project/src/utils/logging.cc #include iostream void LogMessage(const std::string msg) { std::cout [LOG] msg std::endl; }对应的my_project/src/utils/BUILD.gn# my_project/src/utils/BUILD.gn # 声明一个静态库目标 static_library(utils) { # 指定构建此目标所需的源文件 sources [ logging.cc, ] # 公开头文件搜索路径如果头文件在别处需要包含进来 # include_dirs [ ../include ] # 可以设置只对此目标生效的编译标志 # cflags [ -O2 ] }接着是主程序src/main.cc// my_project/src/main.cc #include iostream // 假设LogMessage的声明在logging.h中这里为了简单直接extern void LogMessage(const std::string msg); int main() { std::cout Hello, GN and Ninja! std::endl; LogMessage(Application started.); return 0; }对应的my_project/src/BUILD.gn# my_project/src/BUILD.gn # 声明一个可执行文件目标 executable(hello_gn) { # 指定源文件 sources [ main.cc, ] # 声明依赖项依赖于上面定义的utils静态库。 # 依赖路径使用GN的标签label系统“//”开头表示从源码根目录开始 # “:”后面是目标名。 deps [ //src/utils:utils, ] }最后在项目根目录创建一个总的BUILD.gn它可以是一个容器或者简单地引用子目录的目标# my_project/BUILD.gn # 这个文件可以聚合子目录的目标方便一次性构建多个目标。 group(default) { deps [ //src:hello_gn, ] }group目标本身不产生任何文件它只是一个依赖项的集合。将default设为group是一个常见做法这样在根目录执行构建时默认就会构建所有重要的东西。4. 生成与执行构建GN到Ninja的桥梁配置文件写好了接下来就是让GN把它们“翻译”成Ninja能懂的语言。4.1 运行GN生成构建文件在项目根目录my_project/下打开终端执行gn gen out/Default这条命令做了以下几件事gn: 调用GN程序。gen: 子命令表示“生成”。out/Default: 指定输出目录。这是一个相对路径相对于当前目录。.gn文件中的root_build_dir如果未设置则以此为准。通常我们会用out/Default作为默认配置的构建目录也可以用out/Debug、out/Release等来区分不同的构建类型。执行成功后你会在my_project/out/Default/目录下看到生成的文件其中最重要的是build.ninja。这个文件包含了Ninja执行构建所需的所有规则和依赖关系。同时还会生成toolchain.ninja、ninja.build等文件。关键参数解析--args: 这是最常用的参数之一允许你在生成时传递构建参数覆盖.gn或BUILDCONFIG.gn中的默认设置。例如gn gen out/Debug --argsis_debugtrue is_component_buildfalse target_cpu\x64\这里设置了三个参数开启调试符号、关闭组件化构建影响链接方式、目标CPU为x64。参数使用单引号包裹内部字符串用双引号转义。4.2 使用Ninja进行编译生成构建文件后切换到输出目录或者直接从项目根目录指定构建目录使用Ninja进行编译# 方式一进入输出目录执行 cd out/Default ninja # 方式二从项目根目录指定构建目录 ninja -C out/DefaultNinja会读取build.ninja文件检查文件时间戳然后并行地编译所有需要更新的目标。你应该能在终端看到编译输出并在out/Default目录下找到生成的可执行文件hello_gn在Linux/macOS下或hello_gn.exe在Windows下。运行它./out/Default/hello_gn你会看到输出。4.3 构建参数管理与变体构建GN的强大之处在于灵活的构建参数系统。你可以在BUILD.gn文件中通过declare_args()声明参数在gn gen --args时传入或者在单独的args.gn文件中进行配置。使用args.gn文件进行持久化配置在构建目录如out/Default下可以创建一个args.gn文件。GN在生成构建文件时会读取它。# 在 out/Default 目录下 echo is_debug true args.gn echo is_component_build false args.gn echo target_cpu x64 args.gn创建后下次直接运行gn gen out/DefaultGN会自动应用这些参数。你也可以使用gn args out/Default命令这会打开一个编辑器默认是系统编辑器让你直接编辑args.gn文件非常方便。变体构建示例你可以轻松管理多个构建配置。# 调试版本 gn gen out/Debug --argsis_debugtrue symbol_level2 # 发布版本 gn gen out/Release --argsis_debugfalse is_official_buildtrue # 针对ARM64的交叉编译假设工具链已配置 gn gen out/Android --argstarget_os\android\ target_cpu\arm64\每个out/下的子目录都是独立的构建环境拥有自己的args.gn和生成的Ninja文件互不干扰。5. 高级特性与实战技巧掌握了基础我们来看看GN的一些高级特性和实战中积累的技巧。5.1 依赖管理与可见性控制GN的依赖系统非常直观使用deps列表来声明。但GN还有一个强大的可见性Visibility概念用于控制哪些其他目标可以依赖当前目标。默认情况下一个目标只能被同一BUILD.gn文件内的其他目标依赖。如果你希望跨目录依赖需要设置visibility。# 在 //src/utils/BUILD.gn 中 static_library(internal_utils) { sources [ ... ] # 只允许 //src/app 目录下的目标依赖我 visibility [ //src/app:* ] # 或者允许所有目标依赖 # visibility [ * ] # 或者不允许任何外部依赖最严格 # visibility [] }这是一个重要的工程实践可以防止代码库中形成混乱的、意想不到的依赖关系有助于维护清晰的模块边界。5.2 模板Template的使用模板是GN中用于代码复用的强大工具。它可以让你定义一种通用的目标生成模式。Chromium的构建文件中大量使用了模板。例如我们创建一个用于生成版本信息文件的模板# //build/version.gni (注意后缀是.gni表示GN导入文件) # 定义一个模板 template(“generate_version_header”) { # 模板内部target_name是调用模板时传入的目标名。 # 这里我们假设会传入一个变量 version_file generated_file(target_name) { # 输出文件路径 outputs [ “$target_gen_dir/{{source_name_part}}.h” ] # 数据源这里我们用一个脚本生成 data_keys [ “version” ] # 调用一个Python脚本进行处理 script “//build/scripts/write_version.py” # 传递给脚本的参数 args [ “—output”, rebase_path(outputs[0], root_build_dir), “—version”, invoker.version, ] } }然后在BUILD.gn中使用这个模板# 导入模板文件 import(“//build/version.gni”) generate_version_header(“my_version”) { version “1.2.3.4” }这样我们就通过模板复用了一套生成版本文件的逻辑。模板可以封装复杂的动作、规则是构建系统模块化的关键。5.3 条件判断与配置传播GN支持基于构建参数的条件判断这使得一份BUILD.gn文件可以适配多种平台和配置。static_library(“my_lib”) { sources [ “common.cc”, ] if (is_win) { sources [ “win_specific.cc” ] defines [ “WINDOWS_BUILD” ] } else if (is_mac) { sources [ “mac_specific.mm” ] # 注意Objective-C源文件后缀 } if (is_debug) { cflags [ “-O0”, “-g3” ] } else { cflags [ “-O2”, “-DNDEBUG” ] } }is_win,is_mac,is_debug,target_cpu等都是GN内置或通过构建参数定义的变量。通过if语句我们可以精确控制每个目标的源码、编译标志和依赖。配置Config是另一种复用设置的方式。你可以将一组通用的cflags、defines、include_dirs打包成一个config然后让多个目标引用configs它。# //build/config/compiler.gni (或某个BUILD.gn文件内) config(“strict_warnings”) { cflags [ “-Wall”, “-Wextra”, “-Werror”, # 将警告视为错误 ] } # 在目标中使用 executable(“my_app”) { … configs [ “//build/config:strict_warnings” ] }6. 常见问题排查与性能调优即使工具设计得再好在实际使用中也难免会遇到问题。以下是一些常见场景和排查思路。6.1 依赖问题与Ninja错误解析问题ninja: error: unknown target ‘gz_x500’这个错误直接来源于你提供的网络热词。它意味着Ninja在它读取的build.ninja文件中找不到名为gz_x500的构建目标。原因通常是GN生成不完整或失败可能GN在解析BUILD.gn时遇到了语法错误或者某个依赖的目标不存在导致生成过程未包含你指定的目标。请检查gn gen命令的输出是否有错误。目标名称拼写错误你要求Ninja构建的目标名如ninja gz_x500与BUILD.gn文件中定义的target_name不一致。GN的标签是大小写敏感的。构建目录不对你可能在错误的构建目录如out/Release中尝试构建一个只在另一个目录如out/Debug中定义的目标。排查首先确认你执行ninja命令的目录下存在build.ninja文件。然后运行ninja -t targets all | grep gz_x500查看该目标是否存在。如果不存在回到项目根目录用gn ls out/Default将out/Default替换为你的构建目录列出所有有效目标看看gz_x500是否在其中。问题增量构建失效总是全量重建这可能是依赖关系声明不正确导致的。GN/Ninja严重依赖文件时间戳和声明的依赖关系图。如果头文件未被正确纳入依赖修改头文件后Ninja可能不会重新编译依赖它的源文件。在GN中通常源文件对同目录下的同名头文件foo.cc依赖foo.h是自动推断的。但对于其他头文件你需要确保它们被包含在目标的sources中对于公开头文件或者通过include_dirs引入的路径下的文件GN的依赖扫描器在生成阶段运行会解析#include语句并自动建立依赖。确保你的include_dirs设置正确。可以使用Ninja工具调试ninja -d explain可以解释为什么Ninja决定重建某个目标。ninja -t deps可以输出依赖关系图帮助你验证。6.2 GN语法错误与调试GN的语法错误信息通常比较直观会指出出错的文件和行号。常见错误括号不匹配GN大量使用{}和[]务必保持配对。字符串拼接错误字符串使用双引号变量引用使用$。“prefix_${variable}_suffix”是正确的拼接方式。作用域错误在template内部和外部变量访问规则不同。invoker用于访问模板调用者传入的变量。路径错误GN使用//开头的绝对标签路径。确保路径指向正确的BUILD.gn文件和目标名。调试技巧使用gn desc命令这是一个极其强大的调试工具。例如gn desc out/Default //src:hello_gn显示该目标的所有详细信息。gn desc out/Default //src:hello_gn deps --tree以树形图显示该目标的所有依赖。gn desc out/Default //src:hello_gn sources显示该目标的源文件列表。在BUILD.gn中使用print()函数这会在gn gen阶段输出信息对于调试变量值、查看条件分支非常有用。例如print(“Current OS is: ”, current_os)。6.3 性能优化建议将构建输出放在SSD上这可能是提升构建速度最有效的硬件投资。Ninja会产生大量中间文件磁盘IO是关键。合理设置并发数Ninja默认使用与CPU核心数相同的并行任务数-j。你可以通过环境变量NINJA_STATUS或命令行参数-j N来调整。通常设置为CPU核心数 1或CPU核心数 * 1.5是个不错的起点但需要根据你的内存大小调整避免内存耗尽。利用CCache对于C/C项目强烈建议使用 ccache 编译器缓存。它会缓存编译结果当相同的编译任务再次出现时直接使用缓存对清理后重建或切换分支后的构建提速效果惊人。在GN中可以通过在args.gn中设置cc_wrapper “ccache”来启用前提是ccache已在PATH中。精简构建目标使用gn gen的—args或args.gn来禁用不需要的功能。例如在Chromium中你可以设置is_component_buildtrue进行组件化构建链接更快但最终产物是多个so/dll或者关闭测试、示例等 (enable_naclfalse)。保持构建目录独立为不同的配置Debug/Release/ARM64使用独立的out/子目录避免相互污染和重复生成。7. 与现有构建系统的集成与迁移你可能已经有一个使用CMake、Autotools甚至纯Makefile的项目。完全重写构建系统成本很高GN提供了一些集成路径。7.1 在GN中调用外部构建系统GN可以通过action或action_foreach目标类型执行任意的shell命令或脚本。这意味着你可以封装现有的Make或CMake构建步骤。action(“build_legacy_lib”) { # 脚本文件 script “//scripts/build_legacy.py” # 该动作的输出文件Ninja将根据这些文件的时间戳判断是否需要重新执行action outputs [ “$target_gen_dir/liblegacy.a” ] # 传递给脚本的参数 args [ “—source-dir”, rebase_path(“//third_party/legacy”, root_build_dir), “—output”, rebase_path(outputs[0], root_build_dir), ] # 声明这个动作依赖哪些源文件源文件变化会触发重建 sources [ “//third_party/legacy/Makefile” ] }然后你的新目标可以像依赖普通库一样依赖这个action的输出executable(“my_app”) { deps [ “:build_legacy_lib” ] libs [ “$target_gen_dir/liblegacy.a” ] }7.2 从CMake/Makefile逐步迁移完全迁移大型项目的最佳策略是渐进式从叶子模块开始选择项目中最独立、依赖最少的库或工具为其编写BUILD.gn文件。使用GN构建该模块将其输出.a, .so, .exe集成到现有的主构建流程中例如让CMake去链接这个GN生成的库。建立桥接如上节所述用GN的action调用剩余的CMake/Makefile构建。逐步扩大范围当一个模块被成功迁移并稳定后再迁移其上游依赖模块。像剥洋葱一样从外向内逐步替换。最终切换当所有核心模块都迁移完毕后重写顶层的入口BUILD.gn移除所有对外部构建系统的调用。这个过程需要仔细管理依赖关系并确保中间产物如头文件路径、库文件在两个构建系统间能够正确传递。编写一些辅助脚本来自动生成部分GN配置比如从CMakeLists.txt中提取源文件列表可能会很有帮助。7.3 工具链文件的适配如果你需要进行交叉编译如为Android、iOS或嵌入式设备编译那么编写或适配工具链文件是必须的。这通常是迁移过程中最复杂的部分之一。你需要定义目标系统的编译器路径、sysroot、编译标志、链接标志等。参考Chromium或Fuchsia项目中丰富的工具链定义如//build/toolchains/目录下的文件是最好的学习方式。关键是在toolchain()定义中正确设置toolchain_args字典中的所有必要工具和标志。从我的经验来看引入GN/Ninja最大的挑战往往不是语法本身而是对现有项目复杂构建逻辑的重新梳理和抽象。一旦成功那种构建速度带来的流畅感会让你觉得所有的投入都是值得的。尤其是在持续集成CI环境中构建时间的缩短直接意味着更快的反馈循环和更低的资源成本。