ESP Setup Guide

Last updated October 2, 2026

This guide prepares a Linux host for ESP: system packages, the Python environment used by the ESP configuration tools, CAD tools, environment variables, the ESP source tree, and the processor software toolchains.

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

A legacy Docker guide is retained for reproducing older ESP images. Those images use end-of-life Linux distributions and are not the recommended environment for current ESP.

Supported host operating systems

ESP is developed and tested primarily on Red Hat Enterprise Linux 8. Commercial CAD tools set their own host requirements, so check each vendor’s supported-platform list before choosing a host OS.

Ubuntu and Cadence tools: Cadence does not officially support Ubuntu. Accelerator unit-test simulation in the Cadence Stratus HLS environment may not work correctly on Ubuntu hosts.

Install system packages

Install the following packages with the system package manager. They provide the scripts, libraries and build tools used by ESP, the CAD tools and the software toolchain builds.

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

# AlmaLinux 8
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --set-enabled powertools
sudo dnf install -y epel-release

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

# Python 3.11 with Tk. The ESP configuration GUI requires Python 3.7 or
# later; the default python3 on EL8 is 3.6. See "Set up the Python environment".
sudo dnf install -y python3.11 python3.11-pip python3.11-tkinter

# 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

# Software toolchain builds (GNU toolchain, Buildroot, Linux)
sudo dnf install -y gcc gcc-c++ make autoconf automake libtool
sudo dnf install -y gawk texinfo gperf patchutils
sudo dnf install -y gmp-devel mpfr-devel libmpc-devel expat-devel zlib-devel
sudo dnf install -y dtc bison flex bzip2 patch bc cpio rsync unzip wget
sudo dnf install -y fakeroot

# CAD tools and runtime libraries
sudo dnf install -y xterm csh ksh zsh tcl tk tk-devel
sudo dnf install -y glibc-devel glibc-devel.i686 glibc-static glibc-static.i686
sudo dnf install -y mesa-libGL mesa-libGL.i686 mesa-libGLU mesa-libGLU.i686
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 openmotif ncurses
sudo dnf install -y gdbm-devel gdbm-devel.i686
sudo dnf install -y libSM libSM.i686 libXcursor libXcursor.i686
sudo dnf install -y libXft libXft.i686 libXrandr libXrandr.i686
sudo dnf install -y libXScrnSaver libXScrnSaver.i686
sudo dnf install -y libmpc-devel.i686 nspr nspr.i686 nspr-devel nspr-devel.i686
sudo dnf install -y boost boost-thread boost-devel

# Virtual X server (xvfb-run is used by `make esp-config`)
sudo dnf install -y xorg-x11-server-Xvfb

# Older CAD GUIs (e.g. Stratus)
sudo dnf install -y libpng12 libpng12.i686

# Qt (ESP monitor GUI)
sudo dnf install -y qtcreator

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

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

  # 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

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

# Python with Tk and virtual-environment support
sudo apt install -y python-is-python3 python3 python3-pip python3-venv python3-tk

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

# Software toolchain builds (GNU toolchain, Buildroot, Linux)
sudo apt install -y build-essential autoconf automake autotools-dev libtool
sudo apt install -y gawk texinfo gperf patchutils
sudo apt install -y libgmp-dev libmpfr-dev libmpc-dev libexpat1-dev zlib1g-dev
sudo apt install -y device-tree-compiler bison flex bc cpio rsync unzip wget
sudo apt install -y fakeroot

# CAD tools and runtime libraries
sudo apt install -y xterm csh ksh zsh tcl tk tk-dev
sudo apt install -y libgl1-mesa-dev libglu1-mesa libgl1-mesa-dri
sudo apt install -y libreadline-dev libxpm-dev libmotif-dev libncurses-dev
sudo apt install -y libgdbm-dev libsm-dev libxcursor-dev libxft-dev
sudo apt install -y libxrandr-dev libxss-dev
sudo apt install -y libnspr4 libnspr4-dev libboost-all-dev
sudo apt install -y rename zlib1g:i386 gcc-multilib

# Virtual X server (xvfb-run is used by `make esp-config`)
sudo apt install -y xvfb

# Older CAD tools may require libncurses5 or libpng12. 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.

# Qt (ESP monitor GUI)
sudo apt install -y qtcreator

# 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

# 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 -y boost boost-thread boost-devel

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

# QT
sudo yum install -y qtcreator

# 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

Set up the Python environment

The ESP SoC configuration tools (make esp-xconfig and the batch make esp-config) are Python 3 programs built on Tk. They need:

• Python 3.7 or later with the Tk module, installed with the system packages above
• CustomTkinter, the widget toolkit used by the ESP GUI
• Pmw (Python megawidgets)

Install the Python packages in a virtual environment. Recent distributions, including Ubuntu 24.04, mark the system Python as externally managed and reject pip install --user. A virtual environment works the same way on every supported host and keeps ESP’s packages separate from the system Python.

# Create the environment once. On RHEL 8 and AlmaLinux 8, replace python3
# with python3.11 in this command only.
python3 -m venv ~/.venvs/esp

# Activate it and install the ESP GUI dependencies
source ~/.venvs/esp/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install customtkinter Pmw

# Confirm that Tk, CustomTkinter and Pmw can be imported
python3 -c "import tkinter, customtkinter, Pmw; print('ESP GUI dependencies OK')"

ESP runs python3 from your PATH, so activate the environment in every shell used for ESP. The environment variables section adds the activation command to the ESP shell setup.

