StarRocks 构建与质量保障工具链指南build-support 目录全解析【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本文基于 StarRocks 仓库 build-support/README.md 展开系统梳理该目录下数十个辅助脚本的用途、使用方式与底层实现。StarRocks 是一个面向湖仓一体场景的亚秒级分析型开源查询引擎代码库规模庞大BE 端 C 与 FE 端 Java 并存因此工程基建直接决定开发与 CI 效率。读完本文你将掌握代码格式化、静态检查、模块边界守卫、Schema 兼容性校验、构建版本生成、文档校验等全套工具的正确打开方式并能在本地复现这些守卫逻辑。一、build-support 目录定位StarRocks 的工程治理中枢StarRocks 仓库根目录下有一个专门存放构建与质量保障脚本的目录build-support/。从 build-support/README.md 可以看出它并非普通脚本杂货铺而是一套围绕“代码风格统一、架构边界守卫、Schema 兼容、构建元数据、知识库校验”五大主题的工程治理中枢。从仓库实际文件看该目录包含三类内容Shell 脚本.sh如 check-format.sh、clang-format.sh、clang-tidy.sh 等承担可直接从命令行触发的格式化、检查、编译计时等任务Python 脚本.py如 check_be_module_boundaries.py、check_gensrc_schema_compatibility.py、gen_config_fwd_headers.py 等承担需要解析 CMake、JSON、Thrift/Protobuf 的复杂治理逻辑配置与基线文件如 be_module_boundary_baseline.json、excludes、config_header_include_allowlist.txt、schema_compatibility_waivers.json 等是守卫脚本读取的白名单、豁免名单与历史债务基线。这种“脚本 白名单 基线”的组合是大型 C 仓库控制技术债的常见且有效的手段脚本负责“发现违规”白名单负责“临时放行”基线负责“只减不增”。二、代码风格与静态检查clang-format 与 clang-tidy 全家桶1. 只检查不修改check-format.shcheck-format.sh 是格式化检查的入口它“只检查、不修改”任何 C 文件适合 CI 或提交前的快速验证。其实现非常简洁python3 ${STARROCKS_HOME}/build-support/run_clang_format.py --clang_format_binary${CLANG_FORMAT} \ --source_dirs${STARROCKS_HOME}/be/src,${STARROCKS_HOME}/be/test \ --exclude_globs${STARROCKS_HOME}/build-support/excludes --quiet关键点检查范围be/src与be/test下的全部 C 源码排除规则--exclude_globs指向 excludes该文件内容为*/be/src/thirdparty/*即跳过第三方面板源码如 gutil 中引入的第三方代码二进制选择通过CLANG_FORMAT_BINARY环境变量指定 clang-format 可执行文件缺省时回退到which clang-format执行器真正的格式化逻辑封装在 run_clang_format.py 中它支持 check 与 fix 两种模式可按--help查看全部参数。日常使用只需一行bash build-support/check-format.sh2. 按变更文件精确格式化clang-format-changed 系列当仓库很大时每次全量检查并不划算。StarRocks 提供了只针对“自origin/main以来变更过的 C 文件”做处理的脚本clang-format-changed-check.sh对变更文件做 clang-format 检查不改动文件若缺少origin/main则回退为全量检查clang-format-changed.sh对变更文件直接应用 clang-format修改文件同样支持缺失基线时的全量回退。用法bash build-support/clang-format-changed-check.sh # 检查变更文件的格式 bash build-support/clang-format-changed.sh # 直接格式化变更文件对应地format_changed_files.py 负责从一个变更文件列表中过滤出位于目标目录内的 C 源文件供上述脚本复用属于底层辅助逻辑。3. 统一入口clang-tidy.shclang-tidy.sh 是 clang-tidy 在 CI 与本地运行的统一入口同时兼容新旧两套参数风格。新式参数./build-support/clang-tidy.sh --mode full --branch main --build-type Release -j 32 --add-compile-options --use-staros ./build-support/clang-tidy.sh --mode changed --base-version base_sha --branch main --build-type Release -j 32 --add-compile-options --use-staros旧式兼容形式位置参数./build-support/clang-tidy.sh run-full branch build_type j_parallel [add_compile_options] ./build-support/clang-tidy.sh run-changed base_version branch build_type j_parallel [add_compile_options]值得注意的实现细节--build-type支持Release、Debug、Asan等构建类型默认并行度在 Linux 上取nproc / 4 1见 clang-tidy.sh避免静态分析挤占整机资源changed模式通过git diff --name-only收集相对基线的变更文件并自动补全被变更头文件所“波及”的.cpp文件见 clang-tidy.sh确保头文件改动引发的下游问题也能被发现--add-compile-options允许透传额外编译选项给build.sh例如示例中的--use-staros。4. 编译时间统计与 lint 公共库compile_time.sh收集并输出 clang 的编译耗时统计用于定位编译热点、评估改动对构建时长的影响lintutils.py被多个 lint/format 脚本 import 的共享辅助模块封装了通用的 lint 逻辑。三、BE 模块边界守卫check_be_module_boundaries.pyStarRocks BE 端有数十个内部模块base、gutil、common、cache、column、exec、storage……如果模块间随意 include 或 link架构会迅速腐化。为此仓库引入了“模块边界清单 基线 白名单 守卫脚本”的组合。1. 核心机制check_be_module_boundaries.py 强制约束四类规则include 边include edges每个模块声明允许的 include 前缀如base/、gutil/、gen_cpp/与禁止的 include 前缀脚本扫描模块自有文件的所有#include与 be/module_boundary_manifest.json 中的声明比对显式 target 链接explicit target links通过解析be/src/**/CMakeLists.txt与be/test/**/CMakeLists.txt中的ADD_BE_LIB、target_link_libraries构建 target 依赖图检查模块自有 target 只允许链接清单内声明的依赖聚焦核心测试链接依赖focused core-test link deps同样解析be/test/**/CMakeLists.txt校验测试 target 只能链接其被允许的测试依赖ExecEnv 单例收缩护栏shrink-only guardrailsexec/exec_env.h属于“过重”的全局入口脚本分别用 exec_env_header_include_allowlist.txt允许直接 includeexec/exec_env.h的文件与 exec_env_singleton_allowlist.txt允许在生产代码调用ExecEnv::GetInstance()的位置进行白名单管控。值得注意的是脚本内部维护了一个DEFAULT_CHANGED_FULL_CHECK_PATHS集合见 check_be_module_boundaries.py只要变更涉及清单、基线、脚本本身或be/AGENTS.md等元数据文件就会触发全量检查防止“改规则放水”这类旁路。2. 历史债务基线只减不增be_module_boundary_baseline.json 记录了经过评审的历史违规当前内容为{ include_violations: [ { module: columncore, path: be/src/column/hash_set.h, edge: runtime/memory/counting_allocator.h } ], target_link_violations: [], test_link_violations: [] }即目前只有一条遗留的 include 违规。配合--enforce-baseline-shrink参数脚本会保证基线只能随时间收缩、不能扩张新增违规一律报错且不允许往基线里加新条目来“洗白”。这体现了典型的“承认存量债务但严控增量债务”的工程治理哲学。3. 三种运行模式# 全量检查CI 合入前、大版本分支验证 python3 build-support/check_be_module_boundaries.py --mode full # 只检查相对 origin/main 变更涉及的模块日常 MR 快速反馈 python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main # 变更模式 基线只减不增护栏 python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main --enforce-baseline-shrinkchanged模式并非简单跳过而是通过“变更文件归属模块分析 CMake 目标定义位置 owned_roots 前缀 owned_globs”四重判定选出受影响的模块集合见 check_be_module_boundaries.py做到既快又准。4. 配套渲染与测试render_be_agents.py从 be/module_boundary_manifest.json 渲染或校验be/AGENTS.md中生成的模块边界说明段落保证文档与清单永远同步python3 build-support/render_be_agents.py --write # 写入生成段落 python3 build-support/render_be_agents.py --check # 只校验一致性test_check_be_module_boundaries.py约 24 KB 的配套单元测试覆盖 include 违规、link 违规、baseline 收缩等核心逻辑是守卫脚本自身的质量保障。四、Thrift/Protobuf Schema 兼容性守卫check_gensrc_schema_compatibility.pyStarRocks 通过 gensrc/thrift/ 与 gensrc/proto/ 下的.thrift/.proto文件生成跨进程 RPC 与存储结构。这类 Schema 一旦被老版本 BE/FE 或线上数据引用字段编号、类型、基数cardinality的随意变更会引发灾难性反序列化错误。1. 守卫的兼容性规则check_gensrc_schema_compatibility.py 强制以下规则optional 兼容的追加optional-compatible additions只允许新增 optional 字段且新字段编号不得与既有字段冲突重编号检测renumber detection字段编号是 thrift/protobuf 的“线协议身份”任何重编号都会被判定为破坏性变更类型/基数稳定性type/cardinality stability已有字段的类型与 optional/required/repeated 声明必须保持稳定删除豁免deletion waivers确实需要删除或破坏性变更时必须显式登记到 schema_compatibility_waivers.json且条目要保持“窄”narrow不再需要时及时删除过期豁免清理stale-waiver cleanup脚本会检测已不再对应实际变更的过期豁免条目强制清理避免豁免名单无限膨胀。脚本内部对.proto与.thrift分别建模字段声明见 check_gensrc_schema_compatibility.py将repeated string name 3与3: optional string name这类声明归一化为统一的“签名”再比对从而同时精确覆盖两种 Schema 语法。2. 运行方式# 增量检查对比 origin/main适用于日常 MR python3 build-support/check_gensrc_schema_compatibility.py --mode changed --base origin/main # 全量检查扫描全部 Schema适用于合入前或分支校验 python3 build-support/check_gensrc_schema_compatibility.py --mode full --base origin/main配套的 test_check_gensrc_schema_compatibility.py约 49 KB是仓库内规模较大的测试文件之一充分说明该守卫覆盖了大量边界场景。五、配置头文件与构建元数据生成1. gen_config_fwd_headers.py前向声明头生成器StarRocks 的common/config.h是 BE 全局配置的聚合头若被大量.cpp直接 include会显著拖慢编译。仓库的做法是生成领域化的前向声明头gen_config_fwd_headers.py 依据 be/src/common/config_fwd_headers_manifest.json 中的选择清单从be/src/common/config.h生成be/src/common/config_domain_fwd.h生成器会保留被选中配置项周边的预处理守卫#if/#ifdef等默认只重写内容发生变化的文件未变化的头文件保持原时间戳从而避免无意义的增量编译与 CI 缓存失效。三种用法python3 build-support/gen_config_fwd_headers.py # 生成/更新 python3 build-support/gen_config_fwd_headers.py --check # 校验已提交头文件是否最新 python3 build-support/gen_config_fwd_headers.py --force # 强制全部重写配套测试见 test_gen_config_fwd_headers.py。2. check_common_config_header_includes.shinclude 白名单守卫check_common_config_header_includes.sh 从两个维度把关先调用gen_config_fwd_headers.py --check确认已提交的config_domain_fwd.h与清单一致再扫描be/src与be/test下所有*.{h,hpp,cc,cpp}文件找出所有直接#include common/config.h或#include common/config.h的文件与 config_header_include_allowlist.txt 白名单比对白名单之外的新增 include 一律报错。该脚本优先使用rgripgrep加速扫描rg不存在时回退到find grep兼顾了不同 CI 镜像的环境差异。用法bash build-support/check_common_config_header_includes.sh3. 构建版本与 NOTICE 生成gen_build_version.py生成构建版本元数据git commit、构建时间等python3 build-support/gen_build_version.py --help可查看全部选项gen_notice.py从打包的第三方许可文件生成 NOTICE 文件内容保证开源合规声明与依赖清单同步python3 build-support/gen_notice.py --help查看用法sync_pom_to_gradle.py将 FE 侧 Maven POM 设置同步到 Gradle 配置避免两套构建系统的依赖声明漂移。六、macOS 构建支持与仓库知识库治理1. darwin_build_env.sh 与 build_helpers.shStarRocks 支持在 macOS ARM64 上构建 BEdarwin_build_env.sh 提供内部环境准备逻辑。README 明确建议不要直接 source 该脚本而是使用根目录的./build.sh --be由根构建助手统一编排。build_helpers.sh 则是被根构建脚本 source 的公共函数库封装了CPU 并行度探测macOS 用sysctl -n hw.ncpuLinux 用nprocJAVA_HOME解析兼容 macOS 上.app内嵌 JDK 的路径形态见 build_helpers.shmacOS 第三方面板完整性校验protoc、thrift、protobuf/rocksdb/glog/brpc/grpc 等静态库、krb5/sasl2 等系统 dylib见 build_helpers.sh打包产物对宿主 dylib 依赖清单的生成输出到output/be/HOST_DYLIB_DEPENDENCIES.txt见 build_helpers.sh因为 macOS 包并非完全自包含。这些细节说明 StarRocks 对 macOS 构建环境的处理相当工程化提前校验依赖、检测陈旧 CMake 缓存、必要时自动重置构建目录。2. check_repo_handbook.py 与 handbook_plan.py仓库内存在一个面向内部知识治理的handbook/目录含架构、领域、计划、政策、质量等索引。对应的两个脚本check_repo_handbook.py校验handbook/知识树的结构合法性包括必备入口文件、领域/政策/质量索引、页面标题契约、active 计划的元数据以及AGENTS.md/CLAUDE.md的导航链接是否有效python3 build-support/check_repo_handbook.py配套测试 test_check_repo_handbook.py 保障其自身可靠。handbook_plan.py管理 gitignored 的本地工作计划支持从已有计划派生、创建“checkout 本地覆盖”等场景python3 build-support/handbook_plan.py list python3 build-support/handbook_plan.py create --local --title Scratch Plan --owner Engineering Productivity python3 build-support/handbook_plan.py create --local --from handbook/plans/active/plan.md python3 build-support/handbook_plan.py complete --local --plan path-or-slug配套测试见 test_handbook_plan.py。七、快速参考脚本速查表以下汇总 build-support/README.md 中所有脚本的用途与核心用法便于日常查阅脚本职责核心用法check-format.shclang-format 全量检查不修改bash build-support/check-format.shclang-format.shclang-format 全量应用bash build-support/clang-format.shclang-format-changed-check.sh仅检查相对 origin/main 变更文件bash build-support/clang-format-changed-check.shclang-format-changed.sh仅格式化变更文件bash build-support/clang-format-changed.shrun_clang_format.pyclang-format 底层执行器check/fixpython3 build-support/run_clang_format.py --helpclang-tidy.shclang-tidy 统一入口./build-support/clang-tidy.sh --mode changed --base-version sha --branch main --build-type Release -j 32check_be_module_boundaries.pyBE 模块边界守卫python3 build-support/check_be_module_boundaries.py --mode full/--mode changed --base origin/mainrender_be_agents.py渲染/校验 be/AGENTS.md 模块边界段落python3 build-support/render_be_agents.py --write/--checkcheck_gensrc_schema_compatibility.pythrift/protobuf Schema 兼容性守卫python3 build-support/check_gensrc_schema_compatibility.py --mode changed --base origin/maincheck_repo_handbook.pyhandbook 知识树校验python3 build-support/check_repo_handbook.pycheck_common_config_header_includes.shconfig.h 直接 include 白名单守卫bash build-support/check_common_config_header_includes.shhandbook_plan.py本地工作计划管理python3 build-support/handbook_plan.py list等compile_time.sh编译耗时统计bash build-support/compile_time.shformat_changed_files.py过滤变更文件中的 C 源文件python3 build-support/format_changed_files.py --helpgen_config_fwd_headers.py生成/校验 config_ _fwd.hpython3 build-support/gen_config_fwd_headers.py --checkgen_build_version.py生成构建版本元数据python3 build-support/gen_build_version.py --helpgen_notice.py从许可文件生成 NOTICEpython3 build-support/gen_notice.py --helplintutils.pylint 共享辅助库被其他脚本 importdarwin_build_env.shmacOS 构建环境准备内部通过./build.sh --be间接使用sync_pom_to_gradle.pyPOM → Gradle 配置同步python3 build-support/sync_pom_to_gradle.py --help配套数据文件一览be/module_boundary_manifest.jsonBE 各模块的边界声明owned targets/roots/globs、允许与禁止的 include 前缀、允许的依赖与测试依赖、补救建议be_module_boundary_baseline.json经评审的历史违规基线exec_env_header_include_allowlist.txt 与 exec_env_singleton_allowlist.txtExecEnv相关白名单config_header_include_allowlist.txt允许直接 includecommon/config.h的白名单excludesclang-format 排除规则schema_compatibility_waivers.jsonSchema 变更豁免登记be/src/common/config_fwd_headers_manifest.json前向头选择清单。八、结语从脚本看 StarRocks 的工程治理哲学梳理完build-support/后可以发现StarRocks 的工程基建并非零散工具堆砌而是围绕几条清晰的原则组织增量优先changed模式贯穿 clang-tidy、模块边界、Schema 兼容等多个守卫让每次 MR 只承担与其改动规模匹配的检查成本基线只减不增模块边界基线配合--enforce-baseline-shrink承认存量技术债的同时严格封堵增量白名单是显式承诺无论是config.h的 include 还是ExecEnv的调用点都通过可评审、可 diff 的文本清单显式登记杜绝“加个例外就跑路”文档与代码同源render_be_agents.py、check_repo_handbook.py保证AGENTS.md、handbook/与清单、计划永远同步环境差异被显式处理macOS 的 dylib 依赖清单、缺失工具的rg回退、getopt探测等细节说明这些脚本被设计在多样化的本地与 CI 环境中真实运行。对于想为 StarRocks 贡献代码的开发者本地提交前跑一遍bash build-support/check-format.sh与python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main即可在 CI 之前拦截绝大多数风格与架构违规对于关注大型 C 工程治理的读者这份目录本身就是一份高质量的“可执行架构文档”范本。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
StarRocks 构建与质量保障工具链指南：build-support 目录全解析
StarRocks 构建与质量保障工具链指南build-support 目录全解析【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本文基于 StarRocks 仓库 build-support/README.md 展开系统梳理该目录下数十个辅助脚本的用途、使用方式与底层实现。StarRocks 是一个面向湖仓一体场景的亚秒级分析型开源查询引擎代码库规模庞大BE 端 C 与 FE 端 Java 并存因此工程基建直接决定开发与 CI 效率。读完本文你将掌握代码格式化、静态检查、模块边界守卫、Schema 兼容性校验、构建版本生成、文档校验等全套工具的正确打开方式并能在本地复现这些守卫逻辑。一、build-support 目录定位StarRocks 的工程治理中枢StarRocks 仓库根目录下有一个专门存放构建与质量保障脚本的目录build-support/。从 build-support/README.md 可以看出它并非普通脚本杂货铺而是一套围绕“代码风格统一、架构边界守卫、Schema 兼容、构建元数据、知识库校验”五大主题的工程治理中枢。从仓库实际文件看该目录包含三类内容Shell 脚本.sh如 check-format.sh、clang-format.sh、clang-tidy.sh 等承担可直接从命令行触发的格式化、检查、编译计时等任务Python 脚本.py如 check_be_module_boundaries.py、check_gensrc_schema_compatibility.py、gen_config_fwd_headers.py 等承担需要解析 CMake、JSON、Thrift/Protobuf 的复杂治理逻辑配置与基线文件如 be_module_boundary_baseline.json、excludes、config_header_include_allowlist.txt、schema_compatibility_waivers.json 等是守卫脚本读取的白名单、豁免名单与历史债务基线。这种“脚本 白名单 基线”的组合是大型 C 仓库控制技术债的常见且有效的手段脚本负责“发现违规”白名单负责“临时放行”基线负责“只减不增”。二、代码风格与静态检查clang-format 与 clang-tidy 全家桶1. 只检查不修改check-format.shcheck-format.sh 是格式化检查的入口它“只检查、不修改”任何 C 文件适合 CI 或提交前的快速验证。其实现非常简洁python3 ${STARROCKS_HOME}/build-support/run_clang_format.py --clang_format_binary${CLANG_FORMAT} \ --source_dirs${STARROCKS_HOME}/be/src,${STARROCKS_HOME}/be/test \ --exclude_globs${STARROCKS_HOME}/build-support/excludes --quiet关键点检查范围be/src与be/test下的全部 C 源码排除规则--exclude_globs指向 excludes该文件内容为*/be/src/thirdparty/*即跳过第三方面板源码如 gutil 中引入的第三方代码二进制选择通过CLANG_FORMAT_BINARY环境变量指定 clang-format 可执行文件缺省时回退到which clang-format执行器真正的格式化逻辑封装在 run_clang_format.py 中它支持 check 与 fix 两种模式可按--help查看全部参数。日常使用只需一行bash build-support/check-format.sh2. 按变更文件精确格式化clang-format-changed 系列当仓库很大时每次全量检查并不划算。StarRocks 提供了只针对“自origin/main以来变更过的 C 文件”做处理的脚本clang-format-changed-check.sh对变更文件做 clang-format 检查不改动文件若缺少origin/main则回退为全量检查clang-format-changed.sh对变更文件直接应用 clang-format修改文件同样支持缺失基线时的全量回退。用法bash build-support/clang-format-changed-check.sh # 检查变更文件的格式 bash build-support/clang-format-changed.sh # 直接格式化变更文件对应地format_changed_files.py 负责从一个变更文件列表中过滤出位于目标目录内的 C 源文件供上述脚本复用属于底层辅助逻辑。3. 统一入口clang-tidy.shclang-tidy.sh 是 clang-tidy 在 CI 与本地运行的统一入口同时兼容新旧两套参数风格。新式参数./build-support/clang-tidy.sh --mode full --branch main --build-type Release -j 32 --add-compile-options --use-staros ./build-support/clang-tidy.sh --mode changed --base-version base_sha --branch main --build-type Release -j 32 --add-compile-options --use-staros旧式兼容形式位置参数./build-support/clang-tidy.sh run-full branch build_type j_parallel [add_compile_options] ./build-support/clang-tidy.sh run-changed base_version branch build_type j_parallel [add_compile_options]值得注意的实现细节--build-type支持Release、Debug、Asan等构建类型默认并行度在 Linux 上取nproc / 4 1见 clang-tidy.sh避免静态分析挤占整机资源changed模式通过git diff --name-only收集相对基线的变更文件并自动补全被变更头文件所“波及”的.cpp文件见 clang-tidy.sh确保头文件改动引发的下游问题也能被发现--add-compile-options允许透传额外编译选项给build.sh例如示例中的--use-staros。4. 编译时间统计与 lint 公共库compile_time.sh收集并输出 clang 的编译耗时统计用于定位编译热点、评估改动对构建时长的影响lintutils.py被多个 lint/format 脚本 import 的共享辅助模块封装了通用的 lint 逻辑。三、BE 模块边界守卫check_be_module_boundaries.pyStarRocks BE 端有数十个内部模块base、gutil、common、cache、column、exec、storage……如果模块间随意 include 或 link架构会迅速腐化。为此仓库引入了“模块边界清单 基线 白名单 守卫脚本”的组合。1. 核心机制check_be_module_boundaries.py 强制约束四类规则include 边include edges每个模块声明允许的 include 前缀如base/、gutil/、gen_cpp/与禁止的 include 前缀脚本扫描模块自有文件的所有#include与 be/module_boundary_manifest.json 中的声明比对显式 target 链接explicit target links通过解析be/src/**/CMakeLists.txt与be/test/**/CMakeLists.txt中的ADD_BE_LIB、target_link_libraries构建 target 依赖图检查模块自有 target 只允许链接清单内声明的依赖聚焦核心测试链接依赖focused core-test link deps同样解析be/test/**/CMakeLists.txt校验测试 target 只能链接其被允许的测试依赖ExecEnv 单例收缩护栏shrink-only guardrailsexec/exec_env.h属于“过重”的全局入口脚本分别用 exec_env_header_include_allowlist.txt允许直接 includeexec/exec_env.h的文件与 exec_env_singleton_allowlist.txt允许在生产代码调用ExecEnv::GetInstance()的位置进行白名单管控。值得注意的是脚本内部维护了一个DEFAULT_CHANGED_FULL_CHECK_PATHS集合见 check_be_module_boundaries.py只要变更涉及清单、基线、脚本本身或be/AGENTS.md等元数据文件就会触发全量检查防止“改规则放水”这类旁路。2. 历史债务基线只减不增be_module_boundary_baseline.json 记录了经过评审的历史违规当前内容为{ include_violations: [ { module: columncore, path: be/src/column/hash_set.h, edge: runtime/memory/counting_allocator.h } ], target_link_violations: [], test_link_violations: [] }即目前只有一条遗留的 include 违规。配合--enforce-baseline-shrink参数脚本会保证基线只能随时间收缩、不能扩张新增违规一律报错且不允许往基线里加新条目来“洗白”。这体现了典型的“承认存量债务但严控增量债务”的工程治理哲学。3. 三种运行模式# 全量检查CI 合入前、大版本分支验证 python3 build-support/check_be_module_boundaries.py --mode full # 只检查相对 origin/main 变更涉及的模块日常 MR 快速反馈 python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main # 变更模式 基线只减不增护栏 python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main --enforce-baseline-shrinkchanged模式并非简单跳过而是通过“变更文件归属模块分析 CMake 目标定义位置 owned_roots 前缀 owned_globs”四重判定选出受影响的模块集合见 check_be_module_boundaries.py做到既快又准。4. 配套渲染与测试render_be_agents.py从 be/module_boundary_manifest.json 渲染或校验be/AGENTS.md中生成的模块边界说明段落保证文档与清单永远同步python3 build-support/render_be_agents.py --write # 写入生成段落 python3 build-support/render_be_agents.py --check # 只校验一致性test_check_be_module_boundaries.py约 24 KB 的配套单元测试覆盖 include 违规、link 违规、baseline 收缩等核心逻辑是守卫脚本自身的质量保障。四、Thrift/Protobuf Schema 兼容性守卫check_gensrc_schema_compatibility.pyStarRocks 通过 gensrc/thrift/ 与 gensrc/proto/ 下的.thrift/.proto文件生成跨进程 RPC 与存储结构。这类 Schema 一旦被老版本 BE/FE 或线上数据引用字段编号、类型、基数cardinality的随意变更会引发灾难性反序列化错误。1. 守卫的兼容性规则check_gensrc_schema_compatibility.py 强制以下规则optional 兼容的追加optional-compatible additions只允许新增 optional 字段且新字段编号不得与既有字段冲突重编号检测renumber detection字段编号是 thrift/protobuf 的“线协议身份”任何重编号都会被判定为破坏性变更类型/基数稳定性type/cardinality stability已有字段的类型与 optional/required/repeated 声明必须保持稳定删除豁免deletion waivers确实需要删除或破坏性变更时必须显式登记到 schema_compatibility_waivers.json且条目要保持“窄”narrow不再需要时及时删除过期豁免清理stale-waiver cleanup脚本会检测已不再对应实际变更的过期豁免条目强制清理避免豁免名单无限膨胀。脚本内部对.proto与.thrift分别建模字段声明见 check_gensrc_schema_compatibility.py将repeated string name 3与3: optional string name这类声明归一化为统一的“签名”再比对从而同时精确覆盖两种 Schema 语法。2. 运行方式# 增量检查对比 origin/main适用于日常 MR python3 build-support/check_gensrc_schema_compatibility.py --mode changed --base origin/main # 全量检查扫描全部 Schema适用于合入前或分支校验 python3 build-support/check_gensrc_schema_compatibility.py --mode full --base origin/main配套的 test_check_gensrc_schema_compatibility.py约 49 KB是仓库内规模较大的测试文件之一充分说明该守卫覆盖了大量边界场景。五、配置头文件与构建元数据生成1. gen_config_fwd_headers.py前向声明头生成器StarRocks 的common/config.h是 BE 全局配置的聚合头若被大量.cpp直接 include会显著拖慢编译。仓库的做法是生成领域化的前向声明头gen_config_fwd_headers.py 依据 be/src/common/config_fwd_headers_manifest.json 中的选择清单从be/src/common/config.h生成be/src/common/config_domain_fwd.h生成器会保留被选中配置项周边的预处理守卫#if/#ifdef等默认只重写内容发生变化的文件未变化的头文件保持原时间戳从而避免无意义的增量编译与 CI 缓存失效。三种用法python3 build-support/gen_config_fwd_headers.py # 生成/更新 python3 build-support/gen_config_fwd_headers.py --check # 校验已提交头文件是否最新 python3 build-support/gen_config_fwd_headers.py --force # 强制全部重写配套测试见 test_gen_config_fwd_headers.py。2. check_common_config_header_includes.shinclude 白名单守卫check_common_config_header_includes.sh 从两个维度把关先调用gen_config_fwd_headers.py --check确认已提交的config_domain_fwd.h与清单一致再扫描be/src与be/test下所有*.{h,hpp,cc,cpp}文件找出所有直接#include common/config.h或#include common/config.h的文件与 config_header_include_allowlist.txt 白名单比对白名单之外的新增 include 一律报错。该脚本优先使用rgripgrep加速扫描rg不存在时回退到find grep兼顾了不同 CI 镜像的环境差异。用法bash build-support/check_common_config_header_includes.sh3. 构建版本与 NOTICE 生成gen_build_version.py生成构建版本元数据git commit、构建时间等python3 build-support/gen_build_version.py --help可查看全部选项gen_notice.py从打包的第三方许可文件生成 NOTICE 文件内容保证开源合规声明与依赖清单同步python3 build-support/gen_notice.py --help查看用法sync_pom_to_gradle.py将 FE 侧 Maven POM 设置同步到 Gradle 配置避免两套构建系统的依赖声明漂移。六、macOS 构建支持与仓库知识库治理1. darwin_build_env.sh 与 build_helpers.shStarRocks 支持在 macOS ARM64 上构建 BEdarwin_build_env.sh 提供内部环境准备逻辑。README 明确建议不要直接 source 该脚本而是使用根目录的./build.sh --be由根构建助手统一编排。build_helpers.sh 则是被根构建脚本 source 的公共函数库封装了CPU 并行度探测macOS 用sysctl -n hw.ncpuLinux 用nprocJAVA_HOME解析兼容 macOS 上.app内嵌 JDK 的路径形态见 build_helpers.shmacOS 第三方面板完整性校验protoc、thrift、protobuf/rocksdb/glog/brpc/grpc 等静态库、krb5/sasl2 等系统 dylib见 build_helpers.sh打包产物对宿主 dylib 依赖清单的生成输出到output/be/HOST_DYLIB_DEPENDENCIES.txt见 build_helpers.sh因为 macOS 包并非完全自包含。这些细节说明 StarRocks 对 macOS 构建环境的处理相当工程化提前校验依赖、检测陈旧 CMake 缓存、必要时自动重置构建目录。2. check_repo_handbook.py 与 handbook_plan.py仓库内存在一个面向内部知识治理的handbook/目录含架构、领域、计划、政策、质量等索引。对应的两个脚本check_repo_handbook.py校验handbook/知识树的结构合法性包括必备入口文件、领域/政策/质量索引、页面标题契约、active 计划的元数据以及AGENTS.md/CLAUDE.md的导航链接是否有效python3 build-support/check_repo_handbook.py配套测试 test_check_repo_handbook.py 保障其自身可靠。handbook_plan.py管理 gitignored 的本地工作计划支持从已有计划派生、创建“checkout 本地覆盖”等场景python3 build-support/handbook_plan.py list python3 build-support/handbook_plan.py create --local --title Scratch Plan --owner Engineering Productivity python3 build-support/handbook_plan.py create --local --from handbook/plans/active/plan.md python3 build-support/handbook_plan.py complete --local --plan path-or-slug配套测试见 test_handbook_plan.py。七、快速参考脚本速查表以下汇总 build-support/README.md 中所有脚本的用途与核心用法便于日常查阅脚本职责核心用法check-format.shclang-format 全量检查不修改bash build-support/check-format.shclang-format.shclang-format 全量应用bash build-support/clang-format.shclang-format-changed-check.sh仅检查相对 origin/main 变更文件bash build-support/clang-format-changed-check.shclang-format-changed.sh仅格式化变更文件bash build-support/clang-format-changed.shrun_clang_format.pyclang-format 底层执行器check/fixpython3 build-support/run_clang_format.py --helpclang-tidy.shclang-tidy 统一入口./build-support/clang-tidy.sh --mode changed --base-version sha --branch main --build-type Release -j 32check_be_module_boundaries.pyBE 模块边界守卫python3 build-support/check_be_module_boundaries.py --mode full/--mode changed --base origin/mainrender_be_agents.py渲染/校验 be/AGENTS.md 模块边界段落python3 build-support/render_be_agents.py --write/--checkcheck_gensrc_schema_compatibility.pythrift/protobuf Schema 兼容性守卫python3 build-support/check_gensrc_schema_compatibility.py --mode changed --base origin/maincheck_repo_handbook.pyhandbook 知识树校验python3 build-support/check_repo_handbook.pycheck_common_config_header_includes.shconfig.h 直接 include 白名单守卫bash build-support/check_common_config_header_includes.shhandbook_plan.py本地工作计划管理python3 build-support/handbook_plan.py list等compile_time.sh编译耗时统计bash build-support/compile_time.shformat_changed_files.py过滤变更文件中的 C 源文件python3 build-support/format_changed_files.py --helpgen_config_fwd_headers.py生成/校验 config_ _fwd.hpython3 build-support/gen_config_fwd_headers.py --checkgen_build_version.py生成构建版本元数据python3 build-support/gen_build_version.py --helpgen_notice.py从许可文件生成 NOTICEpython3 build-support/gen_notice.py --helplintutils.pylint 共享辅助库被其他脚本 importdarwin_build_env.shmacOS 构建环境准备内部通过./build.sh --be间接使用sync_pom_to_gradle.pyPOM → Gradle 配置同步python3 build-support/sync_pom_to_gradle.py --help配套数据文件一览be/module_boundary_manifest.jsonBE 各模块的边界声明owned targets/roots/globs、允许与禁止的 include 前缀、允许的依赖与测试依赖、补救建议be_module_boundary_baseline.json经评审的历史违规基线exec_env_header_include_allowlist.txt 与 exec_env_singleton_allowlist.txtExecEnv相关白名单config_header_include_allowlist.txt允许直接 includecommon/config.h的白名单excludesclang-format 排除规则schema_compatibility_waivers.jsonSchema 变更豁免登记be/src/common/config_fwd_headers_manifest.json前向头选择清单。八、结语从脚本看 StarRocks 的工程治理哲学梳理完build-support/后可以发现StarRocks 的工程基建并非零散工具堆砌而是围绕几条清晰的原则组织增量优先changed模式贯穿 clang-tidy、模块边界、Schema 兼容等多个守卫让每次 MR 只承担与其改动规模匹配的检查成本基线只减不增模块边界基线配合--enforce-baseline-shrink承认存量技术债的同时严格封堵增量白名单是显式承诺无论是config.h的 include 还是ExecEnv的调用点都通过可评审、可 diff 的文本清单显式登记杜绝“加个例外就跑路”文档与代码同源render_be_agents.py、check_repo_handbook.py保证AGENTS.md、handbook/与清单、计划永远同步环境差异被显式处理macOS 的 dylib 依赖清单、缺失工具的rg回退、getopt探测等细节说明这些脚本被设计在多样化的本地与 CI 环境中真实运行。对于想为 StarRocks 贡献代码的开发者本地提交前跑一遍bash build-support/check-format.sh与python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main即可在 CI 之前拦截绝大多数风格与架构违规对于关注大型 C 工程治理的读者这份目录本身就是一份高质量的“可执行架构文档”范本。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
