特定于 Fuchsia 的 Ninja 改进

Fuchsia 构建系统使用自定义 Ninja 二进制文件，从多个方面提升开发者体验。本页面介绍了这些类型。

设计初衷

RFC-0153 中详细介绍了为 Fuchsia 自定义 Ninja 的动机。

简而言之，许多功能会让 Fuchsia 开发者显著受益，而上游版本中很难获得这些功能。

所有特定于 Fuchsia 的更改都在我们的本地 Ninja git 镜像的本地 fuchsia-rfc-0153 分支上执行，并且会定期进行重组，以便轻松地将其作为 GitHub 拉取请求发送到上游项目，如 RFC 的“策略”部分中所述。

功能：正在运行的命令的状态

在您的环境中将 NINJA_STATUS_MAX_COMMANDS 设置为严格正整数，让 Ninja 在智能终端中运行时会在状态行下方输出运行时间最长的命令及其所用时间的表格。例如，使用 export NINJA_STATUS_MAX_COMMANDS=4 时，状态可能如下所示：

[0/28477](260) STAMP host_x64/obj/tools/configc/configc_sdk_meta_generated_file.stamp
  0.4s | STAMP obj/sdk/zircon_sysroot_meta_verify.stamp
  0.4s | CXX obj/BUILD_DIR/fidling/gen/sdk/fidl/fuchsia.me...chsia.media/cpp/fuchsia.media_cpp_common.common_types.cc.o
  0.4s | CXX obj/BUILD_DIR/fidling/gen/sdk/fidl/fuchsia.me...fuchsia.media/cpp/fuchsia.media_cpp.natural_messaging.cc.o
  0.4s | CXX obj/BUILD_DIR/fidling/gen/sdk/fidl/fuchsia.me...dia/cpp/fuchsia.media_cpp_natural_types.natural_types.cc.o

下面的动画图片展示了实际操作效果：

Ninja 多行状态示例

请注意：

  • 在对 Ninja 进行试运行或详细调用（即使用 -n 或 --verbose 标志）时，系统会自动停用此功能。

  • 如果 Ninja 未在交互式 / 智能终端中运行，系统会自动停用此功能。

  • 运行控制台命令时，此功能也会暂停（在运行 Bazel 操作时，在上面的示例中可见）。

  • 借助此功能，您可以轻松地直观呈现构建中的瓶颈，即阻止其他命令并行运行的长期命令。

命令表默认每秒更新 10 次，这对于了解哪些长命令妨碍了构建非常有用。可以通过将 NINJA_STATUS_REFRESH_MILLIS 设置为以毫秒为单位的十进制值来更改刷新周期（系统不会忽略任何小于 100 的值，因为经过的时间只能输出到一个小数位）。

功能：持久模式可缩短启动时间

通过在环境中设置 NINJA_PERSISTENT_MODE=1 来加速连续的 Ninja 调用。此功能会使 Ninja 启动后台服务器进程以读取一次 build 清单，然后在连续 build 之间将 build 图保留在内存中。

请注意：

  • 此功能应该是完全透明的，并且不应以其他方式影响 Ninja 的行为。如果您发现了问题或差异，请通过 fuchsia-build-team@google.com 告诉我们！

  • 系统会自动检测输入 .ninja 文件中所做的任何更改。这种情况下，现有服务器将关闭，并自动启动新服务器。更改 GN build 文件或执行 jiri update 后，无需进行额外的用户互动。

  • 服务器进程将在空闲 5 分钟后正常关闭。在您的环境中设置 NINJA_PERSISTENT_TIMEOUT_SECONDS=<count> 可更改此延迟。

  • 使用 fx build -t server status 可检索服务器中当前 build 目录的状态。

  • 使用 fx build -t server stop 可明确停止任何正在运行的服务器实例。

  • 设置 NINJA_PERSISTENT_LOG_FILE=<path> 以将与持久性模式相关的日志发送到给定文件路径。

  • 对于 core.x64 build 配置，目前每个服务器进程占用约 1 GiB 的 RAM。确切数字取决于 Ninja 图的大小，具体取决于您的 args.gn 配置。

  • 每个 Ninja 构建目录最多只能由一个服务器进程提供。但是，使用多个构建目录时，可能会有多个进程。

  • Ninja 工具（例如 ninja -C <dir> -t commands <target>）尚未在服务器上运行，因此启动速度仍然很慢。此问题将来会得到解决，以加快查询速度。

将会解决的已知 bug / 注意事项：

  • 目前，在同一目录中混合使用永久性构建和非永久性构建可能会使服务器混淆，因为无法正确检测对 Ninja 构建和依赖项日志的独立更改。此问题将得到解决。

    权宜解决方法：先使用 -t server stop 停止服务器，然后再在您的环境中取消设置 NINJA_PERSISTENT_MODE。

  • “快速启动”需要几秒钟的时间。目前，每个增量构建仍然需要针对构建图中的所有文件调用 stat()，这目前需要几秒钟的时间。将来，此问题将通过使用主机操作系统的基于 inotify / kqueue 的文件系统监控功能来修复，以便在只有少数文件被修改时立即启动。

  • 尚不支持 Windows。这是由于 Win32 技术限制导致的，该限制会阻止将控制台句柄复制到其他进程。这主要对上游 Ninja 团队来说是一个问题，因为 Fuchsia 开发在 Windows 上不进行。