Getting Started

Installation

Clone the repository:

git clone https://github.com/KULeuven-MICAS/snax_cluster.git --recurse-submodules

If you had already cloned the repository without the --recurse-submodules flag, clone its submodules:

git submodule update --init --recursive

Tools and environment

This repository requires several tools to be installed on your machine. Some of these tools require non-free licenses. However, most of the functionality in this repository can be reproduced with free tools alone.

Note that installing all tools, in appropriate versions, may be non-trivial. For this purpose, we provide a Docker container with all free tools installed.

The following section provides instructions to install the Docker container.

Users with access to ETH Zurich IIS machines can find all tools already installed on these machines. To complete the setup, skip to the IIS environment setup section.

If you do choose to setup a custom development environment on your own machine, we strongly recommend you take example from our Docker file.

Docker container

The following instructions are extracted from the Docker container README.md. For additional information on the Docker container refer to that document.

Installation

Pre-built container

There is a pre-built version of the container available online. This version is up to date with the latest developments on the main branch. The CI publishes a new container every time a new commit is pushed to this branch.

To download the container, first login to the GitHub container registry:

$ docker login ghcr.io

You will be asked for a username (your GitHub username). As a password you should use a personal access token that at least has package registry read permission.

You can then install the container by running:

$ docker pull ghcr.io/kuleuven-micas/snax:main

Build instructions

In case you cannot use the pre-built container, e.g. if you need to make changes to the Dockerfile, you can build the container locally by running the following command in the root of the repository:

$ sudo docker build -t ghcr.io/kuleuven-micas/snax:main -f util/container/Dockerfile .

Python Setup

To make sure the right versions of each tool are picked up, set the following environment variables, e.g. in a bash shell:

export PYTHON="/usr/local/anaconda3-2022.05/bin/python3"
export BENDER="bender-0.28.1"
export CC="gcc-9.2.0"
export CXX="g++-9.2.0"
export LLVM_BINROOT="/usr/pack/riscv-1.0-kgf/pulp-llvm-0.12.0/bin"
# As a temporary workaround (until correct tool versions are installed system-wide):
export PATH=/home/colluca/snitch/bin:$PATH
export PATH=/usr/scratch/dachstein/colluca/opt/verible/bin:$PATH

Add these commands to your shell startup file (e.g. ~/.bashrc if you use bash as the default shell) to ensure that the environment is set up correctly every time you open a new shell.

Create a Python virtual environment:

$PYTHON -m venv ~/.venvs/snitch_cluster

Activate your environment, e.g. in a bash shell:

source ~/.venvs/snitch_cluster/bin/activate

You may want to add the last command to your shell startup file to ensure that the virtual environment is activated on every new shell you open.

Install the required packages in the currently active virtual environment:

pip install -r python-requirements.txt