How to Compile

Note

We recommend you to watch a tutorial video about how-to-compile before getting started

Supported Operating Systems

OpenFPGA is continously tested on

  • Windows 2025 server (compatible to Windows 10 and Windows 11)

  • Ubuntu 22.04

  • Ubuntu 24.04

  • CentOS 9

It might work with earlier versions and other distributions.

In addition to continous integration, our community users have tested OpenFPGA on their local machines using the following operating systems:

  • CentOS 7.8

  • CentOS 7.9

  • CentOS 8

  • Redhat 8

  • Ubuntu 18.04

  • Ubuntu 21.04

  • Ubuntu 20.04

Build Steps

OpenFPGA uses CMake to generate the Makefile scripts. In general, please follow the steps to compile

git clone https://github.com/LNIS-Projects/OpenFPGA.git
cd OpenFPGA
make all

Note

OpenFPGA requires gcc/g++ version >= 11 or clang version >= 17 or MSVC version >= 14.

Note

cmake3.12+ is recommended to compile OpenFPGA with GUI

Note

Recommend using make -j<int> to accelerate the compilation, where <int> denotes the number of cores to be used in compilation.

Note

VPR’s GUI requires gtk-3, and can be enabled with make .. CMAKE_FLAGS="-DVPR_USE_EZGL=on"

Quick Compilation Verification

Note

Ensure that you install python dependences in Dependencies.

To quickly verify the tool is well compiled, users can run the following command from OpenFPGA root repository

python3 openfpga_flow/scripts/run_fpga_task.py compilation_verification --debug --show_thread_logs

If you would like to create an installer, you may run

# Refer to build options for installer customization
make installer

Build Options

General build targets are available in the top-level makefile. Call help desk to see details

make help

The following options are available for a custom build

BUILD_TYPE=<string>

Specify the type of build. Can be either release or debug. By default, release mode is selected (full optimization on runtime)

PACK_INSTALLER=[ON|OFF]

Specify if the installer packages should be included when compiling. When enabled, installer packaging will be enabled in CPack format. Use make installer to create the final package.

INSTALL_DOC=[ON|OFF]

Specify if the installer packages should include the documentation. By default, it is ON. Ensure that you have build the doc locally before creating the installer

INSTALLER_TYPE=[STGZ|DEB|IFW]

Specify type of installer. By default, it is STGZ. If you prefer an installer with graphical user interface, please choose IFW.

CMAKE_FLAGS=<string>

Force build flags to CMake. The following flags are available

  • DOPENFPGA_WITH_TEST=[ON|OFF]: Enable/Disable the test build

  • DOPENFPGA_WITH_YOSYS=[ON|OFF]: Enable/Disable the build of yosys. Note that when disabled, the build of yosys-plugin is also disabled

  • DOPENFPGA_WITH_SLANG=[ON|OFF]: Enable/Disable the build of yosys-plugin Slang. If disabled, system verilog will not be supported. By default, it is enabled.

  • DOPENFPGA_WITH_VERSION=[ON|OFF]: Enable/Disable the build of version number. When disabled, version number will be displayed as an empty string.

  • DOPENFPGA_WITH_SWIG=[ON|OFF]: Enable/Disable the build of SWIG, which is required for integrating to high-level interface.

  • OPENFPGA_ENABLE_STRICT_COMPILE=[ON|OFF]: Specifies whether compiler warnings should be treated as errors (e.g. -Werror)

Warning

By default, only required modules in Verilog-to-Routing (VTR) is enabled. On other words, abc, odin, yosys and other add-ons inside VTR are not built. If you want to enable them, please look into the dedicated options of CMake scripts.

CMAKE_GOALS=<string>

Specify the build target for CMake system. For example, cmake_goals=openfpga indicates that only openfpga binary will be compiled. For a detailed list of targets, use make list_cmake_targets to show. By default, all the build targets will be included.

Dependencies

Dependencies can be installed upon the use of OpenFPGA on different systems In general, OpenFPGA requires specific versions for the following dependencies:

cmake:

version >3.12 for graphical interface

iverilog:

version 10.3+ is required to run Verilog-to-Verification flow

Ubuntu

If your OS is Ubuntu 20.04, 22.04 and 24.04, we offer unified scripts to install all the dependencies.

  • Dependencies required to build the code base

#!/usr/bin/env bash

# The package list is designed for Ubuntu 20.04 LTS
add-apt-repository -y ppa:ubuntu-toolchain-r/test
apt-get update
apt-get install -y \
    autoconf \
    automake \
    bison \
    ccache \
    cmake \
    curl \
    doxygen \
    libfl-dev \
    flex \
    fontconfig \
    gdb \
    git \
    gperf \
    iverilog \
    libc6-dev \
    libcairo2-dev \
    libevent-dev \
    libffi-dev \
    libfontconfig1-dev \
    liblist-moreutils-perl \
    libncurses5-dev \
    libreadline-dev \
    libreadline8 \
    libx11-dev \
    libxft-dev \
    libxml++2.6-dev \
    make \
    perl \
    pkg-config \
    python3 \
    python3-setuptools \
    python3-lxml \
    python3-pip \
    tcllib \
    tcl8.6-dev \
    texinfo \
    time \
    valgrind \
    wget \
    zip \
    swig \
    expect \
    libxml2-utils

