2. 工程目录与版本基线

在Quartus工程签核与交付流程中，工程目录与版本基线是决定“交付物是否可复现、可追溯、可回退”的基础设施。很多团队在项目初期只关注功能实现，把工程文件随意放在桌面或共享盘，等到签核阶段才发现：同一个工程名对应多个不同版本、约束文件被覆盖、编译脚本找不到源文件、IP核版本与Quartus版本不匹配。这些问题本质上不是技术问题，而是目录结构与版本基线管理缺失造成的。

一、Quartus工程目录结构规范

Quartus Prime工程默认会生成大量中间文件，包括 .qpf（工程文件）、.qsf（设置与约束）、db/、incremental_db/、output_files/、tmp/ 等。如果把这些文件与设计源码混在一起，版本控制将变得极其低效。推荐采用“源码与生成物分离”的目录结构，示例如下：

project_root/
├── prj/                    # Quartus工程文件
│   ├── top.qpf
│   ├── top.qsf
│   └── top.sdc
├── rtl/                    # 设计源码
│   ├── top.v
│   ├── core/
│   └── ip/
├── tb/                     # 仿真测试平台
├── scripts/                # 编译、签核脚本
│   ├── build.tcl
│   └── signoff.tcl
├── doc/                    # 设计文档、签核记录
├── output/                 # 编译输出（不纳入版本控制）
└── .gitignore              # 忽略规则

其中 prj/ 只保留 .qpf、.qsf、.sdc 等可读工程描述文件；db/、incremental_db/、output_files/、tmp/ 必须写入 .gitignore 或 SVN 的忽略属性。这样做的直接收益是：仓库体积小、diff 可读、多人协作时不会因二进制中间文件产生冲突。

二、版本命名规则

版本命名应同时表达“项目阶段、功能标识、迭代序号、签核状态”。推荐格式：项目代号_阶段_主版本.次版本.修订号_状态。例如：

版本号一旦进入 baseline 状态，对应Git标签或SVN标签必须同步创建，且该标签指向的提交不允许再被修改。后续任何改动只能通过新分支或新修订号进行。

三、基线冻结方法

基线冻结不是简单打一个标签，而是需要同时冻结源码、约束、脚本、工具版本和签核记录。建议按以下顺序执行：

1. 确认所有RTL、IP、约束文件已提交，工作区干净（git status 无未跟踪或未提交内容）。
2. 在 scripts/build.tcl 中固定Quartus版本，例如 set QUARTUS_VER "23.1std.0"，并在签核记录中写明。
3. 执行一次完整编译，确认时序收敛、资源占用与签核指标一致。
4. 创建标签：git tag -a UART_v1.0.0_baseline -m "签核通过，冻结"，并推送标签到远端。
5. 将编译报告、时序报告、资源报告归档到 doc/signoff/，与标签一一对应。

四、Git/SVN集成与变更记录

Quartus工程适合使用Git进行版本控制，但必须配合合理的忽略规则。以下是一个可直接使用的 .gitignore 示例：

# Quartus 生成物
db/
incremental_db/
output_files/
tmp/
*.rpt
*.sof
*.pof
*.jic
*.sopcinfo
*.qws
*.qpf.bak

# 仿真生成物
simulation/
work/
*.vcd
*.wlf

对于SVN，则通过 svn:ignore 属性设置相同目录。变更记录应遵循“一次提交只做一件事”的原则，提交信息格式建议为：[模块] 动作: 简述，例如 [UART] fix: 修正波特率分频系数。每次签核前，从Git日志导出变更清单，作为签核记录的一部分。

从图中可以看出，目录结构规范解决的是“文件放哪里”的问题，版本命名解决的是“当前处于什么状态”的问题，基线冻结解决的是“哪个提交可以交付”的问题，而Git/SVN集成与变更记录解决的是“如何追溯每一次改动”的问题。四者共同构成签核交付的版本基线体系。实际执行时，建议把上述检查项写入 scripts/signoff.tcl，在签核前自动检查工作区状态、标签是否存在、报告是否归档，减少人为遗漏。