Set Up ESP

Latest update: 2026-08-21

This guide illustrates prerequisites and environment setup for ESP. A legacy Docker guide is retained for older ESP images, but those images use end-of-life Linux distributions and should not be treated as the current recommended environment.

Unless a section is marked Coming soon or legacy, this guide targets ESP 2026.1.0 on the public main branch.

Intel/Altera development preview: the Quartus and SoC EDS instructions support an unreleased DE10-Pro SX port. Coming soon

Table of Contents

Software packages

The ESP design flow is currently developed and tested primarily on Red Hat Enterprise Linux 8, which is our preferred OS. ESP is also used on AlmaLinux 8 systems, including AlmaLinux 8.10, and on Ubuntu 22.04. The Ubuntu 24.04 and 26.04 package list below is a starting point; confirm compatibility with each commercial CAD tool vendor before selecting a host OS. RHEL 10 and AlmaLinux 10 support is unreleased and is documented separately below.

Note: Cadence tools do not officially support Ubuntu. If you choose to work with Ubuntu, accelerator unit-test simulation within the Cadence Stratus HLS environment may not function properly.

In order to support embedded scripts and CAD tools for simulation and implementation, the following packages should be installed using the system package manager.

Back to top

Red Hat Enterprise Linux 8 and AlmaLinux 8

Red Hat Enterprise Linux 8 and AlmaLinux 8

  # Miscellaneous
  sudo dnf install -y epel-release
  sudo dnf install -y git octave octave-io jq

  # Python
  sudo dnf install -y python3 python3-pip python3-tkinter
  python3 -m pip install --user Pmw

  # Perl
  sudo dnf install -y perl perl-Env perl-YAML perl-XML-Simple
  sudo dnf install -y perl-ExtUtils-MakeMaker perl-Thread-Queue perl-Capture-Tiny

  # CAD tools and SW toolchains dependencies
  sudo dnf install -y xterm
  sudo dnf install -y csh ksh zsh tcl
  sudo dnf install -y glibc-devel glibc-devel.i686
  sudo dnf install -y glibc-static glibc-static.i686
  sudo dnf install -y mesa-libGL.i686 mesa-libGLU.i686
  sudo dnf install -y mesa-libGL mesa-libGLU
  sudo dnf install -y mesa-dri-drivers mesa-dri-drivers.i686
  sudo dnf install -y readline-devel readline-devel.i686
  sudo dnf install -y libXp libXp.i686
  sudo dnf install -y openmotif
  sudo dnf install -y ncurses
  sudo dnf install -y gdbm-devel gdbm-devel.i686
  sudo dnf install -y libSM libSM.i686
  sudo dnf install -y libXcursor libXcursor.i686
  sudo dnf install -y libXft libXft.i686
  sudo dnf install -y libXrandr libXrandr.i686
  sudo dnf install -y libXScrnSaver libXScrnSaver.i686
  sudo dnf install -y libmpc-devel libmpc-devel.i686
  sudo dnf install -y nspr nspr.i686
  sudo dnf install -y nspr-devel nspr-devel.i686
  sudo dnf install -y tk tk-devel
  sudo dnf install -y dtc bison flex bzip2 patch bc
  sudo dnf install -y Xvfb
  sudo dnf install -y boost boost-thread boost-devel

  # For older GUIs (e.g. Stratus)
  sudo dnf install -y libpng12 libpng12.i686

  # QT
  sudo dnf install -y qtcreator

Do not create system-wide library aliases to satisfy an older CAD binary. Use vendor-supported compatibility packages or isolate the tool in a supported environment.
Back to top

Red Hat Enterprise Linux 10 and AlmaLinux 10 Coming soon

Red Hat Enterprise Linux 10 and AlmaLinux 10

Release status: EL10 host compatibility is unreleased and is not part of ESP 2026.1.0. The package list below is a preliminary setup for the pending compatibility changes, not a claim that the released main branch or every commercial CAD tool supports EL10.

