Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.alexwennerberg.com/dusk-fun
Log | Files | Refs | README

guide.md (6517B) - raw

      1 # Introduction to Dusk OS (DRAFT)
      3 [Dusk OS](https://git.sr.ht/~vdupras/duskos) is a 32-bit Forth and C-based operating systemcreated by Virgil Dupras.
      5 ## Manifesto
      7 Dusk OS is designed to be maximally useful while being minimally complex. It
      8 builds from bare metal to a simple Forth-based operating system and C compiler
      9 in only a few thousand lines of code.
     11 Dusk's manifesto calls out the need for an operating system in a future of
     12 civilizational collapse. I take a somewhat different perspective: we are
     13 already living in a "collapse" of computing of a certain kind: foundational
     14 computing infrastructure is either abandoned, hardly maintained, or paid for
     15 and controlled by big tech interests. The average person has no access to a
     16 general-purpose computer and instead has their computing infrastrucure
     17 controlled by centralized cloud services. Thus, in my view, Dusk OS is not an
     18 OS for the future, it is an OS for the present.
     20 Because Big Tech controls so much of computing infrastructure, the structure of
     21 computing largely becomes the kind of technology that Big Tech is concerned
     22 with, ie, technology that is build in the context of a large tech organization
     23 staffed by professional engineers. In this way, computing becomes something
     24 professionalized, rather than something accessible to all. Dusk OS is a [Tool for
     25 Conviviality](https://en.wikipedia.org/wiki/Tools_for_Conviviality) -- a means
     26 to gain a stronger understanding of your computer and the computing needs of
     27 your community. 
     29 ## Getting started
     31 Virgil Dupras's
     32 [Substack](https://tumbleforth.substack.com/?utm_source=substack&utm_medium=web&utm_campaign=substack_profile)
     33 explains how to build up to Dusk OS from bare metal, and is, in my view, highly
     34 worth the subscription (which also supports Dusk's development).
     36 This guide takes the opposite approach: starting from your perspective as a user and working down. Let's start by cloning the repository.
     38 ```
     39 git clone https://git.sr.ht/~vdupras/duskos
     40 cd duskos
     41 ```
     43 Dusk has a system emulator that runs in a POSIX environment. All you should need is Make and a C compiler. Run:
     45 ```
     46 make run
     47 ```
     49 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.
     51 As a user, here's what you'll need to understand about Forth to get started.
     52 First, the primary programming language construct is a word. Words are
     53 separated by spaces. A word has a definition, and we can call that word
     54 directly. For example, we can type the word `words`, which prints all the words
     55 in the current dictionary namespace:
     57 ```
     58 words
     59 ```
     61 Forth uses postfix notation, which means that arguments are placed before the
     62 operator. For example, 2 + 3 in forth is instead written 2 3 +. Try it
     63 yourself:
     65 ```
     66 2 3 + . 
     67 ```
     69 The period is also a "word" that emits a number. The plus symbol is also a
     70 "word". The number literals are not words, but again, this guide will not teach
     71 you forth, just enough forth to interact with Dusk OS.
     73 So, we have our environment and we're able to execute words. Where do we start?
     74 Let's list some files.
     76 ```
     77 curpath :listdir
     78 ```
     80 Again, remember our postfix notation. The argument (which directory to target) comes before the operation (list files). Another example:
     82 ```
     83 p" doc" Path :listdir
     84 ```
     86 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.
     88 In order to change directories, we run chdir. Try experimenting with these various commands to see how the Dusk filesystem is laid out.
     90 ```
     91 p" doc" Path :chdir
     92 p" .." Path :chdir
     93 ```
     95 Return to the root directory for our next step, which will be editin files.
     97 Dusk has two editors:
     98 [ed](https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ed.txt?view-source#L1)
     99 and
    100 [ged](https://git.sr.ht/~vdupras/duskos/tree/master/item/fs/doc/text/ged.txt?view-source#L1).
    101 ed is a line-based editor, ged is a
    102 grid-based editor. We will start with ed. If you're not familiar with
    103 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.
    105 Let's get started with ed. First, how do we read files on the Dusk system?
    107 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:
    109 ```
    110 f<< text/ed.fs
    111 ```
    113 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:
    115 ```
    116 I Hello, World!
    117 ```
    119 This will print the contents of the current line, with a carat indicating the
    120 cursor position and then numbers indicating the current line number and the
    121 total number of lines in the buffer. Let's add text on another line with `o`:
    123 ```
    124 o I love Dusk OS!
    125 ```
    127 To read more of the buffer, we can print `pagesz` number of lines using the `p` word.
    130 Loading Files
    131 Printing files
    133 Lastly, lets introduce the Dusk C compiler. TBD. That's it!
    135 ## Conclusion
    137 Now that we're here, what's the point? Why use this extremely austere system?
    138 Dusk OS gives you a deep understanding of the 'guts' of its sytem. It is not
    139 unreasonable for one individual to understand, articulate and modify everything
    140 that we did today down to the bare metal. This is simply inconceivable in a
    141 modern UNIX system. It gives you a deep level of mastery and connection with
    142 your computer that I think we have lost. You can gain any level of
    143 understanding of Dusk OS that you like -- there are parts that are beyond me at
    144 this point etc. A good place to go further is the [Dusk OS
    145 Documentation](ADD HERE) as well as [Virgil Dupras's
    146 Substack](https://tumbleforth.substack.com/?utm_source=substack&utm_medium=web&utm_campaign=substack_profile).
    147 Some background knowledge in Forth and C are also required. If you lack that, I
    148 recommend "Starting Forth" and "The C Programming Language", respectively.
    150 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).