Getting Started

快速开始

本指南帮助你在最短时间内完成 FastQTools 的环境搭建并运行第一个命令。

---

系统要求

运行时（最低）

• Ubuntu 20.04+ 或 Debian 11+
• 1GB RAM / 100MB 磁盘

开发环境（推荐）

• Ubuntu 22.04+ 或 Debian 12+
• 4GB RAM / 2GB 磁盘
• 多核 CPU（加速并行构建）

编译器要求

编译器	最低版本	推荐版本
GCC	11.0	15
Clang	12.0	21

注意: FastQTools 使用 C++23 标准，需要支持 C++23 的编译器。

---

安装依赖

# 完整开发环境（编译器、构建工具、调试工具）
./scripts/core/install-deps

# 仅运行时依赖（生产部署）
./scripts/core/install-deps --runtime

# 查看帮助
./scripts/core/install-deps --help

开发依赖清单

类别	工具
编译器	GCC 15 / Clang 21
构建系统	CMake 3.28+, Ninja
包管理	Conan 2.x
调试	GDB, Valgrind
覆盖率	lcov

运行时依赖

包	版本	用途
onetbb	2022.3.0	TBB 并行库
zlib-ng	2.3.2	gzip 压缩
libdeflate	1.25	高性能解压
cxxopts	3.1.1	命令行解析
spdlog	1.17.0	日志
fmt	12.1.0	格式化
nlohmann_json	3.11.3	JSON

---

编译构建

# 默认构建（Clang + Release）
./scripts/core/build

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

# 指定编译器和构建类型
./scripts/core/build --compiler gcc --type Debug

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

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

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

手动构建（CMake）

# 安装 Conan 依赖
conan install . --build=missing -of=build

# 配置
cmake --preset release

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

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

构建成功后，可执行文件位于 build/clang-release/FastQTools。

---

验证安装

# 查看帮助
./build/clang-release/FastQTools --help

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

---

第一个示例

1. 准备测试数据

# 使用内置工具生成合成 FASTQ 文件
python3 tools/data/gen_fastq.py -o test_data.fastq --reads 5000 --min-len 80 --max-len 150

2. 统计分析

FastQTools stat -i test_data.fastq -o stats.txt --threads 4

输出包含：读段总数、长度分布、碱基组成（A/T/C/G/N）、GC 含量、Q20/Q30 百分比。

3. 质量过滤

FastQTools filter -i test_data.fastq -o filtered.fastq \
  --min-quality 20 \
  --min-length 50 \
  --max-n-ratio 0.1 \
  --trim-quality 20 \
  --trim-mode both

4. 压缩输出

输出文件使用 .gz 后缀即可自动启用 gzip 压缩：

FastQTools filter -i input.fq.gz -o output.fq.gz --min-quality 20

---

常见问题

问题	解决方案
依赖安装失败	确保系统为 Ubuntu/Debian，运行 sudo apt-get update
Conan 找不到	pip install conan 安装 Conan 2.x
CMake 版本过低	需要 CMake 3.28+，通过 cmake --version 检查
找不到可执行文件	检查 ls build/clang-release/FastQTools
缺少共享库	运行 ldd build/clang-release/FastQTools 定位，再安装运行时依赖

---

下一步

• CLI Reference — 完整命令行用法
• Architecture — 技术架构和设计原则
• Build and CI — 高级构建选项与 CI 配置
• DevContainer and Docker — 容器化开发环境