Enable the development and EPEL repositories before installing the packages. On RHEL 10, CodeReady Linux Builder is provided with RHEL subscriptions:

sudo subscription-manager repos \
  --enable codeready-builder-for-rhel-10-$(arch)-rpms
sudo dnf install -y \
  https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm

AlmaLinux 10 enables CRB by default in current releases. Verify that crb appears in dnf repolist --enabled, then install EPEL:

dnf repolist --enabled

# Only if CRB is disabled on this particular image:
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --set-enabled crb

sudo dnf install -y epel-release

The preliminary 64-bit host package set is:

  # Build, repository and command-line tools
  sudo dnf install -y git jq gcc gcc-c++ make m4 autoconf automake libtool
  sudo dnf install -y glibc-devel glibc-static
  sudo dnf install -y dtc bison flex bzip2 patch bc csh ksh zsh tcl

  # Python
  sudo dnf install -y python3 python3-pip python3-tkinter
  python3 -m pip install --user Pmw

  # Perl
  sudo dnf install -y perl perl-Env perl-YAML perl-XML-Simple
  sudo dnf install -y perl-ExtUtils-MakeMaker perl-Thread-Queue perl-Capture-Tiny

  # Libraries used by ESP tools and toolchain builds
  sudo dnf install -y ncurses ncurses-devel readline-devel gdbm-devel
  sudo dnf install -y libmpc-devel nspr nspr-devel boost boost-devel
  sudo dnf install -y tk tk-devel xterm

  # RHEL 10 replacement for zlib development packages
  sudo dnf install -y zlib-ng-compat zlib-ng-compat-devel

  # Used by accelerator reference and verification programs
  sudo dnf install -y octave

Important EL10 differences from the EL8 instructions:

  • Do not add .i686 packages. RHEL 10 removed 32-bit packages, and the pending ESP compatibility work replaces the old 32-bit BCC dependency used by the LEON3 toolchain.

  • The normal source-build dependency is ncurses-devel. If a trusted legacy CAD binary specifically reports a missing libncurses.so.5, EPEL 10 provides ncurses-compat-libs:

    sudo dnf install -y ncurses-compat-libs

    Do not create a libncurses.so.5 symlink to the incompatible ncurses 6 library.

  • RHEL 10 replaces zlib-devel with zlib-ng-compat-devel, which preserves the zlib API and ABI.
  • EPEL 10 is split by EL10 minor release. octave is available in current streams, but octave-io is not currently published for EPEL 10. Workflows that require the IO package remain an EL10 validation item; use only a trusted, reviewable source or internal package rather than mixing packages from another Enterprise Linux release.
  • RHEL 10 removed several legacy graphical dependencies from the EL8 list, including libXp, libXScrnSaver, Motif and Xvfb. The pending ESP batch configuration path no longer requires Xvfb. If a commercial CAD GUI still requires one of the removed libraries, use an OS supported by that vendor rather than importing old distribution packages or making system-wide library aliases.

Before installing CAD tools, check the vendor’s supported-host matrix. Useful distribution references are the RHEL 10 package manifest, the RHEL 10 package-change list, the EPEL setup guide and AlmaLinux’s extra-repository guide.


Back to top

Ubuntu 22.04, 24.04 and 26.04

