Skip to content
Dusk

Documentation

Dusk is a small systems language that compiles to native code. The documentation is split into four sections: guides teach the language by task, the language reference states the rules precisely, the standard library pages document each shipped module’s API, and tooling covers the compiler CLI, the dawn package tool, and the roadmap.

Guides

Section titled “Guides”

Task-oriented walkthroughs, in roughly the order you will want them. New to Dusk? Start with Getting started and the Language tour.

  • Getting started: install the toolchain and run your first program.
  • Language tour: a quick pass over the core features, with small verified programs at each stop.
  • Paradigms: how paradigm directives gate procedural, functional, and OOP features per file.
  • Memory: alloc, free, defer, allocators, arenas, ownership, and the generational heap.
  • Errors as values: (T, error) returns and the must-handle rule.
  • Concurrency: threads, channels, mutexes, atomics, and the thread pool.
  • Async: async func, await, and the event loop.
  • Unicode and runes: the rune primitive, Unicode scalar literals, and decoding UTF-8 strings.
  • Packages with Dawn: importing code and fetching external packages from git.
  • Examples tour: a guided walk through the repository’s runnable programs.

Language reference

Section titled “Language reference”

The normative description of the language. Where a guide and a reference page cover the same ground, the reference is the one that states the exact rules.

  • Overview and philosophy: design pillars, compilation model, and current status.
  • Source files and modules: file structure, import resolution, export, and file privacy.
  • Paradigm system: what each paradigm directive unlocks and how gating works.
  • Type system: primitives, inference, strings, fixed arrays and slices, and the two pointer layers.
  • Operators: the full operator set, the 13-level precedence ladder, and associativity.
  • Enums and match: sum types with payload-carrying variants and exhaustive match.
  • Memory management: allocation, the Allocator interface, ownership, and generational safety.
  • The collected heap: the second managed heap, the collector<T> wrapper, and its main-thread confinement.
  • Foreign functions: calling C from Dusk, variadic functions, structs by value, callbacks, and the @link and @csource directives.
  • C libraries: the boundary read the other way, export "C" and dusk build --lib compiling a module into a static archive and a generated header.
  • Functions: declaration syntax, pass-by-value semantics, and lambda capture.
  • Interfaces and structs: impl blocks, vtable dispatch, and the no-inheritance rule.
  • Functional concepts: map, filter, reduce, fold, foreach, monad blocks, and do notation.
  • Error handling: the error type, fallible functions, and must-handle enforcement.
  • Threads and the memory model: spawn, join, channels, mutexes, the pool, and the memory model.
  • Async: async func, await, async_run, and the deadlock gate.
  • Builtins: every compiler-provided function and which paradigms gate it.

Standard library

Section titled “Standard library”

API pages for the modules shipped under lib/std, all written in Dusk itself.

  • Overview: what ships, how imports work, and what is planned next.
  • std.io: console printing, typed line input, and the file and stdin builtins.
  • std.logging: leveled logging to stderr with a process-wide threshold.
  • std.string: searching, trimming, splitting, joining, and case folding, plus number parsing and the StringBuilder mutable string.
  • std.unicode: rune decoding and encoding, UTF-8 validation, and codepoint counts.
  • std.math: the libm scalar float64 functions, the pi and e constants, and the NaN and infinity predicates.
  • std.rand: an xoshiro256** pseudorandom generator over a heap Rng.
  • std.vector and std.map: the growable array and the hash map, generic over both key and value.
  • std.fs: files, directories, file_stat, directory iteration, and path arithmetic.
  • std.process: running a shell command as a child process and reading its output line by line.
  • std.time: UTC wall clock reads, a proleptic Gregorian calendar, and ISO 8601 formatting.
  • std.json: parsing and emitting JSON over a recursive Json enum.
  • std.memory: the allocator module, the arena allocator, and the collector’s live-heap stats.
  • std.functional: the Maybe, Either, and Result monadic types.
  • std.concurrent: atomics, sleep, channels, mutexes, condition variables, and the thread pool.
  • std.async: futures, the event loop, async sleep, the epoll reactor, and TCP networking.

Tooling

Section titled “Tooling”

The programs around the language.