yosys: a synthesis pass library built with CMake presets

Two packaged suites, and the parsers differ between them

The recommended install is not a package manager entry. yosys ships as part of two commercial and free bundles, and the file is direct about the difference. The Tabby CAD Suite requires contacting YosysHQ for an evaluation licence and a download link. The OSS CAD Suite is free and downloaded from its GitHub releases, and both bundles contain the required dependencies and the related tools, which is why the file calls the binary suite the easiest way to use yosys. The capability gap is named in a single sentence: if you need features such as industry-grade SystemVerilog and VHDL parsers, get the Tabby evaluation licence. Many Linux distributions also package yosys binaries, with the file warning that some are more up to date than others, which makes a distribution package a reasonable but unpinned choice.

The clone is only half the checkout

Building starts with a clone that pulls in submodules:

git clone --recurse-submodules https://github.com/YosysHQ/yosys.git
cd yosys

The --recurse-submodules flag pulls in the submodules listed in .gitmodules as part of the clone. The licence position follows from the same structure. yosys itself is free software under the ISC licence, described as GPL compatible and similar in terms to MIT or the two-clause BSD licence, and the file notes that third-party software distributed alongside it is under compatible licences, with the terms in the abc and libs subdirectories. Anyone redistributing a build therefore has two sets of terms to satisfy, not one, and the file points you at the directories rather than summarising them.

Four version floors, and Ubuntu 22.04 misses one

The README gives the prerequisite libraries for Ubuntu Linux 22.04 LTS based systems as a single command:

sudo apt-get install gawk git make python3 lld bison clang flex \
    libffi-dev libfl-dev libreadline-dev pkg-config tcl-dev zlib1g-dev \
    graphviz xdot

CMake needs its own directory, and a preset file for anything lasting

Configuration uses the presets in CMakePresets.json at the repository root. The README's default build is:

cmake --preset default
cmake --build build --parallel $(nproc)

Release install is three commands and one sudo

For release builds, the README substitutes the cmake commands:

cmake --preset release
cmake --build build-rel --config Release --parallel $(nproc)

The build type comes from the release preset and the parallelism is left to the machine's processor count. The packaged binary suites exist precisely so that none of this has to be installed to use the tool.

Running the tests needs iverilog and gtest, not just the compiler

To run tests, the README points BUILD_DIR at the release build directory and runs the vanilla-test target with make in the tests directory:

export BUILD_DIR=$(realpath build-rel) && make -C tests -j"$(nproc)" vanilla-test

More detail is on the running-the-tests page on Read the Docs.

One job, three ways of driving it

The getting started section performs the same synthesis job three times, which is the fastest way to see the design. Interactively, you launch the built binary and get a yosys prompt, where help lists the commands and help with a command name prints its details. The job reads a SystemVerilog file with read -sv, sets the top with hierarchy -top, dumps the internal representation with write_rtlil, converts processes and optimises with proc; opt, displays the netlist with show, maps to gate logic with techmap; opt and writes a Verilog file with write_verilog. The same sequence becomes a script file, synth.ys, holding the read, hierarchy, proc; opt; techmap; opt and write_verilog steps, and is then run as a single argument to the binary. The README also gives a longer script for builds with ABC enabled, which maps flip-flops with dfflibmap and logic with abc against a liberty cell library such as mycells.lib.

The tree is organised around passes, front ends and back ends

The repository layout explains what the tool actually is. passes/ holds the algorithms, which the file describes as combinable through synthesis scripts, and the design goal is that any synthesis job can be assembled from them or extended by writing more against the C++ code base. frontends/ and backends/ sit either side of that, kernel/ holds the core, techlibs/ the technology libraries, and misc/ the odds and ends. Two Python-facing pieces are worth noting: pyosys/ and a pyproject.toml whose build backend is a local one at pyosys/build, depending on pybind11 and cxxheaderparser, with ruff configured for Python 3.10. The examples directory names its own targets, from hardware vendor families such as basys3, gowin, intel, igloo2 and mimas2 through cxx-api, python-api, smtbmc and aiger. ABC is a subdirectory of its own, referenced in the getting started flow and in the licence note.

Editorial conclusion

yosys fits a hardware engineer who wants to see how a design maps to gates, who wants the intermediate RTLIL rather than a vendor report, and who can assemble a job from passes in a script rather than fill in a vendor GUI. It does not fit a Windows user looking for an installer in this repository, since the platform instructions live on the hosted documentation site, and it does not fit anyone who needs industry-grade SystemVerilog or VHDL parsing without an evaluation licence. Before you build it, check two things: which of the two binary suites matches the parsers you need, and that you read the licence terms in the abc and libs subdirectories if you redistribute a build.

Frequently asked questions

Official sources

1. License: ISC
2. Project website
3. README
4. Releases
5. YosysHQ/yosys on GitHub