Ubuntu 22.04, 24.04 and 26.04

  # Miscellaneous
  sudo apt install -y git octave octave-io jq software-properties-common

  # Python
  sudo apt install -y python-is-python3 python3 python3-pip python3-tk python3-pmw

  # Perl
  sudo apt install -y perl libyaml-perl libxml-perl

  # CAD tools and SW toolchains dependencies
  sudo apt install -y xterm
  sudo apt install -y csh ksh zsh tcl
  sudo apt install -y build-essential
  sudo apt install -y libgl1-mesa-dev libglu1-mesa libgl1-mesa-dri
  sudo apt install -y libreadline-dev
  sudo apt install -y libxpm-dev
  sudo apt install -y libmotif-dev
  sudo apt install -y libncurses-dev
  sudo apt install -y libgdbm-dev
  sudo apt install -y libsm-dev
  sudo apt install -y libxcursor-dev
  sudo apt install -y libxft-dev
  sudo apt install -y libxrandr-dev
  sudo apt install -y libxss-dev
  sudo apt install -y libmpc-dev
  sudo apt install -y libnspr4
  sudo apt install -y libnspr4-dev
  sudo apt install -y libboost-all-dev
  sudo apt install -y tk tk-dev
  sudo apt install -y flex
  sudo apt install -y rename
  sudo apt install -y zlib1g:i386
  sudo apt install -y gcc-multilib
  sudo apt install -y device-tree-compiler
  sudo apt install -y bison
  sudo apt install -y xvfb

  # Older CAD tools may require libncurses5. Do not mix repositories from an
  # older Ubuntu release into the host. Use a vendor-supported environment or
  # a compatibility package from a trusted, signature-verified source.

  # Older CAD GUIs may require libpng12. Obtain legacy compatibility packages
  # only from the CAD vendor or a trusted, signature-verified internal mirror.

  # QT
  sudo apt install -y qtcreator


Back to top

Red Hat Enterprise Linux 7.8 (legacy)

Red Hat Enterprise Linux 7.8 (legacy)

RHEL 7 is EOL for non-ELS users. These instructions are kept for legacy systems only.

  # Miscellaneous
  sudo yum install -y epel-release
  sudo yum install -y git octave octave-io jq

  # Python
  sudo yum install -y python python-pip python3 python3-pip python34-tkinter
  python3 -m pip install --user Pmw

  # Perl
  sudo yum install -y perl perl-YAML perl-ExtUtils-MakeMaker perl-XML-Simple

  # CAD tools and SW toolchains dependencies
  sudo yum install -y xterm
  sudo yum install -y csh ksh zsh tcl
  sudo yum install -y glibc-devel glibc-devel.i686
  sudo yum install -y glibc-static glibc-static.i686
  sudo yum install -y mesa-libGL.i686 mesa-libGLU.i686
  sudo yum install -y mesa-libGL mesa-libGLU
  sudo yum install -y mesa-dri-drivers mesa-dri-drivers.i686
  sudo yum install -y readline-devel readline-devel.i686
  sudo yum install -y libXp libXp.i686
  sudo yum install -y openmotif
  sudo yum install -y ncurses
  sudo yum install -y gdbm-devel gdbm-devel.i686
  sudo yum install -y libSM libSM.i686
  sudo yum install -y libXcursor libXcursor.i686
  sudo yum install -y libXft libXft.i686
  sudo yum install -y libXrandr libXrandr.i686
  sudo yum install -y libXScrnSaver libXScrnSaver.i686
  sudo yum install -y libmpc-devel libmpc-devel.i686
  sudo yum install -y nspr nspr.i686
  sudo yum install -y nspr-devel nspr-devel.i686
  sudo yum install -y tk tk-devel
  sudo yum install -y Xvfb dtc
  sudo yum install -y bison

  # For older GUIs (e.g. Stratus)
  sudo yum install -y libpng12 libpng12.i686

  # QT
  sudo yum install -y qtcreator


Back to top

Ubuntu 18.04 (legacy)

Ubuntu 18.04 (legacy)

