Build and CI

构建与 CI

系统要求

项目	要求
编译器	GCC 15 / Clang 21（开发与生产统一）
CMake	3.28+
并行库	Intel oneTBB（流水线核心依赖）
压缩库	zlib-ng, libdeflate
构建工具	Ninja（推荐）
包管理	Conan 2.x
内存	建议 4GB+ RAM

---

快速构建

# 一键构建（Clang + Release）
./scripts/core/build

# 指定编译器和配置
./scripts/core/build --compiler gcc --type Debug

# 开发模式（Debug + 详细输出）
./scripts/core/build --dev

# 启用 Sanitizers
./scripts/core/build --sanitizer asan --dev
./scripts/core/build --sanitizer tsan --dev
./scripts/core/build --sanitizer ubsan --dev

# 覆盖率构建
./scripts/core/build --coverage

# 查看所有选项
./scripts/core/build --help

---

Conan 依赖管理

依赖清单

依赖定义在 conanfile.py（根目录）：

包	版本	用途
cxxopts	3.1.1	命令行解析
spdlog	1.17.0	日志（header-only 模式）
fmt	12.1.0	格式化（header-only 模式）
zlib-ng	2.3.2	gzip 压缩
nlohmann_json	3.11.3	JSON 处理
onetbb	2022.3.0	并行计算
libdeflate	1.25	高性能解压

安装依赖

# 使用脚本（推荐）
./scripts/core/install-deps

# 手动安装
conan install . --build=missing -of=build

特殊配置

• fmt 和 spdlog 使用 header-only 模式，避免新版编译器下 consteval 编译问题
• onetbb 要求 hwloc 以 shared 模式构建

---

CMake 配置

CMake 选项

选项	说明	默认值
CMAKE_BUILD_TYPE	构建类型	Release
BUILD_TESTING	构建单元测试	ON
BUILD_BENCHMARKS	构建基准测试	OFF
ENABLE_COVERAGE	启用代码覆盖率	OFF
ENABLE_FUZZING	启用模糊测试	OFF

编译器优化（Release 模式）

标志	说明
-O3	最高优化级别
-march=native	针对本机 CPU 优化
-mavx2	启用 AVX2 指令集
-ftree-vectorize	自动向量化
-funroll-loops	循环展开
-ffast-math	快速浮点运算
-ffunction-sections -fdata-sections	段级 DCE
LTO/IPO	跨模块链接时优化

CMake 目标

# 基础模块
fq_common          # Timer, IDGenerator
fq_error            # 异常体系
fq_config           # 配置管理

# 核心功能
fq_modern_io        # FastqReader / FastqWriter
fq_processing       # ProcessingPipeline
fq_statistics       # StatisticCalculator

# 应用层
fq_cli              # CLI 命令

# 可执行文件
FastQTools          # 主程序

手动 CMake 构建

# 配置
cmake --preset release

# 编译
cmake --build build/build/Release -j$(nproc)

# 测试
ctest --test-dir build/build/Release

# 安装
cmake --install build/build/Release --prefix /usr/local

---

代码质量检查

# 格式化代码
./scripts/core/lint format

# 检查格式（不修改）
./scripts/core/lint check

# clang-tidy 静态分析
./scripts/core/lint tidy

# clang-tidy 自动修复
./scripts/core/lint tidy-fix

# Cppcheck
./scripts/core/lint cppcheck

# Include-What-You-Use
./scripts/core/lint iwyu

# 运行所有检查
./scripts/core/lint all

---

测试

# 所有测试
./scripts/core/test

# 仅单元测试
./scripts/core/test --type unit

# 仅集成测试
./scripts/core/test --type integration

# 过滤特定测试
./scripts/core/test --filter "*timer*"

# 重复执行
./scripts/core/test --repeat 5

# 覆盖率报告
./scripts/core/build --coverage --dev
./scripts/core/test --coverage

---

CI/CD 流程

GitHub Actions Workflows

Workflow	触发条件	内容
ci.yml	Push / PR	构建 + 测试 + lint
pages.yml	Push to main	部署文档到 GitHub Pages
release.yml	Tag 创建	打包 + 上传 GitHub Release

CI 检查流程

1. 代码格式检查 (clang-format)
2. 静态分析 (clang-tidy)
3. 依赖安装 (Conan)
4. 编译构建 (CMake + Ninja)
5. 单元测试 (GTest)
6. 集成测试
7. 覆盖率报告 (lcov)
8. 性能基准测试（定时）

---

配置目录 (config/)

子目录	用途
conan/	Conan 编译器 profiles（profile-clang, profile-gcc）
dependencies/	Conan 依赖配置
sanitizers/	ASan/TSan/UBSan/MSan 运行时选项
valgrind/	Valgrind 抑制规则
cppcheck/	Cppcheck 静态分析配置
coverage/	覆盖率阈值配置
iwyu/	Include-What-You-Use 映射

---

脚本目录 (scripts/)

脚本	用途
scripts/core/build	统一构建入口
scripts/core/test	统一测试入口
scripts/core/lint	代码质量检查
scripts/core/install-deps	依赖安装
scripts/benchmark	性能基准测试
scripts/tools/deploy	Docker 部署
scripts/tools/coverage-report	覆盖率报告
scripts/tools/package-release	发布打包

---

发布流程

# 本地打包
./scripts/tools/package-release

# 产物输出到 dist/
ls dist/*.tar.gz

GitHub Actions 在 tag 创建时自动触发 release.yml，执行打包并上传到 GitHub Release。

---

相关页面

• Getting Started — 环境搭建
• Testing Strategy — 测试策略详解
• Code Quality Tools — 质量工具完整指南
• DevContainer and Docker — 容器化开发环境