Install CAD tools

ESP combines open-source tools and scripts with commercial CAD tools. The lists below give the tool versions currently used by the ESP team. Support for tools marked Beta has not been fully tested or completed.

Required

• RTL simulation: one of the following (64-bit version)
  • Siemens ModelSim DE 2023.2
  • Cadence Xcelium 19.03 (apply the Ariane patch when simulating Ariane)
• FPGA prototyping: the tool for the selected board
  • AMD/Xilinx Vivado 2023.2: synthesis and implementation for AMD/Xilinx FPGA boards
  • Intel Quartus Prime Pro 19.4: validated for the Terasic DE10-Pro SX Coming soon

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

Optional

• Accelerator design
  • Cadence Stratus HLS 20.24: high-level synthesis from SystemC
  • AMD/Xilinx Vivado HLS 2019.2: high-level synthesis from C/C++ Beta
  • Siemens Catapult HLS 2024.1: high-level synthesis from SystemC and C/C++
  • PandA Bambu: open-source high-level synthesis from C/C++ Coming soon. Use the feature/unified_ac_channels branch; ESP validation used revision 4150ff6e20d5, Clang 16 and Verilator 4.038. See the Bambu HLS guide.

  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, which requires no additional tool and supports both multi-core execution and accelerator coherence. ESP also provides a SystemC implementation of the caches that can be synthesized with Cadence Stratus HLS. The SystemC model is easier to modify than the RTL, which makes it useful for architectural research on coherence.

Set environment variables

Add the settings for the tools you installed to the shell profile used for ESP. Replace each <placeholder> with the path on your system.

# Python environment for the ESP configuration tools
  source ~/.venvs/esp/bin/activate

# 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 (DE10-Pro SX development preview)
  # Add the Quartus Prime Pro 19.4 binaries to PATH using the environment
  # setup supplied with your installation.
  export LM_LICENSE_FILE=$LM_LICENSE_FILE:<intel_license_path>

# Siemens: 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

# PandA Bambu HLS (optional, development branch)
  # e.g. <bambu_path> = /opt/panda/unified_ac_channels/install
  export BAMBU=<bambu_path>/bin/bambu
  export BAMBU_ENV=<bambu_path>/settings.sh

# RISC-V toolchains (Ariane, CVA6 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 toolchain
  # 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

Get the ESP source code

ESP is available as an open-source GitHub repository. All original files in ESP are governed by the Apache 2.0 License; third-party open-source software keeps its original license and copyright notice.

The maintained guides target the 2026.1.0 release tag. Checking out the tag makes the instructions and submodule revisions reproducible.

git clone https://github.com/sld-columbia/esp.git
cd esp
git switch --detach 2026.1.0
./utils/scripts/submodule_init.sh

ESP depends on many large submodules, including several Linux kernels. The interactive submodule_init.sh script asks which processors, accelerator flows and optional components you need and downloads only those. Alternatively, initialize every submodule at once; this can take a long time:

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

# Or initialize all submodules in an existing clone
git submodule update --init --recursive

git switch dev
./utils/scripts/submodule_init.sh

./utils/scripts/apply_patches.sh

Build the software toolchains

Every ESP SoC includes at least one processor core to run the operating system and applications. ESP supports the 32-bit SPARC V8 LEON3 core from GRLIB, the 64-bit RISC-V Ariane core, and the 32-bit RISC-V Ibex core. The development branch adds the upstream 64-bit RISC-V OpenHW CVA6 core Coming soon.

Because these processors do not use the x86 ISA, software for them must be built with a cross compiler. Linux also requires a root filesystem with initialization scripts, header files and dynamically linked libraries. ESP includes a partial root-filesystem overlay; the toolchain scripts build BusyBox and the required libraries and add them to the overlay. Linux cannot finish booting without this step.

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 build each toolchain:

cd <esp>

# LEON3 toolchain
./utils/toolchain/build_leon3_toolchain.sh

# RISC-V 64-bit toolchain (Ariane and CVA6)
./utils/toolchain/build_riscv_toolchain.sh

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

The scripts are interactive. If a step fails because of a missing host package, install the package, rerun the script and skip the phases that already completed. For a default installation, accept the default answer at every prompt.

• The RISC-V 64-bit script uses the Ariane Linux sources to build the Linux toolchain and root filesystem. Install the Ariane Linux submodule (soft/ariane/linux) first, even if you only plan to use CVA6. On the development branch, the script also copies the root filesystem to soft/cva6/sysroot for CVA6. Coming soon
• On hosts with glibc 2.33 or later, such as Ubuntu 22.04 and newer, the RISC-V and LEON3 Linux builds use the system fakeroot. Install it with the host packages above; otherwise the RISC-V script stops and asks for it.

Patch Ariane for the Xcelium simulator

The Ariane source code includes UVM and SVA features that work only with ModelSim. The ESP Makefile disables them by defining VERILATOR during compilation. As a result, Ariane’s UVM-based instruction tracer is not instantiated, and Ariane uses custom tracing RTL meant for Verilator instead. That RTL triggers non-suppressible errors in the Xcelium compiler.

We recommend ModelSim for simulation, with all UVM and SVA features enabled. If you need to simulate Ariane with Xcelium, apply this patch to the Ariane repository in rtl/cores/ariane/ariane. The patch comments out the Verilator instruction tracing code.

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

Incisive cannot compile the Ariane source code, but it works with LEON3-based ESP instances.