# Getting Started

This page provides instructions on how to set up the PicoNut project on any Linux operating system. 
There are two methods available: the recommended approach is to use Docker, 
but you can also install all the necessary dependencies natively. The Setup has to be done for both methods.

## Setup

Clone the PicoNut repository.

## Docker (Recommended)

### Install
1. Set up Docker's apt repository: \
Note: The Example below is for `Ubuntu`. More information about installing docker for other distrobutions can be found [here](https://docs.docker.com/engine/install/).
```bash
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
````

2. Install latest version of docker
```bash
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

2. Add User to docker group:
replace your username with `<user>`.
```bash
$ sudo usermod -aG docker <user>
```

Log out and log back in after running this command for the changes to take effect.

3. Build the docker piconut image: \
Note: This creates a docker image of size `~10Gb`. Make sure there is `~30Gb` 
disk space available before continue, this extra space is needed for the build 
process of some packages! Depending on the hardware this process takes `~2h`.\
First, navigate to the PicoNut repository directory.
```bash
$ cd tools/docker
$ chmod +x docker-create-piconut-image.sh
$ ./docker-create-piconut-image.sh
```

Note: If the `riscv` stage fails, try restarting the shell script. 
This is likely due to a git clone timeout caused by overloaded remote servers.

Now there should be a docker images created named `piconut_image`. To check it use:
```bash
$ docker images
```

There should be a image listed called `piconut_image` listed with `~10Gb`.

4. Add GUI support: \
To run the Docker container with GUI support, you’ll need to configure X11 server access.
```bash
$ xhost +local:docker
```

### Workflow
1. Start the docker container: \
First, navigate to the PicoNut repository directory.

To start a docker container `docker compose` is used. If no container for the
`piconut_image` exists the `docker compose` command creates a container based on 
the previous built `piconut_image`. The created container is called `piconut_container`.
Else it just starts the container called `piconut_container`.
```bash
$ docker compose up -d
```

Note: The docker compose behaveiour is found in `docker-compose.yml`. If you want to mount
additional directories you can do this there.

2. Open a terminal inside the docker container:
   
To start a terminal, with `user` privilege, inside the `piconut_cotainer` type: \
Note: Use this in almost all cases.
```bash
$ docker exec -it piconut_container bash
```

To start a terminal, with `root` privilege, inside the `piconut_cotainer` type: \
Note: E.g. needed when you want to install additional packages etc.
```bash
$ docker exec -itu root piconut_container bash
```

The PicoNut repository is mounted to `~/ees/piconut`.

3. Use VSCode with docker container: \
When you don't use VSCode you can skip this part.

Install the VSCode extension `ms-vscode-remote.remote-containers`. 

When you start VSCode from the Piconut Project base directory. 
There will be a popup in the bottom left corner. Showing a button `Reopen in Container`. 
When it is clicked the VSCode connects to the container and you are working inside the container.

### Run reference design simulation

```bash
$ cd ~/ees/piconut/systems/refdesign/hw
$ make run-tb
```

If everything works, console should show the output of a simple hello world program.

## Native install

For native install you can install the packages and software by hand listed in `tools/docker/Dockerfile`.

### Run reference design simulation

```bash
$ cd <path-to-piconut-repository>/systems/refdesign/hw
$ make run-tb
```

If everything works, console should show the output of a simple hello world program.