commit 299f1d65d71999c59adcf65fdd22d1ff3bb1c068
parent 11e955c8eeb34431218cb257898257ddc27ab9c2
Author: alex wennerberg <alex@alexwennerberg.com>
Date: Mon, 1 May 2023 20:04:26 -0400
extend duskos guide
Diffstat:
| M | guide.md | | | 101 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------- |
1 file changed, 73 insertions(+), 28 deletions(-)
diff --git a/guide.md b/guide.md
@@ -1,34 +1,30 @@
-# Introduction to Dusk OS
+# Introduction to Dusk OS (DRAFT)
[Dusk OS](https://git.sr.ht/~vdupras/duskos) is a 32-bit Forth and C-based operating systemcreated by Virgil Dupras.
## Manifesto
-Dusk OS is designed to be maximally useful with as simple of an architecture as possible. It builds from bare metal to a simple Forth-based operating system and C compiler.
+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: software builds
-upon greater and greater towers of abstractions and few people are concerned
-simplifying things or returning to foundational principles. Foundational
+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 infrastrucure
-controlled by centralized cloud services, and almost all computing
-infrastructure is in some way compromised (funded and controlled) by big tech
-interests. Thus, in my view, Dusk OS is not an OS for the future, it is an OS
-for the present.
+controlled by centralized cloud services. 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
+professionalized, rather than something accessible to all. Dusk OS is a [Tool for
Conviviality](https://en.wikipedia.org/wiki/Tools_for_Conviviality) -- a means
-to gain control and understanding of your computer and the computing needs of
-your community. It is relatively early in its development, but it brings me a lot of excitement.
+to gain a stronger understanding of your computer and the computing needs of
+your community.
## Getting started
@@ -37,8 +33,7 @@ Virgil Dupras's
explains how to build up to Dusk OS from bare metal, and is, in my view, highly
worth the subscription (which also supports Dusk's development).
-This guide takes the opposite approach -- starting from a user's perspective and then working down. Let's start by cloning the repository.
-
+This guide takes the opposite approach: starting from your perspective as a user and working down. Let's start by cloning the repository.
```
git clone https://git.sr.ht/~vdupras/duskos
@@ -53,40 +48,91 @@ make run
This will open the Dusk OS Forth REPL. 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](https://www.forth.com/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. A word has a definition, and we can call that word directly. For example, we can call the word "words", which prints all the words in the current dictionary namespace:
+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 has a 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:
+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 + .
```
-The period is also a "word" that emits a number. The plus symbol 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 the Dusk OS system, coming from a POSIX-like environment.
+The period is also a "word" that emits a number. The plus symbol 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 Dusk OS.
-So, we have our environment and we're able to execute words. Where do we start? Let's list some files.
+So, we have our environment and we're able to execute words. Where do we start?
+Let's list some files.
```
curpath :listdir
```
-Again, remember our postfix notation. Think of this as analogous to the unix command "ls [path]: -- the path instead comes before the operator. Another example:
+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. TODO
+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](https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/struct.txt?view-source#L1) 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 filesystem is laid out.
+
+```
+p" doc" Path :chdir
+p" .." Path :chdir
+```
-Next: Change Dirs, List files, cat/head files
+Return to the root directory for our next step, which will be editin files.
-Dusk has two editors: ed and ged. ed is a line-based editor, ged is a
+Dusk has two editors:
+[ed](https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ed.txt?view-source#L1)
+and
+[ged](https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ged.txt?view-source#L1).
+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 excellent and will cover in more detail than this guide does.
+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. First, how do we read files on the Dusk system?
+
+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 carat 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.
+
+
+Loading Files
+Printing files
+
+Lastly, lets introduce the Dusk C compiler. TBD. That's it!
+## Conclusion
Now that we're here, what's the point? Why use this extremely austere system?
Dusk OS gives you a deep understanding of the 'guts' of its sytem. It is not
@@ -96,10 +142,9 @@ modern UNIX system. It gives you a deep level of mastery and connection with
your computer that I think we have lost. You can gain any level of
understanding of Dusk OS that you like -- there are parts that are beyond me at
this point etc. A good place to go further is the [Dusk OS
-Documentation](https://oldbytes.space/@rc2014) as well as [Virgil Dupras's
+Documentation](ADD HERE) as well as [Virgil Dupras's
Substack](https://tumbleforth.substack.com/?utm_source=substack&utm_medium=web&utm_campaign=substack_profile).
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. Feel free to email me at
-alex@alexwennerberg.com
+I'm happy to help and answer questions about Dusk. If you have any questions or feedback, please email [alex@alexwennerberg.com](mailto:alex@alexwennerberg.com).
