Goose documentation

Goose is a memory-safe systems language with no heap allocator, garbage collector or lifetime annotations (what it is and why). This page is the map of its documentation. The language is described four times, at increasing depth, and the rest of the documents cover the library, the tools and the compiler.

The language, in reading order

Document	What it is	Read it when
README	What Goose is and why, in one page, with the numbers.	You want to know whether to look further.
Tutorial	The language by example, concentrating on what is different about Goose: where values live, the array family, references that survive growth, enums in two sizes, `return … from`, threads.	You are starting. An afternoon's read.
Language reference	Every feature, topic by topic, with a compiling example for each: the whole language laid out to be read, with a pointer into the specification for every rule.	You know the basics and want all of it, or want to look something up.
Specification	The exact rules, in the language an implementor needs: size classes, construction, the lifetime and shrink rules, the compilation model, the representation.	You want to know why something did not compile, or are writing an implementation.

Library and tools

Standard library: the fifteen modules, std, dictionary, vec, math, os, binary, base64, csv, json, regex, exception, and gfx, audio, physics and ui for graphics, sound, rigid bodies and widgets. All readable Goose under stdlib/.
Building programs and using packages: goose build, libraries from git repositories or directories, a program's own C, and how to make a package.
Samples: thirty-one complete programs in reading order, from a tour of the language to a JSON parser, a threaded Mandelbrot, a spinning cube and two small games.
VS Code extension: highlighting, checks on save, and one-key runs.
Other editors: the language server in Neovim, Helix and Emacs.

Benchmarks

Summary: what the sixteen benchmarks show, gains and losses, and why.
Results: every measurement, against idiomatic and expert C++ and against safe Rust.
Design: what the suite tests and how it is run.

The compiler

Implementation notes: how the compiler works, pass by pass: the typechecker's roots and provenance, the shrink rules, the optimizer, bounds-check elimination, code generation and the runtime.
Testing: the test suite, its fixtures and how to run it.

Design notes

The reasoning behind features, kept as it was written. The specification and the reference describe what was built; these say why.

Index types and checkfree functions: bounds checks moved to where data enters the program, and functions the compiler proves check-free.
const for: specialization-time expansion over a struct's fields, an enum's variants, a list of types or a list of constants.
Relative references: self-relative against pool-relative links, measured.
Serialization: the verified loader for structures of relative references.
Namespaces: minimal namespaces and qualified names.
Builds and packages: the design behind goose build and packages from git.
The in-process backend: how TinyCC runs a program inside the compiler, and what it cannot do.
String constants, writability and threads: why read-only data cannot be laundered into writable data.
Independently owned dynamic data: an editor's open documents as a worked example of slice pools.
Standard library design: the library's original scope and conventions.
Compiler analyses: an inventory of the checker's analyses and options for simplifying them.
Column arrays: a struct-of-arrays storage proposal, not implemented.
WebAssembly: running without address-space reservation, fixed partitions against relocating stacks; a proposal.
Prior art: the languages, libraries and papers nearest Goose's memory model, ranked, and what has no precedent.

Getting the compiler

Prebuilt compilers for Windows, Linux and macOS are on the releases page; the README says what each platform needs beside them, and how to build from source. Questions and discussion: the Discord and the GitHub repository.

These pages are built from the repository's markdown by docs/site/build.py, so the same files read on GitHub and here.