# Install Ubuntu 20.04 packages
if [ "$(lsb_release -rs)" = "20.04" ]; then
    apt-get install -y \
        ctags \
        qt5-default \
        g++-7 \
        gcc-7 \
        g++-8 \
        gcc-8 \
        g++-9 \
        gcc-9 \
        g++-10 \
        gcc-10 \
        g++-11 \
        gcc-11 \
        clang-6.0 \
        clang-7 \
        clang-8 \
        clang-10 \
        clang-format-10 \
        libssl-dev
# Install Ubuntu 22.04 packages
elif [ "$(lsb_release -rs)" = "22.04" ]; then
    apt-get install -y \
        exuberant-ctags \
        qtbase5-dev \
        g++-9 \
        gcc-9 \
        g++-10 \
        gcc-10 \
        g++-11 \
        gcc-11 \
        clang-11 \
        clang-12 \
        clang-13 \
        clang-14 \
        clang-format-14
# Install Ubuntu 24.04 packages
elif [ "$(lsb_release -rs)" = "24.04" ]; then
    apt-get install -y \
        exuberant-ctags \
        qtbase5-dev \
        g++-13 \
        gcc-13 \
        clang-18 \
        clang-format-18
fi

  • Dependencies required to run regression tests

# Update as required by some packages
apt-get update
apt-get install --no-install-recommends -y \
libdatetime-perl libc6 libffi-dev libgcc1 libreadline8 libstdc++6 \
libtcl8.6 tcl python3-pip zlib1g libbz2-1.0 \
iverilog git rsync make curl wget tree

# Install Ubuntu 20.04 packages
if [ "$(lsb_release -rs)" = "20.04" ]; then
    apt-get install --no-install-recommends -y \
        python3.8 \
        python3.8-venv
# Install Ubuntu 22.04 packages
#elif [ "$(lsb_release -rs)" = "22.04" ]; then
fi

Note

Python packages are also required. If you are using Ubuntu 24.04, the required Python version is <= 3.12.3

python3 -m pip install -r requirements.txt

  • Dependencies required to build documentation

#!/usr/bin/env bash

# The package list is designed for Ubuntu 20.04 LTS
apt-get install python3-sphinx
python3 -m pip install -r docs/requirements.txt

CentOS

If your OS is CentOS 7.9, we offer the script to install all the dependencies.

# Install essential packages
yum update -y
yum install -y \
    epel-release \
    vim \
    wget \
    git \
    tar \
    unzip

yum install -y \
    gcc \
    gcc-c++ \
    make \
    cmake \
    autoconf \
    automake \
    libtool \
    flex \
    bison \
    python3 \
    python3-pip \
    tbb \
    yum-utils \
    glibc-locale-source \
    glibc-langpack-en \
    tree \
    procps \
    perl \
    gperf \
    openssl-devel \
    tcl \
    tk \
    tk-devel \
    zlib-devel \
    readline-devel

# Install required gcc version and setup
yum install -y centos-release-scl
yum install -y devtoolset-10

# FIXME: This may only work on CentOS8 or later. Consider to compile from scratch
yum install -y https://dl.fedoraproject.org/pub/epel/8/Modular/x86_64/Packages/s/swig-4.0.2-9.module_el8+12710+6335019d.x86_64.rpm
localedef -i en_US -f UTF-8 en_US.UTF-8

cd /tmp/iverilog \
    && git clone https://github.com/steveicarus/iverilog.git \
    && cd iverilog \
    && sh autoconf.sh \
    && ./configure &&  make && make install

If your OS is CentOS 9, we offer the script to install all the dependencies.

