# Dusk Deployments

This is a list of [Dusk OS][dusk] configurations for specific machines. Dusk
OS doesn't do any kind of auto-probing, so you have to know your hardware and
adjust configuration appropriately. You can use this repository as an
inspiration for your own deployments.

This code is available from [Dusk OS' files folder][files] or as a Git
repository ([without SSL][ssl]) at:

	git://git.duskos.org/duskos-deployments.git

If you have a deployment that isn't an exact copycat of something that is
already in there, please send it to me, I'll merge it in. The more the merrier.

[dusk]: http://duskos.org
[ssl]: http://duskos.org/ssl.html
[files]: http://duskos.org/files/

## Separation of concerns

The idea behind this separate repository is to avoid polluting Dusk OS's code
with the myriad of possible configurations for a given system and have a
"bazaar" of configurations here. Configurations are something that you'll want
to maintain personally, but it's much easier to build a configuration if you
have a wide selection of examples to choose from.

What we *do* want in Dusk OS directly are tools to work with specific machines.
A machine running Dusk OS and having its whole `fs` directory should have all
as many tools as possible to work with specific machines.

In short, configurations come in here, tools stay in Dusk OS.

### The case of the Raspberry Pi

Raspberry Pi need opaque firmware on their boot partitions. Generally, if you
have a Raspberry Pi, you have those `bootcode.bin` and `start.elf` file, but
it's possible that you don't. So if you don't have them handy, it's nice that
Dusk comes with it. But where should it go, Dusk OS or Dusk Deployments?

On the one hand, if you're stuck with only a machine running Dusk OS and a
Raspberry Pi with no firmware file, you need those files to deploy Dusk OS. So
on the first look, they should go in Dusk OS.

But on the other hand, these files are deeply tied to the machine. If you have
one without the other, you have a broken machine. Should Dusk OS also carry
backup dumps of PC BIOS ROM in case you have a machine with a corrupted BIOS? I
don't think so.

Therefore, these files live in Dusk Deployments.

## Code duplication

All configurations committed here have been tested on their target machine.
There isn't supposed to be any broken configuration in this repo, only
configurations targeting older Dusk releases.

The broad idea behind this repo is that testing configurations on real hardware
is time consuming. We want to minimize dependency chains, as in "I need to test
that thing on hardware X Y and Z before I can mark it as correct".

Therefore, we allow different configurations to target different Dusk releases.
When we happen to dust off a particular hardware, we "bump" the release.

This design also forces us to minimize code reuse and accept code duplication.
If we share code between two configurations, it also means that we will need to
update and test them together.

For some configurations that are very close to each other, such as `pc-piix`
and `pc-bios`, we do share. But most of the time, we will just copy and paste
configurations around to minimize coupling.

## Usage

Each deployment has its own directory with its own Makefile which targets a
specific version of Dusk, that is, the last version this hardware has been
tested as "correct" on.

To build a deployment configuration, you need:

* a C compiler
* Make (BSD or GNU)
* A way to fetch a file from http: either `curl`, `wget`, or BSD's `ftp`.
* [mtools](https://www.gnu.org/software/mtools/)

Dusk OS has the ability to copy itself into a FAT without external tooling, but
the makefiles in this repo don't bother using this capability and use mtools
instead as its an easier fit with POSIX makefiles.

Then, `cd` into the directory and run `make`. This should yield an image which
you can deploy on your target media.

Each subdirectory has a README with hardware and deployment details.

### Emulation

Some targets can readily emulated via QEMU. Such target indicate `(QEMU)` next
to their name in the list below. In such target, in addition to the regular
`make` target, you can also run `make emul` to launch QEMU with the right
parameters to run it.

## Deployment list

### i386

* `pc-bios`: Barebone PC and BIOS diagnostic tools (QEMU)
* `pc-piix`: PC of the "PIIX" architecture (QEMU)
* `pc-floppy`: Example floppy PC deployment (QEMU)
* `hp-mini-2103070`: HP Mini 210-3070
* `pcengine-alix`: PC Engine's Alix board

### ARM

* `rpi`: Raspberry Pi (Model 1, 2, 3) (QEMU)
* `pine64`: Pine A64 LTS (WIP)