upsilon-docker/README.md

Upsilon docker development environment setup.  
Written by Peter McGoron.

# Setup steps

## Rebinding Caps Lock to Escape

	gsettings set org.gnome.desktop.input-sources xkb-options "['caps:swapescape']"

## Installing OpenFPGALoader

Then install [openFPGALoader][1]. This utility entered the Ubuntu repositories
in 23.04. Install and compile it if you do not have it. Install the udev rule
so that admin access is not required to load FPGA bitstreams.

[1]: https://trabucayre.github.io/openFPGALoader/index.html

## Setup Rootless Docker

Docker allows you to run programs in containers, which are isolated
environments. Upsilon development (at the Maglab) uses Docker for
reproducibility: the environment can be set up automatically, and re-setup
whenever needed.

If you have issues with docker, try adding to `~/.config/docker/daemon.json`

    {
       "storage-driver": "fuse-overlayfs"
    }


## Download and Install Python3

Install `python3-venv` (or `python3-virtualenv`) and `python3-pip`.

## Clone External Repositories

Run `make clone`. You may need to download the upsilon repositories
and put them in the same folder as the Makefile.

## Setup Images

Run `make images` to create all docker images.

## Setup and Run Containers

There are three containers: `hardware`, `buildroot`, and `opensbi`. For
each of these:

1. Run `make $NAME-container` to build the container.
2. Run `make $NAME-container-copy` to copy Upsilon's code into the container.
3. Run `make $NAME-container-execute` to build the data.
4. Run `make $NAME-container-get` to retrieve the build artefacts.
5. (Optionally) run `make $NAME-container-clean` to delete the container.