# Directory structure

UNIX platforms have a very specific directory structure, its root directories
discriminating between fundamental roles for files in them. For example, /lib is
for libraries, /bin is for binaries.

In Forth, every word defined by a unit is potentially usable interactively,
which makes the whole /lib vs. /bin distinction rather moot. Everything is
executable.

Because the breadth of applications included directly in Dusk OS is rather small
and that "user files" will typically be on a separate volume, we give ourselves
a wide root directory structure based on general topics of the included code.

/ar    Archive access
/asm   Assemblers
/bin   Binary blobs processing
/com   Communicate
/comp  Compilers
/cos   Collapse OS (see doc/cos/intro)
/doc   Documentation
/drv   Drivers
/emul  Emulators
/fs    Filesystems
/gr    Graphics
/home  Virgil's workspace
/lib   Miscellanous little routines
/mem   Memory management and data structures
/sys   Subsystems
/tests Automated tests
/text  Text processing
/xcomp Cross compilation

## /ar -- Archive access

Provides decoding (and sometimes encoding) access to data structured in
particular manner. In this section fits:

* Compression and decompression
* tar
* Document formats such as MS Word and PDF

## /asm -- Assemblers

Provides assemblers for different CPUs or VMs. Those will convert mnemonics into
native bytecode.

Disassemblers also go there.

## /bin -- Binary blobs processing

Provides facilities to process binary blobs. Hex editors go there.

## /com -- Communicate

Provide facilities for communicating with other machines.

## /comp -- Compilers

Provides compilers for different languages such as DuskC. Those compilers will
typically use assemblers to yield native bytecode.

## /doc -- Documentation

Dusk documentation in text format.

## /drv -- Drivers

Drivers for supported peripherals. For each supported architecture, there's a
subdirectory. Drivers will be placed in the most general directory possible for
that peripheral.

## /emul -- Emulators

Provides facilities for emulating a machine. This includes CPU and peripheral
emulation logic.

## /fs -- Filesystems

Filesystem implementations, which run on top of storage drivers.

## /home -- Virgil's workspace

The contents of this directory is not really a part of Dusk because it
represents the "work" files that Dusk's main author uses when working within
Dusk. It's included in Dusk's packages because it's a good example of how Dusk
ought to be used effectively.

## /lib -- Miscellanous

If a unit doesn't go anywhere else, it goes in /lib.

## /mem -- Memory management and data structures

Allocators and generic data structures go there.

## /pic -- Picture processing

Provides facilities to decode data representing pictures.

## /sys -- Subsystems

Subsystems are units that modify the system in an important way and will
typically be loaded by the operator (in the init.fs unit for example) rather
than by another unit. Therefore, we will generally see "require /sys/..."
instead of "?f<< /sys/..." (see [doc/sys/file]).

There are two broad subsystem types: driver subsystems and "innards" subsystems.

Driver subsystems unify the API coming from various drivers. /sys/kbd,
/sys/grid, sys/screen, sys/timer are driver subsystems. What makes them a
subsystem is inherently clear.

"Innards" subsystems come and muck with the innards of the system to change its
behavior. You don't want such logic to be automatically applied as a transitive
dependency to another piece of code. you want, as an operator, to explicitly
muck with those innards.

/sys/rdln is a subsystem because it changes the whole interpret loop.
/sys/loop is a subsystem because it changes the meaning of the "idle" word.

sys/io and sys/file are fuzzier, but because they are foundational to the
bootstrapping process, they have their place there.

## /tests -- Automated tests

Collection of tests for all units in the system. Its directory structure mirrors
the root structure. Each directory has a "all.fs" unit that includes all units
of the directory. Loading "/tests/all.fs" runs all tests in the system.

## /text -- Text processing

Provides facilities to process and vizualize textual data. Text editors go
there.

## /xcomp -- Cross compilation

Provides facilities to cross compile Dusk to any of the supported target
machines.