Ubuntu 18.04 instructions are kept for legacy systems only.

  # Miscellaneous
  sudo apt install -y git octave octave-io jq

  # Python
  sudo apt install -y python python-pip python3 python3-pip python3-tk
  python3 -m pip install --user Pmw

  # Perl
  sudo apt install -y perl libyaml-perl libxml-perl

  # CAD tools and SW toolchains dependencies
  sudo apt install -y xterm
  sudo apt install -y csh ksh zsh tcl
  sudo apt install -y build-essential
  sudo apt install -y libgl1-mesa-dev libglu1-mesa libgl1-mesa-dri
  sudo apt install -y libreadline-dev
  sudo apt install -y libxpm-dev
  sudo apt install -y libmotif-dev
  sudo apt install -y libncurses5
  sudo apt install -y libncurses-dev
  sudo apt install -y libgdbm-dev
  sudo apt install -y libsm-dev
  sudo apt install -y libxcursor-dev
  sudo apt install -y libxft-dev
  sudo apt install -y libxrandr-dev
  sudo apt install -y libxss-dev
  sudo apt install -y libmpc-dev
  sudo apt install -y libnspr4
  sudo apt install -y libnspr4-dev
  sudo apt install -y libboost-all-dev
  sudo apt install -y tk tk-dev
  sudo apt install -y flex
  sudo apt install -y rename
  sudo apt install -y zlib1g:i386
  sudo apt install -y gcc-multilib
  sudo apt install -y device-tree-compiler
  sudo apt install -y bison
  sudo apt install -y xvfb

  # Older CAD GUIs may require libpng12. Do not add an EOL Ubuntu repository
  # to the system; use a vendor-supported environment or a trusted,
  # signature-verified internal package source.

  # QT
  sudo apt install -y qtcreator


Back to top

CentOS 7 (EOL)

CentOS 7 (EOL)

CentOS 7 is EOL. These instructions are kept for legacy systems only.

  # Miscellaneous
  sudo yum install -y epel-release
  sudo yum install -y git octave octave-io jq

  # Python
  sudo yum install -y python python-pip python3 python3-pip python3-tkinter
  python3 -m pip install --user Pmw

  # Perl
  sudo yum install -y perl perl-Env perl-YAML perl-XML-Simple
  sudo yum install -y perl-ExtUtils-MakeMaker perl-Thread-Queue perl-Capture-Tiny

  # CAD tools and SW toolchains dependencies
  sudo yum install -y xterm
  sudo yum install -y csh ksh zsh tcl
  sudo yum install -y glibc-devel glibc-devel.i686
  sudo yum install -y glibc-static glibc-static.i686
  sudo yum install -y mesa-libGL.i686 mesa-libGLU.i686
  sudo yum install -y mesa-libGL mesa-libGLU
  sudo yum install -y mesa-dri-drivers mesa-dri-drivers.i686
  sudo yum install -y readline-devel readline-devel.i686
  sudo yum install -y libXp libXp.i686
  sudo yum install -y openmotif
  sudo yum install -y ncurses
  sudo yum install -y gdbm-devel gdbm-devel.i686
  sudo yum install -y libSM libSM.i686
  sudo yum install -y libXcursor libXcursor.i686
  sudo yum install -y libXft libXft.i686
  sudo yum install -y libXrandr libXrandr.i686
  sudo yum install -y libXScrnSaver libXScrnSaver.i686
  sudo yum install -y libmpc-devel libmpc-devel.i686
  sudo yum install -y nspr nspr.i686
  sudo yum install -y nspr-devel nspr-devel.i686
  sudo yum install -y tk tk-devel
  sudo yum install -y dtc bison flex bzip2 patch bc
  sudo yum install -y Xvfb
  sudo yum install boost boost-thread boost-devel

  # For older GUIs (e.g. Stratus)
  sudo yum install -y libpng12 libpng12.i686

  # QT
  sudo yum install -y qtcreator


Back to top

CAD tools

ESP leverages a mix of open-source tools and scripts, as well as commercial tools. The following list specifies which commercial tools are currently supported and which tools are required to complete some steps of the ESP design methodology. Support for the tools marked as beta in the following list has not been fully tested or completed.

Required

  • RTL simulation: requires one of the following tools (64-bit version)
    • Mentor Graphics ModelSim DE 2023.2: RTL system-level simulator
    • Cadence Xcelium 19.03: RTL system-level simulator (apply patch below)
  • FPGA prototyping: requires the tool for the selected board
    • AMD/Xilinx Vivado 2023.2: logic synthesis and implementation for AMD/Xilinx FPGA boards
    • Intel Quartus Prime Pro 19.4: validated for the Terasic DE10-Pro SX
    • Intel SoC EDS 19.1: additionally required to generate the DE10-Pro SX HPS boot artifacts

    The DE10-Pro SX port is maintained against Quartus Prime Pro 19.4 and SoC EDS 19.1. Newer versions may work, but have not been validated with the tracked Tcl, SDC, Verilog and Platform Designer inputs.

