2. 工程创建与管理错误：工程路径包含中文或空格、工程名与顶层模块名不一致、版本管理混乱

说实话，FPGA开发里最让人头疼的往往不是代码逻辑有多复杂，而是工程创建阶段埋下的那些坑。我见过太多新手甚至老手，花了一整天调一个bug，最后发现——嗯，问题出在工程路径里有中文。

这一章咱们就聊聊工程创建和管理上的三个常见错误。都是些看似不起眼的小事，但踩过一次你就知道疼了。

2.1 工程路径包含中文或空格

先说说路径的问题。Lattice的Diamond或Radiant软件，底层用的是Tcl脚本和GCC编译器。这些工具对中文和空格的支持，说白了就是「看心情」。

为什么会这样？因为编译工具链在处理路径时，会把中文字符解析成多字节编码。一旦某个环节的编码表对不上，就会报一些莫名其妙的错误。比如：

• 综合时报错「Can't open file」
• 布局布线时卡住不动
• 生成比特流时提示「Unexpected token」

我在项目中遇到过一回，同事把工程放在「D:\项目\FPGA开发\测试工程」下。结果每次编译到一半就报错，查了两天才发现是路径里的中文在作怪。改成「D:\project\fpga_dev\test_prj」后，一次通过。

空格的问题更隐蔽。有些同学喜欢在路径里加空格，比如「My Project」。编译时工具会把空格当成参数分隔符，结果路径被截断了。你想想看，工具拿到的是「My」和「Project」两个参数，它不报错才怪。

避坑指南： 我曾经在路径里用过下划线代替空格，比如「my_project」。后来发现连下划线都别用最好，就用纯字母和数字。简单粗暴，但管用。

2.2 工程名与顶层模块名不一致

这个错误，说大不大，说小不小。但一旦犯了，编译时工具会直接给你甩个红脸。

Lattice的工程结构里，有一个顶层模块（Top Module）的概念。综合工具会以这个模块为入口，递归地例化所有子模块。如果工程名叫「led_blink」，但顶层模块名叫「top_led」，工具就会懵掉——你到底让我综合哪个？

我记得有一次帮同事排查问题，他的工程叫「uart_test」，但顶层模块写的是「uart_top」。综合时报错说找不到顶层模块。我打开工程设置一看，果然，顶层模块名没改过来。改完后，编译就正常了。

具体操作上，在Diamond或Radiant里创建工程时，会让你指定顶层模块。如果你用的是Verilog，顶层模块就是module后面的那个名字。比如：

module led_blink (
    input  clk,
    input  rst_n,
    output reg led
);
// 代码内容
endmodule

那么工程名就应该叫「led_blink」。别问我为什么，这就是工具的规矩。

2.3 版本管理混乱

版本管理这事儿，说起来都是泪。我见过最夸张的情况是，一个工程文件夹里有十几个备份：

• led_blink_v1
• led_blink_v2
• led_blink_v2_改
• led_blink_v2_改_最终版
• led_blink_v2_改_最终版_真的不改了

你想想看，这种命名方式，过两周你自己都分不清哪个是哪个。

为什么会这样？ 说白了就是没有用版本管理工具。很多FPGA工程师习惯手动备份，觉得Git太麻烦。但手动备份的代价就是——你永远不知道哪个版本是能用的。

用Git其实不复杂，记住几个基本操作就够了：

# 初始化仓库
git init

# 添加文件
git add .

# 提交修改
git commit -m "完成了LED闪烁功能"

# 查看历史
git log

我个人建议，每次提交时写清楚注释。比如「修复了时钟分频的bug」而不是「改了点东西」。这样以后回溯时，一眼就能看出每个版本做了什么。

另外，工程文件里有些是自动生成的，比如.lpf约束文件、.syn综合脚本等。这些文件建议也纳入版本管理。但像.log、.jou这些日志文件，每次编译都会变，就别加进去了。用.gitignore把它们过滤掉：

# .gitignore 示例
*.log
*.jou
*.bak
__pycache__/
.ip/
.syn/
.rpt/

我曾经有个项目，开发到一半发现之前删掉的一个功能需要加回来。幸好有Git，一条git checkout命令就恢复了。要是手动备份，估计得翻半天文件夹。

本章小结

工程创建和管理看似基础，但恰恰是这些基础环节最容易出问题。路径别用中文和空格，工程名和顶层模块名保持一致，版本管理用Git。这三条做到了，能省下你至少一半的调试时间。

嗯，这些经验都是我踩过坑之后总结出来的。你照着做，肯定能少走弯路。

---