1. 为什么要单独写一篇Yosys安装教程搞FPGA或者数字IC相关工作的同学就算没用过Yosys也大概率在GitHub或者某些开源项目里见过这个名字。Yosys是一个开源的Verilog综合工具支持从Verilog RTL代码综合出门级网表也能输出BLIF、EDIF、BTOR等多种格式配合nextpnr、开源的器件数据库可以直接走完“RTL → 综合 → 布局布线 → 生成比特流”这条完整链路。说白了它就是开源数字芯片/FPGA设计工具链里的“编译器”环节地位相当于GCC在C语言生态里的角色。这篇教程主要解决一个实际问题怎么在你的电脑上把Yosys装好、跑起来。内容覆盖Linux、Windows、macOS三种平台从包管理器安装讲到源码编译从环境变量配置讲到安装后的功能验证最后附上我实际踩过的坑和排查思路。无论你是刚接触开源EDA的学生还是想给私活项目搭一套免费FPGA工具链的工程师看完这篇应该都能把环境搞定并且能确认它真的能干活。先说明一下我本身是Linux重度使用者平时做FPGA验证也是在这套开源工具链上跑所以下文里很多经验是从日常使用中沉淀下来的。如果你只是临时想跑个Demo可以直接跳到对应的平台安装部分如果你打算长期把这套工具用在项目里建议把全文看完尤其是“源码编译”和“常见问题”这两块里面有不少常规教程不会写的东西。2. 安装前的准备与方案选型先搞明白四条路怎么选我见过不少人一上来就git clone然后make结果编到一半缺东缺西最后整个下午都耗在装依赖上。其实Yosys的安装方式有好几条路每条路的适用场景不一样选对了能省很多事。2.1 各有优劣的四种安装方式安装方式适用平台优点缺点推荐指数系统包管理器apt/brewUbuntu/Debian、macOS安装快、自动处理依赖版本通常比较旧部分新命令缺失★★★☆OSS CAD Suite预编译包Windows/Linux/macOS开箱即用、工具齐全、免编译体积大、二进制包需到GitHub下载★★★★★源码编译全平台版本最新、可定制编译选项依赖多、耗时长、新手容易卡住★★★★Docker容器全平台环境隔离、一次配置到处跑需要熟悉Docker、GUI场景麻烦★★★☆我实际用得最多的是OSS CAD Suite和源码编译。如果你是Windows用户强烈建议直接用OSS CAD Suite这可以说是目前Windows上玩开源FPGA的最省心方案。如果你在Linux上做开发并且系统是Ubuntu 20.04以上的源码编译其实也没那么难而且能拿到最新版本。至于Docker适合要复现别人实验或者多人协作统一环境的场景个人日常用反而有点绕。2.2 安装前必须确认的几件事在动手之前先花两分钟确认自己的环境避免后面装到一半才发现问题。第一确认你的系统架构。Yosys官方预编译包和Docker镜像都分amd64和arm64Apple SiliconM1/M2/M3系列要选arm64版本别选错了。如果是老一点的Intel Mac那就还是amd64。第二确认磁盘空间。源码编译需要至少2GB的临时空间OSS CAD Suite解压后大约3GB。有些人的根分区就剩一两个G编译到一半报No space left on device那体验可太酸爽了。第三如果网络环境不太理想GitHub下载大文件可能会很慢。OSS CAD Suite的压缩包通常在200MB到400MB之间如果网速不乐观可以考虑用镜像站点或者让同事帮忙下载后内网传给你。这一步我经历过太多次下载工具本身比安装还费时间。2.3 为什么我不建议只靠系统包管理器Ubuntu用户跑sudo apt install yosys确实很快装上就能用玩个小Demo完全没问题。但要注意Ubuntu仓库里的Yosys版本通常滞后官方好几个大版本。比如官方已经出到0.40了apt源里可能还停留在0.30左右。每次新版本都会增加一些命令和修复一堆Bug尤其是跟nextpnr配合时新旧版本之间的兼容性差异可能会让你在排查问题时走很多弯路。我之前帮朋友调试一个问题他用的apt版Yosys不支持某个新命令我还以为是脚本写错了折腾了一个多小时才发现是版本太旧。从此以后只要是打算正式用的机器我都会优先上源码编译或OSS CAD Suite。如果你只是好奇想看看Yosys长什么样那apt装一个也无妨但看完最好还是卸了装正式的。3. 实操各平台的详细安装步骤这里我不废话直接按平台给出可复现的安装命令和步骤。你在自己电脑上操作时如果碰到输出跟我不一样的报错先别慌跳到第5节查一下常见问题那里应该能找到答案。3.1 Ubuntu / Debian 系列源码编译安装源码编译这部分我以Ubuntu 22.04 LTS为例其他Debian系版本大同小异。第一步安装依赖。Yosys的编译依赖比较多我建议直接一次性装上sudo apt update sudo apt install build-essential clang bison flex \ libreadline-dev gawk tcl-dev libffi-dev git \ graphviz xdot pkg-config python3 python3-setuptools \ libboost-system-dev libboost-python-dev libboost-filesystem-dev \ zlib1g-dev这里面bison和flex是生成语法分析器必需的libreadline-dev提供交互式命令行支持tcl-dev用于Tcl脚本接口libffi-dev和libboost系列则关系到Python绑定的编译。我第一次装的时候漏了libreadline-dev结果编译能过但yosys进去之后命令行编辑功能是坏的方向键都没反应非常难受。第二步克隆源码并编译git clone https://github.com/YosysHQ/yosys.git cd yosys make -j$(nproc) sudo make install-j$(nproc)是让make用你CPU的所有核心并行编译可以大幅缩短时间。我这边8核16线程的机器全量编译大概四五分钟。如果你的机器比较老或者用的是虚拟机建议把核心数调低一点比如make -j4否则内存不够会直接OOM。第三步确认安装结果yosys -V如果输出类似Yosys 0.40 (git sha1 1234567, clang 14.0.0-1ubuntu1)这样的信息说明安装成功。这里有个细节默认安装路径是/usr/local/bin如果你的PATH里没有这个目录需要手动加一下echo export PATH$PATH:/usr/local/bin ~/.bashrc source ~/.bashrc3.2 Windows一步到位的OSS CAD Suite方案Windows用户不要自己去源码编译太折腾了。直接下载OSS CAD Suite这是Yosys官方团队维护的预编译工具集里面除了Yosys还有nextpnr、开源的FPGA厂商工具链比如Lattice iCE40、ECP5的装一个等于把整套开源FPGA工具链都备齐了。下载地址在GitHub的YosysHQ/oss-cad-suite-buildReleases页面。选择oss-cad-suite-windows-x64_日期.exe那个文件下载后双击解压到某个目录比如C:\oss-cad-suite。注意解压路径最好不要有中文和空格有些工具对路径空格处理得不好很容易出现莫名其妙的报错。解压完成后打开终端CMD或者PowerShell都行进入解压目录运行environment.bat这个批处理脚本会把所有工具的路径设置到当前会话的环境变量里。之后你在同一个终端窗口里输入yosys -V能正常输出版本号就说明OK了。这里有个很容易踩的坑environment.bat只对当前终端窗口生效你新开一个终端窗口又要重新运行一次。如果你不想每次都手动执行可以在系统环境变量PATH里手动添加C:\oss-cad-suite\bin和C:\oss-cad-suite\lib这两个路径一劳永逸。3.3 macOSHomebrew一键安装与源码编译两条线macOS用户最简单的方式是Homebrewbrew install yosys装完同样用yosys -V验证。如果brew源里版本不更新或者你想用最新版可以在官方GitHub仓库看是否有为macOS提供的预编译包。Apple Silicon的机器记得选arm64的包Intel选x86_64。源码编译在macOS上也是一样的套路先装依赖brew install bison flex readline tcl-tk libffi boost python3然后克隆编译跟Linux的命令一样git clone https://github.com/YosysHQ/yosys.git cd yosys make -j$(sysctl -n hw.ncpu) sudo make installmacOS上编译经常碰到的一个问题是readline库找不到这个通常是因为Homebrew没有把它的路径暴露给编译器。解决办法是在编译前设置一下环境变量export CPPFLAGS-I/opt/homebrew/opt/readline/include export LDFLAGS-L/opt/homebrew/opt/readline/libApple Silicon上用Homebrew路径一般是/opt/homebrewIntel的是/usr/local根据实际情况替换。3.4 Docker一条命令拉起干净的Yosys环境Docker方式适合想快速体验或者不想在自己系统里装一堆依赖的情况。Yosys官方在Docker Hub上有镜像docker pull yosyshq/yosys然后在你的工作目录下运行容器把当前目录挂载进去docker run --rm -it -v $(pwd):/work -w /work yosyshq/yosys这样你就在容器里有了一个随时可用的Yosys环境宿主机的Verilog文件也能通过挂载目录访问。容器里跑yosys -V验证一下确认OK后就能正常使用了。这个方式的最大优点是不污染宿主机适合我只是临时想跑一个综合脚本不想动自己环境的情况。缺点也很明显如果涉及GUI查看原理图show命令Docker里需要额外配置X11转发比较麻烦所以日常我有图形需求时还是会用原生安装。4. 安装后必做的功能验证与配套工具链看到这里你的Yosys应该已经装上了但装好不等于能用好。我建议你不要急着跑大项目先花十分钟做一次完整的“健康检查”确认工具链各个部件都正常再开始正式使用。4.1 写个最小Verilog文件验证综合流程新建一个测试文件counter.vmodule counter(input clk, input rst_n, output reg [3:0] q); always (posedge clk or negedge rst_n) begin if (!rst_n) q 4b0; else q q 1b1; end endmodule这个模块就是一个简单的4位计数器异步复位很适合用来验证综合流程。在终端先进入到文件所在目录然后启动YosysyosysYosys会进入一个交互式命令行提示符是yosys。逐行输入以下命令read_verilog counter.v hierarchy -check -top counter proc; opt techmap; opt abc -g AND,NAND,OR,NOR,XOR,XNOR,NOT,BUF opt stat write_verilog synth_out.v exit我来解释一下每条命令的作用。read_verilog是把Verilog文件读进内存hierarchy用来检查模块层级并指定顶层模块proc是把always块转换成触发器DFF和组合逻辑的标准形式opt做逻辑优化techmap把通用逻辑映射到工艺相关的单元比如LUT、FFabc是伯克利大学的逻辑综合工具这里指定它只能使用基本逻辑门进行布尔化简。最后的stat会输出综合后的逻辑单元统计信息这是我们判断综合是否正常完成的重要指标。如果一切正常stat会显示出类似“Number of cells: 4”这样的信息write_verilog会生成综合后的网表文件synth_out.v。打开这个文件看一下你会看到原来的always块变成了具体的触发器和门级逻辑这对理解综合的实质非常有帮助。4.2 环境变量与常用选项配置Yosys有一个用户配置文件的概念路径是~/.config/yosys/yosysrc。如果你有常用的选项可以写在这个文件里启动时自动加载。比如我的配置里就加了这么一行proc; opt这样每次启动Yosys时默认就先把这两步跑了不需要每次手敲。如果你是刚接触先不急着配这些等对流程比较熟了再自己调整。不过有一点建议如果环境中存在多个Yosys版本可以用which yosys先看一下当前调用的到底是哪个路径下的可执行文件这一点在排查问题时很重要。我之前碰到过一次yosys -V显示的版本号和which yosys指向的路径对不上就是因为PATH里有多个版本在打架。4.3 配套安装nextpnr与厂商工具链Yosys完成的是综合工作综合之后还需要布局布线PR。在开源工具链里这个角色通常由nextpnr担任。以Lattice iCE40为例安装完OSS CAD Suite就有了全套工具直接可以用nextpnr-ice40。如果是用源码编译方式装的需要额外下载构建nextpnrgit clone https://github.com/YosysHQ/nextpnr.git cd nextpnr cmake -DARCHice40 -DCMAKE_INSTALL_PREFIX/usr/local . make -j$(nproc) sudo make install当然具体的FPGA型号还需要对应的厂商工具链文件比如iCE40用的是开源的icestorm。整个开源FPGA流程配齐之后你就能实现从Verilog到比特流文件的全流程开发了。这一步在OSS CAD Suite里是免配置的也是我上面推荐它的一个重要原因——新手用源码方式把Yosys、nextpnr、icestorm三个项目分别编译配好安装过程中遇到的坑加起来可能够写一本书了。5. 常见问题与排查技巧实录这部分是干货中的干货。我从自己实际使用和帮别人排查问题的经历中整理了出现频率最高的一些坑和解决办法。5.1 编译阶段的经典报错源码编译时最常见的报错是缺头文件或者库找不到。典型的错误信息是fatal error: readline/readline.h: No such file or directory解决方案就是安装libreadline开发包。Ubuntu下sudo apt install libreadline-devmacOS下brew install readline然后设置上面说过的CPPFLAGS和LDFLAGS。还有一个我踩过的大坑是abc相关的编译失败。Yosys内部集成了ABC综合工具需要从子模块拉取代码。如果克隆时没有带--recursive参数或者网络不稳定导致子模块没拉全编译过程会在与ABC相关的文件上报错。解决办法是cd yosys git submodule update --init --recursive然后再重新make。这个问题在老旧版本的编译教程里很少被提到因为以前ABC是以外部依赖形式提供的现在改为子模块后很多人就直接懵了。5.2 运行阶段命令找不到或行为异常yosys: command not found这类问题基本都是PATH环境变量没配好。解决方法前面已经说过把安装路径下的bin目录加到PATH里即可。如果是用sudo make install装的路径通常就是/usr/local/bin这个一般已经在系统的默认PATH里了。还有一种情况是你运行yosys进入了交互式界面但输入命令时提示Unknown command。比如输入read_verilog却提示Unknown command这通常有两个原因一是版本太老不够0.9之类二是你进入的不是Yosys的交互界面而是系统自带的其他同名程序比如Cisco的Yosys不存在但确实有过yosys被其他软件占用的例子。用which yosys和yosys -V先确认调用的是谁是最快的排查方法。5.3 Windows用户最容易碰到的三个坑用OSS CAD Suite的Windows用户常见的问题有这么三类。第一类运行environment.bat后依然找不到命令。原因是每次新开终端都要重新运行一遍而且必须是在同一个终端窗口里运行。如果你设置的PATH没生效检查是否把路径加到了“用户变量”而不是“系统变量”改完之后要重启终端才能生效。第二类Yosys能启动但读文件时中文路径乱码。这个就是编码问题解决方法是把项目路径全部改成英文字母这也是我在前面强调解压路径不要有中文的原因。其实不只是Yosys很多开源工具在Windows上对中文路径的支持都不太好。第三类编译能跑但速度慢得离谱。如果你的Windows是虚拟机里的性能瓶颈在虚拟化开销上尽量把CPU核心数和内存调大一点。如果是真机但还是很慢可以看看是不是杀毒软件在实时扫描编译目录把项目目录加入白名单速度会有明显提升。5.4 与Python绑定相关的问题Yosys的Python绑定pysys在源码编译时经常出问题。如果你不需要Python API可以在编译时显式关闭make ENABLE_PYOSYS0需要的话确保系统有python3-dev或python3-devel包并且编译过程能在日志里看到Building Python bindings的字样。如果看到这个字样但是导入失败可以检查一下Python版本是否匹配Yosys官方推荐Python 3.7以上。5.5 问题排查速查表问题现象可能原因解决方案编译时报缺少readline/head缺libreadline开发库apt/brew安装对应dev包编译到ABC相关文件卡住子模块未拉取完整git submodule update --init --recursive运行yosys提示command not foundPATH未设置或未生效检查PATH重新加载shell配置输入命令报Unknown command版本过旧换用新版预编译包或源码编译最新版Windows下工具路径不对environment.bat未运行或路径有中文重新运行bat确保路径为纯英文Python绑定导入失败编译时未启用或Python版本不匹配用make ENABLE_PYOSYS0关闭或安装匹配的Python版本综合结果与预期不符约束文件未指定或写错检查组IO约束与时钟约束6. 安装完Yosys之后建议你再做这几件事如果你看到这里并且已经成功装好了环境那我得恭喜你开源数字设计的大门已经向你敞开了。最后我想根据个人经验再分享几点建议。第一把你这个装好的环境固化一下。如果你是通过源码编译装的编译好的二进制直接放进项目目录避免以后系统升级或重装导致重新编译。我在自己机器上就把/usr/local/bin/yosys整个文件备份到了网盘出问题的时候直接拷回来就能用。第二建议安装一个配套的HDL文本编辑器。Yosys本身是命令行工具不带代码编辑功能。你还需要一个好的Verilog编辑器VS Code搭配Verilog-HDL/SystemVerilog扩展是现在比较主流的选择免费而且支持语法高亮和代码跳转对新手很友好。第三找一份系统的Yosys文档来读。官方文档在github.com/YosysHQ/yosys的docs目录下里面包含了命令参考和一些示例脚本。你不需要从头到尾读一遍但把命令参考目录过一遍知道Yosys能做什么、有哪些命令对后续学习很有帮助。第四给自己的电脑配一套完整的练习环境。光有Yosys只能做综合和验证性实验如果目标是做完整的FPGA开发最好把nextpnr和icestorm这种配套工具也一并装上。OSS CAD Suite一次性提供的整套环境在这方面确实省心。我自己的体验是Yosys这套开源工具链的成长速度非常快。刚接触时有些地方文档不完善会让人觉得难上手但这几年的版本迭代已经把很多痛点都解决了。坚持用下去你会发现它不仅能满足学习需求甚至能胜任很多实际项目的开发工作。这次分享就先写到这里接下来我还会围绕Yosys的综合脚本编写、nextpnr布局布线流程、开源FPGA工具链的完整开发实例等主题继续更新。如果你在安装过程中遇到了本文没有覆盖到的问题欢迎回头再看一遍排查部分或者带着具体的报错信息去社区搜索基本都能找到答案。装环境这个事就是这样多踩几次坑后面就顺了。