FlatBuffers 贡献指南从 CLA 签署到 flatc 构建、goldens 再生成与多语言测试的完整开发工作流【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffersFlatBuffers 是一个内存高效的跨语言序列化库其核心工具链由flatc编译器与多语言运行时组成。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合 docs/source/contributing.md 与仓库内的构建、生成、测试脚本完整梳理贡献者从签署 CLA、提交 Pull Request到修改flatc后重新生成 golden 文件、执行跨语言测试与代码格式化的端到端流程。读完本文你将掌握一套可复现的 FlatBuffers 本地开发与提交流程能够独立完成一次符合项目规范的代码或文档贡献。一、贡献前准备必须签署的 CLA与许多 Google 发起的开源项目一样FlatBuffers 在合入任何代码之前要求贡献者签署贡献者许可协议CLA。签署是先提交、后补签的流程你可以先提交代码并进入评审评审通过后再完成签署但在代码真正合入代码库之前必须完成。CLA 之所以必要核心原因在于即使你的改动被合入项目你依然保留改动的版权因此项目需要获得你的明确授权才能使用和分发这些代码同时协议还要求你承诺不会在不知情的情况下引入侵犯他人专利的代码。按贡献主体分为两类个人贡献Individual签署 Google Individual Contributor License Agreement可在线自助完成。仓库的代码评审流程会自动检测你是否已签署所以不必过度焦虑但如果你计划投入大量时间做较大的贡献提前签署会更稳妥。企业贡献Corporate以公司名义做出的贡献适用不同的协议——Google Software Grant and Corporate Contributor License Agreement即软件授权与企业贡献者许可协议覆盖范围与个人协议不同CONTRIBUTING.md 中称之为 the small print。二、代码评审规范如何写一个好的 Pull Request所有提交——包括项目成员自己的提交——都必须经过代码评审评审通过 GitHub Pull Request 进行。仓库给出了四条核心要求遵循 Google Style Guide针对你提交的语言遵守 Google 风格指南拿不准时尽量与项目现有代码保持一致。保持 PR 小而聚焦Keep PRs small and focused这既是良好实践也能显著提高 PR 被批准的概率。尽可能补充测试新功能或修复应伴随测试用例。写描述性 commit message说清楚解决了什么问题、影响是什么、在哪里测试过。此外还有一条实操性很强的建议如果你的 PR 由多个连续改进或修复的 commit 组成考虑使用git rebase -i将它们压缩squash为单个 commit使其成为当前 HEAD 之上的一个干净提交。这样评审者阅读代码会轻松得多项目历史也更清晰。三、修改代码的标准工作流TL/DRCONTRIBUTING.md 用一段 TL/DR 浓缩了修改代码的标准流程这也是本文的核心$ cp build/flatc . $ goldens/generate_goldens.py $ scripts/generate_code.py再配合测试与格式化用 tests/TestAll.sh位于 tests 目录运行测试也可以直接运行它调用的任意子脚本提交 PR 前按 Formatters.md 格式化代码。下面逐一深入讲解每一步的底层细节。3.1 第一步构建 flatc 编译器flatc是 FlatBuffers 的 schema 编译器所有代码生成都依赖它。构建方式见 docs/source/building.md项目主构建系统为 CMake# Unix可用 CC/usr/bin/clang CXX/usr/bin/clang 切换到 clang cmake -G Unix Makefiles -DCMAKE_BUILD_TYPERelease make -j # Windows cmake -G Visual Studio 17 2022 -DCMAKE_BUILD_TYPERelease msbuild.exe FlatBuffers.sln # MacOS cmake -G Xcode -DCMAKE_BUILD_TYPERelease xcodebuild -toolchain clang -configuration Release构建产物中flatc可执行文件位于构建目录下。这里有个关键细节值得注意提交代码前必须开启严格模式。默认情况下 CMake 配置的目标不会开启严格告警如-Werror或/WX而 CI 要求代码必须在严格模式下编译通过所以本地开发建议加cmake -DFLATBUFFERS_STRICT_MODEON另外还有FLATBUFFERS_MAX_PARSING_DEPTH可用于覆盖嵌套对象递归解析的默认深度限制见 docs/source/building.md 中关于add_subdirectory集成的说明。3.2 第二步再生成 goldens 文件查看改动效果cp build/flatc .把刚构建的编译器放到仓库根目录随后执行$ goldens/generate_goldens.pygoldens黄金文件是各语言代码生成器的基准输出。修改flatc的代码生成逻辑后运行该脚本即可直观看到改动影响了哪些语言的生成结果。从脚本源码看它实际上串联了 14 个语言子模块的生成逻辑goldens/generate_goldens.pyfrom cpp.generate import GenerateCpp from csharp.generate import GenerateCSharp from dart.generate import GenerateDart from go.generate import GenerateGo from java.generate import GenerateJava from kotlin.generate import GenerateKotlin from lobster.generate import GenerateLobster from lua.generate import GenerateLua from nim.generate import GenerateNim from php.generate import GeneratePhp from py.generate import GeneratePython from rust.generate import GenerateRust from swift.generate import GenerateSwift from ts.generate import GenerateTs # Run each language generation logic GenerateCpp() GenerateCSharp() GenerateDart() ...也就是说一次运行即可覆盖 C、C#、Dart、Go、Java、Kotlin、Lobster、Lua、Nim、PHP、Python、Rust、Swift、TypeScript 全部支持语言的 golden 输出。goldens 的基准 schema 位于 goldens/schema/basic.fbs各语言产物如 goldens/cpp/basic_generated.h、goldens/rust/basic_generated.rs都是提交在仓库中的。3.3 第三步再生成其他代码文件goldens 覆盖的是基准 schema 的输出而 scripts/generate_code.py 负责再生成测试套件与运行库中用到的全部生成代码这是验证改动是否破坏各语言测试的关键一步$ scripts/generate_code.py这个脚本是理解 FlatBuffers 内部结构的最佳入口之一。它通过 scripts/util.py 中的flatc()辅助函数反复调用flatc以不同的选项组合针对不同 schema 生成代码公共选项BASE_OPTS [--reflect-names, --gen-mutable, --gen-object-api]是绝大多数语言生成的基础语言专属选项各不相同例如 C# 用[--csharp, --cs-gen-json-serializer]C 用[--cpp, --gen-compare, --gen-absl-hash]Rust 用[--rust, --gen-all, --gen-name-strings, --rust-module-root-file]Python 用[--python, --python-typing, --python-decode-obj-api-strings]等脚本还覆盖了--grpc代码生成含回调 API 变体、--filename-suffix/--filename-ext命名定制、--jsonschema、BFBS 二进制 schema 生成、--annotate二进制注解文件等场景最后会调用 scripts/generate_grpc_examples.py 为grpc/examples下的 Go、Python、Swift、TypeScript 示例重新生成 gRPC 代码。值得注意的细节util.py会在脚本启动时断言 flatc 可执行文件存在assert flatc_path.exists(), Cannot find the flatc compiler ...默认查找名为flatcWindows 为flatc.exe的文件也可通过--flatc参数指定路径同时提供--skip-monster-extra、--skip-gen-reflection、--cpp-0x等开关控制生成范围。3.4 运行测试tests/TestAll.sh测试入口是 tests/TestAll.sh它依次驱动各语言的独立测试脚本并打印分节输出************************ Java: sh JavaTest.sh ************************ Kotlin: sh KotlinTest.sh ************************ Go: sh GoTest.sh ************************ Python: sh PythonTest.sh ************************ TypeScript: python3 ts/TypeScriptTest.py ************************ C: ./flattests位于 tests 上一级 ************************ C#: sh NetTest.shFlatBuffers.Test 目录内 ************************ PHP: php phpTest.php sh phpUnionVectorTest.sh ************************ Dart: sh DartTest.sh ************************ Rust: sh RustTest.sh ************************ Lobster: 当前为 TODO未启用 ************************ Swift: sh SwiftTest.shFlatBuffers.Test.Swift 目录内对应的测试代码分散在仓库各处例如 C 测试主体是 tests/test.cpp连同 tests/monster_test.cpp、tests/flexbuffers_test.cpp、tests/json_test.cpp 等C# 测试在 tests/FlatBuffers.Test 下Rust 测试在 tests/rust_usage_test 下。改动flatc后除了跑TestAll.sh全家桶也可以只运行与你改动语言相关的子脚本以加快迭代。3.5 提交前格式化代码Formatters.md 明确了各语言的格式化/检查工具且有一条通用原则不要格式化或 lint 生成的代码只处理你手写的部分C使用clang-format运行脚本sh scripts/clang-format-git.sh即可按 Google 风格格式化。从 scripts/clang-format-git.sh 源码可以看到它针对include/flatbuffers/*、src/*.cpp、tests/*.cpp、samples/*.cpp、grpc/src/compiler/schema_interface.h、grpc/tests/*.cpp运行git clang-format两次Running it twice corrects some bugs in clang-format最后用git checkout include/flatbuffers/reflection_generated.h还原自动生成的 reflection 头文件避免污染生成代码。Swift使用 SwiftFormat在项目根目录运行swiftformat --config swift.swiftformat .配置文件即仓库根目录的 swift.swiftformat。TypeScript使用 ESLint在项目根目录运行eslint ts/** --ext .ts配置见 eslint.config.mjs。仓库还提供了配套的 scripts/clang-format-all.sh 与 scripts/clang-tidy-git.sh前者可用于全量格式化后者用于静态检查。四、文档贡献用 MkDocs 本地预览FlatBuffers 的官方文档站点由 docs/mkdocs.yml 驱动采用 MkDocs 与 Material for MkDocs 框架生成文档源码就存放在仓库的 docs/source 目录与本文同源的另一份贡献说明见 docs/source/contributing.md。文档的构建与发布在 commit 提交后自动完成因此文档改动应随代码改动一起提交。4.1 本地安装依赖pip install mkdocs-material pip install mkdocs-redirectsmkdocs-material是主题框架mkdocs-redirects提供页面重定向插件支持。4.2 启动本地预览在仓库根目录运行mkdocs serve -f docs/mkdocs.yml该命令会持续监听仓库中文档的改动并即时渲染在本地浏览器中即可实时预览效果非常适合在提交前检查排版与链接是否正确。五、提交前自检清单综合以上内容一个完整、合规的 FlatBuffers 贡献流程可以浓缩为如下清单规划阶段较大的贡献建议先在 issue tracker 中提出想法与维护者提前沟通、获得引导避免返工维护团队并非全职投入响应速度与专业度会有波动见 docs/source/contributing.md 的说明。本地修改遵循 Google 风格指南保持改动与项目现有代码风格一致。构建验证cmake -DFLATBUFFERS_STRICT_MODEON开启严格模式构建确认在 CI 同等条件下编译通过。生成验证cp build/flatc .后用goldens/generate_goldens.py和scripts/generate_code.py再生成全部相关代码检查 golden 差异是否符合预期。测试验证运行tests/TestAll.sh或与改动相关的语言子脚本Java/Kotlin/Go/Python/TypeScript/C/C#/PHP/Dart/Rust/Swift。格式化按 Formatters.md 对 Csh scripts/clang-format-git.sh、Swiftswiftformat、TypeScripteslint分别处理且不触碰生成代码。提交 PR写描述性 commit message必要时git rebase -i压缩为单个 commit保持 PR 小而聚焦并补上测试。签署 CLA评审通过后补签个人或企业 CLA随后代码即可合入。六、结语CONTRIBUTING.md 篇幅不长但背后是一套精心设计的质量保障流水线goldens 机制保证了 14 种语言代码生成器的输出可被机器比对scripts/generate_code.py保证了测试与运行库代码始终与编译器行为同步tests/TestAll.sh则把跨语言回归测试收敛为一条命令。对贡献者而言理解这条构建 → 再生成 → 测试 → 格式化 → 提交的链路不仅能让你的 PR 更容易被批准也是快速掌握 FlatBuffers 内部架构从 src 下的代码生成器到 include/flatbuffers 的运行时头文件的捷径。【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FlatBuffers 贡献指南：从 CLA 签署到 flatc 构建、goldens 再生成与多语言测试的完整开发工作流
FlatBuffers 贡献指南从 CLA 签署到 flatc 构建、goldens 再生成与多语言测试的完整开发工作流【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffersFlatBuffers 是一个内存高效的跨语言序列化库其核心工具链由flatc编译器与多语言运行时组成。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合 docs/source/contributing.md 与仓库内的构建、生成、测试脚本完整梳理贡献者从签署 CLA、提交 Pull Request到修改flatc后重新生成 golden 文件、执行跨语言测试与代码格式化的端到端流程。读完本文你将掌握一套可复现的 FlatBuffers 本地开发与提交流程能够独立完成一次符合项目规范的代码或文档贡献。一、贡献前准备必须签署的 CLA与许多 Google 发起的开源项目一样FlatBuffers 在合入任何代码之前要求贡献者签署贡献者许可协议CLA。签署是先提交、后补签的流程你可以先提交代码并进入评审评审通过后再完成签署但在代码真正合入代码库之前必须完成。CLA 之所以必要核心原因在于即使你的改动被合入项目你依然保留改动的版权因此项目需要获得你的明确授权才能使用和分发这些代码同时协议还要求你承诺不会在不知情的情况下引入侵犯他人专利的代码。按贡献主体分为两类个人贡献Individual签署 Google Individual Contributor License Agreement可在线自助完成。仓库的代码评审流程会自动检测你是否已签署所以不必过度焦虑但如果你计划投入大量时间做较大的贡献提前签署会更稳妥。企业贡献Corporate以公司名义做出的贡献适用不同的协议——Google Software Grant and Corporate Contributor License Agreement即软件授权与企业贡献者许可协议覆盖范围与个人协议不同CONTRIBUTING.md 中称之为 the small print。二、代码评审规范如何写一个好的 Pull Request所有提交——包括项目成员自己的提交——都必须经过代码评审评审通过 GitHub Pull Request 进行。仓库给出了四条核心要求遵循 Google Style Guide针对你提交的语言遵守 Google 风格指南拿不准时尽量与项目现有代码保持一致。保持 PR 小而聚焦Keep PRs small and focused这既是良好实践也能显著提高 PR 被批准的概率。尽可能补充测试新功能或修复应伴随测试用例。写描述性 commit message说清楚解决了什么问题、影响是什么、在哪里测试过。此外还有一条实操性很强的建议如果你的 PR 由多个连续改进或修复的 commit 组成考虑使用git rebase -i将它们压缩squash为单个 commit使其成为当前 HEAD 之上的一个干净提交。这样评审者阅读代码会轻松得多项目历史也更清晰。三、修改代码的标准工作流TL/DRCONTRIBUTING.md 用一段 TL/DR 浓缩了修改代码的标准流程这也是本文的核心$ cp build/flatc . $ goldens/generate_goldens.py $ scripts/generate_code.py再配合测试与格式化用 tests/TestAll.sh位于 tests 目录运行测试也可以直接运行它调用的任意子脚本提交 PR 前按 Formatters.md 格式化代码。下面逐一深入讲解每一步的底层细节。3.1 第一步构建 flatc 编译器flatc是 FlatBuffers 的 schema 编译器所有代码生成都依赖它。构建方式见 docs/source/building.md项目主构建系统为 CMake# Unix可用 CC/usr/bin/clang CXX/usr/bin/clang 切换到 clang cmake -G Unix Makefiles -DCMAKE_BUILD_TYPERelease make -j # Windows cmake -G Visual Studio 17 2022 -DCMAKE_BUILD_TYPERelease msbuild.exe FlatBuffers.sln # MacOS cmake -G Xcode -DCMAKE_BUILD_TYPERelease xcodebuild -toolchain clang -configuration Release构建产物中flatc可执行文件位于构建目录下。这里有个关键细节值得注意提交代码前必须开启严格模式。默认情况下 CMake 配置的目标不会开启严格告警如-Werror或/WX而 CI 要求代码必须在严格模式下编译通过所以本地开发建议加cmake -DFLATBUFFERS_STRICT_MODEON另外还有FLATBUFFERS_MAX_PARSING_DEPTH可用于覆盖嵌套对象递归解析的默认深度限制见 docs/source/building.md 中关于add_subdirectory集成的说明。3.2 第二步再生成 goldens 文件查看改动效果cp build/flatc .把刚构建的编译器放到仓库根目录随后执行$ goldens/generate_goldens.pygoldens黄金文件是各语言代码生成器的基准输出。修改flatc的代码生成逻辑后运行该脚本即可直观看到改动影响了哪些语言的生成结果。从脚本源码看它实际上串联了 14 个语言子模块的生成逻辑goldens/generate_goldens.pyfrom cpp.generate import GenerateCpp from csharp.generate import GenerateCSharp from dart.generate import GenerateDart from go.generate import GenerateGo from java.generate import GenerateJava from kotlin.generate import GenerateKotlin from lobster.generate import GenerateLobster from lua.generate import GenerateLua from nim.generate import GenerateNim from php.generate import GeneratePhp from py.generate import GeneratePython from rust.generate import GenerateRust from swift.generate import GenerateSwift from ts.generate import GenerateTs # Run each language generation logic GenerateCpp() GenerateCSharp() GenerateDart() ...也就是说一次运行即可覆盖 C、C#、Dart、Go、Java、Kotlin、Lobster、Lua、Nim、PHP、Python、Rust、Swift、TypeScript 全部支持语言的 golden 输出。goldens 的基准 schema 位于 goldens/schema/basic.fbs各语言产物如 goldens/cpp/basic_generated.h、goldens/rust/basic_generated.rs都是提交在仓库中的。3.3 第三步再生成其他代码文件goldens 覆盖的是基准 schema 的输出而 scripts/generate_code.py 负责再生成测试套件与运行库中用到的全部生成代码这是验证改动是否破坏各语言测试的关键一步$ scripts/generate_code.py这个脚本是理解 FlatBuffers 内部结构的最佳入口之一。它通过 scripts/util.py 中的flatc()辅助函数反复调用flatc以不同的选项组合针对不同 schema 生成代码公共选项BASE_OPTS [--reflect-names, --gen-mutable, --gen-object-api]是绝大多数语言生成的基础语言专属选项各不相同例如 C# 用[--csharp, --cs-gen-json-serializer]C 用[--cpp, --gen-compare, --gen-absl-hash]Rust 用[--rust, --gen-all, --gen-name-strings, --rust-module-root-file]Python 用[--python, --python-typing, --python-decode-obj-api-strings]等脚本还覆盖了--grpc代码生成含回调 API 变体、--filename-suffix/--filename-ext命名定制、--jsonschema、BFBS 二进制 schema 生成、--annotate二进制注解文件等场景最后会调用 scripts/generate_grpc_examples.py 为grpc/examples下的 Go、Python、Swift、TypeScript 示例重新生成 gRPC 代码。值得注意的细节util.py会在脚本启动时断言 flatc 可执行文件存在assert flatc_path.exists(), Cannot find the flatc compiler ...默认查找名为flatcWindows 为flatc.exe的文件也可通过--flatc参数指定路径同时提供--skip-monster-extra、--skip-gen-reflection、--cpp-0x等开关控制生成范围。3.4 运行测试tests/TestAll.sh测试入口是 tests/TestAll.sh它依次驱动各语言的独立测试脚本并打印分节输出************************ Java: sh JavaTest.sh ************************ Kotlin: sh KotlinTest.sh ************************ Go: sh GoTest.sh ************************ Python: sh PythonTest.sh ************************ TypeScript: python3 ts/TypeScriptTest.py ************************ C: ./flattests位于 tests 上一级 ************************ C#: sh NetTest.shFlatBuffers.Test 目录内 ************************ PHP: php phpTest.php sh phpUnionVectorTest.sh ************************ Dart: sh DartTest.sh ************************ Rust: sh RustTest.sh ************************ Lobster: 当前为 TODO未启用 ************************ Swift: sh SwiftTest.shFlatBuffers.Test.Swift 目录内对应的测试代码分散在仓库各处例如 C 测试主体是 tests/test.cpp连同 tests/monster_test.cpp、tests/flexbuffers_test.cpp、tests/json_test.cpp 等C# 测试在 tests/FlatBuffers.Test 下Rust 测试在 tests/rust_usage_test 下。改动flatc后除了跑TestAll.sh全家桶也可以只运行与你改动语言相关的子脚本以加快迭代。3.5 提交前格式化代码Formatters.md 明确了各语言的格式化/检查工具且有一条通用原则不要格式化或 lint 生成的代码只处理你手写的部分C使用clang-format运行脚本sh scripts/clang-format-git.sh即可按 Google 风格格式化。从 scripts/clang-format-git.sh 源码可以看到它针对include/flatbuffers/*、src/*.cpp、tests/*.cpp、samples/*.cpp、grpc/src/compiler/schema_interface.h、grpc/tests/*.cpp运行git clang-format两次Running it twice corrects some bugs in clang-format最后用git checkout include/flatbuffers/reflection_generated.h还原自动生成的 reflection 头文件避免污染生成代码。Swift使用 SwiftFormat在项目根目录运行swiftformat --config swift.swiftformat .配置文件即仓库根目录的 swift.swiftformat。TypeScript使用 ESLint在项目根目录运行eslint ts/** --ext .ts配置见 eslint.config.mjs。仓库还提供了配套的 scripts/clang-format-all.sh 与 scripts/clang-tidy-git.sh前者可用于全量格式化后者用于静态检查。四、文档贡献用 MkDocs 本地预览FlatBuffers 的官方文档站点由 docs/mkdocs.yml 驱动采用 MkDocs 与 Material for MkDocs 框架生成文档源码就存放在仓库的 docs/source 目录与本文同源的另一份贡献说明见 docs/source/contributing.md。文档的构建与发布在 commit 提交后自动完成因此文档改动应随代码改动一起提交。4.1 本地安装依赖pip install mkdocs-material pip install mkdocs-redirectsmkdocs-material是主题框架mkdocs-redirects提供页面重定向插件支持。4.2 启动本地预览在仓库根目录运行mkdocs serve -f docs/mkdocs.yml该命令会持续监听仓库中文档的改动并即时渲染在本地浏览器中即可实时预览效果非常适合在提交前检查排版与链接是否正确。五、提交前自检清单综合以上内容一个完整、合规的 FlatBuffers 贡献流程可以浓缩为如下清单规划阶段较大的贡献建议先在 issue tracker 中提出想法与维护者提前沟通、获得引导避免返工维护团队并非全职投入响应速度与专业度会有波动见 docs/source/contributing.md 的说明。本地修改遵循 Google 风格指南保持改动与项目现有代码风格一致。构建验证cmake -DFLATBUFFERS_STRICT_MODEON开启严格模式构建确认在 CI 同等条件下编译通过。生成验证cp build/flatc .后用goldens/generate_goldens.py和scripts/generate_code.py再生成全部相关代码检查 golden 差异是否符合预期。测试验证运行tests/TestAll.sh或与改动相关的语言子脚本Java/Kotlin/Go/Python/TypeScript/C/C#/PHP/Dart/Rust/Swift。格式化按 Formatters.md 对 Csh scripts/clang-format-git.sh、Swiftswiftformat、TypeScripteslint分别处理且不触碰生成代码。提交 PR写描述性 commit message必要时git rebase -i压缩为单个 commit保持 PR 小而聚焦并补上测试。签署 CLA评审通过后补签个人或企业 CLA随后代码即可合入。六、结语CONTRIBUTING.md 篇幅不长但背后是一套精心设计的质量保障流水线goldens 机制保证了 14 种语言代码生成器的输出可被机器比对scripts/generate_code.py保证了测试与运行库代码始终与编译器行为同步tests/TestAll.sh则把跨语言回归测试收敛为一条命令。对贡献者而言理解这条构建 → 再生成 → 测试 → 格式化 → 提交的链路不仅能让你的 PR 更容易被批准也是快速掌握 FlatBuffers 内部架构从 src 下的代码生成器到 include/flatbuffers 的运行时头文件的捷径。【免费下载链接】flatbuffersFlatBuffers: Memory Efficient Serialization Library项目地址: https://gitcode.com/GitHub_Trending/fl/flatbuffers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考