git.alexw.nyc home about git garden 
    1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
  100
  101
  102
  103
  104
  105
  106
  107
  108
  109
  110
  111
  112
  113
  114
  115
  116
  117
  118
  119
  120
  121
  122
  123
  124
  125
  126
  127
  128
  129
  130
  131
  132
  133
  134
  135
  136
  137
  138
  139
  140
  141
  142
  143
  144
  145
  146
  147
  148
  149
  150
  151
  152
  153
  154
  155
  156
  157
  158
  159
  160
  161
  162
  163
  164
  165
  166
  167
  168
  169
  170
  171
  172
  173
  174
  175
  176
  177
  178
  179
  180
  181
  182
  183
  184
  185
  186
  187

<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <link rel="stylesheet" type="text/css" href="../style.css">
    <link rel="icon" type="image/png" href="../icon.png">
    <title>alexw.nyc</title>
  </head>
<body>
  <header>
    <table><tr><td><a href="../index.html"><img src="../icon.png" width=20 /></a></td>
			<td>alexw.nyc</td>
			<td><a href="../index.html">home</a></td>
			<td><a href="../about.html">about</a></td>
			<td><a href="../garden.html">garden</a></td>
		</tr></table>
  </header>
<main>
<h1>Getting Started With Dusk OS</h1>
<p><a href="https://git.sr.ht/~vdupras/duskos">Dusk OS</a> 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.</p>
<h2>Manifesto</h2>
<p>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.</p>
<p>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.</p>
<p>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 <a href="https://en.wikipedia.org/wiki/Tools_for_Conviviality">Tool for
Conviviality</a> -- a means
to gain a stronger understanding of your computer and the computing needs of
your community. </p>
<h2>Getting started</h2>
<p>Virgil Dupras's
<a href="https://duskos.org/">website and associated book</a>
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.</p>
<p><pre>
git clone https://git.sr.ht/~vdupras/duskos
cd duskos
</pre></p>
<p>Dusk has a system emulator that runs in a POSIX environment. It requires Make and a C compiler. To get started, run:</p>
<p><pre>
$ make run
</pre></p>
<p>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 <a href="https://www.forth.com/starting-forth/">Starting Forth</a> for reading later.</p>
<p>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 <code>words</code>, which prints all the words
in the current dictionary namespace:</p>
<p><pre>
$ words
</pre></p>
<p>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:</p>
<p><pre>
$ 2 3 + . 
</pre></p>
<p><code>.</code> is also a "word" that emits a number. <code>+</code> 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.</p>
<p>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.</p>
<p><pre>
$ curpath :listdir
</pre></p>
<p>Again, remember our postfix notation. The argument (which directory to target) comes before the operation (list files). Another example:</p>
<p><code>
$ p" doc" Path :listdir
</code></p>
<p>Let's break this command down. <code>p"</code> is a word that says to interpret a string as a path until the next double quote. <code>Path</code> is a struct (see Dusk's <a href="https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/struct.txt?view-source#L1">documentation</a> on structs), which allows us to access namespace word <code>:listdir</code>. <code>curpath</code> is a <code>Path</code> that points to the current directory.</p>
<p>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>
<p><pre>
$ p" doc" Path :chdir
$ p" .." Path :chdir
</pre></p>
<p>Return to the root directory for our next step, which will be editing files.</p>
<p>Dusk has two editors:
<a href="https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ed.txt?view-source#L1">ed</a>
and
<a href="https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ged.txt?view-source#L1">ged</a>.
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.</p>
<p>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:</p>
<p><pre>
$ f&lt;&lt; text/ed.fs
</pre></p>
<p>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 <code>I</code>, to insert text. Let's write:</p>
<p><code>
$ I Hello, World!
</code></p>
<p>This will print the contents of the current line, with a <code>^</code> 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 <code>o</code>:</p>
<p><code>
$ o I love Dusk OS!
</code></p>
<p>To read more of the buffer, we can print <code>pagesz</code> number of lines using the <code>p</code> word. Let's move the cursor up 1 line and print what we have so far.</p>
<code>
$ 1 l- p
</code>
<p>
If you want to play around with ed and ged further, I recommend reading the docs listed above.</p>

<p>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 <a href="https://www.qemu.org/">QEMU</a>. Make sure you get qemu-system-i386 via your package manager, then run <code>make pcrun</code>. This is a more full-fledged dusk system running on emulated hardware.
</p>

<p>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.</p>

<pre>
$ f&lt;&lt; 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&lt;&lt; hello.fs
$ hello
Hello, World! 
</pre>

<p>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.</p>
<pre>
$ f&lt;&lt; comp/c/cc.fs \ import Dusk's C compiler
$ :c int adder(int a, int b) { return a + b; }
$ 4 5 adder . \ prints 9
</pre>

<p><code>:c</code> 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 <a href="https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/cc/usage.txt">Dusk OS documentation</a>.
<p>Finally, let's write our hello world program in C and save it to disk.</p>

<pre>
$ f&lt;&lt; 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&lt;&lt; hello.c
$ helloc 
Hello, C!
</pre>

<h2>Conclusion</h2>
<p>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 <a
href="https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/deploy.txt">deploy
guide</a> for more info.</p>

<p>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.</p>

<p>I am still new to Dusk OS, but I'm excited to explore it further. A good place to look is the <a href="https://duskos.org/">Dusk OS
  Documentation</a>. 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 <a href="mailto:alex@alexwennerberg.com">alex@alexwennerberg.com</a>.</p>
</main>
<footer>
<a href="/tech/infra.html">live</a> from beautiful brooklyn, new york
<a href="mailto:alex@alexwennerberg.com">email</a>
<a href="https://merveilles.town/@aw">mastodon</a>
</footer>
</body>
</html>