# Disable GPG checks for repositories (if needed)
sed -i 's/gpgcheck=1/gpgcheck=0/g' /etc/yum.repos.d/*.repo

# Install essential packages
dnf install -y \
    epel-release \
    vim \
    wget \
    git \
    tar \
    unzip \
    && dnf clean all

dnf install -y \
    gcc \
    gcc-c++ \
    make \
    cmake \
    autoconf \
    automake \
    libtool \
    flex \
    bison \
    python3 \
    python3-pip \
    tbb \
    yum-utils \
    glibc-locale-source \
    glibc-langpack-en \
    tree \
    procps \
    perl \
    gperf \
    openssl-devel \
    tcl \
    tk \
    tk-devel \
    zlib-devel \
    readline-devel \
        ccache \
    && dnf clean all

yum install -y https://dl.fedoraproject.org/pub/epel/8/Modular/x86_64/Packages/s/swig-4.0.2-9.module_el8+12710+6335019d.x86_64.rpm
localedef -i en_US -f UTF-8 en_US.UTF-8

mkdir -p /tmp/iverilog \
    && cd /tmp/iverilog \
    && git clone https://github.com/steveicarus/iverilog.git \
    && cd iverilog \
    && sh autoconf.sh \
    && ./configure &&  make && make install

Windows (Mingw64)

If your OS is Msys2 in Windows, we offer the script to install all the dependencies

Note

We support only MINGW64 on Msys2.

#!/usr/bin/env bash

# Build dependencies for MSYS2 (Windows)
# Converted from Ubuntu 22.04 apt-get script
# Run this script inside an MSYS2 MINGW64 shell (or UCRT64)

# Update package database
# Latest gcc-16 is not yet stable. Pacman can only install the rolling version. So comment it out
#pacman -Syu --noconfirm
#    mingw-w64-x86_64-toolchain \

# This is for code compilation
pacman -S --noconfirm --needed \
    autoconf \
    automake \
    libtool \
    bison \
    ccache \
    base-devel \
    mingw-w64-x86_64-autotools \
    mingw-w64-x86_64-cmake \
    mingw-w64-x86_64-ctags \
    curl \
    mingw-w64-x86_64-doxygen \
    flex \
    mingw-w64-x86_64-fontconfig \
    gdb \
    git \
    gperf \
    mingw-w64-x86_64-iverilog \
    mingw-w64-x86_64-cairo \
    mingw-w64-x86_64-libevent \
    mingw-w64-x86_64-libffi \
    mingw-w64-x86_64-fontconfig \
    ncurses-devel \
    mingw-w64-x86_64-readline \
    mingw-w64-x86_64-libxml2 \
    mingw-w64-x86_64-make \
    perl \
    mingw-w64-x86_64-pkg-config \
    mingw-w64-x86_64-python3 \
    mingw-w64-x86_64-python \
    mingw-w64-x86_64-python-pip \
    mingw-w64-x86_64-python-setuptools \
    mingw-w64-x86_64-flexdll \
    mingw-w64-x86_64-qt5-base \
    mingw-w64-x86_64-tcl \
    mingw-w64-x86_64-tcllib \
    texinfo \
    wget \
    zip \
    mingw-w64-x86_64-swig \
    expect \
    mingw-w64-x86_64-lld \
    mingw-w64-x86_64-clang \
    mingw-w64-x86_64-yosys \
    mingw-w64-x86_64-boost-libs \
    libreadline-devel \
    zlib-devel \
    openssl-devel \
    mingw-w64-x86_64-zlib \
    mingw-w64-x86_64-graphviz \
    mingw-w64-x86_64-qt5 \
    mingw-w64-x86_64-qt-installer-framework \
    mingw-w64-x86_64-capnproto \
    mingw-w64-x86_64-openssl

# This is for openfpga regression tests
pacman -S --noconfirm --needed \
    mingw-w64-x86_64-gtkwave \
    mingw-w64-x86_64-iverilog

## Yosys is still based on this version of gcc
## Install fixed GCC 15.0.1 tools from MSYS2 archive
#pacman -U --noconfirm \
#    https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-ccmake-3.30.2-1-any.pkg.tar.zst \
#    https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-gcc-15.2.0-14-any.pkg.tar.zst \
#    https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-gcc-ada-15.2.0-14-any.pkg.tar.zst \
#    https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-gcc-libs-15.2.0-14-any.pkg.tar.zst
#
## Prevent pacman from upgrading GCC tools beyond 15.0.1
## Add to /etc/pacman.conf IgnorePkg line if not already present
#if grep -q "^IgnorePkg" /etc/pacman.conf; then
#    sed -i 's/^IgnorePkg\s*=\s*/IgnorePkg = mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-gcc-ada mingw-w64-x86_64-gcc-libs /' /etc/pacman.conf
#else
#    echo "IgnorePkg = mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-gcc-ada mingw-w64-x86_64-gcc-libs" >> /etc/pacman.conf
#fi

Yosys Slang build is not supported yet on Msys2. Please disable it during the build by adding to cmake flags (See details in Build Options)

make all CMAKE_FLAGS="-DOPENFPGA_WITH_SLANG=OFF"

Instead, please use the prebuilt version of Yosys at mingw-w64-x86_64-yosys.

Windows (MSVC)

If your OS is Windows and use Microsoft Visual C++ as compiler, you need to install packages through vcpkg, chocolatery etc. You may refer to the section win_msvc_installer in .github/workflows/build.yml for full details.

Running with pre-built docker image

Users can skip the traditional installation process by using the Dockerized version of the OpenFPGA tool. The OpenFPGA project maintains the docker image/Github package of the latest stable version of OpenFPGA in the following repository openfpga-master. This image contains precompiled OpenFPGA binaries with all prerequisites installed.

# To get the docker image from the repository,
docker pull ghcr.io/lnis-uofu/openfpga-master:latest

# To invoke openfpga_shell
docker run -it ghcr.io/lnis-uofu/openfpga-master:latest openfpga/openfpga bash

# To run the task that already exists in the repository.
docker run -it ghcr.io/lnis-uofu/openfpga-master:latest bash -c "source openfpga.sh && run-task compilation_verification"

# To link the local directory wihth docker
mkdir work

docker run -it -v work:/opt/openfpga/ ghcr.io/lnis-uofu/openfpga-master:latest bash
# Inside container
source openfpga.sh
cd work
create_task _my_task yosys_vpr