Optional

  • Accelerator design: the following tools are optional
    • Cadence Stratus HLS 20.24: high-level synthesis of accelerators from SystemC
    • Xilinx Vivado HLS 2019.2: high-level synthesis of accelerators from C/C++ (beta)
    • Mentor Catapult HLS 2024.1: high-level synthesis of accelerators from SystemC and C/C++

    ESP’s HLS flows currently depend on AMD/Xilinx-specific technology mappings and are not supported by the Intel/Altera FPGA flow. On the DE10-Pro SX, use an accelerator from the RTL or Third-Party flow.

  • Cache hierarchy: the default ESP configuration selects an RTL implementation of the cache hierarchy (no additional tool required). This supports both multi-core execution and coherence for accelerators. Optionally, ESP provides a SystemC implementation of the caches that can be synthesized with Cadence Stratus HLS. The SystemC version of the caches is particularly helpful to conduct architectural research on coherence, as the SystemC model is significantly easier to modify than the RTL implementation.

Back to top

Environment variables

Here are the environment variables required by the CAD tools:

# Cadence: Stratus HLS, Incisive, Xcelium
  # e.g. <stratus_path> = /opt/cadence/stratus2024
  # e.g. <incisive_path> = /opt/cadence/incisive152
  # e.g. <xcelium_path> = /opt/cadence/xcelium1903
  export LM_LICENSE_FILE=$LM_LICENSE_FILE:<cadence_license_path>
  export PATH=$PATH:<stratus_path>/bin:
  # Uncomment either the Incisive or Xcelium paths, but not both.
  # export PATH=$PATH:<incisive_path>/tools/cdsgcc/gcc/bin
  # export PATH=$PATH:<incisive_path>/tools/bin
  export PATH=$PATH:<xcelium_path>/tools/cdsgcc/gcc/bin
  export PATH=$PATH:<xcelium_path>/tools/bin
  export CDS_AUTO_64BIT=all
  export HOST=$(hostname) # for Ubuntu only

# AMD/Xilinx: Vivado, Vivado HLS
  # e.g. <vivado_path> = /opt/xilinx/Vivado/2023.2
  export XILINXD_LICENSE_FILE=<xilinx_license_path>
  source <vivado_path>/settings64.sh

# Intel: Quartus Prime Pro and SoC EDS
  # Add the Quartus Prime Pro 19.4 binaries to PATH using the environment
  # setup supplied with your installation. Run `make hps` from the Intel
  # SoC EDS 19.1 embedded command shell.
  export LM_LICENSE_FILE=$LM_LICENSE_FILE:<intel_license_path>

# Mentor: Catapult HLS, Modelsim
  # e.g. <modelsim_path> = /opt/mentor/modeltech
  # e.g. <catapult_path> = /opt/mentor/catapult
  export LM_LICENSE_FILE=$LM_LICENSE_FILE:<mentor_license_path>
  export PATH=$PATH:<modelsim_path>/bin
  export AMS_MODEL_TECH=<modelsim_path>
  export PATH=$PATH:<catapult_path>/Mgc_home/bin
  export SYSTEMC=<catapult_path>/Mgc_home/shared
  export CATAPULT_HOME=<catapult_path>/Mgc_home
  export LIBDIR=-L<catapult_path>/Mgc_home/shared/lib $LIBDIR

# RISC-V (for Ariane and Ibex)
  # e.g. <riscv_path> = /opt/riscv
  # e.g. <riscv32imc_path> = /opt/riscv32imc
  export RISCV=<riscv_path>
  export RISCV32IMC=<riscv32imc_path>
  export PATH=$PATH:<riscv_path>/bin:<riscv32imc_path>/bin

