1. 为什么大家都要自己编译 Yosys接触数字 IC 设计或 FPGA 开源工具链的朋友对 Yosys 这个名字应该都不陌生。作为目前最流行的开源 Verilog 综合工具它能把 Verilog-2005 和部分 SystemVerilog 代码综合成门级网表配合 nextpnr、IceStorm 这类开源布线工具或者直接输出 BLIF、Verilog 网表供其他工具使用已经成了开源硬件流程里绕不开的一环。但 Yosys 的安装确实有点尴尬。你直接apt install yosys装出来的版本大概率是两年甚至更早之前的旧版本。对于想跑新语法、新架构支持或者需要配合新版 nextpnr 使用的场景这个太旧的版本就成了瓶颈。我自己第一次折腾的时候就遇到了综合某个用了较新 SystemVerilog 语法的模块直接报语法错误的情况后来排查了半天发现就是系统源里那个 Yosys 版本太老根本不认识这个语法。所以自己从源码编译 Yosys对认真玩开源流程的人来说基本上是绕不过去的一步。这篇文章把我从零开始编译 Yosys 的完整过程、遇到的坑、排查的方法都整理出来了。不管你是想在 Ubuntu、CentOS、macOS 上装还是想用现成的二进制包快速搞定或者非要在 Windows 上跑都有对应的方案。内容适合三类读者刚接触开源 EDA 工具链的学生、需要在服务器上部署 Yosys 的工程师、以及想搞清楚编译过程中那些报错到底是怎么回事的好奇派。2. Yosys 能做什么以及不同安装方式怎么选2.1 先用 30 秒搞懂 Yosys 在流程中的位置在进入安装步骤之前先花几句话把 Yosys 的定位说清楚。一个典型的 FPGA 开源设计流程是写 Verilog 代码 - Yosys 完成综合RTL 到门级网表- nextpnr 完成布局布线 - 生成比特流。Yosys 处于最前端的综合环节它的主要工作是把可综合的 RTL 代码转换成由查找表LUT、触发器FF、DSP 块等基本单元组成的网表。这个工具最大的特点就是开放。内部的综合过程被拆成了几十个 pass你可以像流水线一样把不同的 pass 串起来自定义综合策略。这一点和商用工具的黑盒工作方式差别很大也是很多人在学习阶段用 Yosys 来理解综合原理的原因。2.2 三种安装路径按场景选Yosys 的安装方式主要有三种我先把它们适用的场景和优缺点列出来再逐个讲具体的操作。安装方式适用场景优点缺点包管理器安装快速体验、学习入门、对版本不敏感快一条命令搞定版本通常较旧官方发布 Release 源码编译正式项目、需要稳定版本、配合工具链使用版本较新可控性强需要处理编译依赖Git 主干源码编译尝鲜新特性、开发调试 Yosys 本身功能最全可能不稳定依赖变化快我个人的建议是如果只是上课作业或者快速跑通流程用系统包管理器装一个就够用如果是要配合开源 FPGA 工具链做实际项目优先选择官方 Release 源码编译如果你已经准备给 Yosys 提交 bug report 或者想玩里面的新功能那就直接上 Git 主干。下面重点讲最常用也最有价值的源码编译方式。3. 环境准备编译 Yosys 前必须踩平的坑3.1 依赖关系全景图编译 Yosys 不是一个 ./configure 就能从头跑到尾的项目它对系统的工具链和库有明确要求。第一次编译如果缺依赖报错信息千奇百怪很容易把人搞蒙。我帮大家把依赖分成三类逐个说明。第一类是基础编译工具链包括 gcc、g版本要求 4.8 以上实测 GCC 8 到 13 都正常、make、git。这些没有的话编译任何源码都是空谈。第二类是 Yosys 的核心依赖库包括 bison、flex用于生成语法解析器、libreadline-dev用于交互式命令行、libffi-dev用于加载共享库、pkg-config、libtcl-devTcl 接口支持、python3-devPython 模块支持。第三类是可选的工具和库包括 libboost-dev部分功能加速、libeigen3-dev某些优化 pass 用、qt5-qmake 和 libqt5-dev用于编译图形界面 yosys-svgviewer 等、libgsl-dev某些统计优化功能。提示千万不要因为嫌麻烦就跳过 bison 和 flex。Yosys 的 Verilog 语法解析器是基于这两个工具生成的缺了它们编译进度跑到一半就会在 frontends/verilog 目录直接报错停止。3.2 Ubuntu/Debian 系统依赖安装在 Ubuntu 20.04 或更新版本的 Ubuntu 上安装依赖比较简单。我个人测试过的组合是 Ubuntu 22.04 GCC 11编译 Yosys 0.33 完全没问题。下面这条命令把核心依赖一次装齐sudo apt update sudo apt install build-essential clang bison flex \ libreadline-dev libffi-dev git \ tcl-dev libtcl-dev python3 pkg-config \ libboost-dev libeigen3-dev如果你想编译带 GUI 工具的版本再补一条sudo apt install qt5-qmake qtbase5-dev libqt5svg5-dev这里有个小细节build-essential包含了 gcc 和 make但有些精简版系统镜像可能连这个包都没有所以单独列出来。另外Ubuntu 20.04 上如果系统自带的是 GCC 9也不会有问题Ubuntu 18.04 建议先确认一下 GCC 版本是否在 4.8 以上太老的话先升级编译器。3.3 CentOS/RHEL 系统的依赖安装CentOS 7 和 CentOS 8 情况有点不一样。CentOS 8 自带的是 GCC 8可以直接装依赖sudo dnf install gcc gcc-c make git bison flex \ readline-devel libffi-devel tcl-devel \ python3-devel pkgconfig boost-develCentOS 7 默认的 GCC 4.8.5 虽然理论上够用但编出来的 Yosys 在链接时偶尔会有一些小问题。如果遇到诡异的问题建议用scl工具集或者直接从源码装一个 GCC 8 来编译。还要注意 CentOS 上包名带-devel和 Ubuntu 上的-dev后缀不同。这是两大家族的习惯差异用 apt 思路去装 dnf 包会找不到名字。3.4 在 Windows 上怎么装两条现实路径很多朋友用的是 Windows 机器Yosys 官方其实不直接支持 Windows 原生编译。历史上想在 Windows 上用 Yosys只有两条路装虚拟机或者用 WSL。第一个方案是使用 WSL2 安装 Ubuntu然后在里面按照上面的步骤操作。这个方法最接近原生 Linux 环境兼容性最好。我自己在 Windows 11 WSL2 的 Ubuntu 22.04 里编译过整个过程和在真实 Ubuntu 机器上没区别。第二个方案是使用安装包管理器 MSYS2。在 MSYS2 的终端里可以这样装pacman -S mingw-w64-x86_64-yosys这个包里带了编译好的二进制不用自己折腾依赖。不过 MSYS2 里的 Yosys 版本更新会滞后于官方 Release而且某些和 Qt 相关的辅助工具可能没有打包进去。对于只是临时用一下的场景MSYS2 是省时省力的选择。注意WSL2 里编译 Yosys文件读写性能比原生 Linux 慢一些尤其在大规模综合时。建议把源码放在 WSL2 的 ext4 文件系统内即~/yosys等路径不要放在/mnt/c/下的 Windows 目录里否则编译时间能差出两到三倍。3.5 macOS 上的依赖准备macOS 上主要靠 Homebrew 补齐依赖。先确保装了 Xcode Command Line Toolsxcode-select --install然后用 brew 安装依赖brew install bison flex readline libffi pkg-config \ tcl-tk python3 boost eigen经验macOS 上 bison 的版本比较关键。系统自带的 bison 是 2.3很老Yosys 需要 bison 3.0 以上。用 brew 装的 bison 路径通常在/opt/homebrew/opt/bison/binApple Silicon或/usr/local/opt/bison/binIntel需要在 PATH 中把它放到前面。export PATH/opt/homebrew/opt/bison/bin:$PATH然后在编译 Yosys 前还要告诉 make 去哪里找 bison 和 flexexport BISON/opt/homebrew/opt/bison/bin/bison export FLEX/opt/homebrew/opt/flex/bin/flex如果我们用的是 Intel Mac把前面的路径换成/usr/local/opt就对了。这一步忘了设置的话编译时会出现bison: command not found或者版本不对导致的解析错误。4. 源码编译全流程从下载到验证4.1 获取源码下载 Release 包还是直接 Git Clone现在到了核心环节。获取源码有两种方式。如果你要用稳定版本就去 GitHub 的 Yosys Releases 页面找一个带 tag 的版本然后下载 tar.gz 压缩包。以 0.38 版本为例wget https://github.com/YosysHQ/yosys/archive/refs/tags/yosys-0.38.tar.gz tar -zxvf yosys-0.38.tar.gz cd yosys-yosys-0.38如果你想直接使用最新开发版就 clone 仓库git clone https://github.com/YosysHQ/yosys.git cd yosys提示追求稳定项目使用建议用 Release 版本。Git 主干上的代码通常和 Release 相差几千个提交语法支持更全但综合结果偶尔会有行为变化不适合直接用于依赖明确结果的项目。4.2 最简单的三步编译法Yosys 的 Makefile 写得很直观门槛其实不高三步就能跑通make config-gcc make -j$(nproc) sudo make install第一步的config-gcc是选择一个编译配置。Yosys 的 Makefile 里预置了好几个配置模板config-gcc是基于 GCC 的默认配置还有config-clang用 clang 编译、config-msvcWindows 上用 MSVC 编译不推荐等。执行完make config-gcc后项目目录下会生成一个Makefile.conf文件里面是当前编译配置的具体内容。如果你不想修改默认配置直接往下走就行。第二步的-j$(nproc)表示用机器上所有的 CPU 核心并行编译。Yosys 的源码量不小全量编译在 8 核的机器上大概需要五到八分钟在 4 核机器上可能要十五分钟以上。编译过程中终端会刷屏看到类似g ... -o yosys的输出就说明在正常推进。第三步的sudo make install会把编译产物装到/usr/local/bin下同时把一些共享库放到/usr/local/lib。这一步需要 root 权限。装完以后先验证一下yosys -V如果看到类似Yosys 0.38 (git sha1 ...)的输出恭喜基本安装成功了。4.3 静态编译还是动态编译这里有个细节值得说道一下。Yosys 编译默认是动态链接的模式也就是生成的二进制依赖系统里的共享库。如果你手动设置了自定义的 Tcl 库路径或者其他的特殊配置编译出来的 Yosys 换到另一台机器上就可能出现error while loading shared libraries的报错。解决这个问题有两条路。第一条是把自己编译时用的库路径写入二进制。编译时增加环境变量export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH或者使用静态链接方式。Yosys 的 Makefile 里提供了一个make static目标把 ABC、Tcl 等都静态编进去这样生成的是一个完全独立的二进制make clean make config-gcc make static -j$(nproc) sudo make installmake static和make的差别在于它会尝试把各种依赖库以静态方式链接进来。编译时间会长一些生成的yosys二进制也会大不少可能到几十 MB但好处是拷到别的相同架构 Linux 机器上能直接运行。注意静态编译时如果系统缺少静态库文件比如libtclstub.a需要额外安装对应的-static版本依赖包。Ubuntu 上是sudo apt install libtcl8.6-dev自带的静态库通常够用但如果遇到 libffi 或 readline 静态库缺失就得补装libffi-dev里的.a文件或手动下载。4.4 自定义安装路径避免污染系统很多人不喜欢把工具装到/usr/local特别是服务器上有模块管理环境时这样包体稀疏。Yosys 支持自定义PREFIXmake config-gcc make PREFIX$HOME/tools/yosys -j$(nproc) make PREFIX$HOME/tools/yosys install然后再把$HOME/tools/yosys/bin添加到 PATHexport PATH$HOME/tools/yosys/bin:$PATH这个方式的好处是卸载的时候直接删目录就行不会留下一堆散落在系统目录里的文件。对于把 Yosys 当作项目工具链一部分来管理的场景强烈推荐这种方式。它和 Conda 的管理思路类似自成一套目录互不干扰。5. 编译过程中的常见报错与解决方案5.1bison: command not found或 bison 版本报错这是新手编译 Yosys 时遇到最多的问题。编译到frontends/verilog目录时如果系统没装 bison 或者 bison 版本太老macOS 系统自带的特别容易踩坑就会出现类似下面的报错。/bin/sh: 1: bison: not found在 Ubuntu 上直接执行sudo apt install bison在 macOS 上需要指定 bison 路径开头已经说过这里不再重复。关键是检查版本bison --version应该输出 3.0 以上。5.2readline.h: No such file or directory这个报错说明系统里缺了 readline 的开发头文件。Yosys 的交互式命令行依赖这个库没有头文件编译会失败。Ubuntu/Debian 执行sudo apt install libreadline-devCentOS/RHEL 执行sudo dnf install readline-devel5.3 链接阶段libtcl.so找不到这个问题的典型表现是编译基本能跑过但最后一步链接时报类似下面的错。/usr/bin/ld: cannot find -ltclYosys 的 Tcl 接口需要链接 Tcl 库。Ubuntu 上需要装tcl-dev或者libtcl-devsudo apt install tcl-dev装完以后再跑一次 make链接就能通过了。CentOS 上要装tcl-devel。5.4 缺少 Python 绑定相关报错Yosys 从较新版本开始支持 Python 模块调用通过 pybind11如果缺少相关依赖编译时会有类似下面的提示ERROR: Python bindings requested but Python library not found大多数情况下我们不一定要 Python 绑定功能可以通过配置关闭。在Makefile.conf里查找和 Python 相关的选项或者执行make config-gcc然后在Makefile.conf中把ENABLE_PYTHON相关的行注释掉或改为 0再重新编译。如果你确实需要 Python 接口需要安装python3-dev并确保python3-config在 PATH 中。5.5 make 进度卡在 ABC 编译不出结果ABC 是 Yosys 内部集成的逻辑综合与优化工具编译过程中它会被作为子模块一起构建。Compiling ABC 这一步涉及的代码量很大如果电脑内存不足比如在 4GB RAM 的虚拟机里编译有时会出现编译器被杀死的现象也就是 OOM内存耗尽。解决办法有几个减小并行度用make -j2代替make -j$(nproc)或者给虚拟机分配更多内存再或者先编译其他部分把ABC相关目标单独编译。ABC 编译的时间通常占整体的一多半很多朋友第一次编译时以为是卡死了其实它在正常编译需要一点耐心。5.6 升级 Yosys 时直接增量编译出错如果你之前在源码目录编译过旧版本后来用git pull拉取了新代码再编译有概率会遇到奇怪的编译错误。这是因为增量编译的依赖跟踪不完整部分遗留的旧生成文件会和新代码冲突。这个时候不要死磕执行make clean make config-gcc make -j$(nproc) sudo make installmake clean会清空所有编译中间文件虽然要重新编译整个项目但通常能解决绝大多数升级后编译出错的问题。经验就是升级 Yosys 时不跑 clean就等于给自己埋雷。6. 快速验证安装是否正常6.1 版本检查与自检安装完成后第一个要做的就是验证版本yosys -V正常输出类似Yosys 0.38 (git sha1 1234567, gcc 11.4.0 -fPIC -Os)。注意看后面有没有-fPIC之类的编译参数有时这些参数对后续加载插件有影响。Yosys 还内置了一个自检命令yosys -Q它会跑一遍内置的测试用例输出类似Tests passed的结果。这个过程可能需要几分钟但它能全面验证二进制是否正常建议第一次安装完都跑一遍。6.2 用最小 Verilog 文件实测综合流程只检查版本还不够真正能说明问题的是跑一个简单的综合流程。创建一个test.v文件module top(input a, b, c, output y); assign y (a b) | c; endmodule然后执行yosys -p read_verilog test.v; synth; stat其中read_verilog读取文件synth执行默认综合流程stat输出统计信息。如果综合成功终端会打印出逻辑单元统计Number of cells: ...看到这个结果说明 Yosys 已经能正确读取和综合 Verilog 代码。6.3 检查 ABC 是否有独立可执行文件Yosys 在综合过程中会调用 ABC 做逻辑优化。如果你用的发行版把yosys-abc作为独立二进制它在$PREFIX/bin下面。检查一下which yosys-abc yosys-abc -h如果不显示路径或者报错也不要慌。新版本 Yosys 默认把 ABC 编译成了共享库的方式在yosys进程内部调用。只要yosys -p read_verilog test.v; synth能跑通就说明综合链路没问题。6.4 Windows WSL 环境验证的额外注意点在 WSL2 环境里验证时除了上述三个步骤还要注意Yosys运行时的临时目录权限。如果你在/mnt/c下的 Windows 目录里运行 Yosys遇到奇怪的读写权限问题把工作目录切到 WSL 内部的 Linux 文件系统再试很多问题会迎刃而解。7. 一些值得记住的经验之谈7.1 Yosys 的版本选择和上游工具链的配合Yosys 的版本直接影响它和 nextpnr 等下游工具的兼容性。某些版本的 Yosys 综合出的网表格式或生成的属性需要特定版本的 nextpnr 才能正确解析。所以确定项目使用的工具链版本组合比追求单个工具的最新版更重要。我目前比较稳的组合是 Yosys 0.38 nextpnr 0.5 系列。如果你的项目里用了较新的 FPGA 芯片型号确认一下它们在这个组合下有没有布局布线支持。7.2 第三方 Verilog 前端 yosys-slangYosys 自带的 Verilog 前端frontends/verilog对 SystemVerilog 的支持一直比较有限。如果你需要更好的 SystemVerilog 解析能力官方在较新版本里已经集成了 yosys-slang 作为独立的前端模块。在编译 Yosys 时使用ENABLE_SLANG相关配置启用就可以了这部分功能对应的依赖会拉取 Slang 库。如果你平时主要写的是普通可综合的 Verilog自带的解析器已经完全够用但如果项目里用了大量interface、struct、enum等 SystemVerilog 语法调研一下 slang 前端是非常值得的。7.3 环境变量的问题Yosys 运行时依赖一些环境变量影响插件搜索路径。默认情况下它会在$PREFIX/share/yosys/下寻找内置脚本和技术映射库。如果你用自定义 PREFIX 安装但忘了把这个路径加入环境变量有的功能可能运行正常但某些技术映射库找不到综合时直接报错说缺少某个.lib文件。解决办法有两个安装时确保把share目录装上运行前设置export YOSYS_DATDIR$HOME/tools/yosys/share/yosys严格来说YOSYS_DATDIR这个环境变量是 Yosys 加载数据文件时的重要参考。在交叉安装或者打包分发场景下这个变量特别关键。7.4 别忽略 Licenses 和 EasyLogYosys 本身是开源的但它在编译 ABC 时会从上游拉取部分代码。如果你们公司对 License 有严格审查确认一下 ABC 的许可证和你的使用场景是否匹配。另外 Yosys 支持一个叫EasyLog的功能可以导出综合过程的 JSON 日志这在做脚本自动化或者想精细分析综合结果时很有用它的分析方式能帮你把握综合中的资源占用情况。8. 装完只是开始用它跑通一个完整的最小流程安装 Yosys 是为了干活光验证synth; stat能通过还差得很远。这里用一个最小项目把完整开源流程串起来帮大家确认整个工具链是否通畅。假设我们要在 iCE40UP5K 芯片上跑一个点亮 LED 的小模块。除了 Yosys还需要 nextpnr-ice40 和 IceStorm 工具icepack、iceprog等。综合命令yosys -p synth_ice40 -blif example.blif -top top test.v布局布线命令nextpnr-ice40 --hx8k --json example.json --pcf example.pcf --asc example.asc生成比特流icepack example.asc example.bin这三步都成功说明 Yosys 安装正确并且和下游工具衔接正常。如果在这一步发现synth_ice40命令不存在回到 Yosys 源码目录检查是不是有某些特性的synth_*流程没有编译进去或者 Yosys 版本是不是太老不支持这个目标芯片。这个流程对 FPGA 开发很有价值因为很多装完 Yosys 的人能在yosys -V这一步通过后信心满满地开始综合实际工程结果发现芯片对应的综合命令根本不存在或者映射库路径错误。用一次最小流程提前把这些坑踩完后面才能真正顺利。9. 我的实际体验和最终建议从我自己的使用经历来看Yosys 的安装并不是一个高难度的任务难点在于不同环境下依赖的不确定性和版本兼容问题。国内网络环境下GitHub 访问可能出现各种状况如果git clone太慢可以用一些镜像加速方式或者直接下载 Release 的 tar.gz 包而不是 clone 整个仓库——注意这是建议涉及到具体网络工具需要大家根据自己的实际环境选择合适方式。最后总结几个关键经验第一优先根据项目需求确定 Yosys 版本然后用 Release 源码编译不要盲目追新第二编译环境的依赖尽量一次装齐尤其是 bison 和 flex 这类容易忽略的小工具第三遇到诡异报错时先make clean再重编比漫无目的地搜索错误信息高效得多第四版本检查、自检、最小综合流程这三步验证一个都别省。希望这篇教程能帮大家少折腾几个小时。按照上面的步骤走你大概率能在半小时内拿到一个完全可用、版本明确的 Yosys 工具链。装好了之后下一步就放心大胆地去综合你的第一个 Verilog 工程吧。