FPGA 进阶 41：工程与 IP 版本管理——让工程可复现、可追溯
本文是
fpga/进阶层第 45 篇。RTL 版本意识在入门篇提过，这里讲工程级/团队级纪律。参数化复用见 RTL 复用，自动化构建接 [CI/CD]（专家层）。
本文要回答的问题
- git 该提交什么、忽略什么？
- 为什么 .xpr 不该进仓库？可移植工程怎么建？
- IP 升级、工具版本怎么管理？
- 发布比特流怎么追溯？
一、源 vs 产物
.gitignore 典型片段：
gitignore
*.cache/
*.runs/
*.hw/
*.sim/
*.Xil/
*.jou
*.log
*.xpr
*.bit
*.ltx二、可移植构建：build.tcl
tcl
# 用法: vivado -mode batch -source build.tcl
create_project myproj ./work -part xc7a100tfgg484-2 -force
add_files -scan_for_includes {../rtl ../ip}
add_files -fileset constrs_1 ../constraints/top.xdc
# IP 由 .xci 自动重建, 或用 tcl 创建
read_ip ../ip/fifo.xci
synth_design -top top -part xc7a100tfgg484-2
opt_design; place_design; route_design
write_bitstream -force ./out/top.bit- 也可 Write Project to Tcl 导出后精简维护；
- 块设计导出 tcl（比二进制 .bd 易 review/合并）；
- clone 后一条命令出工程是验收标准。
三、IP 与工具版本纪律
| 事项 | 纪律 |
|---|---|
| Vivado 版本 | 全团队统一，README 记录；跨版本升级走分支+全量回归 |
| IP 版本 | 随工具版本锁定；不随手点 Upgrade，升级按代码改动对待（仿真+时序+上板回归） |
| .xci | 提交（小、可重建 IP）；coe/mif 同步提交 |
| IP 产物 DCP | 不进 git，制品库存档 |
| 块设计 | 提交 .bd 或导出 tcl |
四、发布追溯
- 发布打 git tag（rel-vX.Y.Z），commit 干净；
- 比特流/
.ltx归档制品库，文件名含版本+commit hash； - RTL 固化版本寄存器（软件可读 PL 版本）；
- tag 说明记录工具版本、已知问题；
- 维护分支只做 backport，冻结工具/IP 版本。
常见坑对照
| 坑 | 后果 | 正确做法 |
|---|---|---|
| 提交 .runs/.xpr | 仓库巨大、换机器坏 | 提交源 + build.tcl |
| .xci 没提交 | IP 重建参数丢失 | .xci 与 coe 进 git |
| 随手 Upgrade All IP | 时序/行为悄悄变 | 升级走分支+全回归 |
| 团队工具版本各异 | 综合结果不一致 | 统一版本并记录 |
| 发布 bit 无 tag | 无法追溯/复现 | tag+版本寄存器+归档 |
| 手工点 GUI 出比特流 | 无人能复现 | 脚本化构建 |
相关与延伸
参数化与打包：RTL 复用、块设计 IPI。 自动化延伸：专家层《FPGA CI/CD》（自动综合/时序门禁）、RTL 质量检查。
一句话总结
FPGA 版本管理的本质是管理'能重建工程的最小源集合'：RTL/TB/XDC/.xci/.bd 或 tcl/coe 进 git，.runs/.cache/.xpr（绝对路径、可再生）全部 ignore。可移植性靠构建 tcl 保证——clone 后 vivado -mode batch -source build.tcl 一条命令重建工程出比特流，而不是提交含绝对路径的 .xpr。版本纪律：全团队统一 Vivado 版本并记录，IP 不随手升级（升级=网表行为变更，必须重跑时序+仿真+上板回归，在分支做），块设计导 tcl 便于 review。发布时打 git tag、比特流与 commit hash 绑定归档、RTL 固化版本寄存器供软件查询——比特流是全部输入（RTL/约束/IP/coe/工具版本）的函数，任何一个变了都不算复现。