Getting Started With Dusk OS

Dusk OS is a 32-bit Forth and C-based operating system created by Virgil Dupras. This guide will provide a brief introduction and hopefully inspire interest in this system, which I find to be novel and exciting. We will be starting up Dusk OS under an emulator, editing some files, and executing Forth and C programs.

Manifesto

Dusk OS is designed to be maximally useful while being minimally complex. It builds from bare metal to a simple Forth-based operating system and C compiler in only a few thousand lines of code.

Dusk's manifesto calls out the need for an operating system in a future of civilizational collapse. I take a somewhat different perspective: we are already living in a "collapse" of computing of a certain kind: foundational computing infrastructure is either abandoned, hardly maintained, or paid for and controlled by big tech interests. The average person has no access to a general-purpose computer and instead has their computing infrastructure controlled by centralized cloud services. Most of computing seems to be about building more and more unsustainable abstractions on top of broken systems. Thus, in my view, Dusk OS is not an OS for the future, it is an OS for the present.

Because Big Tech controls so much of computing infrastructure, the structure of computing largely becomes the kind of technology that Big Tech is concerned with, ie, technology that is build in the context of a large tech organization staffed by professional engineers. In this way, computing becomes something professionalized, rather than something accessible to all. Dusk OS is a Tool for Conviviality -- a means to gain a stronger understanding of your computer and the computing needs of your community.

Getting started

Virgil Dupras's website and associated book explains how to build up to Dusk OS from bare metal. This guide takes the opposite approach: starting from your perspective as a user and working down. Let's start by cloning the repository. Note that Dusk OS is still under early and active development, so do not be surprised if you find bugs or issues.

git clone https://git.sr.ht/~vdupras/duskos
cd duskos

Dusk has a system emulator that runs in a POSIX environment. It requires Make and a C compiler. To get started, run:

$ make run

This will open the Dusk OS Forth environment using the POSIX emulator. This guide won't assume you have Forth knowledge, but it is essential to understanding Dusk more deeply. Pick yourself up a copy of Starting Forth for reading later.

As a user, here's what you'll need to understand about Forth to get started. First, the primary programming language construct is a word. Words are separated by spaces. A word has a definition, and we can call that word directly. For example, we can type the word words, which prints all the words in the current dictionary namespace:

$ words

Forth uses postfix notation, which means that arguments are placed before the operator. For example, 2 + 3 in forth is instead written 2 3 +. Try it yourself:

$ 2 3 + . 

. is also a "word" that emits a number. + is also a "word". The number literals are not words, but again, this guide will not teach you Forth, just enough forth to interact with and hopefully get you interested in Dusk OS. If you're familiar with UNIX, you can see how Dusk OS's forth interpreter is sort of like a unix shell with reversed syntax.

So, we have our environment and we're able to execute words. Where do we start? Let's list the files and directories at the current path.

$ curpath :listdir

Again, remember our postfix notation. The argument (which directory to target) comes before the operation (list files). Another example:

$ p" doc" Path :listdir

Let's break this command down. p" is a word that says to interpret a string as a path until the next double quote. Path is a struct (see Dusk's documentation on structs), which allows us to access namespace word :listdir. curpath is a Path that points to the current directory.

In order to change directories, we run chdir. Try experimenting with these various commands to see how the Dusk file system is laid out.

$ p" doc" Path :chdir
$ p" .." Path :chdir

Return to the root directory for our next step, which will be editing files.

Dusk has two editors: ed and ged. ed is a line-based editor, ged is a grid-based editor. We will start with ed. If you're not familiar with line-based editors (I wasn't) this may take some getting used to. The documentation for both are great and will cover in more detail than this guide does.

Let's get started with ed. Dusk as a file buffer that holds file content for reading and writing. By default, these tools are not imported, so we will need to load them with the following command:

$ f<< text/ed.fs

Now, let's write text to the buffer. This editor has a number of single-character helper words to handle writing. One of them is I, to insert text. Let's write:

$ I Hello, World!

This will print the contents of the current line, with a ^ indicating the cursor position and then numbers indicating the current line number and the total number of lines in the buffer. Let's add text on another line with o:

$ o I love Dusk OS!

To read more of the buffer, we can print pagesz number of lines using the p word. Let's move the cursor up 1 line and print what we have so far.

If you want to play around with ed and ged further, I recommend reading the docs listed above.

The POSIX emulator is quite limiting, for example: it is a read-only file system. For our next tasks, editing code and executing a C compiler, we will need to run Dusk on QEMU. Make sure you get qemu-system-i386 via your package manager, then run make pcrun. This is a more full-fledged dusk system running on emulated hardware.

Let's start editing code. I'm going to use the root directory as our working directory. Let's make a forth file and a c file and execute both.

$ f<< text/ed.fs \ import ed.fs if it isn't already
$ S" hello.fs" curpath :newfile \ Create a file
$ f" hello.fs" edload \ Load it into the text buffer
$ I : hello ." Hello, World!\n"; \ Write to the text buffer
$ edsave \ save the text buffer to disk
$ f<< hello.fs
$ hello
Hello, World! 

We have written our first forth word and saved it to disk. Now, let's introduce Dusk's C compiler and compile a C program. Dusk's C compiler compiles C code to Forth words, smoothly integrating the two languages. For example, let's write an adder function and compile it in-line.

$ f<< comp/c/cc.fs \ import Dusk's C compiler
$ :c int adder(int a, int b) { return a + b; }
$ 4 5 adder . \ prints 9

:c is a word that compiles C code directly from the forth interpreter. For more information about Dusk's C compiler and dialect of C, see the relevant Dusk OS documentation.

Finally, let's write our hello world program in C and save it to disk.

$ f<< comp/c/lib.fs \ import libc functions, including printf
$ S" hello.c" curpath :newfile
$ f" hello.c" edload
$ I int helloc() { printf("Hello, C!\n"); return 0; } 
$ edsave
$ cc<< hello.c
$ helloc 
Hello, C!

Conclusion

Hopefully now you have the ability and interest to explore Dusk further. Dusk OS is still a new system and under active development and we have only scratched the surface here. Ultimately, Dusk OS is designed to run on bare metal, but currently the hardware that it supports is limited, although Raspberry Pi support is in progress. See the deploy guide for more info.

So, what's the point? Why use this extremely austere system? Dusk OS gives you a deep understanding of its underlying code. It is not unreasonable for one individual to understand, articulate and modify everything that we did today down to the machine. This is simply inconceivable in a modern UNIX system, or really anything that isn't a microprocessor. What's exciting about Dusk OS to me is the prospect of a maintainable, repairable, comprehensible system that is still capable of doing pretty substantial computing tasks.

I am still new to Dusk OS, but I'm excited to explore it further. A good place to look is the Dusk OS Documentation. Some background knowledge in Forth and C are also required. If you lack that, I recommend "Starting Forth" and "The C Programming Language", respectively. I'm happy to help and answer questions about Dusk. If you have any questions or feedback, please email alex@alexwennerberg.com.