Installation

This document will guide you through the process of installing Yosys.

CAD suite(s)

Yosys is part of the Tabby CAD Suite and the OSS CAD Suite! The easiest way to use yosys is to install the binary software suite, which contains all required dependencies and related tools.

Make sure to get a Tabby CAD Suite Evaluation License if you need features such as industry-grade SystemVerilog and VHDL parsers!

For more information about the difference between Tabby CAD Suite and the OSS CAD Suite, please visit https://www.yosyshq.com/tabby-cad-datasheet

Many Linux distributions also provide Yosys binaries, some more up to date than others. Check with your package manager!

Targeted architectures

The OSS CAD Suite releases nightly builds for the following architectures:

  • linux-x64 - Most personal Linux based computers

  • darwin-x64 - macOS 12 or later with Intel CPU

  • darwin-arm64 - macOS 12 or later with M1/M2 CPU

  • windows-x64 - Targeted for Windows 10 and 11

  • linux-arm64 - Devices such as Raspberry Pi with 64bit OS

For more information about the targeted architectures, and the current build status, check the OSS CAD Suite git repository.

Building from source

The Yosys source files can be obtained from the YosysHQ/Yosys git repository. ABC and some of the other libraries used are included as git submodules. To clone these submodules at the same time, use e.g.:

git clone --recurse-submodules https://github.com/YosysHQ/yosys.git  # ..or..
git clone https://github.com/YosysHQ/yosys.git
cd yosys
git submodule update --init --recursive

Note

As of Yosys v0.47, releases include a yosys.tar.gz file which includes all source code and all sub-modules in a single archive. This can be used as an alternative which does not rely on git.

Supported platforms

The following platforms are supported and regularly tested:

  • Linux

  • macOS

Other platforms which may work, but instructions may not be up to date and are not regularly tested:

  • FreeBSD

  • WSL

  • Windows with (e.g.) Cygwin

Build prerequisites

A C++ compiler with C++20 support is required as well as some standard tools such as GNU Flex, GNU Bison (>=3.8), CMake (>=3.27), Make (or other CMake generator such as Ninja), and Python (>=3.11). Some additional tools: readline, libffi, Tcl and zlib; will be used if available but are optional. Graphviz and Xdot are used by the show command to display schematics.

Installing all prerequisites:

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
sudo snap install cmake --classic

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

brew tap Homebrew/bundle && brew bundle

sudo port install bison cmake flex readline gawk libffi graphviz \
   pkgconfig python311 zlib tcl

pkg install bison cmake-core flex readline gawk libffi graphviz \
   pkgconf python311 tcl-wrapper

Use the following command to install all prerequisites, or select these additional packages:

setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,cmake,make,pkg-config,python3,tcl-devel,zlib-devel

Warning

As of this writing, Cygwin only supports up to Python 3.9.16 while the minimum required version of Python is 3.11. This means that Cygwin is not compatible with many of the Python-based frontends. While this does not currently prevent Yosys itself from working, no guarantees are made for continued support. You may also need to specify CXXSTD=gnu++20 to resolve missing strdup function when using gcc. It is instead recommended to use Windows Subsystem for Linux (WSL) and follow the instructions for Ubuntu.

Build configuration

The Yosys build is configured via CMake, and uses a number of variables which influence the build process. When setting one-off variables, CMake provides the -D <var>=<value> command line option. For example, disabling zlib support:

cmake -B build . -DYOSYS_WITHOUT_ZLIB=ON

Warning

Yosys does not support in-tree builds. If calling cmake from the root yosys directory the -B option must be provided.

For a more persistent configuration, we recommend creating and using a CMakeUserPresets.json file in the root yosys directory. Below is an example file which enables ccache and sets the default compiler to clang when calling cmake --preset default:

Listing 1 CMakeUserPresets.json
{
   "version": 1,
   "configurePresets": [
      {
         "name": "default",
         "binaryDir": "build",
         "generator": "Unix Makefiles",
         "cacheVariables": {
            "CMAKE_C_COMPILER": "clang",
            "CMAKE_CXX_COMPILER": "clang++",
            "YOSYS_COMPILER_LAUNCHER": "ccache"
         }
      }
   ]
}

Once generated, available build variables can be inspected and modified with ccmake or opening the generated build/CMakeCache.txt file:

ccmake build              #..or..
vi build/CMakeCache.txt

If you have clang, and (a compatible version of) ld.lld available in PATH, it’s recommended to speed up incremental builds with lld by enabling LTO with CMAKE_INTERPROCEDURAL_OPTIMIZATION=ON. On macOS, LTO requires using clang from homebrew rather than clang from xcode. For example:

cmake -B build . -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
   -DCMAKE_C_COMPILER=$(brew --prefix)/opt/llvm/bin/clang \
   -DCMAKE_CXX_COMPILER=$(brew --prefix)/opt/llvm/bin/clang++

By default, building (and installing) Yosys will build (and install) ABC, using yosys-abc as the executable name. To use an existing ABC executable instead, set the YOSYS_ABC_EXECUTABLE CMake variable to point to the desired executable.

Running the build system

To quickly install Yosys with default settings, call the following commands from the root yosys directory:

cmake -B build . -DCMAKE_BUILD_TYPE=Release --fresh
cmake --build build --config Release --parallel $(nproc)
sudo cmake --install build --strip

To use an existing configuration, use the --build option, e.g:

cmake -B build .
ccmake build              # modify configuration
cmake --build build

See also

Refer to Testing Yosys for details on testing Yosys once compiled.

Source tree and build system

The Yosys source tree is organized into the following top-level directories:

backends/

This directory contains a subdirectory for each of the backend modules.

cmake/

Additional .cmake files used by CMake during build generation.

docs/

Contains the source for this documentation, including images and sample code.

examples/

Contains example code for using Yosys with some other tools including a demo of the Yosys Python api, and synthesizing for various toolchains such as Intel and Anlogic.

frontends/

This directory contains a subdirectory for each of the frontend modules.

kernel/

This directory contains all the core functionality of Yosys. This includes the functions and definitions for working with the RTLIL data structures (rtlil.h|cc), the main() function (driver.cc), the internal framework for generating log messages (log.h|cc), the internal framework for registering and calling passes (register.h|cc), some core commands that are not really passes (select.cc, show.cc, …) and a couple of other small utility libraries.

libs/

Libraries packaged with Yosys builds are contained in this folder. See Auxiliary libraries.

misc/

Other miscellany which doesn’t fit anywhere else.

passes/

This directory contains a subdirectory for each pass or group of passes. For example as of this writing the directory passes/hierarchy/ contains the code for three passes: hierarchy, submod, and uniquify.

pyosys/

Contains the scripts and wrappers necessary for building Pyosys.

techlibs/

This directory contains simulation models and standard implementations for the cells from the internal cell library.

tests/

This directory contains the suite of unit tests and regression tests used by Yosys. See Testing Yosys.