Skip to content

Development environment setup

Jump to bottom
marwannismail edited this page Nov 30, 2025 · 20 revisions

There are multiple ways of working with RISC-V repo:

  1. Using WSL (Windows Subsystem for Linux) on Windows
  2. Using a Linux distro
  3. Using a devcontainer

While its also possible to use Quartus ecosystem on Windows to build the project, it is currently not officially suported.

Prerequisites

WSL

For setup instructions, see WSL Onboarding

Linux
Devcontainer

Installing dependencies

This subsection applies to those using WSL or Linux to interact with the RISC-V repo. Those using devcontainer already have everything setup.

This doc assumes you are using a recent Ubuntu (e.g. 22.04); if you are using another distro you can probably figure out how to modify the instructions accordingly.

  1. Update your system 
    sudo apt update
sudo apt upgrade -y
  2. Install some essentials 
    sudo apt update
sudo apt install -y \
  man make build-essential git zsh vim curl wget procps gnupg gnupg2 ca-certificates zip \
  software-properties-common autoconf gperf gcc g++ bison flex \
  python3 python3-pip python3-venv libpython3-dev unzip
  3. (optional) Set up oh-my-zsh
  4. Build Icarus Verilog 
    ICARUS_SRC_TAR="s20251012.tar.gz"
ICARUS_SRC_URL="https://github.com/steveicarus/iverilog/archive/refs/tags/${ICARUS_SRC_TAR}"
ICARUS_SRC_HASH="97776c5dd1ee09157f7cb9f48978c7687b9157b09fa7029c0f9378aac9a6f58c  ${ICARUS_SRC_TAR}"

cd /tmp
wget "${ICARUS_SRC_URL}"
echo "${ICARUS_SRC_HASH}" | sha256sum -c
tar -xzf "${ICARUS_SRC_TAR}"
cd iverilog-*
sh autoconf.sh
./configure
make -j"$(nproc)"
make check
sudo make install
cd ..
rm -rf iverilog-* "${ICARUS_SRC_TAR}"

# quick sanity check
iverilog -V
  5. Install Docker for Windows; make sure to check the "Use WSL 2 instead of Hyper-V" checkbox during installation. On Ubuntu, you can install Docker Desktop or get it your package manager.
  6. Get yourself a GitHub access token:

    1. On GitHub, go to Settings:

    2. Navigate to Developer Settings in the panel on the left:

    3. Navigate to Personal access tokens > Tokens (classic):

    4. Click Generate new token > Generate new token (classic):

    5. Call it whatever you want, set expiry to 7 days and pick write:pacakges scope:

    6. Copy the new personal access token:

  7. Login into GHCR (GitHub Container Registry) via docker using the token you just created: 
    export GHCR_TOKEN="<paste token here>"
echo $GHCR_TOKEN | sudo docker login ghcr.io -u <your github username> --password-stdin
    Make sure you see Login Succeeded; make sure to use sudo here, unless you know how to configure Docker to run without sudo which is outside of the scope of this setup
  8. Get RISC-V toolchain from our Docker image. Toolchain is a collection of binraires needed to run programs on a specific architecture (in this case RISC-V), these include assemblers, compilers, linkers and debuggers. Since it takes quite a bit of time to build it from source -- we uploaded a docker contianer with the binaries, compiled to run on x86 architecutres. Essentially this means that the toolchain can be used to cross-compile programs for RISC-V on an x86-based computer. Perform the following commands in a shell in WSL.
    1. Set up some variables in shell: 
      DOCKER_IMAGE="ghcr.io/utoss/risc-v-toolchain:latest"
