# 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. Almost 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.

The contents of all subdirectories listed below, except "doc" and "data" is
source code.

/ar    Archive access
/asm   Assemblers
/bin   Binary blobs processing
/com   Communicate
/comp  Compilers
/cos   Collapse OS (see doc/cos/intro)
/data  Non-executable data
/doc   Documentation
/drv   Drivers
/emul  Emulators
/fs    Filesystems
/gr    Graphics
/home  Examples
/io    Input/Output
/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.

## /data -- Non-executable data

The vast vast majority of Dusk's content is source code compiling to executable
words. But sometimes, we need a place to put non-executable data. This is this
place.

This directory as well as all its subdirectories, contain a "desc.txt"
containing the description of all files contained in that directory.

## /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. Filesystems are
often accompanied by tools, which will also live in the "fs" directory, but in
a separate unit with a "t" suffix. For example, "/fs/fatt.fs" is the unit for
FAT tools.

In short, anything revolving around [doc/fs/core].

## /home -- Examples

This directory contains a few example usage of Dusk's API for concrete purposes.
These is no associated documentation, see source comments.

It's also a good place to place "work files" specific to your own system.

## /io -- Input/Output

Units revolving around stream IOs (io/stream) or sector IOs (io/drive).

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

## /sys -- Subsystems

This directory is the remnants of an outdated concept. It will soon disappear as
its units are moved elsewhere.

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