# Leon3
  # e.g. <leon3_path> = /opt/leon
  export PATH=$PATH:<leon3_path>/bin
  export PATH=$PATH:<leon3_path>/mklinuximg
  export PATH=$PATH:<leon3_path>/sparc-elf/bin


Back to top

ESP repository

ESP is available as an open-source GitHub repository. All original files in ESP are governed by the Apache 2.0 License, whereas third-party open-source software maintains its original license and includes the copyright notice from the authors.

Use the following commands to obtain the ESP source code from GitHub. To avoid installing large, unnecessary submodules, we recommend to run the provided submodule installation script, which interactively installs submodules as required by users.

The maintained guides target the 2026.1.0 release tag, which matched main at this page’s latest review. Checking out the tag makes the instructions and submodule revisions reproducible. Omit the tag checkout only when you intentionally want the moving development branch.

Alternatively, a recursive clone can be used to initialize and download the source code from all submodules that are linked by the main ESP repository. Please be patient, as one of the submodules is Linux, which embeds a very large history.

# "Bare" clone of ESP and interactive submodule installation
git clone https://github.com/sld-columbia/esp.git
cd esp
git switch --detach 2026.1.0
./utils/scripts/submodule_init.sh

# Clone ESP and all Git submodules at once
git clone --recursive --branch 2026.1.0 https://github.com/sld-columbia/esp.git

# Clone ESP and then install all submodules
git clone https://github.com/sld-columbia/esp.git
cd esp
git switch --detach 2026.1.0
git submodule update --init --recursive


Back to top

Software toolchain

Every ESP SoC must include at least one processor core to execute the operating system and the target applications. ESP currently supports the Leon3 core from GRLIB, implementing the 32-bit SPARC V8 instruction-set architecture (ISA), the 64-bit RISC-V Ariane/CVA6 core and the 32-bit RISC-V Ibex core.

Since the target ISA is not x86, a cross compiler is required to build software that can execute on the target processor. In addition, Linux requires a root filesystem that hosts all necessary initialization scripts, header files and dynamically-linked libraries. A partial overlay for the root filesystem is embedded into the ESP code base, however, binaries from busybox and libraries must be compiled and combined to the overlay. Failure to complete this step will prevent Linux from completing the boot process.

Security note: the development Linux image uses well-known default credentials. Change or disable them before connecting an ESP board to an untrusted network; do not reuse production credentials in generated images.

ESP provides scripts that allow users to build the toolchain automatically.

cd <esp>

# Leon3 toolchain
./utils/toolchain/build_leon3_toolchain.sh

# RISC-V 64-bit toolchain (for the Ariane processor)
./utils/toolchain/build_riscv_toolchain.sh

# RISC-V 32-bit toolchain (for the Ibex processor)
./utils/toolchain/build_riscv32imc_toolchain.sh


The scripts go through several interactive steps to build the toolchain. If one step fails due to missing packages on the host system, users can restart the script and skip phases that completed successfully. For a default installation the user can select all the default answers of the interactive script.

Back to top

Patching Ariane for Xcelium Simulator

The source code of Ariane includes UVM and SVA features that can only work with Modelsim. These features are disabled by the ESP Makefile by defining the variable VERILATOR during compilation. As a result, the instruction tracer is not instantiated, because it requires UVM support. The developers of Ariane replaced the instruction tracer with custom RTL code when simulating with Verilator. This code, unfortunately, triggers non suppressible errors in the Xcelium compiler.

While we do recommend to use Modelsim for simulation and keep all of the UVM and SVA features enabled, if you need to simulate using Xcelium, please apply this patch to the Ariane repository in rtl/cores/ariane/ariane. The patch is simply commenting the code for instruction tracing with Verilator.

cd rtl/cores/ariane/ariane
cp path/to/xcelium_ariane.patch .
git apply xcelium_ariane.patch

Finally, please note that Incisive cannot compile the source code of Ariane, but it will work with Leon3-based ESP instances.

Back to top