跨平台图形学前端【免费下载链接】engineThe Flutter engine项目地址https://gitcode.com/gh_mirrors/eng/engine点击查看免费下载etengine tool是 Flutter Engine 仓库提供的一款命令行工具旨在为构建与开发 Flutter Engine这一高频场景提供统一入口它把 GN 配置生成、Ninja 构建、C/Dart 测试、格式化、静态检查乃至用本地引擎运行 Flutter 应用等操作封装为一组简洁的子命令。本文以 tools/engine_tool/README.md 为骨架结合 tools/engine_tool 下各命令的 Dart 实现源码系统讲解et的安装验证、构建配置build configuration机制、常见任务与高级功能帮助读者快速上手并理解其底层原理。一、认识 et面向 Flutter Engine 的统一 CLIet是一个命令行工具它的设计目标是为构建和在 Flutter Engine 中开展工作提供统一的接口。其定位可从两方面理解对普通引擎开发者提供build、test、format、lint、run等高频命令避免记忆繁琐的gn/ninja参数组合对引擎维护者构建配置以 JSON 形式集中管理在ci/builders/下et自动按平台过滤可用配置保证本地开发与 CI 使用同一套配置语义。从源码结构看et的命令体系定义在 tools/engine_tool/lib/src/commands/command_runner.dart 的ToolCommandRunner中它注册了 8 个子命令cleanup、fetch、format、query、build、run、lint、test并提供了两个全局选项-h/--help与-v/--verbose。使用前提et假定使用者已具备 Flutter 框架与引擎的基本知识例如理解引擎的架构分层在受支持的平台上有一份有效的引擎源码检出搭建步骤见仓库文档 docs/contributing/Setting-up-the-Engine-development-environment.md。事实上工具在非法的仓库环境下根本无法运行——因为它强依赖引擎检出目录中的gn二进制、ci/builders配置与out/输出目录结构。安装与验证建议将引擎根目录下的bin目录加入PATH引擎源码中确实存在可执行入口bin/et与 Windows 下的bin/et.batPATH$PATH:/path/to/engine/flutter/bin注上面示例中的/path/to/engine/flutter即引擎检出的src/flutter目录也就是本仓库的根目录。安装完成后用et help验证是否可用$ et help A command line tool for working on the Flutter Engine. This is a community supported project, file a bug or feature request: https://flutter.dev/to/engine-tool-bug. Usage: et command [arguments] Global options: -h, --help Print this usage information. -v, --verbose Prints verbose output Available commands: build Builds the engine fetch Download the Flutter engines dependencies format Formats files using standard formatters and styles. lint Lint the engine repository. query Provides information about build configurations and tests. run Run a Flutter app with a local engine build. test Runs a test target Run et help command for more information about a command.输出中的命令清单与command_runner.dart中注册的命令一一对应。首次使用前通常还需要执行et fetch下载引擎的依赖即文档中提到的fetch命令对应源码 tools/engine_tool/lib/src/commands/fetch_command.dart。二、理解构建配置build configuration概念et的许多命令都会引用一个构建配置build configuration文档中也称 variant通常用--config简写-c显式指定。一个构建配置至少包含三要素要素字段作用可运行的平台drone_dimensions声明该构建能在哪些主机OS/设备类型上运行编译期标志gn传递给 GN 的编译参数决定产物形态如 runtime mode、是否 LTO名称与描述name、description人类可读的标识也是--config的引用名配置定义在哪里构建配置通常定义在 ci/builders 目录下分两类任务专用配置文件用于 CI 上构建并运行测试例如 ci/builders/mac_unopt.json本地开发配置仅用于本地开发与迭代的配置合集集中在 ci/builders/local_engine.json。以local_engine.json中的一条配置为例截取自该文件开头可以看到真实的结构{ builds: [ { cas_archive: false, drone_dimensions: [osMac-13|Mac-14, device_typenone], gclient_variables: { download_android_deps: false, download_jdk: false, use_rbe: true }, gn: [ --ios, --runtime-mode, debug, --no-stripped, --no-lto, --xcode-symlinks, --rbe, --no-goma ], name: macos/ios_debug, description: Builds a debug mode engine that targets iOS from a macOS host., ninja: { config: ios_debug, targets: [] } } ] }可见一个配置条目由drone_dimensions运行平台约束、gnGN 参数列表、name/description名称与描述、ninja.config输出子目录名等字段组成——这正是文档所说至少包含三要素的完整形态。通过 --config 引用配置配置文件中定义的构建会按名称被--config引用。当名称以ci/为前缀时隐式指向ci/builders/下的 CI 配置文件否则指向local_engine.json# 隐式引用 ci/builders/mac_unopt.json et build --config ci/host_debug_unopt_arm64 # 隐式引用 ci/builders/local_engine.json et build --config host_debug_unopt_arm64底层et 如何加载与过滤配置在源码层面配置的加载与过滤逻辑位于 tools/engine_tool/lib/src/build_plan.dartconfigureArgParser会调用_runnableBuildConfigs用config.canRunOn(platform)过滤出当前平台可运行的配置默认非 verbose模式下还会用_extractBuilds隐藏以ci/前缀开头、不太可能被本地开发选用的配置让--help输出更简洁加-v后才会展示全部配置包括可能的重复项BuildPlan.fromArgResults读取--config的值若未指定则默认回退到host_debug_defaultHostDebug找不到配置时会抛出FatalError。重要警告输出目录占用空间每种构建配置variant都会在$ENGINE/src/out下产生一组不同的输出文件例如$ENGINE/src/out/host_debug。这些输出动辄数 GB且会快速累积。文档明确建议考虑使用et cleanup自动删除较旧的输出目录详见第五节回收旧输出目录。三、常见任务从构建到测试的日常操作以下任务覆盖了引擎开发者和使用者的绝大多数日常需求。3.1 构建 host engine本机桌面引擎最常用、也是默认的操作是构建host变体——即在当前桌面操作系统上运行的引擎。例如在 ARM64 macOS 笔记本上构建 ARM64 macOS 桌面引擎或在 x64 Linux 桌面上构建 x64 Linux 桌面引擎# 构建当前平台host的 debug 构建 et build # 与上面等价 et build --config host_debug关于host_debug这类名字的来源参见上文理解构建配置一节。host engine 在以下场景尤其有用想在脱离具体设备/平台的情况下测试、调试或迭代功能正在开发当前桌面平台相关的功能想组合使用 host 与 target 引擎来运行 Flutter 应用。3.2 构建 target engine目标平台引擎Flutter Engine 还支持多种target引擎——即非当前桌面操作系统的引擎例如 Android 或 iOS。例如在 macOS 笔记本/台式机上可以构建 iOS 模拟器或真机引擎# 构建 iOS 真机非模拟器引擎 et build --config ios_debug # 构建 iOS 模拟器引擎 et build --config ios_debug_sim按约定target 引擎的名称不带host前缀。这在 ci/builders/local_engine.json 中可以印证名为macos/ios_debug、macos/ios_debug_unopt的条目都由 macOS host 构建 iOS target。target engine 在以下场景有用正在开发目标平台特有的功能想组合使用 host 与 target 引擎来运行 Flutter 应用。3.3 构建特定 target精确控制构建范围默认情况下et build会构建整个引擎。例如下面两条命令等价et build --config host_debug et build --config host_debug //flutter/...缓存通常能避免重建未变更的部分但有时开发者比依赖树更清楚到底该重编什么。此时可以给出 GN target 的完整路径来构建特定目标# 只构建 flutter.jar 工件 et build --config android_debug_unopt_arm64 //flutter/shell/platform/android:android_jar目标范围还支持两种通配写法# 递归构建 //flutter/shell/platform 下的所有 target et build --config android_debug_unopt_arm64 //flutter/shell/platform/... # 非递归构建 //flutter/shell/platform 下的所有 target et build --config android_debug_unopt_arm64 //flutter/shell/platform:all底层原理从 tools/engine_tool/lib/src/commands/build_command.dart 的BuildCommand.run()可以看到命令行的目标模式会被TargetPattern.parse解析再调用 tools/engine_tool/lib/src/gn.dart 中的Gn.desc()——等价于执行gn desc --formatjson out/{config} {pattern}——把模式展开成具体的BuildTarget标签集合最后统一交给runBuild执行 Ninja 构建。若某个模式没有匹配到任何 targetgn.dart还会给出是否想写//flutter/...之类的提示。3.4 运行 C 测试C 单元测试可以用et test一边重建一边运行et test //flutter/impeller:impeller_unittests/...与:all两种通配同样被支持。底层原理TestCommandtools/engine_tool/lib/src/commands/test_command.dart的执行分三步用Gn.desc展开用户给定的模式通过whereTypeExecutableBuildTarget().where((t) t.testOnly)过滤出可执行且标记为测试专用的 targettestonly属性来自gn desc的 JSON 输出先runBuild构建这些 target再用WorkerPool并发执行每个测试可执行文件对应源码 tools/engine_tool/lib/src/worker_pool.dart。注意对非 C 测试的支持目前有限见下文运行 Dart 测试。3.5 运行格式化工具对变更过的文件运行所有格式化工具et format有时依赖或工具本身的变更会弄脏你并未修改的文件dirty 状态此时需要全量检查# 检查 *所有* 文件会 *慢得多* et format --all底层原理FormatCommandtools/engine_tool/lib/src/commands/format_command.dart通过启动另一个 Dart VM 运行引擎ci/bin/format.dart来实现并透传相关参数--all-files全量检查、--fix原地修复、--verbose此外它还支持-d/--dry-run只打印 diff 不修改与-q/--quiet仅输出错误和警告。源码注释指出未来计划把format.dart移入 engine_tool 包内、拆分为独立的FormatChecker并补充单元测试。3.6 运行静态检查linter与 formatter 类似仓库级静态检查用et lintet lint在本文写作时linters 总是针对整个仓库运行。3.7 用本地引擎构建运行 Flutter 应用通常用预构建引擎运行 Flutter 应用只需要cd to/project/dir flutter run而在迭代引擎源码时你往往希望使用上面构建出的引擎产物host 与 target 都要。et run正是为此设计cd to/project/dir et run注意et run会在必要时重建 host 与 target 构建可能花费相当长的时间。底层原理RunCommandtools/engine_tool/lib/src/commands/run_command.dart的实现值得展开检查flutter命令是否在PATH中否则直接报错通过 Flutter tool 查询已连接的设备flutter devices根据-d/--device-id前缀或默认首设备选出运行目标RunTarget.detectAndSelect从传给flutter run的参数中嗅探运行模式默认debug含--profile则profile含--release则release再结合设备的目标平台映射出构建配置buildConfigFor——例如 Android 设备映射为android_debug_arm64、桌面平台映射为host_debug、Web 映射为chrome_debugiOS、Fuchsia、flutter_tester等平台目前会明确抛出暂不支持的错误确定 host 构建_findHostBuild若目标配置名包含host_则目标即宿主否则按_debug/_profile/_release后缀匹配对应的host_debug/host_profile/host_release先构建 host再按需构建 target 的 shell 目标例如 Android 是//flutter/shell/platform/android:android_jarWeb 是//flutter/web_sdk:flutter_web_sdk_archive最终以flutter run --local-engine-src-path srcDir --local-engine targetConfig --local-engine-host hostConfig的形式把本地引擎交给 Flutter tool 使用--之后的参数原样透传给flutter run例如et run -- --profile、et run -- -d macos。四、高级功能Advanced Features以下功能可能主要面向引擎团队的部分成员或上游用户例如 Dart VM / SDK 团队开发者相比常见任务它们可能处于相对不完整的状态或不够直观易用。4.1 启用远程构建执行RBEGoogle 员工可以选择使用远程构建执行Remote Build ExecutionRBE来大幅加速构建复用先前构建并缓存的工件并把编译任务委托给高配的远程虚拟机。启用 RBE 需要遵循引擎官方指引文档原文给出flutter.dev/to/engine-rbe入口此处不再粘贴外部链接。启用后默认情况下et构建会尽可能使用 RBE这也隐式要求网络处于连通状态。可以用--build-strategy为单条命令临时切换本地/远程偏好# 完全在本地构建对某些增量构建可能更快且不要求联网 et build --build-strategylocal # 完全在远程构建对本机负担更小但要求快速网络 et build --build-strategyremote如果想在启用后禁用RBE可用--no-rbeet build --no-rbe警告禁用 RBE 会使构建上下文失效之前启用状态下构建的工件不会被复用。除非你在调试工具本身或 RBE 配置否则建议使用--build-strategylocal而不是--no-rbe。底层原理BuildStrategy枚举tools/engine_tool/lib/src/build_plan.dart定义了三种策略auto优先远程、失败时静默回退本地也是默认值、local本地构建不要求网络、remote远程构建未指定--rbe时构建会失败。构建计划通过toRbeConfig()将其转换为RbeConfig同时configureArgParser会用environment.hasRbeConfigInTree()检测仓库内是否已配置 RBE——只有检测到 RBE 配置时--rbe才默认为开启且--build-strategy选项才默认可见。若--rbe被显式要求但仓库内没有对应配置BuildPlan会抛出带说明的FatalError。4.2 运行 Dart 测试et对运行Dart单元测试提供有限支持et test //flutter/tools/engine_tool/...注意与 C 不同目前 Dart 测试并不强制要求在BUILD.gn中声明 target绝大多数包都没有声明。随着 GN 在引擎中被更广泛采用该命令将变得更具通用性。从源码看Gn.desc在解析gn desc结果时会检查action类型 target 的metadata.action_type是否包含dart_test命中则构造为ExecutableBuildTarget可执行文件来自其 outputs 列表这正是et test能直接运行 Dart 测试的基础。engine_tool 自身的测试体系可见于 tools/engine_tool/BUILD.gn 中的testsgroup其public_deps列出了build_command_test、cleanup_command_test、run_command_test等二十余个测试 target。4.3 使用自定义引擎配置大多数情况下开发者直接使用预配置的构建配置即可见理解构建配置一节——这些配置已被普遍支持且通常在 CI 上验证过。若需要构建一个未预定义的配置请先回答两个问题1. 我的配置代表的标志组合是否应该上 CI 测试、或供他人复用如果是最佳做法是把该构建加入 ci/builders——既可以作为 CI 构建也可以仅仅作为 local engine build 条目。这样配置对其他人可复现、有文档记录并能被et自动使用。2. 我的配置仅用于一次性测试或验证如果是任何额外的 GN 参数即那些本应由 tools/gn 解析的参数都可以通过--gn-args传入通常与某个现有配置模板搭配使用。例如开启链接时优化LTOet build --config host_release --lto或者使用源码构建的 Dart SDK常被 Dart SDK 与 VM 开发者使用et build --config host_debug --gn-args--no-prebuilt-dart-sdk提示关于构建配置的更多信息见 ci/builders/README.md。底层原理--gn-args的校验逻辑在 tools/engine_tool/lib/src/build_plan.dart 的_checkExtraGnArgs中参数必须是--flag/--no-flag形式的布尔标志不能包含或空格同时rbe、lto及其否定形式被列为reservedGnArgs必须作为et的直接参数如--lto、--no-rbe提供否则会抛出提示错误。构建计划最终通过toGnArgs()把--no-rbe/--lto/--no-lto与额外参数合并进 GN 调用。4.4 回收旧输出目录et cleanup会删除较久未访问的输出目录默认以最近 30 天为界可用--untouched-since自定义时间点。建议先用dry-run预览将要删除的内容# 删除所有超过 30 天的输出目录 et cleanup # 预览上面的命令会删除哪些目录 et cleanup --dry-run # 删除所有最后访问时间早于 2024-01-01 的输出目录 et cleanup --untouched-since2024-01-01底层原理CleanupCommandtools/engine_tool/lib/src/commands/cleanup_command.dart实现要点包括--untouched-since默认值为当前时间减去 30 天Duration(days: 30)格式必须是YYYY-MM-DD用正则^(\d{4})-(\d{2})-(\d{2})$校验遍历引擎out/目录下的子目录依据statSync().accessed最后访问时间判定是否早于阈值--dry-run别名-d只打印目录名和可回收空间以 KB/MB/GB 友好展示不动文件系统实际删除时逐个delete(recursive: true)单个失败仅告警不中断该命令还注册了别名gc与et gc等价。五、参与 et 的开发Contributing社区欢迎所有开发者改进et。贡献时请遵循以下约定对 Dart 代码遵循 Flutter 风格指南涉及框架仓库之外的部分同样适用它包含超出代码格式的约定即使未来使用dart format也应遵守不要直接调用dart:io除非是在main.dart中访问系统只能通过Environment对象对应源码 tools/engine_tool/lib/src/environment.dart所有命令必须有单元测试若某些功能需要假实现fake就编写一个 fake 实现新增或修改功能时同步更新本 README 文档以终为始Begin with the end in mind先从该工具应有的接口形态出发设计再改造底层脚本与工具以提供支撑 API。运行测试et test //flutter/tools/engine_tool/...如果还不确定从何入手可以关注e: engine-tool标签下待办的问题。仓库内测试与实现的对应关系也很清晰test/commands/下每个命令都有同名测试如build_command_test.dart、cleanup_command_test.dart、run_command_test.darttest/external_tools/覆盖了对flutter_tools与gn外部工具交互的测试而BUILD.gn中的testsgroup 则把这些测试统一编排为 GN 目标供et test //flutter/tools/engine_tool/...一键执行。总结et把 Flutter Engine 开发中最繁琐的配置生成—构建—测试—格式化—运行链路收敛为 8 个命令其核心价值在于以ci/builders/下的 JSON 为单一配置源按当前平台自动过滤出可用的构建配置再通过BuildPlan统一把--config、--build-strategy、--rbe、--lto、--gn-args、--concurrency等选项翻译为底层的gn/ninja调用。理解构建配置这一概念就能自然掌握build、test、run、query等绝大多数命令的用法而cleanup、RBE 策略等高级能力则为长时间、大规模迭代的引擎开发者提供了资源管理与构建加速的保障。赞分享跨平台图形学前端【免费下载链接】engineThe Flutter engine项目地址https://gitcode.com/gh_mirrors/eng/engine点击查看免费下载相关推荐Flutter Engine 开发工具 etEngine Tool完全指南统一构建与本地调试工作流Flutter Engine 开发工具 etEngine Tool完全指南统一构建与本地调试工作流 导读 本文基于 engine/src/flutter/跨平台移动开发前端UI组件桌面应用Flutter Engine RBE 远程构建配置指南基于 et 工具的完整实践Flutter Engine RBE 远程构建配置指南基于 et 工具的完整实践 导读 本文是围绕 Flutter Engine 仓库中 docs/rbe/r跨平台图形学前端Flax Engine项目构建与部署从开发到发布的完整工作流Flax Engine项目构建与部署从开发到发布的完整工作流 Flax Engine是一款基于C和C 开发的高质量现代3D游戏引擎支持多平台部署。本指南游戏开发图形学3D渲染上一篇SuperClaude Framework /sc:analyze 命令深度解析多维度静态代码分析与质量评估实战指南下一篇深度学习中的特征工程fast.ai课程中的数据预处理技术终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
