# Dusk OS

Dusk OS is a 32-bit Forth and big brother to Collapse OS[1]. Its primary purpose
is to be maximally useful during the first stage of civilizational collapse,
that is, when we can't produce modern computers anymore but that there's still
many modern computers around.

It does so by aggressively prioritizing simplicity at the cost of unorthodox
constraints, while also aiming to make operators happy.

Dusk OS innovates by having an "almost C" compiler allowing it to piggy-back on
UNIX C code, through a modest porting effort, to reach its goals and stay true
to its design constraints with a minimal effort.

This is Dusk OS' source code and the rest of the README assumes that you want to
run it. To read more about why this OS exists, see its gopherhole[2]. To read
more about the design constraints of this OS, see the "fs/doc/design" directory
of this project.

[1]: http://collapseos.org
[2]: gopher://self.duskos.org

## Build and run Dusk

Dusk is designed to run on bare metal and to build itself from itself.  However,
it's also possible to build Dusk from any POSIX platform using Dusk's POSIX VM
from posix/vm.c. This VM implements a Forth that can interpret the whole of
Dusk's Forth code in a CPU-agnostic manner.

That is enough to generate bare metal images for any of its target platforms,
so that's why it exists. To build this VM, you need:

* Make (GNU or BSD)
* A C compiler
* tar

Running "make" will yield a "./dusk" binary which if executed, provides an
interactive prompt.

Documentation lives in "fs/doc/". You can begin with index.txt.

Type "bye" to quit.

Dusk OS expects a non-canonical raw input. With a regular TTY, your input will
be buffered and echoed twice and reads to it will be blocking. We don't want
that. To avoid that, you can invoke it like this:

  (stty -icanon -echo min 0; ./dusk; stty icanon echo)

"make run" does this for you.

## Running the "SDL" flavor

The basic POSIX Dusk deals with streams only. You can't use the grid or
graphics from within there. However, it's possible to build a "SDL" version of
Dusk that has these capabilities. See posix/README for details.

## Running on Usermode

Graphics from within SDL, cool right? It gets even better: Usermode Dusk allows
you to run these things at *native speed*. See usermode/README for details.

## Running on bare metal

Even if Dusk is super powerful even within the constraints of a POSIX
environment, it unleashes its full powers on bare metal.

Deploying Dusk on a real machine is a bit more involving than running the POSIX
VM and you should read doc/deploy.txt. There's a collection of deployment
configurations in the "deploy" directory to help you get started on deploying
Dusk OS to your machine.

This directory contains a few targets with convenient QEMU launchers, so this
can be a good way to quickly see a fully featured Dusk OS in action.

## Trusting this code

The release tags on this git repo used to be signed, but they aren't anymore.
If you wonder how you can trust this software package, see the TRUST file.