从源码构建 StarRocks 全指南build.sh 编译流程、单元测试与构建选项详解【免费下载链接】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 仓库的开发者构建手册为核心系统讲解如何从源码完成 StarRocks 的编译与单元测试从一键执行./build.sh构建全部组件到按需单独构建 FE/BE、在命令行直接运行 Backend 单元测试再到通过BUILD_TYPE、STARROCKS_LINKER、Clang 等构建选项定制编译产物。文中所有命令与结论均以当前仓库的实际脚本build.sh、run-be-ut.sh、run-fe-ut.sh、env.sh与 CMake 配置be/CMakeLists.txt为依据适合 StarRocks 二次开发、源码阅读与性能调试场景。构建前的准备环境与依赖在运行任何构建命令之前StarRocks 会先通过 env.sh 对构建环境做一次完整体检任一环节不满足都会直接退出GCC/G版本必须≥ 12.1.0否则报Error: GCC version (...) must be greater than or equal to 12.1.0。JDKJAVA_HOME必须正确设置且$JAVA_HOME/bin/java可执行要求JDK 11 及以上env.sh。Python需要python3可通过PYTHON环境变量覆盖。构建工具链mvnMaven与cmake必须可用若系统装有ninja构建系统会自动从make切换为ninja并采用 Ninja 生成器。自定义环境如果仓库根目录存在custom_env.shenv.sh 会先加载它方便开发者覆盖JAVA_HOME、STARROCKS_THIRDPARTY、CUSTOM_MVN、CUSTOM_CMAKE等变量。另一个关键前置条件是第三方依赖库thirdparty。build.sh 会检查${STARROCKS_THIRDPARTY}/installed/llvm/lib/libLLVMInstCombine.a是否存在若尚未构建会自动调用${STARROCKS_THIRDPARTY}/build-thirdparty.sh先行编译所有第三方库。这一步骤耗时较长首次构建请保持耐心。如果不想手工准备整套编译环境可以直接使用官方开发镜像如starrocks/dev-env-ubuntu在 Docker 容器中构建具体流程见 Build_in_docker.md在 Ubuntu 上手工安装依赖的方式见 build_starrocks_on_ubuntu.md。一键构建./build.sh在满足上述环境要求后构建整个 StarRocks 只需一条命令./build.sh其完整执行流程见 build.sh 源码如下解析仓库根目录并导出STARROCKS_HOME若未显式设置STARROCKS_VERSION/STARROCKS_COMMIT_HASH会自动从 Git 标签、分支名或 commit 推断版本号build.sh。加载 env.sh 完成环境校验并检测并行度——默认并行数约为CPU 核数 / 4 1。检查 thirdparty 依赖是否就绪未就绪则自动构建。生成代码gensrc在 gensrc 目录执行make script生成 proto/thrift 相关的脚本生成代码。构建BackendBE以CMAKE_BUILD_TYPE配置 be/CMakeLists.txt编译目录为be/build_${BUILD_TYPE}随后执行install并默认继续构建 Java Extensionsjava-extensions可用--without-java-ext关闭。构建FrontendFE在fe目录通过 Maven 打包plugin/hive-udf,fe-testing,plugin/spark-dpp,fe-server等模块。组装输出目录并调用 build-support/gen_notice.py 生成 NOTICE 文件。构建成功后产物统一放置在output目录默认${STARROCKS_HOME}/output/可用--output PATH指定build.shoutput/fe/Frontend 产物包含lib/starrocks-fe.jar、bin/、conf/fe.conf、spark-dpp/、hive-udf/、webroot/等output/be/Backend 产物核心二进制为lib/starrocks_be另有bin/、conf/be.conf、lib/jni-packages/Java 扩展 JAR、lib/jemalloc/等output/format-lib/format library仅--format-lib构建时生成。对于 RELEASE 构建脚本还会使用objcopy/strip把starrocks_be的调试符号拆分到starrocks_be.debuginfo以减小发布二进制体积build.sh。按模块分别构建 FE / BE日常开发中通常只需要重新编译改动的模块无需每次都全量构建。./build.sh支持按模块构建只构建 Backend./build.sh --be只构建 Frontend同时包含 Spark DPP 应用./build.sh --fe其它可独立构建的模块包括./build.sh --format-lib构建 StarRocks format library用于 shared-data 模式集群./build.sh --spark-dpp单独构建 Spark DPP 应用./build.sh --hive-udf单独构建 Hive UDF。模块与--clean可以组合使用例如清理并重新构建 FE./build.sh --fe --clean注意--clean必须与--fe、--be、--format-lib、--spark-dpp、--hive-udf之一同时使用否则脚本会报错build.sh--format-lib与--be互斥不能同时指定build.sh。构建时可以显式指定并行度例如用 24 个核编译./build.sh -j 24运行单元测试StarRocks 的 BE 与 FE 单元测试相互独立分别通过 run-be-ut.sh 与 run-fe-ut.sh 运行。运行 BE 单元测试./run-be-ut.sh该脚本会以ASANAddressSanitizer构建类型构建并运行 BE 单元测试run-be-ut.sh 中CMAKE_BUILD_TYPE${BUILD_TYPE:-ASAN}测试构建目录为be/ut_build_ASAN。脚本会依次完成构建 Java Extensions、生成 gensrc 代码、以-DMAKE_TESTON配置并编译、拆分测试二进制调试符号然后设置ASAN_OPTIONS、LSAN_OPTIONS使用 conf/asan_suppressions.conf 抑制误报、配置 JVM 的LD_LIBRARY_PATH与 Hadoop classpath最后运行starrocks_test、starrocks_dw_test以及各模块的独立测试二进制。run-be-ut.sh提供以下常用参数详见脚本头部 usage参数作用--test TEST_NAME只运行指定测试会自动追加*通配--gtest_filter FILTER使用 gtest 过滤器选择用例--module MODULE指定运行某个模块的测试二进制正则默认.*--clean清理旧的测试构建产物--dry-run只列出将要执行的测试不真正运行--excluding-test-suit排除指定测试套件|分隔多个--build-target TARGET只编译指定测试目标如base_test--with-gcov/--with-aws/--with-bench以 gcov 覆盖率 / AWS / benchmark 模式构建--enable-shared-data启用 shared-data 特性--without-starcache/--without-tenann/--without-paimon-cpp关闭对应组件--without-debug-symbol-split不拆分调试符号可加速加载-j N并行度例如只运行CompactionUtilsTest与TabletUpdatesTest两个测试套件./run-be-ut.sh --gtest_filter CompactionUtilsTest*:TabletUpdatesTest*运行 FE 单元测试./run-fe-ut.shFE 测试基于 Maven Surefire 执行mvn verify。常用参数包括--test [TEST_NAME]运行指定测试例如--test com.starrocks.utframe.Demo--filter [TEST_NAME]跳过指定测试多个用逗号分隔并加引号--dry-run仅预览--coverage执行覆盖率统计任务--dumpcase [PATH]运行 dump case 回归测试并输出到指定路径--enable-profiler [0|1]启用/禁用 async-profiler 性能分析需 Linux 平台且存在build-support/libasyncProfiler.so-j [N]测试并行度默认取FE_UT_PARALLEL未设置时为 4。在命令行中直接运行 BE 单元测试./run-be-ut.sh封装了很多环境准备逻辑但如果想更灵活地直接运行测试二进制可以手动设置运行依赖后直接执行starrocks_test对应 run-be-ut.sh 中的环境变量导出逻辑UDF_RUNTIME_DIR./ STARROCKS_HOME./ LD_LIBRARY_PATH/usr/lib/jvm/java-18-openjdk-amd64/lib/server ./be/ut_build_ASAN/test/starrocks_test其中UDF_RUNTIME_DIRUDF 运行时工作目录脚本内部会创建${STARROCKS_HOME}/lib/udf-runtime并清空其中的旧文件STARROCKS_HOME仓库根目录用于定位配置与依赖LD_LIBRARY_PATH必须包含 JVM 的lib/server目录BE 需要加载 JVM 相关动态库run-be-ut.sh 会根据 JDK 版本自动定位该路径手动执行时需自行指定测试二进制位于be/ut_build_ASAN/test/starrocks_test默认 ASAN 构建目录。用 gtest filter 运行部分用例BE 单元测试基于 GoogleTest 构建因此可以直接使用--gtest_filter按名称过滤用例。例如只运行与 MapColumn 相关的测试对应的测试文件为 be/test/column/map_column_test.cpp 和 be/test/column/map_column_core_test.cppUDF_RUNTIME_DIR./ STARROCKS_HOME./ LD_LIBRARY_PATH/usr/lib/jvm/java-18-openjdk-amd64/lib/server ./be/ut_build_ASAN/test/starrocks_test --gtest_filter*MapColumn*--gtest_filter支持*通配、:分隔多个正例、-排除负例等语法。run-be-ut.sh内部也在使用这一机制例如无 Hadoop 环境时自动追加负例-HdfsFileSystemTest*关闭 AWS 时追加-*S3*run-be-ut.sh因此手动运行时可以沿用同样的过滤思路精确定位到某个列类型、算子或存储组件的测试。构建选项使用 Clang 构建除了默认的 GCC也可以使用 Clang 编译 BackendCCclang CXXclang ./build.sh --be构建成功后输出信息中可以看到类似-- compiler Clang version 14.0.0的提示。env.sh中通过CLANG_COMPATIBLE_FLAGS从 GCC 提取系统头文件路径传给 Clang保证两者 ABI 兼容env.sh。更换链接器加速链接默认链接器速度较慢开发者可以通过环境变量STARROCKS_LINKER指定其他链接器来加速链接阶段。以 LLVM 生态的lld为例先安装lldsudo apt install lld再指定链接器并构建STARROCKS_LINKERlld ./build.sh --be该变量的底层实现在 be/CMakeLists.txt脚本读取环境变量STARROCKS_LINKER后通过add_link_options(-fuse-ld${STARROCKS_LINKER})将其注入编译命令。另外有一个自动兜底逻辑当主机 glibc 版本低于 2.29 且编译器版本高于 14.0.0非 aarch64时即使未设置该变量也会强制切换到gold链接器以保证兼容性。不同的构建类型BUILD_TYPE通过BUILD_TYPE环境变量可以切换构建类型默认值为RELEASE。例如构建 ASANAddressSanitizer版本BUILD_TYPEASAN ./build.sh --be构建目录会随类型变化即be/build_${BUILD_TYPE}如be/build_Release、be/build_ASAN。当前仓库的 be/CMakeLists.txt 定义了以下受支持的构建类型及其编译标志BUILD_TYPE编译标志适用场景RELEASE默认-O3 -gdwarf-4 -DNDEBUG生产发布开启全部优化并关闭断言DEBUG-ggdb -O0 -gdwarf-5 -DDEBUG本地调试关闭优化、保留调试信息ASAN-ggdb3 -O0 -gdwarf-5 -fsanitizeaddress -DADDRESS_SANITIZER内存错误检测BE 单测默认类型LSAN-fsanitizeleak -DLEAK_SANITIZER内存泄漏检测UBSAN-O3 -fsanitizeundefined基于 RELEASE未定义行为检测TSAN-O0 -ggdb3 -fsanitizethread -DTHREAD_SANITIZER数据竞争检测此外链接行为也随构建类型变化be/CMakeLists.txtRELEASE/DEBUG链接 jemalloc 作为内存分配器ASAN/LSAN/UBSAN/TSAN则改为静态链接对应的 sanitizer 运行库。需要注意的是ASAN 与 gcov 互斥二者不能同时开启build.sh。build.sh 常用参数一览结合 build.sh 的 usage 输出除模块选择外还有大量针对 Backend 的编译选项常用者整理如下参数作用--clean清理后重新构建--enable-shared-data构建支持 shared-data存算分离特性的 Backend--with-bench同时构建 benchmark默认不构建--with-gcov/--without-gcov开启 / 关闭 gcov 覆盖率构建--with-clang-tidy开启 clang-tidy 静态检查--with-glibc-compat生成兼容更老 glibc 的二进制并校验 ABI 下限--without-java-ext不构建 Java Extensions--without-pch关闭预编译头默认开启--without-avx2不启用 AVX2 指令--without-starcache/--without-tenann/--without-paimon-cpp关闭对应组件构建--without-connector-jdbc/--without-connector-mysql/--without-connector-elasticsearch/--without-connector-benchmark关闭对应 Connector--output PATH指定输出目录--output-compile-time记录每个 C 文件的编译耗时到compile_times.txt会关闭 ccache--with-maven-batch-mode {ON\|OFF}控制 Maven batch 模式--disable-java-check-style跳过 Java checkstyle 检查-j N并行编译核数关于指令集还有一处自动检测逻辑脚本会读取/proc/cpuinfo若 CPU 不支持 AVX2 / AVX512 / SSE4.2 / BMI2则自动关闭对应的USE_*开关build.sh因此在新老硬件上构建均可安全执行。常见问题Ubuntu 24.04 或 GCC 12 下构建失败报严格警告错误可先导出DISABLE_WARNING_AS_ERROR1再执行./build.sh避免第三方库中的警告被当作错误见 build_starrocks_on_ubuntu.md 的 FAQ。Docker 容器中构建 BE 报g: fatal error: Killed signal terminated program cc1plus这是容器内存不足导致的编译进程被杀需要为容器分配至少 8 GB 内存见 Build_in_docker.md。构建aws_cpp_sdk报undefined reference to pthread_create通常是 CMake 版本过低需要升级到 3.20.1 及以上。--clean单独使用报错--clean必须与至少一个构建模块参数--fe/--be/--format-lib/--spark-dpp/--hive-udf搭配使用。首次构建耗时极长thirdparty 第三方库需要先完整编译一遍属于正常现象后续增量构建会快很多且脚本会自动复用已安装的 thirdparty 产物。小结本手册覆盖了 StarRocks 从源码构建的完整链路环境体检env.sh→ 依赖就绪检查与自动编译build.sh 内嵌逻辑→ BE/FE 全量或按模块编译 → 产物组装到output目录测试侧则分别说明了run-be-ut.shASAN 默认、gtest filter 过滤与run-fe-ut.shMaven Surefire、覆盖率与 profiler的使用方式以及脱离脚本直接运行starrocks_test的依赖清单。在此基础上通过BUILD_TYPERELEASE / DEBUG / ASAN / LSAN / UBSAN / TSAN、CC/CXXclang、STARROCKS_LINKERlld等选项可以按调试、测试或发布需求灵活定制构建产物。文中涉及的所有脚本与 CMake 配置都位于仓库根目录与 be 目录下读者可以对照源码进一步深入每一个开关的具体行为。【免费下载链接】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），仅供参考