# Mittos toolchain

> - [Mittos64 documentation chapter 1](https://github.com/thomasloven/mittos64/blob/master/doc/1_Toolchain.md).

Building and emulating/debugging Mittos is done with Docker and docker-compose.

Two containers are defined in the compose file `/toolchain/docker-compose.yml`

To build them run
```
> docker-compose -f toolchain/docker-compose.yml build
```

The build image (`thomasloven/mittos-build`) derives from Alpine. \
It includes a custom compiled version of gnu binutils and gcc, so it will take a few minutes to build. It also includes grub-bios and xorriso in order to build a bootable image as well as python3, git and rsync.

The run image (`thomasloven/mittos-run`) derives from Debian. \
It includes qemu and gdb for testing and debugging. It also includes novnc and will serve a HTTP vnc server on port 6080 for graphical output from qemu.

## Building
Run
```
> ./make
```
This will run the make command inside a mittos-build container. Any arguments (e.g. `make kernel`) will be forwarded.

If the first argument is a dash, the following command will be run instead of `make`. E.g. `make - sh` to open a shell in the build container.

## Testing
To run the built Mittos in qemu, run
```
> ./emu
```
This will launch `qemu` inside a mittos-run container. An interface to qemu is published to [http://localhost:6080](http://localhost:6080) and also to the terminal output.

The emulator is setup to not start running until a debugger has attached. Do this with
```
> ./dbg
```
which launches `gdb` and attaches it to the running container.

Both commands pass any arguments to `qemu` or `gdb` respectively unless the first argument is `-` in which case the following command override the default.
Note that the dbg script will always wait for a qemu debug connection to be available before starting, though.

## Running on real hardware
The image created by `make dist` should work when burned to a USB stick and booted on a BIOS machine.

For booting on a UEFI machine, you need to create a bootable USB stick from a machine with grub-uefi installed.

Format your stick with a single FAT partition `sd<XX>` and mount it to `/media/<MOUNTPOINT>`. Then run:

```
> sudo grub-install --no-floppy --root-directory=/media/<MOUNTPOINT> --recheck --force --target=i386-pc /dev/sd<XX>
```

You can then put Mittos on it (and sync changes) with
```
> rsync -urv sysroot/ /media/<USB stick mountpoint>
```


## Relevant files:

- `toolchain/docker-compose.yml`
    - `toolchain/Dockerfile.build`
        - `toolchain/build-toolchain.sh`
    - `toolchain/Dockerfile.run`
        - `toolchain/run-entrypoint.sh`
- `make`
- `emu`
- `dbg`
- `Makefile`
- `src/kernel/Makefile`
- `toolchain/setup-grub.sh`
- `toolchain/gdbinit`