GN

GN 是一个元构建系统，用于为 Ninja 生成构建文件。

相关资源：

• docs/ 中的文档。特别是：
  • GN 快速入门指南。
  • 常见问题
  • 参考手册（所有内置帮助整合为单个文件）。
  • 入门 演示文稿。
  • 邮件列表。
  • 缺陷数据库。

GN 的用途

GN 目前被用作 Chromium、Fuchsia 及相关项目的构建系统。GN 的一些优势包括：

• 专为大型项目和大型团队设计。它能高效扩展到数千个构建文件和数万个源文件。

  • 语法简洁易读。构建配置完成后，即使没有 GN 背景知识的人员，通常也能轻松对构建进行基本编辑。

  • 专为多平台项目设计。它能清晰地表达跨不同平台的多种复杂构建变体。单次构建调用可面向多个平台。

  • 支持多个并行输出目录，每个目录都有其自己的配置。这使开发者能并行维护面向调试、发布或不同平台的构建，切换时无需强制重建。

  • 注重正确性。GN 会尽可能检查依赖项、输入和输出的正确性，并提供多种工具确保构建按预期演进（例如 gn check、testonly、assert_no_deps）。

  • 命令行提供全面的内置帮助。

尽管小型项目也成功使用了 GN，但针对大型项目的侧重点也带来了一些劣势：

• GN 的目标是保持最小表达性。虽然它可以相当灵活，但设计目标是引导大型团队中可能对构建了解不多的成员走上易于理解、路径清晰的道路。对于小型项目而言，这不一定是正确的权衡。

  • 最小构建配置相对重量级。需要多个文件，并且必须在配置中明确指定所有编译器和链接器的运行方式（见下文“示例”）。没有默认的编译器配置。

  • 不易组合。GN 设计用于编译具有相对统一设置和规则的单个大型项目。像 Chromium 这样的项目确实整合了来自多个团队的多个代码库，但这些项目必须在构建文件中达成一些约定才能实现这一点。

  • GN 的设计前提是，构建项目的开发者希望编译完全相同的配置。因此，虽然构建可以根据需要集成用户环境变量（如 CXX 和 CFLAGS），但这不是默认行为，且大多数项目的构建不会这样做。结果是，许多 GN 项目与 ebuild 等其他系统的集成不够顺畅。

  • 没有简单的发布方案（见下文“版本控制和分发”）。项目需要自行管理其所需的 GN 版本。获取合适的 GN 二进制文件可能对项目的新贡献者构成障碍。由于 GN 相对不常见，查找相关信息和示例可能更加困难。

GN 可以为大多数主流平台上的 C、C++、Rust、Objective-C 和 Swift 源代码生成 Ninja 构建文件。其他语言可以使用由 Python 或其他脚本语言执行的通用“action”规则进行编译（Google 就是这样编译 Java 和 Go 的）。但由于这种方式不够简洁，通常只有当构建的主要部分使用内置的主要语言之一时，才会使用 GN。

获取二进制文件

您可以从 Google 的构建基础架构下载适用于 Linux、 macOS 和 Windows 的最新版本 GN 二进制文件（有关其预期工作方式，请参见下文的“版本控制和分发”）。

或者，您可以使用 C++17 编译器从源代码构建 GN：

git clone https://gn.googlesource.com/gn cd gn python build/gen.py # 如果希望在构建时包含警告，请使用 --allow-warning。 ninja -C out # 运行测试： out/gn_unittests

在 Windows 上，要求 cl.exe、link.exe 和 lib.exe 能在 PATH 中找到，因此您需要从 Visual Studio 命令提示符或类似环境中运行。

在 Linux、Mac 和 z/OS 上，默认编译器是 clang++，要求 PATH 中存在其最新版本。可以通过设置 CC、CXX 和 AR 环境变量来覆盖默认编译器。

在 MSYS 和 MinGW 上，默认编译器是 g++，要求 PATH 中存在其最新版本。可以通过设置 CC、CXX、LD 和 AR 环境变量来覆盖默认编译器。

在 z/OS 上，构建 GN 需要安装 ZOSLIB，具体安装方法如该网址所述。使用 build/gen.py 构建时，使用选项 --zoslib-dir 指定 ZOSLIB 的路径：

cd gn python build/gen.py --zoslib-dir /path/to/zoslib

默认情况下，如果不指定 --zoslib-dir，gn/build/gen.py 会期望在 gn/third_party/ 目录下找到 zoslib 目录。

示例

examples/simple_build 目录中有一个简单示例，是了解最小配置的良好起点。

要使用默认的 gcc 编译器构建并运行简单示例：

cd examples/simple_build ../../out/gn gen -C out ninja -C out ./out/hello

有关完整配置，请参见 Chromium 设置：

• .gn
  • BUILDCONFIG.gn
  • 工具链设置
  • 编译器设置

以及 Fuchsia 设置：

• .gn
  • BUILDCONFIG.gn
  • 工具链设置
  • 编译器设置

报告缺陷

如果您发现缺陷，可以先查看该缺陷是否为已知问题，或在缺陷数据库中进行报告。

提交补丁

GN 使用 Gerrit 进行代码审查，其托管地址为 gn-review.googlesource.com。提交补丁的简要步骤如下：

首先在 https://gn-review.googlesource.com 注册账号。

... 编辑代码 ...
ninja -C out && out/gn_unittests

然后，上传更改以进行审查：

git commit git push origin HEAD:refs/for/main

首次执行此操作时，服务器可能会提示缺少 change-ID 错误。请按照错误消息中的说明安装 change-ID 钩子，并运行 git commit --amend 将该钩子应用于当前提交。

修订更改时，请使用：

git commit --amend git push origin HEAD:refs/for/main

这会将新更改添加到现有代码审查中，而不是创建新的审查。

我们要求所有贡献者签署 Google 的贡献者许可协议（根据情况选择个人或企业协议，选择“任何其他 Google 项目”）。

社区

您可以在 Chromium 的 gn-dev@ Google 群组中提问并关注 GN 的开发动态。

版本控制与分发

大多数开源项目旨在使用开发者计算机上当前的工具链，例如编译器、链接器和构建工具。但 GN 所面向的大型集中控制项目通常需要更封闭的环境。这些项目会确保开发者使用与代码版本相匹配的特定兼容工具链。

因此，GN 期望项目为每个版本选择与之兼容的 GN 版本。不存在一个“当前稳定版本”的 GN 可适用于所有项目。

因此，GN 开发者不会在各种打包系统（Debian、RedHat、HomeBrew 等）中维护任何软件包。其中一些系统可能有 GN 软件包，但这些均由第三方维护，使用时需自行承担风险。相反，我们建议您通过签出工具从 Google 的构建基础架构 下载特定哈希值的二进制文件，或自行编译。

GN 不保证新版本的向后兼容性，除了 main git 分支上的提交序列（预期是稳定的）外，没有其他分支或版本控制方案。

不过，实际上 GN 具有很强的向后兼容性。核心功能多年来一直保持稳定，仅 Google 内部就有大量的 GN 代码，这使得即使非向后兼容的更改是可取的，实施起来也非常困难。

关于添加具有向后兼容性保证的版本控制方案已有相关讨论，但目前尚未实施。