INSTALL_DIR="/opt/riscv"
TEMP_CONTAINER="riscv-toolchain-temp"
    2. Pull the docker image from GHCR: 
      sudo docker pull ${DOCKER_IMAGE}
    3. Start the toolchain container so that we can copy the binaries from it: 
      sudo docker create --name ${TEMP_CONTAINER} ${DOCKER_IMAGE}
    4. Copy the toolchain files from the container to WSL: 
      sudo docker cp ${TEMP_CONTAINER}:/opt/riscv/. ${INSTALL_DIR}/
    5. Make sure you own them: 
      sudo chown -R $(id -u):$(id -g) ${INSTALL_DIR}
    6. Get rid of the temporary docker container: 
      docker rm ${TEMP_CONTAINER}
    7. Add RISC-V toolchain to your PATH, i.e. so that you can run the executables without specifying complete path to their location: 
      BASHRC_LINE='export PATH="/opt/riscv/bin:$PATH"'
echo "${BASHRC_LINE}" >> ~/.bashrc
source ~/.bashrc # this line will make sure the PATH variable is also updated for your current shell sesison
    8. Do a quick test by running 
      riscv32-unknown-elf-gcc --version
      If this does list the version of the compiler, things are set up correctly.
  9. Instal SAIL simulator. This is a reference model for us to test our implementation of RISC-V against. 
    SAIL_RISCV_VERSION=0.7
SAIL_RISCV_ZIP_NAME=sail_riscv-Linux-x86_64.tar.gz
SAIL_RISCV_ZIP_URL=https://github.com/riscv/sail-riscv/releases/download/${SAIL_RISCV_VERSION}/${SAIL_RISCV_ZIP_NAME}
SAIL_RISCV_ZIP_HASH="6b8c3abc3126ce14911a3dec46ff540a60841ef090898f72c4c6f9b0b825efab  ${SAIL_RISCV_ZIP_NAME}"

mkdir -p /tmp/sail-riscv
cd /tmp/sail-riscv
wget ${SAIL_RISCV_ZIP_URL}
echo ${SAIL_RISCV_ZIP_HASH} | sha256sum -c
tar -xzf ${SAIL_RISCV_ZIP_NAME}
sudo mv sail_riscv-Linux-x86_64/bin/* /usr/local/bin/
cd ..
sudo rm -r /tmp/sail-riscv
cd /usr/local/bin
sudo mv riscv_sim_rv32d riscv_sim_RV32
sudo mv riscv_sim_rv64d riscv_sim_RV64
  10. Install RISCOF: 
    sudo apt update
sudo apt install -y python3 python3-pip
pip3 install riscof
  11. Install SVlint: 
    SVLINT_VERSION="0.9.3"
# if you are on a linux-based distro or WSL with x86 arch
SVLINT_ZIP_NAME="svlint-v${SVLINT_VERSION}-x86_64-lnx.zip"
# if you are on a mac with apple silicon
SVLINT_ZIP_NAME="svlint-v${SVLINT_VERSION}-aarch64-mac.zip"
SVLINT_ZIP_URL="https://github.com/dalance/svlint/releases/download/v${SVLINT_VERSION}/${SVLINT_ZIP_NAME}"

mkdir -p /tmp/svlint
cd /tmp/svlint && \
wget ${SVLINT_ZIP_URL}
unzip ${SVLINT_ZIP_NAME}
sudo mv bin/* /usr/local/bin/
cd .. && rm -r /tmp/svlint

# quick check
svlint --version
    If the last command does not work, check that echo $PATH contains /usr/local/bin
  12. Install Verilator (see the Verilator installation guide for more information):
   # Prerequisites:
   sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache
   sudo apt-get install libgoogle-perftools-dev numactl perl-doc
   sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
   sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
   sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)

   git clone https://github.com/verilator/verilator   # Only first time

   # Every time you need to build:
   unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
   unset VERILATOR_ROOT  # For bash
   cd verilator
   git pull         # Make sure git repository is up-to-date

   autoconf         # Create ./configure script
   ./configure      # Configure and create Makefile
   make -j `nproc`  # Build Verilator itself (if error, try just 'make')
   sudo make install

Smoke test

Run the following command while in the RISC-V repo and make sure that you don't see any errors:

make run_tb

Follow the instructions in Running RISCOF to make sure RISCOF dependencies are installed correctly.

Recommended VSCode extensions

Clone this wiki locally