# Dusk OS usage

Dusk OS is a Forth that generally follows conventions described in "Starting
Forth" by Leo Brodie, except that words are in lowercase. If you don't know
Forth, it's recommended that you start there. Dusk's documentation assumes this
knowledge.

Then, you can look at [doc/dict] to get an broad idea of the vocabulary that is
available to you. You will recognize many words in there from Starting Forth and
should be able to get started after that.

That being said, Dusk OS has some additional features and peculiarities that
need explaining.

## Subroutine Threaded Code

This Forth is a Subroutine Threaded Code (STC) Forth, that is, each reference to
words is a native call instead of being a reference. The drawback to this
structure, compared to DTC or ITC forths, is significantly bigger binary size.
It's also more complex to "disassemble" a compiled word. The upsides, however,
are real juicy.

First, there's speed. Calling words natively is faster than going through DTC or
ITC's "next" routine.

Second, and most importantly, there's the ability for forth code to freely mix
up with native code. That's huge and we use this extensively in Dusk through
its meta compilation capabilities, which is what the HAL is all about.

## The HAL

Dusk features a Harmonized Assembly Layer on which DuskCC [doc/comp/c] relies
and allows some really nice tricks. For regular usage, HAL knowledge isn't
needed, so it's not covered here. However, you should know that it's a central
feature of Dusk.  You can read about it in [doc/hal].

## Usage guide index

lit    Literals and strings
flow   Control flow
iter   Iterators
mem    Accessing memory
word   What's in a word?
bind   Binding data to behavior
data   Fundamental data structures
rs     Playing with the Return Stack
bwm    Binary Width Modulation
imm    Immediate mechanics
ns     Namespaces and Structures
io     Input/Output
file   Files

## What now?

This document covers Dusk's basic functionalities. You can try a few things in
the interpreter, but you are hungry for more. What to read next?

* Take a look at doc/dict to have an idea of available base words.
* doc/sys/io is central to many, many things in Dusk.
* doc/sys/file lets you play with the filesystem.
* doc/mem/alloc covers dynamic memory allocation.
* doc/hal covers the HAL on which the coolest Dusk features rely.
* doc/comp/c covers Dusk's C compiler.
* doc/text/ed to edit text files.
* doc/code explains how to grok Dusk's code.

There are many more subjects covered by this documentation, but these listed
above should be read first. As for the rest, I'll let you browse.
