Goose documentation

Goose is a memory-safe systems language with no heap allocator, garbage collector, or lifetime annotations (what it is and why). Start with the language guides below, arranged from introduction to detailed specification. The other documents cover the library, tools, and 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 new to Goose. It takes about an afternoon to read.
Language reference	Every feature, topic by topic, with a compiling example for each. It covers the whole language in a form meant for reading, and points 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 sixteen modules, std, dictionary, vec, math, os, ffi, binary, base64, csv, json, regex, exception, and gfx, audio, physics and ui for graphics, sound, rigid bodies and widgets. All are written in readable Goose under stdlib/.
The command line: every command and option of goose: running, building and checking programs, what the compiler prints, writing the C yourself, the formatter and the language server.
Building programs and using packages: 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, and goose format, the formatter, on save.

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: a measured comparison of self-relative and pool-relative links.
Serialization: the verified loader for structures of relative references.
Namespaces: minimal namespaces and qualified names.
Call location: src_file() and src_line(), and why a default takes the line of the call that left it out.
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.
Cleanup at scope exit: defer, destructor types and pool finalizers compared against the compiler's exit paths and return … from; a proposal.
Nested growth: building a recursive tree (a JSON tape) in place on one stack by growing a container on the open path; the type relaxations, append handles with a checked push, the static proofs that elide the check, and how the result is stepped through without re-walking subtrees, compared.
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, comparing fixed partitions with relocating stacks; a proposal.
Prior art: the languages, libraries and papers nearest Goose's memory model, ranked, and what has no precedent.
Dynamic externs: extern "lib" { ... }, an extern fn bound from a shared library by name at program start; a proposal.
Coroutines: stackless coroutines whose frame is an ordinary fixed-size value, driven by resume and scheduled by libraries; what Rust, C++, Kotlin, Go and Zig learned; a proposal.
Claims the compiler checks and spends: where the next frontier lies for code written by language models and reviewed by people: contracts in the prover's own fact language, abortfree, pure, a race-free par for by proof, owning pool handles, and what each costs; a research note.
Debugging: Goose source lines, names and values in a debugger, through #line and a compiler-written map read by a goose dap adapter in front of lldb-dap, compared with visualizers in the native debuggers and with a debugger built into the compiler; a proposal.
Ownership without destructors: an own qualifier that is an obligation the checker discharges, never a release the compiler writes; what that costs against the existing non-copyable class, how pools and coroutine frames would use it, and what it leaves untouched; a research note.
Child threads: fork-join over shared memory inside one program, with the parent dormant: par for as one claim with a thread level and a lane level, what a body may touch, structural and proven disjointness, a pool measured against today's spawn, and what ISPC, Halide, OpenMP, rayon and the rest built; a research note.

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. For questions and discussion, use the Discord and the GitHub repository.

Standalone pages

These pages were made as finished HTML. They are kept in docs/html and published as they are.

Goose, Byte by Byte: the language on one long illustrated page, with its data drawn byte by byte. It covers the array family, nested data kept inline, references the compiler proves valid, and where the speed comes from.

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