Debian 下 Fortran 项目的协作开发实践
一 环境与工具基线
- 编译器与基础工具：安装 gfortran、make、git，确保团队使用一致的编译器版本与优化级别；并行与数值库按需准备（如 libopenmpi-dev、libblas-dev、liblapack-dev、libfftw3-dev、hdf5-dev）。示例：sudo apt update && sudo apt install -y gfortran make git。并行构建建议使用 mpif90。
- 构建方式：小型与模块化项目优先 fpm（Fortran Package Manager）；中大型与复杂依赖使用 Makefile 或 CMake。fpm 提供标准化的项目骨架（src/、test/）、一键构建与运行，便于新人上手与 CI 复用。
- 版本控制：使用 Git 进行分布式协作，约定 main/develop 分支策略与保护规则，配合 PR/MR 进行代码评审与 CI 门禁。
二 仓库骨架与本地开发流程
- 推荐的仓库结构（示例）：
- 使用 fpm：项目根含 fpm.toml、src/、test/，可选 examples/、benchmarks/、README.md、LICENSE、.gitlab-ci.yml/Jenkinsfile。
- 使用 Make：项目根含 Makefile、src/、test/、lib/（若有）、scripts/（如 run_tests.sh）、CI 文件。
- 本地开发闭环（确保“本地一键构建+测试”与 CI 一致）：
- fpm：fpm build、fpm run、fpm test（或脚本封装）；
- Make：make、make test、make clean；
- 统一用根目录的 run_tests.sh 执行测试并以退出码表示结果，便于 CI 判定成功/失败。
- 多人协作节奏（简要）：
- 从 main 拉出功能分支（如 feature/xxx 或 bugfix/yyy）；
- 本地实现与自测（含新增/修改的单元测试）；
- 提交前确保通过本地构建与测试；
- 推送分支并发起 PR/MR，在评论中关联需求/任务；
- 通过评审后由维护者合并，删除已合并分支。
三 持续集成与质量门禁
- 自建或托管 CI 均可：自建推荐 Jenkins（Debian 上 apt 安装），托管可用 GitLab CI/CD 或 Travis CI。CI 目标：多编译器矩阵构建、依赖安装、构建与测试、结果归档与报告、质量门禁（失败即阻断合并）。
- 编译器与特性矩阵：至少覆盖多个 gfortran 版本与关键特性（如 MPI 开关），在矩阵中并行执行，提高覆盖率与问题早期发现率。
- 示例要点（概念）：
- Jenkins 使用 matrix 并行覆盖 gfortran 版本与 MPI；构建阶段按是否启用 MPI 选择 FC=mpif90 或 FC=gfortran，测试阶段执行 run_tests.sh 并以退出码判定；
- GitLab CI 使用官方 fortran 镜像或 debian:stable-slim，在 before_script 安装 gfortran 与依赖，构建后执行测试并归档产物。
- 质量门禁建议：
- 所有提交必须通过构建与测试；
- 新增代码需配套测试，覆盖率与测试结果作为合并前置条件；
- 静态检查/代码风格（如可用工具）、编译器警告升级为错误（-Wall -Wextra -Werror）等可按项目启用。
四 代码评审与发布打包
- 代码评审要点（PR/MR 流程）：
- 范围包含设计、功能正确性、复杂度、可测试性、命名、代码风格、文档与原子性提交；
- 提交需“小而专注”，一次 PR 只做一件事；
- 评审响应时效建议不超过 1 个工作日；讨论留痕，修改后重新推送以更新评审。
- 发布与 Debian 打包简述（面向对外发布）：
- 版本管理：遵循语义化版本；合并到 main 后打 Git tag（如 v1.2.3）；
- 打包流程：使用 debmake 或 dh_make 生成打包模板，完善 debian/ 目录（control、rules、changelog、copyright 等），在干净环境构建 .deb 并做安装/卸载/升级回归；
- 持续交付：CI 中增加构建 .deb 的 job，产物上传至制品库（如自建 apt 仓库或 GitHub Releases），并在变更日志中记录 ABI/接口变更与升级指引。
五 常见问题与排错清单
- 编译与链接：
- “undefined reference” 多为未链接依赖库或链接顺序不当；确认 -l 与 -L 路径，库在链接命令行中置于引用者之后；
- 多文件/多模块工程注意编译顺序或改用构建系统（Make/fpm）自动处理依赖。
- 运行时错误：
- “Segmentation fault” 使用 gdb 定位；重点排查数组越界、未初始化变量、空指针/无效内存访问；
- 增加日志与 iostat 检查文件 I/O 状态，确保路径、权限与格式正确。
- 环境与依赖：
- 多版本 gfortran 并存时，显式设置 FC 与 PATH；
- 动态库路径问题使用 LD_LIBRARY_PATH 或系统库目录规范安装，避免运行时找不到库。
