roc Documentation

Technical Documentation: roc-lang/roc

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Work in progress!

Roc is not ready for a 0.1 release yet, but we do have:

• installation guide
• tutorial
• docs for the standard library
• examples
• faq: frequently asked questions
• group chat for help, questions and discussions

If you'd like to contribute, get started here. Don't hesitate to ask for help on our group chat, we're friendly!

Sponsors Copy Chapter

You can 💜 sponsor 💜 Roc on:

• Every.org (supports credit card, bank, Venmo, PayPal, cryptocurrencies, and more)
• GitHub
• Liberapay

We are very grateful for our corporate sponsors Lambda Class, ohne-makler, and Decem:

If you would like your company to become a corporate sponsor of Roc's development, please DM Richard Feldman on Zulip!

We'd also like to express our gratitude to our generous individual sponsors! A special thanks to those sponsoring $25/month or more:

• Peter Marreck
• Barry Moore
• Eric Andresen
• Jackson Lucky
• Agus Zubiaga
• Angelo Ceccato
• Krzysztof G.
• Sam Mohr
• Steven Chen
• Drew Lazzeri
• Alex Binaei
• Jono Mallanyk
• Chris Packett
• James Birtles
• Ivo Balbaert
• Lucas Rosa
• Jonas Schell
• Christopher Dolan
• Nick Gravgaard
• Zeljko Nesic
• Shritesh Bhattarai
• Richard Feldman
• Ayaz Hafiz
• Anthony Bullard

Thank you all so much for helping Roc progress!

Overview (`CONTRIBUTING/README.md`) Copy Section

Contributing

Code of Conduct Copy Chapter

We are committed to providing a friendly, safe and welcoming environment for all. See our Code of Conduct for details.

How to contribute Copy Chapter

All contributions are appreciated! Typo fixes, bug fixes, feature requests,
bug reports...

For ideas, proposals and feature request, click here, for all other contributions, read on.

For a good place to start, check out good first issues or reach out on the #contributing channel on our zulip group chat.
Before making your first pull request, create a new topic in the contributing channel on zulip to discuss what you plan to do! This can avoid duplicated effort or a rejection because the change doesn't fit with the goals of the language.

If you are interested in larger, implementation- or research-heavy projects
related to Roc, check out Roc Project Ideas and reach out to us
on zulip! These projects may be suitable for academic theses, internships,
independent research, or just valuable projects to learn from and improve Roc with.

Building from Source Copy Chapter

Check Building from source for instructions.

Glue Code Generation Copy Chapter

Roc platforms use generated glue to connect Roc values to host-language code in
C, Zig, and Rust. The roc glue command compiles a platform, reads the checked
type, layout, and ownership metadata emitted by the compiler, and runs a glue
script such as CGlue.roc, ZigGlue.roc, or RustGlue.roc to generate the
host-facing interface.

Glue exists so platform authors can depend on generated, idiomatic helpers
instead of hand-writing Roc ABI layout, ownership, and refcount logic. This also
gives Roc a path to evolve the ABI: consumers regenerate glue rather than
maintaining private bindings to compiler internals.

For the glue architecture, generated-helper contract, and ABI risk register,
see src/glue/README.md.

Build Step Names Copy Chapter

Build steps follow a build/run split:

• build-* steps compile, install, generate files, or prepare inputs.
• run-* steps execute tools after their build inputs are ready.
• run-check-* steps run checks.
• run-test-* steps run tests.

Do not add duplicate alias steps. When adding CI or MiniCI coverage, wire prep
work into a build-* step and add that step to build-ci; add the executable
test or check as a leaf run-* step.

Running Tests Copy Chapter

Most contributors should run MiniCI before pushing their code:

zig build minici

MiniCI is the local orchestrator for the CI-shaped set of checks and tests. It
first builds the inputs behind build-ci, then runs the leaf run-check-* and
run-test-* jobs with separate logs and report entries. It actually runs the
tests; it does not just build them.

Test prerequisites Copy Section

Only the JavaScript cell tests in run-test-repl-wasm require
Node.js 22.7.0 or newer, available as node on your
PATH. Node.js is not required to use Roc, build the compiler, or develop Roc
in general. MiniCI includes this test, so running MiniCI also requires Node.js
for this test alone.

This version is needed because the test imports a .js ES module without a
package.json declaring its module type; Node.js 22.7.0 enabled
module syntax detection by default.
Check your version with node --version. To run just these JavaScript tests
from the repository root:

node --test test/repl-wasm-test/cells.test.mjs

The run-test-cli job includes the glue test suite, which compiles generated
Rust glue for the wasm32 target. Install a Rust toolchain (via rustup) with
the WebAssembly target so those cases can build:

rustup target add wasm32-unknown-unknown

Without it, the glue cases fail with error[E0463]: can't find crate for std
(the wasm32-unknown-unknown target may not be installed).

After each run, MiniCI writes a report directory:

• zig-out/minici/index.html is a static dashboard you can open directly in a
  browser. It shows the run timeline, failures, job details, slowest harness
  cases, and per-case timing for harness-backed tests.
• zig-out/minici/report.json is the machine-readable run summary. It contains
  schema_version, run_started_unix_ms, build_ci, and jobs. Each result
  includes status, start_ns, end_ns, duration_ns, log_path, command,
  and stats_path.
• zig-out/minici/logs/*.txt contains captured stdout and stderr for each
  build, check, and test job.
• zig-out/minici/raw/*.json contains harness runner statistics for jobs with a
  stats_path. These files include runner, summary, and events with case
  names, statuses, timings, worker indexes, parent ids, and per-stage details.

Agents and scripts should read zig-out/minici/report.json first, then follow
log_path for raw command output and stats_path for per-case statistics. If a
job fails, rerun the failed command from the report or from MiniCI's terminal
hint.

For focused local iteration, run an exact leaf step. To run a specific Zig unit
test:

zig build run-test-zig -- --test-filter "name of test"

Contribution Tips Copy Chapter

• If you've never made a pull request on github before, this will be a good place to start.
• You can find good first issues here. Once you have gained some experience you can take a look at the intermediate issues.
• It's a good idea to open a draft pull request as you begin working on something. This way, others can see that you're working on it, which avoids duplicate effort, and others can give important feedback sooner rather than later. Click the button "ready for review" when it's ready.
• The Glossary file explains terms commonly used in the compiler.

Bidirectional source controls Copy Section

MiniCI rejects literal Unicode Bidi_Control characters in tracked text,
filenames, and symlink targets to protect against CVE-2021-42574. Run the gate
locally with zig build run-check-source-bidi. It scans bytes even in malformed
UTF-8 or NUL-containing text and recognizes UTF-16/32 byte order marks. Known
binary extensions are listed explicitly in ci/check_source_bidi.zig; changes
to that list need review. The gate has no inline suppression syntax.

Construct security test inputs with escaped code points, rather than placing
invisible controls in fixtures. Roc strings can use \u(202E); Zig tests can
use \u{202E}. Ordinary Arabic and Hebrew text is allowed. Enable your editor's
invisible-character warnings when reviewing Unicode changes. Remove a reported
control from comments, or explicitly escape it in a literal when it is intended
as runtime data; roc fmt refuses to rewrite affected source.

Debugging tips Copy Section

If you need to do some debugging, check out our tips.

Code coverage Copy Section

To measure eval interpreter code coverage and find untested code paths, see the eval coverage guide.

Commit signing Copy Section

All your commits need to be signed to prevent impersonation.
Check out our guide for commit signing.

⚠️ Tip for NixOS users

On NixOS pinentry can cause problems, the following setup works well for those with a KDE desktop. From /etc/nixos/configuration.nix:

programs.gnupg.agent = {
    enable = true;
    pinentryFlavor = "qt";
    enableSSHSupport = true;
  };

Forgot to sign commits?

:exclamation: Make sure to set up signing on your device first, then continue below.

You can view your commits on github, those without the "Verified" badge still need to be signed.
If any of those is a merge commit, follow these steps instead of the ones below.

If you have only one commit, running git commit --amend --no-edit -S would sign the latest commit 🚀.

In case you have multiple commits, you can sign them in two ways:

1. Switching to interactive rebase mode and editing the file:
   • Enter into interactive mode, by running git rebase -i HEAD~n where n is the number of commits up to the most current commit you would like to see.
   • This would display a set of commits in a text file like below:
     text Copy

     pick hash2 commit message 2
     pick hash1 commit message 1

   • On a new line below a commit you want to sign, add exec git commit --amend --no-edit -S. Do this for all your unsigned commits.
2. Or run git rebase recursively:
   • Find the oldest commit you want to sign, using the git log --show-signature command.
   • Run the command git rebase --exec 'git commit --amend --no-edit -n -S' -i HASH which would sign all commits up to commit HASH.

If you already pushed unsigned commits, you may have to do a force push with git push origin -f .

Can we do better? Copy Chapter

Feel free to open an issue if you think this document can be improved!

Overview (`examples/README.md`) Copy Section

Examples

See the examples site.

Overview (`projects/README.md`) Copy Section

Compiler Improvement Projects

This folder contains self-contained project specifications for structural
improvements to the compiler. Each .md file is written so that someone brand
new to the codebase (human or agent) can read that one file and understand the
problem, the solution approach, what success looks like, how to evaluate the
result for long-term correctness and performance, and what tests to add. Each
doc's "What success looks like" section is a completion contract: the project
is not done until every criterion listed there holds.

• small/—localized, mostly additive checks or deletions, low design risk;
  hours to days each.
• Projects on the order of weeks each (cross-cutting, and several
  requiring a design decision before implementation starts) are tracked
  as GitHub issues and linked from this README by issue number.

The projects come from a root-cause analysis of eight weeks of bug fixes
(May–June 2026), a July 2026 duplication audit, and a July 2026 differential
re-analysis of the fixes that landed since. The recurring disease across
independent bug clusters was: facts proven during checking get re-derived
downstream from type, name, or structure content instead of traveling as
explicit data, keyed by fragile identity (name strings, positional order,
mutable keys) and enforced only by panics at the consumption site. The
re-analysis added a second-order lesson: generators whose mechanism was
deleted stayed dead, while generators that were centralized but left a
parallel old path kept firing on uncovered axes—so each project's finishing
move is deleting the re-derivation path, not just adding the carried fact
beside it. design.md at the repo root is the authoritative post-check
design; these projects implement its stated principles more completely.

A second batch of projects came out of the 2026-07 comparative review of
the post-check pipeline against the cor lss prototype it was
productionized from (stage-by-stage divergence review; no shipped
miscompile found, but several unstated load-bearing invariants, one
termination hazard, and one verification coverage gap):

• small/spec-constr-specialization-limits.md—
  termination budgets for call-pattern specialization (compile-time
  divergence is reachable today).
• small/empty-tag-union-yield-provenance.md—
  key Lambda Solved's one unification escape hatch on carried provenance
  instead of shape.
• small/pin-lambda-solved-invariants.md—
  state, assert, and test the four invariants that make monomorphic
  lambda-set solving sound.
• small/lambda-mono-oracle-fidelity.md—
  agreement asserts and contract pins for the Debug Lambda Mono oracle;
  delete its dead Queue.
• small/monotype-machinery-hardening.md—
  release-gate verification-only type checks; measure-first fixes for
  digest depth fallback, unify memo, spec duplication, cross-store reuse.
• small/lift-capture-single-sourcing.md—
  one capture-fixpoint driver, the if_initialized_payload binder
  question, and the capture-id override path.

Within this batch the projects are independent.
(spec-constr-specialization-limits used to be paired here with
spec-constr-static-match-soundness, which has since landed and had its
doc removed.)

A third batch came out of a whole-codebase competing-sources-of-truth
audit (2026-07-18): a sweep of every subsystem for the same fact
encoded independently in N places with no cross-check. The sweep also
confirmed the prevailing single-source pattern holds in most places
(escape alphabet, LowLevel vocabulary, layout/abi classification,
RocTarget, precedence table, snapshot file format, serde audits)—
these projects close the holdouts. All are independent of the earlier
batches and of each other:

• #12165—
  backends stop re-encoding RocStr/RocList offsets, flag bits, the
  refcount contract, and C-ABI thresholds as magic numbers.
• small/llvm-conversion-op-explicit-dispatch.md—
  end the LLVM backend's @tagName-substring dispatch for numeric
  conversion ops (the one backend exempt from switch exhaustiveness).
• small/build-and-ci-single-lists.md—
  the nightly and Nix CI legs name MiniCI jobs by hand instead of
  invoking MiniCI's own gate list.

A fourth batch (2026-07-20) targets operational robustness and
build-throughput gaps rather than sources of truth. The projects are
independent of the earlier batches and of each other:

• #12162—
  dev-backend RC helpers and wasm backend code generation move to the
  per-proc worker generation and single deterministic writer the
  dev backend already uses for procedures.
• #12164—
  every unreachable under src/ carries a same-line rationale (or
  is converted to a checked invariant), enforced forever by a CI lint
  with a shrinking allowlist.
• small/ice-crash-context.md—
  a panic handler that prints what the compiler was doing (phase,
  module, def) plus a repro command before the stack trace, built from
  thread-local context frames pushed at existing phase boundaries.

A fifth batch (2026-08-24) came out of a duplication audit of the
stages between type checking and code generation—Monotype, Monotype
Lifted, SpecConstr, Lambda Solved, the two LIR lowerers, the LIR
passes, and ARC. It looked specifically for multiple implementations
of one semantic rule rather than for repeated text. The recurring
shape: .lss and .boxy were scoped by the phases they skip, but
value semantics (equality, hashing, Inspect, match compilation)
are not phase artifacts and got duplicated along with the phases; and
inside each strategy, producer/consumer boundaries that design.md
states as "record the decision, consume it later" are implemented as
"re-derive it from the emitted shape". Several of these pairs have
already diverged in behavior, not just in text.

• #12166—
  Inspect (three implementations, three copies of the format
  strings), structural equality and hashing (three to four), and match
  compilation (.boxy never adopted the shared decision-tree
  compiler, contrary to design.md) collapse
  onto one shape-parameterized layer, plus a standing .lss/.boxy
  differential harness.
• #12163—
  the god-structs (BodyContext at 44.5k lines, ProcBodyBuilder at
  28.3k) that force helpers to be copied rather than shared, with
  divergence already present in both.
• small/arc-shared-predicates.md—
  four ARC predicates defined twice, including the refcounted-local
  predicate where the RC inserter and its own certifier already use
  different code.
• small/erased-ownership-as-lir-data.md—
  the lowerer records erased ownership and the certifier re-derives it
  with a copy of the rule; .boxy has no producer at all.

Single-source primitive tables have landed (the batch's first
project): CheckedPrimitive's four post-check mappings—storage layout,
inspect low-level op, hasher write op, and builtin owner—each have one
definition. The first three live in src/postcheck/common.zig; the
owner table lives beside CheckedPrimitive itself in
src/check/checked_artifact.zig. A structural_test.zig lint fails the
build if a second definition of any of them appears. None of the copies
had been forced by a type barrier: MonoType.Primitive is a plain alias
of checked.CheckedPrimitive.

Boxy representation queries on the plan have landed: the ~45 queries
Boxy lowering re-derived are now Plan.RepQuery / Plan.NamedRepQuery,
one definition each, and a structural_test.zig lint keeps every
consumer calling them. This closed a live plan/lower disagreement—the
planner's repSubtreeHasDescriptorInOtherChildren skips siblings the
selected child's subtree already covers, and both lowering copies
lacked that carve-out, so lowering could refuse an unwrap the planner
had planned. It also separated two predicates a shared name had blurred:
exact-role equality and sameChildRoleKind, which answers false for
every role carrying a payload.

One call-result fusion machinery has landed: return_slot and
str_append were the same pass twice, and the walk, the single-use
liveness guard, and the variant clone now live once in body_clone.zig,
whose charter already named them. Each pass keeps only what is genuinely
its rule—which consumer statement it matches, and how it rewrites the
variant's returns. The merge fixed a silent drop: str_append's variant
clone did not carry erased_reuse_arg through, so a fused
erased-callable proc lost it. box_reuse adopted the shared
eligibility predicate; loop_append_promote deliberately did not,
because its gate is a genuinely different one (it admits non-Roc ABI
procs), which is recorded here rather than papered over.

One correction to the batch, from implementing it. The audit filed a
spec-constr-single-cloner project on the claim that Monotype Lifted's
two cloners cover 29 and 44 expression variants and that the narrower
one declines the difference silently, so a new variant would be
half-supported without a build error. That claim was wrong.
Pass.cloneExprFresh ends in an explicit 19-variant arm returning null,
and grep -c 'else =>' src/postcheck/monotype_lifted/spec_constr.zig is
zero—the repo's ban on non-exhaustive switch prongs already forces both
cloners to make a decision about every variant. The coverage gap is a
deliberate, compiler-enforced decline set, not a silent one, so the
project's premise did not survive contact and the risky part of it (one
traversal through a compile-time-hot pass, for a drift the compiler
already catches) was not worth doing.

The real duplication that project found was there, one layer down:
the pattern walk that collects a pattern's bound locals existed three
times—the lift pass's bound-set scan, its capture graph builder, and
SpecConstr's body-local scope—identical in every position, differing
only in what each does at a binding site. That is now
Ast.forEachBoundLocal, taking the binding action as a comptime
parameter, with a structural_test.zig lint keeping it single. Three
copies could have come to disagree about whether a given position
binds—a list rest pattern, say—and only one would have been right.

A second correction, also from implementing it. The audit filed a
postcheck-ir-store-boilerplate project proposing a comptime
FlatStore(Spec) mixin that generates each store's add*, get*,
set*, *Count, *View, and *Span surface. Zig 0.16 removed
usingnamespace, so a mixin cannot inject named declarations into a
struct at all; every accessor has to stay a hand-written name whatever
sits behind it. The project's mechanism does not exist in this compiler,
so the doc is deleted rather than left proposing it.

The duplication it counted is real—57 byte-identical bodies between
monotype/ast.zig and monotype_lifted/ast.zig—but most of those
bodies are already one-line delegations whose only content is the field
they name, which is the part that legitimately differs per store. The
part with real duplicated logic was the span append: three lines
(len(), appendSlice, construct the span) written out 33 times across
the three stores. That is now Common.appendSpan /
Common.appendNonemptySpan, with Span itself single-sourced, and a
structural_test.zig lint keeps the hand-written form from coming back.
addTypedLocalSpan deliberately kept its own body: it preallocates
through ensureUnusedCapacity, which is a different append, not the
same one spelled differently.

Two doc claims were also corrected in the code. match_tree.zig and
postcheck/mod.zig both described the decision-tree match compiler as
"shared by both LIR lowerers"; it is used by .lss only, and a doc
comment asserting a sharing invariant that does not hold is worse than
no comment, because the next reader budgets for one match semantics when
there are two. Both now say what is true, and a lint pins the claim to
the imports so it moves when the gap closes.

Housekeeping in the same pass. float-range-flat-representation.md was
carrying its own "Status: Resolved" section rather than a project: range
syntax now constructs a reusable Num.Range(num) whose single
Builtin.Num.Range.iter is the monomorphization-recognized iterator
source, so integer, Dec, and float ranges all keep flat by-value
iterator state and the element-type performance cliff is gone. Its
verification lives in src/eval/test/eval_iter_alloc_tests.zig and
src/eval/test/lir_inline_test.zig, both present and covering it, so
the doc is deleted. Twelve cross-references to four project docs that
landed and were removed (silent-drift-guards,
store-generation-counters, spec-constr-static-match-soundness,
audit-solver-mutating-rewrites) were dangling links; they now read as
plain names marked landed, and the two recommended-order lists dropped
their landed entry and renumbered.

Within the rest of this batch, #12166 and #12163 compose in either
order. The rest are independent.

Recommended order Copy Chapter

Start here—enforcement layers, cheap and load-bearing Copy Section

1. small/cross-phase-coverage-parity-tests.md—
   the divergence-classification parity suite; a regression net the big
   lowering projects inherit.
2. small/rceffect-conformance.md—
   comptime validity plus a per-op refcount conformance harness for the
   central ownership table (the PR 10023 bug class).
3. small/cache-and-identity-residuals.md—
   closes the four small seams left after the identity/cache cures
   (name-text fallback, hand-enrolled serde contracts, split version
   hashes, type_name in nominal keys).

Chain A—dispatch evidence, consumed everywhere Copy Section

1. small/hoist-consumes-dispatch-evidence.md—
   hoist selection reads the dispatch resolution instead of re-deriving
   evidence-dependence from type-var content (the PR 10073 seam), and
   recovers the hoisting its conservative gate gives up.

Chain B—the host/platform boundary Copy Section

1. small/hosted-extern-declared-abi.md—
   the invariant that a hosted extern is only specialized at its declared
   type, enforced at the producer instead of by a checker rewrite.

The solver-rewrite audit that followed this chain has landed: design.md's
"Solver-Mutating Rewrites" section holds the mechanism/policy inventory,
Store.dangerousSetVarRedirect requires a declared RedirectRule at every
call site, and the 9966 widening is the declared Hosted Try Question
Widening rule, scoped to direct hosted calls with both sides pinned by
tests.

The platform-relation migration that concluded this chain has landed:
checking records each platform requirement's solution in the app's checked
artifact, finalization consumes it, and the platform root is published
once—the name-keyed re-resolution and double publication are deleted.

Chain C—specialization sealing Copy Section

1. small/pin-deferred-spec-requests.md—
   seal-time instrumentation, the snapshot-regime pin, and the
   unifyThroughBacking decision; end state: row_default unreachable
   for checker-constrained rows.

Independent—start any time, in any order Copy Section

Small:

• small/frame-partitioned-checker-state.md—
  inventory and convert frame-scoped checker/canonicalizer state to
  dedicated frame storage (the 9929→10010 and 10001 shape).
• small/compact-constant-aggregates.md—
  static-data and builtin-call materialization for constant/repeated
  lists, ending the one-local-per-element explosion behind issue 9898.

The decision-tree match compiler has landed for .lss: the direct
solved-to-LIR lowering compiles match through one shared Maranget-style
module (src/postcheck/match_tree.zig)—one multiway switch per tested
position, one discriminant read, strings and list-length buckets as
ordinary arms—with the sharing invariant documented in design.md and
enforced by a debug statement-count lint. The 2026-08-24 audit found
.boxy never adopted it (grep -rn match_tree src/postcheck/boxy/ is
empty; boxy/lower.zig folds branches into a sequential chain), so the
"shared by both LIR lowerers" claim in src/postcheck/mod.zig is not yet
true. Closing that is part of
#12166.

Single-source builtin registration has landed: the seven hand-typed
roc_builtins_* symbol/ABI tables now derive from one comptime registry
(src/builtins/builtin_registry.zig), and the LowLevel-to-builtin member
choice is shared across backends via base.LowLevelBuiltins.

Suggested overall sequence Copy Section

If one person or agent works through everything serially, this order
front-loads leverage and keeps prerequisites satisfied:

1. small/cross-phase-coverage-parity-tests.md
2. small/rceffect-conformance.md
3. small/cache-and-identity-residuals.md
4. small/pin-deferred-spec-requests.md
5. small/hoist-consumes-dispatch-evidence.md
6. small/hosted-extern-declared-abi.md
7. small/frame-partitioned-checker-state.md
8. small/compact-constant-aggregates.md

Overview (`src/README.md`) Copy Section

Roc Compiler (Zig Implementation)

Navigation Copy Chapter

Core compiler directories:

• base/ - Core data structures and utilities shared across the compiler
• check/ - Main compilation pipeline (parsing, canonicalization, type checking)
• types/ - Type system definitions and utilities
• builtins/ - Built-in types, functions, and operations
• reporting/ - Error reporting and diagnostic formatting
• collections/ - Efficient data structures used throughout the compiler
• cache/ - Compilation caching system for faster incremental builds
• coordinate/ - Cross-module compilation coordination and dependency management
• eval/ - Runtime evaluation and interpretation system
• fs/ - Filesystem operations and file I/O utilities
• layout/ - Memory layout computation and management for code generation
• serialization/ - Serialization utilities for compiler data structures
• snapshots/ - Snapshot tests validating compiler behavior across all stages

Status Copy Chapter

This table provides a summary of progress for the zig compiler re-write and should be updated with the PR that includes new features.

• N/A Not applicable
• 🚧 Work Started
• 🪫 Tests Passing
• 🔋 Polished

Fast Feedback Loop Copy Chapter

The roc zig compiler can have a very fast feedback loop. We support zigs incremental compilation and watch mode.
By avoiding generating final executables, we can build and typecheck much much faster.

Try it with zig build -Dno-bin -fincremental --watch

Running Language Server (LSP) Tests Copy Section

The LSP tests are split into fast unit coverage and compiler-backed integration
coverage.

zig build run-test-zig-module-lsp_unit
zig build run-test-zig-module-lsp_integration

For faster iteration with incremental compilation and watch mode:

zig build run-test-zig-module-lsp_unit -fincremental --watch

Use lsp_unit for protocol, transport, document store, token-only coloring,
and handler routing work that does not need compiler checking. Use
lsp_integration when changing syntax checking, completions, hover,
definition, document symbols, diagnostics, or behavior that depends on real Roc
source, compiled builtins, and platform/app checking. The integration command
is a parallel harness; pass -- --threads N to cap workers or
-- --test-filter "case name" to run matching integration cases.

Expanding to ZLS Copy Section

This fast config can also be used with zls. Simply follow these steps:

1. run zls --version and make sure it supports Zig 0.17.0.
2. run zls env and grab the config_file path.
3. Edit the config file to include

{
  "enable_build_on_save": true,
  "build_on_save_args": ["-Dno-bin", "-fincremental"]
}

4. Advised, also changing the cache dir, I use --cache-dir .zig-cache/zls.
   Otherwise, zig commands run manually can lead to the lsp breaking and requiring a restart.
5. Optionally, add -Dfuzz above as well to get type checking of fuzz scripts as well.
6. Note, I had to fully delete my .zig-cache to get zls to start.
   Make sure to check the logs if you aren't getting type failures.
7. Enjoy better lsp results.

Simply testing feedback loop Copy Section

Sadly, this is not nearly as fast due to building binaries.
One day, we will get dev zig backends, and it should be fast.

Try it with zig build run-test-zig -fincremental --watch

Overview Copy Chapter

Overview (`CONTRIBUTING/profiling/README.md`) Copy Section

Profiling Roc

Profiling is a very big topic with many facets and pitfalls.
This is just a preliminary doc to recommend some nice tools and basic flows.

If you have any question, please reach out on zullip.
Feel free to at Brendan Hansknecht in the discussion thread.

General Tips Copy Chapter

1. Build with optimizations and retain debug symbols (-Doptimize=ReleaseFast -Dstrip=false).
2. Try to benchmark real world rather than synthetic inputs.
3. Prefer end to end benchmarks when possible.
   Microbenchmarks can be misleading and even potentially lead to end to end slowdowns.
4. Probably use linux (linux just gives a lot more info and tools in general).
   That said, mac and windows can also be ok.
5. Make sure you have a long enough execution horizon to get good results (sometimes requires looping over the same work multiple times).

Some Nice Tools Copy Chapter

These are tools I recommend for profiling that help get a solid picture.

[Flamegraph](https://github.com/flamegraph-rs/flamegraph) Copy Section

Flamegraphs are the core of basic profiling.
They enable quickly finding hotspots in execution.
By regularly sampling callstacks, flamegraphs are able to identify where time is being spent.
This tool simply generates an svg to view.

This is a great place to start if new to profiling, but has a number of limitations.
For examples, flamegraphs simply aggregate information with sampling and can miss a lot of data.
They also lack interactivity and many low level details.
Flamegraphs are essentially a still frame view into an apps performance.

The tool is simple to run.
Using it with roc can be as simple as flamegraph --root -- ./zig-out/bin/roc fmt /tmp/app.roc.

Note: --root is not always needed, but it generally gives better results.

If you open the flamegraph in a browser, you can explore where time is spent.
There is a search button in the top right corner (almost not visible) that enables better discovery of percentage of time used in various functions.
For example, here is a flamegraph from parsing and formatting a roc file.
It was search for memmove and shows that 25% of time is spent moving bytes.

[Samply](https://github.com/mstange/samply) Copy Section

Samply is a sampling profiler that that uses the Firefox profiler to give richer info and interactivity on top of a flamegraph.
I find it to be a richer and nicer default than simple flamegraphs, but it is also more complex.
Not only do you get a flamegraph, but you get callstacks, can collapse recursive nodes, and are able to view source lines and assembly hit by the sampler.

Using samply is also super simply, just samply record -- ./zig-out/bin/roc fmt /tmp/new.roc.

Here is an example output after searching for memmove.
We can see in the top graph, all the specific times during execution that memmove was using the cpu.
On top of that, we can see that 42% of memmoves happened during tokenization.

[Tracy](https://github.com/wolfpld/tracy) Copy Section

Unlike the above, tracy is not primarily a sampling profiler.
Instead, tracy focuses on tracing through explicit code annotations.
Tracy is significantly more complex than the other solutions, but is always way more powerful.
Tracy has an ~100 page detailed manual and an online interactive demo: https://tracy.nereid.pl/.
The most important part of the manual to read is probably Analyzing captured data (which is about the UI).

Simply using tracy is more work than the other tools.
Beyond having tracy install, you also need to download the source of tracy checked out to the same version.
For example, I installed tracy with homebrew. It is at version 0.11.0.
As such, I have checked out the tracy github repro to the v0.11.0 tag in my ~/vendor/tracy directory.

Then, on my linux machine (which tracy works better on), I run zig build -Doptimize=ReleaseFast -Dstrip=false -Dtracy=$HOME/vendor/tracy roc.
This builds tracy with all of the bells and whistles.
One of those cool features is tracy callstacks. This feature gives much more precision of information, but adds significant overhead.
Often times, it is worth profiling once with -Dtracy-callstack=false to have much less overhead.

Now that I have the compiler built with tracy, I can launch the tracy server on my mac machine to record the result (you can also run it on the same machine if wanted).
Run tracy-profiler, input the correct ip address, and press connect.
Then run the instrumented version of zig: ./zig-out/bin/roc fmt /tmp/new.roc.
Also, run with the root user to capture more information.
In this case, I ran:

sudo ./zig-out/bin/roc fmt /tmp/new.roc

After that, welcome to a wealth of information:

• Everything running on the cpu over the course of the execution
• Zone info and statistics
• Source information with disassemblies
• Memory allocations and frees.
• Locks and multithread info (once the zig roc compiler uses them)

At some point, hopefully we will have videos on using tracy with roc.
Until then, here is a video on tracy from cppcon and here is an example output.

Overview (`docs/langref/README.md`) Copy Section

NOTE: This is heavily WIP! This line will be removed when the langref is considered complete, and at that point, missing sections and outdated information will be considered bugs. If you'd like to contribute to this (other than minor corrections of obvious mistakes), definitely mention it in the langref Zulip channel before getting started on anything!

Language Reference

This is Roc's language reference (or langref for short).

If you're looking for a beginner tutorial, check out roc-lang.org/tutorial instead; the langref is a detailed reference intended for experienced Roc programmers.

Outline Copy Chapter

• Expressions
  • Values
    • Reference Counting
    • Reference Cycles
    • Opportunistic Mutation
  • Block Expressions
• Statements
  • = (assignment)
    • Type Annotations
  • import
  • expect
  • return
  • break
  • continue
  • Block Statements
• Error Handling
  • Try
  • Handling Errors
  • Crashing
  • Performance
• Conditionals
  • if
  • else
    • else if
  • and
  • or
  • match
  • Bool
• Pattern Matching
  • match
    • Branch Alternatives
    • if Guards on Branches
  • Exhaustiveness
    • Catch-all Patterns (_)
  • Destructuring
    • Destructuring Assignments (with =)
  • Performance
• Functions
  • Pure Functions
  • Effectful Functions
    • ! suffix
  • Closures
  • Recursive Functions
    • Self-recursive Functions
    • Mutually Recursive Functions
  • Tail Calls
    • Self-Tail Calls
    • Tail-Call Optimization
      • Modulo Cons
  • Performance
• Naming
  • Rules
    • Lowercase Names
    • Uppercase Names
  • Unused Names
  • Shadowing
  • Constants
  • Variables (with var)
    • var keyword
    • $ prefix
  • Type Variables
  • Type Aliases
    • Parameterized Type Aliases
  • Module Names
  • as
• Modules
  • Type Modules
  • Imports
  • Package Modules
  • Platform Modules
  • Application Modules
• Platforms
  • Applications
  • Domain-specific functionality
  • Platform scope
    • Ecosystem benefits
    • Security benefits
    • Performance benefits
  • How platforms are implemented
    • Host
    • Memory management
    • Program start
• Types
  • Type Annotations
    • Where Clauses
  • Nominal Types
    • Opaque Nominal Types
  • Structural Types
  • Type Aliases
  • Performance
• Static Dispatch
  • Methods
    • Calling Methods
    • Well-Known Methods
    • Compiler-Derived Methods
  • Where Clauses
  • Aliases
  • Performance
• Operators
  • Desugaring
  • Precedence
  • Binary Infix Operations
    • And
    • Or
    • Arithmetic Operators
    • Comparison Operators
    • Range Operators
    • ?? (default value on Err)
    • ? with a Handler
    • |> (pipe)
  • Unary Prefix Operators
    • - (.negate())
    • ! (.not())
  • Unary Postfix Operators
    • ? (unwrap if Ok; early return if Err)
    • […] (subscript operator)
• Records
  • Fields
  • Structural Records
  • Optional Fields
  • Nominal Records
  • Defaulted Fields
  • The Empty Record ({})
  • Performance
• Tuples
  • Tuple Literals
  • Accessing Tuple Elements
  • Tuple Types
  • Destructuring Tuples
  • Tuples vs Records
  • Performance
• Tag Unions
  • Structural Tag Unions
  • Nominal Tag Unions
  • Performance
• Lists
  • List Literals
  • Using Lists
  • Performance
• Boxes
  • Memory Layout
  • When to Use a Box
• Loops
  • for Loops
  • Looping over Streams with for!
  • while Loop
  • Infinite Loops
  • Performance
• Iterators
  • Transforming Iterators
  • Laziness
  • Custom Iterators
  • Performance
• Numbers
  • Number Literals
  • Builtin Number Types
    • Overflow and Division by Zero
  • Ranges
  • Custom Number Types
  • Performance
• Strings
  • String Literals
  • Unicode
  • String Normalization
  • UTF-8
  • Performance
• Dictionaries and Sets
  • Dictionaries
  • Sets
  • Keys and Hashing
  • Performance
• Parsers
  • Parsing JSON
  • Which Types Can Be Parsed
  • Parsers at Compile Time
  • Performance
• Compile-Time Evaluation
  • Which Expressions Get Evaluated?
  • Performance
• Comments
  • Single-line Comments
  • Doc Comments
  • Generating Docs with roc docs
• Packages
  • Depending on Packages
  • Shorthands

Overview (`src/backend/README.md`) Copy Section

Backend Development Guide

This directory contains the code generation backends for Roc.

Native procedure artifacts Copy Chapter

The dev backend shares one procedure-emission pipeline between native compile-time
evaluation and object generation. Workers borrow frozen LIR and return owned,
relocatable artifacts; deterministic placement and linking belong to the coordinator.
Executable images are execution resources, not reusable compiler output.

Reuse requires an explicit same-program capability, producer revisions, and
compatible emission policies. Compile-time hooks and mutable slot addresses cannot
escape through cached code. Immutable runtime data travels with its referenced
artifact closure; mutable CTFE slots remain external bindings. See design.md for
the lifetime and placement invariants.

Running Tests with Filters Copy Chapter

To run a specific eval test by name filter:

# Run a single test
zig build run-test-zig -- --test-filter "list refcount function"

Debugging Generated Code Copy Chapter

When debugging code generation issues (calling conventions, register allocation, etc.),
you can enable hex dumping of the generated machine code.

Enable Hex Dump Copy Section

Use a targeted debug print in the backend code path you are investigating and
re-run the relevant eval test. The inspect-only eval harness no longer keeps a
test-helper-specific generated-code dump switch.

Disassembling the Output Copy Section

On Windows, save the hex bytes to a file and use:

# Using dumpbin (from Visual Studio)
dumpbin /disasm code.bin

# Or using objdump (from MinGW/MSYS2)
objdump -D -b binary -m i386:x86-64 code.bin

On Linux/macOS:

objdump -D -b binary -m i386:x86-64 code.bin

Using Python to convert hex dump to binary:

import re
hex_dump = """
55 48 89 E5 53 41 54 48  81 EC 00 04 00 00 48 89
CB 49 89 D4 ...
"""
hex_values = re.findall(r'[0-9A-Fa-f]{2}', hex_dump)
code_bytes = bytes(int(h, 16) for h in hex_values)
with open('code.bin', 'wb') as f:
    f.write(code_bytes)

Overview (`src/base/README.md`) Copy Section

Base

Foundation utilities and common functionality used throughout the Roc compiler.

Overview Copy Chapter

The base module provides essential utilities, data structures, and abstractions that are used across multiple stages of the Roc compiler. It serves as a shared foundation that other modules depend on.

Purpose Copy Chapter

This module provides:

• Common Data Structures: Shared data structures and collections used throughout the compiler
• Memory Management: Safe memory allocation and management utilities
• Parallel Processing: Utilities for parallel execution and work distribution
• Error Handling: Common error types and error handling patterns
• Debugging Support: Debugging and logging utilities
• Platform Abstractions: Cross-platform abstractions for common operations

Overview (`src/builtins/README.md`) Copy Section

Builtins

Built-in functions, types, and runtime support for the Roc language.

Overview Copy Chapter

The builtins module provides the core runtime functionality that every Roc program depends on. It includes fundamental operations, data types, and the interface between Roc code and the host platform.

Purpose Copy Chapter

This module provides:

• Core Data Types: Built-in types like strings, numbers, and basic collections
• Runtime Operations: Fundamental operations like memory allocation, string manipulation, and arithmetic
• Host Platform Interface: The bridge between Roc code and the underlying platform (ABI, system calls, etc.)
• Standard Library: Essential functions that are always available in Roc programs

The builtins module is essential for both the compiler (during type checking and code generation) and the runtime (during program execution).

Numeric Oracle Tests Copy Chapter

Numeric builtins should have tests whose expected values come from an
independent, known-good computation rather than from the implementation under
test. Prefer generating those expected values at Zig comptime, then storing them
in ordinary test fixture arrays.

The usual pattern is:

1. Write an explicit input corpus that covers ordinary values, sign boundaries,
   representation boundaries, domain boundaries, overflow/underflow edges,
   branch cutoffs, and special values such as zero, infinity, and NaN where the
   type supports them.
2. Build fixture arrays at comptime from that corpus.
3. Compute expected values with Zig language builtins or std.math functions
   that are independent of the Roc builtin implementation being tested.
4. Run the Roc builtin implementation at test runtime and compare it to the
   comptime-generated expectation.

For exact operations, compare exact representations. Examples include integer
overflow flags, bit conversions, parsing/formatting cases with exact expected
text, and Dec operations whose semantics define an exact fixed-point result.
For Dec this usually means comparing the raw scaled i128 payload.

For approximate operations, keep the approximation explicit in the test name and
fixture. Transcendental functions such as sin, cos, tan, asin, atan,
log, and fractional pow generally do not have exactly representable Dec
results. Their tests should use comptime oracle values plus a stated error
envelope, not an ambiguous "close enough" check hidden inside the assertion.
For floating-point functions, prefer ULP-aware comparisons that preserve signed
zero and NaN behavior.

Do not use the implementation under test as its own oracle. Also avoid relying
on a backend host import as evidence for a custom builtin implementation unless
that import is exactly the code under test. For example, a wasm host math import
can validate wasm linking and call plumbing, but direct Zig tests are still
needed for a self-contained builtin math port.

When adding a new numeric builtin, add tests at the lowest layer that owns the
algorithm and add integration coverage for the public Roc API or low-level
operation that reaches it. The comptime oracle fixtures establish algorithmic
expectations; eval, CLI, wasm, and backend tests establish that the compiler and
runtime plumbing call the intended builtin.

Test Maturity TODOs Copy Chapter

• TODO: Add property-style List tests for refcounted elements, seamless slices,
  aliasing, concat/drop/replace/reverse chains, and allocation-count invariants.
  The current List tests cover many targeted cases; the follow-up should add a
  systematic corpus that exercises ownership-sensitive operation sequences.

Overview (`src/canonicalize/README.md`) Copy Section

Canonicalize

Transforms Abstract Syntax Tree (AST) into Canonical Intermediate Representation (CIR) through semantic analysis of the program.

The canonicalize module is the second stage of the Roc compiler pipeline. It performs semantic analysis, resolves names, and transforms the AST into a normalized intermediate representation that's easier for the type checker to process.

Overview (`src/check/README.md`) Copy Section

Check Types

Performs Hindley-Milner type inference with constraint solving and unification on the Canonical Intermediate Representation (CIR).

The check module is the third stage of the Roc compiler pipeline. It performs type inference using the Hindley-Milner algorithm, ensuring type safety and generating the necessary type information for code generation. This stage catches type errors and ensures the program is well-typed before proceeding to evaluation or compilation.

Exhaustiveness uses read-only nominal views so declaration substitutions cannot
mutate solver types or escape as solver blockers. Exact template dependencies
allow irrelevant substitutions to share identity while private unknowns retain
their application scope.

Inhabitedness uses a greatest fixed point to preserve conservative recursive
payload semantics without enumerating shared paths. Row-only cycles provide no
constructor witness. General, constructor-payload, and known-absent queries retain
distinct leaf and open-row policies; only settled answers are memoized.

Overview (`src/cli/README.md`) Copy Section

CLI

This directory contains the source code for the roc command-line interface (CLI) tool.

The CLI is the main entry point for developers using Roc. Its responsibilities include:

• Command Parsing: Parsing commands (e.g., build, run, fmt, test) and their options through cli_args.zig
• Compilation Orchestration: Managing the compilation pipeline and integrating with the Roc compiler
• Linker Integration: Using an abstraction for the LLD linker as a library through linker.zig for code generation
• Performance Profiling: Integration with Tracy profiler for performance analysis
• Testing: Built-in execution of top-level expects through the test command
• Shared Memory Management: Testing utilities for the shared memory system used in IPC
• Default-App Staging: Turning a file that runs on the built-in Echo platform—a headerless file with main!, or an app header that names no platform—into an ordinary app rooted beside a copy of that platform, through default_app.zig

The CLI coordinates between the compiler frontend (parsing, type checking) and backend (code generation, linking) to provide a seamless development experience.

Multiline strings in the REPL Copy Chapter

The terminal REPL keeps consecutive multiline string lines in one statement.
A blank line, a following non-string statement, or EOF submits the pending string.
String payloads retain their trailing spaces.

Overview (`src/collections/README.md`) Copy Section

Collections

The collections module provides efficient data structures that are tailored for use throughout the Roc compiler. These collections are designed to handle the specific needs of compiler operations like symbol tables, dependency graphs, and intermediate representations.

Purpose Copy Chapter

This module provides:

• Specialized Data Structures: Collections optimized for compiler-specific use cases
• Memory Efficiency: Data structures designed to minimize memory overhead during compilation
• Performance: Fast access patterns for common compiler operations
• Type Safety: Safe, generic collections that work with Roc's type system

RekeyingHashMap keeps lookup cost independent of deletion history for indexes
whose keys are repeatedly removed and reinserted as compiler identities evolve.

Overview (`src/compile/README.md`) Copy Section

Compile

This directory holds the core logic for compiling Roc modules. It takes Roc source code and processes it through various stages to produce an executable or library.

Key responsibilities include:

• Compilation Pipeline: Managing the flow of a module through the compiler stages:
  • Tokenizing
  • Parsing
  • Canonicalizing
  • Type Checking
  • Code Generation (Not yet implemented)
• Module Caching: Managing the cache of compiled modules to speed up subsequent builds
• Package Building: Building complete packages
• Build Environment: Managing build contexts and environments

The compile module serves as the orchestrator that coordinates between the different compiler stages and manages the build process efficiently.

Embedding Copy Chapter

Roc can be embedded in another Zig program to compile and run .roc files in-process. The driver is Coordinator; the in-process execution path uses lir.LirImage and eval.LirInterpreter.

The embedding API is stable in shape; implementation details may change between releases.

Using Roc as a Zig dependency Copy Section

Pin a Roc commit in your package manifest with
zig fetch --save=roc 'git+https://github.com/roc-lang/roc.git#<full-commit-sha>'.
In your build, resolve b.dependency("roc", .{ .target = target, .optimize = optimize })
and import its named modules with exe.root_module.addImport("compile", roc.module("compile")).
The same interface exports lir, eval, check, base, ctx, builtins,
roc_target, and build_options, including their transitive dependencies and
generated builtins. The consumer's executable must link libc.

test/downstream-compiler is a complete
standalone driver exercised against a fetched package by
zig build run-test-downstream-package. Updating a downstream dependency means
updating the pinned commit and package hash, without copying compiler sources.

Canonical sequence Copy Section

/* Detailed source-code truncated for AI context efficiency. */

postCheckExecutor() reuses the coordinator's persistent compilation workers
for graph-free post-check tasks. It is intentionally a synchronous borrowed
capability: obtain and use it only after coordinatorLoop() has drained the
frontend and before coordinator shutdown. Frontend and post-check work share
the same task/result channels, so overlapping those phases is an invariant
violation.

Type-check-only flow Copy Section

For LSP, fuzzing, or any consumer that only needs diagnostics, stop after step 3:

try coord.start();
try coord.discoverAppFromPath(arena, .{ .entry_path = app_path });
try coord.coordinatorLoop();

var it = coord.iterReports();
while (it.next()) |entry| {
    // render entry.report
}
const had_errors = coord.hasUserErrors();

Skip finalizeExecutableArtifacts, LIR lowering, and execution entirely.

Runtime arena Copy Section

fillHeaderInBuffer and viewMappedImage compute offsets via ptr - base_ptr arithmetic, so the image allocator must own a single contiguous virtual region. std.heap.ArenaAllocator grows by allocating new pages and will not work—the offsets it computes will be wrong, either silently producing a broken image or tripping error.InvalidLirImage.

Use a std.heap.FixedBufferAllocator over a heap-allocated contiguous buffer:

const RUNTIME_ARENA_SIZE = 128 * 1024 * 1024; // 128 MiB

const runtime_buffer = try gpa.alignedAlloc(u8, 16, RUNTIME_ARENA_SIZE);
defer gpa.free(runtime_buffer);

var runtime_fba = std.heap.FixedBufferAllocator.init(runtime_buffer);
const runtime_alloc = runtime_fba.allocator();

Sizing: budget at least 128 MiB for a typical app—even a "hello world" needs more than 16 MiB after lowering all reachable modules. Anonymous virtual memory overcommits on Linux/macOS, so a generously-sized buffer doesn't cost real RAM until actually touched. Pick a number that comfortably exceeds your largest expected program.

Memory ownership Copy Section

Refcounted values that Roc returns to the host (a RocStr, RocList, or RocBox written through ret_ptr; or any of those passed as arguments to your hosted functions) are heap-owned by the host. The interpreter does not auto-tear-down on eval return—that's intentional, since embedders frequently want to inspect the return value before freeing it.

The host must explicitly decref returned refcounted values when done. Without this, host allocator leak-checking will report leaks tracing back to rocAllocFn in the interpreter:

// After interp.runEntrypoint(...) returns, if the entrypoint's return type
// is a refcounted value (e.g. RocStr returned via ret_ptr), decref before
// tearing down. `RocStr.decref` takes the value by copy and a *RocOps; it's
// a no-op for small (stack) strings.
const result_str: RocStr = @as(*const RocStr, @ptrCast(@alignCast(&result_buf))).*;
defer result_str.decref(&my_roc_ops);

The same rule applies to hosted-fn arguments: the host owns each *RocStr (or other refcounted pointer) it receives for the call's duration. Read freely, but if you stow the value to use later, call the appropriate incref helper first.

Custom filesystem Copy Section

Implement the Io vtable and pass it via coord.setIo(...). The default Io reads from std.fs.cwd().

For embedders that don't have a filesystem at all (e.g. wasm), Coordinator doesn't require one as long as every path passed in is served through the configured Io. The cache manager (cache_manager parameter to Coordinator.init) can be left null.

Host functions Copy Section

Set coord.enable_hosted_transform = true before coord.start(). Hosted lambda bodies in platform modules are auto-converted during canonicalization.

At execution time, RocOps.hosted_fns.fns is a positional array—the interpreter calls fns[dispatch_index]. The dispatch index is the hosted function's position in the platform header's hosted section, so the array follows the order the section is written in:

hosted { "roc_stdout_line": Stdout.line!, "roc_stderr_line": Stderr.line! }

gives Stdout.line! index 0 and Stderr.line! index 1, whatever modules they are declared in. roc glue emits the same numbering, so generated glue and a hand-written array agree. A declaration in the platform module itself is named without a module, since a platform cannot import itself: hosted { "roc_helper": helper! }.

Wrong order is silent (wrong function called), not loud—be deliberate, especially when reordering the hosted section.

A platform without a hosted section has no bound declarations, and post-check lowering orders whatever remains by the procedure's deterministic order key.

URL-resolved packages Copy Section

Coordinator.discoverAppFromPath does not download URL-specified packages—it only supports relative paths. For URL support:

1. Call compile.app_header.parseAppHeader(io, gpa, arena, path) to get the raw header.
2. Resolve URLs to local paths using your own caching policy.
3. Register packages with coord.ensurePackage / coord.registerInlinePackage instead of discoverAppFromPath.

The Roc CLI follows exactly this pattern—see buildLirImageWithCoordinator in src/cli/main.zig for a worked example.

Overview (`src/eval/README.md`) Copy Section

Interpreter Overview

This directory contains Roc's interpreter. It powers the REPL, the interpreter
shim (for the default roc command and roc build in interpreter mode), and
the evaluation tests. This document introduces the core pieces so a new contributor can
navigate the code without prior context.

High-Level Architecture Copy Chapter

The interpreter works by consuming ARC-inserted LIR and interpreting that
program directly. In the public post-check pipeline, CIR is never given to the
interpreter or interpreter shim; the parent compiler lowers through checked
modules, post-check IRs, LIR, and ARC first.

checked modules → post-check IRs → LIR → TRMC/TCE → ARC → Interpret

Core Modules Copy Section

• interpreter.zig exports LirInterpreter. Each Roc call gets a frame
  whose local slots are looked up through the proc's sorted frame_locals
  span. Within a frame, execStmtChain walks the statement chain in a flat
  loop—join/jump execute as loops without growing any stack—while
  assign_call recurses natively into the callee (bounded by the call-depth
  cap below).

• value.zig defines Value—a raw pointer to bytes in memory. Values
  carry no runtime type information; the layout is always tracked separately
  via layout.Idx.

Evaluation Flow Copy Chapter

1. Published inputs—Consumers (REPL, tests, CLI) type check source and
   publish checked modules plus explicit roots.
2. Lowering—The checked-module pipeline lowers through post-check IRs
   and LIR, rewrites tail recursion via TRMC/TCE (src/lir/trmc.zig), and
   inserts ARC, producing a LirStore, committed layouts, and explicit root
   procedures.
3. Execution—On native compiler hosts, compile-time roots execute as
   dev-backend machine code. When the compiler itself targets wasm32 or another
   freestanding host, compile-time roots execute through LirInterpreter.
   This host-platform choice is not configurable. Both compile-time paths
   unconditionally use .normalize, so stored f32/f64 NaNs have canonical,
   host-independent bits; runtime consumers unconditionally use .preserve.
4. Interpreter statement walk—When the interpreter is the selected
   execution engine, execStmtChain executes each frame's statement chain
   iteratively, dispatching per CFStmt variant; low-level ops go through
   evalLowLevel.
5. Crash handling—A Roc crash records its message in the interpreter and
   unwinds as error.Crash (getCrashMessage returns the message). The
   interpreter never calls the host's roc_crashed, which does not return;
   the embedder delivers the crash to its host. Expect expressions delegate to
   the host via RocOps.

All RocOps interactions (alloc, dealloc, crash, expect, dbg) happen through the
RocOps pointer. This keeps host integrations consistent.

Evaluation Limits Copy Chapter

• Call-depth cap—LirInterpreter crashes ("stack overflow") after 1024
  nested Roc calls (max_call_depth). Tail-recursive and
  constructor-tail-recursive functions don't hit this: the TRMC/TCE pass
  (src/lir/trmc.zig) rewrites them into join-point loops before the
  interpreter ever sees them.
• Debug value validation—In Debug builds, setLocal walks values to
  check they match their layouts. The walk is best-effort: it stops at
  max_debug_value_depth (64) nested values and after
  max_debug_value_visits (16) heap cells (so deep lists can't overflow the
  native stack and wide trees don't make every assignment O(structure size)),
  and inside TRMC-transformed procs a null box pointer is accepted as a legal
  not-yet-filled hole.

Host Integrations Copy Chapter

• Inspected evaluation (inspected.zig, inspected_run.zig)—Compiles an
  explicit checked root and executes it through a selected backend while
  returning the inspected value, crash outcome, allocation count, and ordered
  host events.
• Runtime host (runtime_host.zig)—Implements compiler-owned RocOps
  callbacks with allocation tracking and ordered dbg, failed-expect, and
  crash capture. Production REPLs and evaluator tests use the same host.
• Interpreter shim (src/interpreter_shim/main.zig)—Provides a
  C-callable entry point (roc_entrypoint) that maps/views an ARC-inserted LIR
  image and evaluates it via the interpreter.

Tests Copy Chapter

Evaluation coverage lives in src/eval/test/:

• parallel_runner.zig—Runs every data-driven TestCase on all enabled
  backends (interpreter, dev, wasm; llvm with --llvm) in forked
  subprocesses, requiring byte-identical Str.inspect output.
• eval_tests.zig—Aggregates the TestCase tables from the
  eval_*_tests.zig files (recursive data, closures, low-level ops,
  polymorphism, issue repros, ...). eval_trmc_tests.zig holds the TRMC/TCE
  stack-safety gates and the CFold/NQueens/RBTreeCk benchmark ports.
• trmc_lir_test.zig, lir_inline_test.zig—Standalone binaries asserting
  on LIR structure (TRMC pointer ops, detection/transform outcomes, inlining).
• host_effects_runner.zig / host_effects_tests.zig—Runtime host-effect
  coverage.
• runtime_host.zig—Shared RocOps host with allocation leak checks and
  event capture.

Run tests with:

zig build run-test-eval                 # interpreter + dev + wasm
zig build run-test-eval -- --llvm       # also the LLVM backend
zig build run-test-zig-trmc-lir         # LIR-level TRMC tests
zig build run-test-zig-lir-inline       # LIR-level inlining tests

Debugging Copy Chapter

The interpreter supports a compile-time tracing flag that enables detailed
evaluation output. To build with tracing enabled:

zig build -Dtrace-eval=true

When enabled, the interpreter outputs detailed information about evaluation
steps. Both tracing flags default to false.

Allocation-Failure Injection Copy Section

Bugs on the out-of-memory path (double frees, cleanup of never-initialized
state, leaks) never run while allocation succeeds. The eval test runner can
make them run on demand; each test executes in a forked child, and these
options act inside that child:

# Fail a random allocation in every child; each child logs the index it drew.
zig build run-test-eval -- --fail-alloc random --child-log-dir /tmp/child-logs --debug-allocator
# Reproduce one finding exactly.
zig build run-test-eval -- --fail-alloc 78 --filter "the test's name" --debug-allocator

--debug-allocator runs the child on a DebugAllocator (arenas pass every
allocation through it), so double and invalid frees are reported; build with
-Ddebug-gpa-traces=true to get allocation traces. Leaks are not reported
here, because the child exits without tearing its allocator down; the
checkAllAllocationFailures unit tests cover those. The allocation
count a child reaches depends on this choice, so reproduce with the same flags
that found the bug. --freeze-on-crash keeps a segfaulting child alive and
ptrace-able so gdb -p can inspect the crashed state (Linux only).

Refcount Tracing Copy Section

For debugging memory management issues, use the -Dtrace-refcount flag:

zig build -Dtrace-refcount=true

When enabled, this outputs detailed refcount operations to stderr:

[REFCOUNT] DECREF str ptr=0x1234 len=5 cap=32
[REFCOUNT] DECREF list ptr=0x5678 len=3 elems_rc=1 unique=1
[REFCOUNT] INCREF str ptr=0x1234 len=5 cap=32

Expect a large volume of output: every incref/decref is logged.

Overview (`src/fmt/README.md`) Copy Section

Fmt

This directory contains the implementation of the roc fmt command, the code formatter for the Roc language.

Its primary purpose is to format .roc source files with a consistent and deterministic style.

While this module is currently only used by the roc CLI, it is designed to be reusable so that it can be integrated into other tools in the future.

Overview (`src/glue/README.md`) Copy Section

Roc Glue

roc glue generates platform-facing bindings from checked Roc platform
metadata. A glue script such as src/glue/src/ZigGlue.roc,
src/glue/src/RustGlue.roc, or src/glue/src/CGlue.roc receives the
compiler-emitted type table and writes host-language source files for platform
authors.

Why Glue Code Generates the Interface Copy Chapter

The Roc platform ABI is not just a collection of structs that can be copied by
hand into C, Zig, or Rust. Host-visible values carry target-specific layout,
ownership, and refcounting contracts:

• records and tag unions have compiler-committed field order, padding, size,
  alignment, discriminants, payload offsets, and pointer-width differences
• Str, List, Box, and erased callables have runtime allocation headers
  and ownership rules that are not visible from the Roc source type alone
• lists of refcounted elements need different allocation metadata and teardown
  than lists of plain bytes
• seamless slices do not necessarily point at the allocation base that must be
  retained or released
• hosted functions receive owned refcounted arguments, and Roc-provided
  functions return owned refcounted values
• recursive refcounted data requires compiler-derived retain/release plans
• erased callables require a specific call ABI, capture teardown callback, and
  host/runtime context
• 128-bit integer vectors use the target C ABI's native vector class, including
  different direct-argument, direct-result, and aggregate rules, and
  memory-class multi-vector aggregates need the union spelling in C

For those reasons, platform code should consume generated glue instead of
hand-rolling Roc ABI bindings. The generated interface is the compatibility
layer between platform authors and Roc compiler internals. If Roc needs to
change its ABI in the future, platform consumers should be able to regenerate
glue and keep using the generated helper API rather than rewriting manual
layout and ownership code.

Generated Helper Contract Copy Chapter

CGlue, ZigGlue, and RustGlue should expose idiomatic helpers for their host
languages while enforcing the same underlying ABI contract. Generated helpers
should cover:

• layout assertions for ABI-visible types
• typed views and constructors for strings, lists, boxes, records, tag unions,
  integer vectors, and erased callables
• retain, release, and recursive teardown for refcounted public types
• explicit ownership transfer for hosted arguments, provided returns, stored
  values, and values returned back to Roc
• allocation helpers for Roc headers, alignment, overflow checks, static data,
  list element metadata, and pointer-width differences
• erased-callable invocation helpers for args buffers, return buffers, captures,
  and owned results
• unsafe or ownership-typed APIs where the host language cannot make invalid
  states impossible

Glue generators must consume compiler-emitted metadata such as RecordRepr,
RecordField, TagUnionRepr, TagVariant, TypeRepr, and explicit ownership
plans. They must not reconstruct runtime layout or ownership behavior from
display strings, semantic type names, source field order, or incidental data
structure shape.

For concrete Roc-owned values, Zig and Rust glue compose zero-runtime-storage
release policies. RocList(T).deinit in Zig selects the compiler-generated
policy for T at comptime. Rust provided functions whose results have complete
release policies also get an _owned wrapper returning RocOwned; its
zero-sized policy implements recursive Drop without adding a descriptor or
context pointer to the value. List release atomically claims the final spine
reference before reading elements, then releases the allocation's complete
element range and finally frees the spine. Opaque payloads are not assigned a
structural policy: recursive teardown across that boundary requires an explicit
compiler-owned release root or descriptor rather than host-side guessing.

Pointer-Width Contract Copy Chapter

The glue script input is targetless. It carries no concrete Roc build target,
OS, or architecture, and roc glue has no --target flag: running it on any
machine produces the same generated source for a given platform and glue
script. Compiler-emitted layout facts vary only by host pointer width, modeled
as AbiWidth := [Pointer32, Pointer64]. Generated source may additionally use
the host compiler's target conditionals to select the natural C spelling and
calling convention for a native vector leaf; that selection does not alter any
compiler-emitted record, union, or ownership fact.

What the compiler guarantees to glue scripts:

• Every layout fact arrives for both widths (size32/size64,
  offset32/offset64, alignment32/alignment64,
  discriminant_offset32/discriminant_offset64, ...), read from the layout
  store with explicit dual-width queries. Use the width-parameterized
  accessors (AbiLayout.size(layout, width),
  AbiFieldLayout.offset(field, width), ...).
• Everything else is width-independent: field order, field names, tag names,
  discriminant values, and refcount plans.
• AbiRecordLayout.fields and AbiTagLayout.payload_fields are emitted in
  committed layout order, which is identical at both widths with
  non-decreasing offsets at both widths (asserted in src/glue/glue.zig).
  Emitters must iterate fields in the given order and must not re-sort them.
• Padding fields (is_padding) have nonzero size at both widths; zero-sized
  padding markers such as _ : {} are dropped before emission.

What generators must do with that data:

• Render pointer-sized Roc values (Str, List, Box, erased callables)
  with the host language's pointer-sized types (size_t/uintptr_t, usize,
  raw pointers), not hardcoded 4- or 8-byte shapes.
• Render every Vector128 leaf with the target's native vector type rather
  than a byte array or U128 substitute. Keep all eight Roc vector names as
  distinct generated binding types.
• Emit one source file per language containing both width shapes, resolved by
  the host compiler: #if UINTPTR_MAX == UINT64_MAX in C,
  if (@sizeOf(usize) == 4) in Zig, #[cfg(target_pointer_width = "32")] in
  Rust. A future language without a compile-time width idiom may instead emit
  one file per width; the dual-width schema supports both.
• Emit size/alignment/offset assertions from the emitted facts for both
  widths, so the host compiler proves the generated shapes match the
  committed ABI.
• Never compute sizes, offsets, or padding from reflected type shape; the
  compiler owns the ABI facts.

Concrete build targets still exist, but only in the test harness and roc build: the runtime matrix compiles the same generated source for native and
wasm32 hosts and runs it in both.

Regenerating the C Header Snapshot Copy Chapter

glue command with CGlue generates expected C header byte-compares CGlue
output for test/fx/platform/main.roc against
test/glue/fx_platform_cglue_expected.h. After an intentional CGlue change,
regenerate the snapshot with:

roc glue src/glue/src/CGlue.roc /tmp/cglue-out test/fx/platform/main.roc
cp /tmp/cglue-out/roc_platform_abi.h test/glue/fx_platform_cglue_expected.h

Treat an unexpected diff as an emitter bug, not a regen trigger.

Host ABI Lock Copy Chapter

The templates restate the host ABI—the RocStr/RocList/RocDec
layouts, the RocHost callback vtable, the extern runtime symbols, and the
erased-callable payload—as text in their output languages, so the compiler
cannot import those restatements. zig build run-check-glue-abi is the
enforcement. It generates Zig glue and compiles test/glue/zig_abi_lock.zig
against both the generated file and the canonical builtins definitions for
x86-64 and AArch64 on Linux, macOS, and Windows, plus wasm32. It also generates
the vector-heavy layout-probe C and Rust bindings: C is compiled over that
same seven-target matrix, while Rust is compiled for the configured native
target and wasm32 (rustc requires an installed core library for every
additional cross target).
Template drift from src/builtins/host_abi.zig, str.RocStr,
list.RocList, dec.RocDec, or erased_callable fails that step at compile
time. Generated C and Rust files carry matching offsetof/offset_of! static
assertions, which their compile controls and the native/wasm runtime matrix
verify per target.

test/glue/generate_abi_lock.zig reflects the canonical builtins declarations
into target-independent C and Rust reference declarations. C includes the
resulting canonical_host_abi.h; Rust compiles a copy of its generated bindings
with canonical reference structs, layout assertions, and type assignments
appended. The foreign compilers determine each target's physical layout. C
locks strings, lists, and erased-callable callbacks; Zig and Rust also lock the
runtime symbol signatures and the helper-only RocHost callback prefix.
RocHost deliberately excludes interpreter-only hosted dispatch tables and is
never passed across compiled Roc entrypoints.

Glue platform marshalling Copy Chapter

glue.zig materializes glue input and reads its result through the checked
platform's runtime schemas and committed LIR layouts. The old
platform/host.zig extern records have been removed; alphabetical field order
is no longer a handwritten ABI assumption. GlueRocValueWriter.recordField
uses the schema's logical field index and the layout store's physical offset.

The glue platform marshalling schema matches checked Roc records test compiles
DebugGlue.roc and locks the complete marshalling protocol against the actual
checked platform, including nested list elements, records, tag payloads, and
scalar leaf types.
A second test copies the platform sources into isolated temporary directories,
mutates field names, field sets, scalar types, nested record types, and tag
payloads. Every mutated checked schema must fail the same lock. Run both with:

zig build run-test-zig-module-glue -- --test-filter 'glue platform'

ABI Risk Register and Roc Glue Runtime Controls Copy Chapter

Every risk in this section must be covered by at least one Roc glue test
platform. In this context, "runtime control" means a check executed by the Roc
glue test harness, not a production assertion inserted into ordinary generated
glue.

The glue runtime harness works by:

1. selecting realistic platform shapes,
2. generating C, Zig, and Rust glue for those platforms,
3. compiling each generated interface with a matching host implementation for
   native and wasm targets,
4. building a Roc app that imports the platform, and
5. executing the resulting native program or wasm module.

The host implementation in those runs is deliberately a contract test runner.
It implements the platform API while collecting allocator statistics,
telemetry, ownership events, layout checks, refcount checks, and scenario
results.

The control column names concrete glue runtime scenarios, platform shapes,
language matrix cells, compile checks, or source-shape assertions that enforce
the contract. glue runtime: means the CGlue, ZigGlue, and RustGlue
runtime matrix for both native and wasm32 targets unless the entry names a
specific language, target, or custom case.

Those controls should run through realistic glue platforms and should cover
CGlue, ZigGlue, and RustGlue. A bug found in one generated language should be
captured as a shared platform shape unless the behavior is genuinely
language-specific.

Release Files Copy Chapter

The checked-in glue specs under src/glue/src/ use platform glue, a
compiler-owned platform embedded in the Roc compiler. Keep that form for local
compiler development and releases.

Nightly releases should use generated copies instead:

zig build build-glue-release -Dglue-release-tag=nightly-YYYY-Month-DD-SHORTSHA

This writes zig-out/glue-release/:

glue/RustGlue.roc
glue/ZigGlue.roc
glue/CGlue.roc
glue/README.md
glue/env

Include the generated glue/ directory in every platform compiler archive for
that same release. The generated specs rely on the compiler-owned glue platform
embedded in that compiler build, so downstream repos do not need a Roc source
checkout or a separate glue platform package.

When roc-lang/setup-roc installs a nightly that contains glue/, it exports:

ROC_GLUE_DIR
ROC_RUST_GLUE
ROC_ZIG_GLUE
ROC_C_GLUE

Downstream CI can then run:

roc glue "$ROC_RUST_GLUE" ./platform/main.roc --output-dir ./platform

Overview (`src/interpreter_shim/README.md`) Copy Section

Interpreter Shim

The interpreter shim runs already-lowered Roc programs. The compiler parent
process owns checking and post-check compilation and publishes an ARC-inserted
LIR image into shared memory. The child process maps that same memory, creates
zero-copy views over the LIR/runtime-layout arrays, and evaluates them with the
LIR interpreter.

Runtime Boundary Copy Chapter

┌─────────────────┐   LIR image    ┌──────────────────┐
│    roc CLI      │ ──────────────────────> │  Interpreter     │
│  (parent proc)  │                         │  Host (child)    │
└─────────────────┘                         └──────────────────┘

Parent responsibilities:

1. Parse and canonicalize source.
2. Type check and publish checked modules.
3. Resolve roots, platform entrypoints, hosted procedures, static dispatch, and
   compile-time constants before post-check lowering.
4. Lower through the post-check IRs to LIR and insert ARC statements.
5. Publish the target-specific LIR image into shared memory.

Child responsibilities:

1. Map shared memory.
2. Validate the LIR image header and bounds.
3. Create zero-copy views of the LIR store, committed layouts, literal pool,
   root procedures, and hosted-function dispatch metadata.
4. Initialize LirInterpreter.
5. Invoke the explicit LIR root procedure requested by the host.

The child must never receive ModuleEnv, CIR, checked modules, or post-check
IRs. It must not perform compiler lowering, root discovery, static dispatch
resolution, platform lookup, compile-time evaluation, or recovery of missing
compiler data.

Operating Modes Copy Chapter

IPC Mode (`roc path/to/app.roc`) Copy Section

The parent publishes the LIR image into shared memory using the existing
shared-memory coordination path. The child maps that memory and views the image
in place.

Embedded Mode (`roc build --opt=interpreter path/to/app.roc`) Copy Section

The parent embeds a viewable LIR image into the output binary. At runtime,
the shim views that image without running semantic compiler stages.

Key Symbols Copy Chapter

• roc__main: Entry point called by the platform host.
• roc_alloc, roc_dealloc, roc_realloc: Memory allocation functions.

Overview (`src/ipc/README.md`) Copy Section

IPC (Inter-Process Communication)

This directory contains helpers for communication between the roc CLI and the Roc interpreter, which is spawned as a child process.

The communication is implemented using shared memory to ensure high performance.

The roc CLI owns parse, canonicalization, type checking, checked module publication, post-check lowering, LIR lowering, and ARC insertion. After ARC insertion, the parent publishes a target-specific LIR image into the existing shared-memory region. The interpreter child maps that same shared memory, validates the LIR image header, creates zero-copy LIR views, and evaluates explicit roots.

The interpreter child must not receive or inspect ModuleEnv, CIR, checked modules, or post-check IRs, and it must not run compiler lowering stages. Parent-child IPC for the LIR image is shared-memory mapping only, not serialization/deserialization.

This allows for a very responsive CLI and a fast development loop.

Overview (`src/layout/README.md`) Copy Section

Layout

Memory layout and data structure representation for the Roc runtime.

Overview Copy Chapter

The layout module is responsible for determining how Roc data types are represented in memory during execution. It handles memory alignment, field ordering, and efficient storage of Roc's algebraic data types.

Purpose Copy Chapter

This module provides:

• Memory Layout: Determining the optimal memory layout for Roc data structures
• Field Ordering: Performing one shared stable alignment sort at the IR -> LIR/layout boundary while preserving earlier semantic field order among equal-alignment fields
• Alignment: Ensuring proper memory alignment for different data types
• Size Calculation: Computing the memory requirements for Roc types
• Runtime Support: Layout information needed by the interpreter and code generator

The layout module is crucial for the eval stage (interpreter) and any future code generation stages, as it determines how data is stored and accessed in memory.

Overview (`src/lir/README.md`) Copy Section

Low-level intermediate representation

LIR is the common, layout-complete boundary between checked-program lowering
and execution. Ownership-neutral transformations preserve explicit value,
control-flow, and frame inventories; ARC then makes every ownership operation
explicit so backends and the interpreter need no reference-counting policy.

Parallel procedure rewrites and ARC emission share frozen inputs and publish
private body output in deterministic order. Global analyses and identity
reservation remain coordinator-owned. LirImage preserves the resulting
ARC-complete program without compiler scratch or worker state.

use_order.zig owns the neutral control-flow queries shared by loop promotion
and ARC. Procedure rewrites use compact statement/local domains; ARC retains
its store-indexed topology and reuses scratch across procedure queries, resetting
only touched entries. Neither client reconstructs ownership decisions from the
other.

See design.md for the transformation, ownership, and serialization contracts.

Overview (`src/llvm_compile/README.md`) Copy Section

LLVM Compile

Compiles LLVM bitcode into native shared libraries for JIT evaluation.

This module sits between the LLVM IR codegen backend (src/backend/llvm/) and
the evaluators that execute compiled Roc code. It handles the LLVM-to-native
compilation pipeline and platform-specific linking so that callers can simply
dlopen the result and call roc_eval.

Overview (`src/lsp/README.md`) Copy Section

Roc LSP

The Roc compiler can now expose an experimental Language Server Protocol (LSP) endpoint
written in Zig as part of the Rust to Zig rewrite.

Current state Copy Chapter

The following requests are handled:

• initialize, shutdown
• textDocument/hover
• textDocument/definition
• textDocument/completion
• textDocument/documentSymbol
• textDocument/documentHighlight
• textDocument/references
• textDocument/inlayHint
• textDocument/codeAction
• textDocument/formatting
• textDocument/foldingRange
• textDocument/selectionRange
• textDocument/semanticTokens/full
• textDocument/rename, textDocument/prepareRename

The following notifications are handled:

• initialized, exit
• didOpen (stores the buffer into a StringHashMap)
• didChange (same as didOpen, and supports incremental changes)

Diagnostics are pushed as textDocument/publishDiagnostics when a document is opened or changed.

Inlay hints Copy Section

Roc infers most types, and an annotation can still leave parts to inference with _, so the
type a binding actually has is often written nowhere in the file. textDocument/inlayHint
renders it next to the name.

Only plain bindings get a hint—one name, one type. Skipped are bindings that already carry a
written annotation (their type is on screen), bindings marked unused with a leading _, and
any pattern whose source text is not exactly the name: a compiler-synthesized binding has no
name in the source, and import "x" as name : Str already spells its type.

Labels are cut at 56 bytes with a trailing …, because a hint is drawn inside the line it
annotates and an inferred Roc type can be far longer than the code it describes—a generic
function carries its whole where clause. Hovering the same name gives the type in full.

Each hint carries the edit that writes its type into the source, so a client that lets the
reader accept a hint inserts the annotation instead of leaving them to retype it. That matters
here more than elsewhere: a hint reads like an inline annotation, which is how several
languages spell one, and Roc has no name : Type = value form - inside a block that spelling
is already taken by record fields, so retyping what a hint shows changes what the braces mean.
The edit writes the two-line form, and carries the type in full even where the label is cut.

A hint on a lambda parameter carries no edit. The type is still worth seeing, but a parameter
takes no annotation, and one written above it would land in the parameter list. The same
applies to any binding that does not open its line.

A document that does not build produces no hints, which leaves whatever the editor last drew
in place rather than blanking every hint on each keystroke.

Code actions Copy Section

Two actions are offered, both written from the checked types rather than from the text on
screen. Neither is offered unless it can be written in full: a document that does not build
has no types to read, and handing the author source that does not compile is worse than
offering nothing.

Annotate a binding with its inferred type writes the type on its own line above the
binding, carrying the indentation of the line it opens. Roc has no inline foo : U64 = 100
form, so this two-line one is the only one there is. It is offered for any binding a
definition or a statement declares that does not already write its type - top level, or
several blocks deep inside a function.

Lambda parameters and destructured fields are left out. They are plain bindings like any
other, and a Roc lambda may spread its parameters over several lines, so a parameter can open
a line of its own: what declares a binding tells the two apart, the source around it does not.
The binding must still open its line, which rules out a block written on a single line, since
anything in front of the binding would be split across the inserted line break. A selection
covering several bindings is answered with one action per binding, each title naming its own:
the range does not say which was meant, and no comparison of names or positions recovers it.
A cursor, which is how the request usually arrives, touches one name and so produces one
action. A selection covering several functions is answered the same way.

Generate an expect test for a function writes an expect that calls the function,
directly after the definition it tests. Each argument and the expected result are placeholder
literals of the right type - "", 0, [], Bool.True, and records and tuples of those -
so the generated test compiles and fails loudly until the author replaces the values.

The action is left out rather than guessed at when a type has no such literal: a nominal type
the author declared, a tag union, a function argument, or a type variable. It is also left out
for effectful functions, because expect checks a value rather than running effects, for
functions taking no arguments, and for anything that is not a top-level definition - a
generated expect sits at the top level, where a name bound inside a block cannot be reached.

Both actions write their line breaks the way the open document writes its own, so applying one
to a CRLF file does not leave a lone LF behind. The compiler rewrites CRLF as it loads a file,
so this is read from the document the client holds rather than from the module's source.

The inserted annotation is the checker's own rendering of the type, which is worth a read
before it is kept: an inferred type can be wider than the one the author would write.

References Copy Section

textDocument/references reports every place a symbol is written in the requested document.
Occurrences come from the CIR, so a reference resolves to the binding it actually names rather
than to matching text, and a same-named binding in another scope is not reported. Unlike rename
it only reports, so it is not limited to plain bindings—a destructured field can have its uses
listed even though renaming one is refused.

includeDeclaration controls whether the binding site and the name on its type annotation are
included; both count as the declaration. A client that omits the field gets everything.

Only the requested document is searched, so a short result is not proof that a symbol is unused
across a project—see the cross-module note below.

Positions Copy Section

Positions are exchanged in UTF-16 code units, as the protocol specifies and as the server
advertises with positionEncoding. src/lsp/position.zig owns the conversion in both
directions, with an ASCII fast path, and the same helper backs the incremental edits in
document_store.zig in a strict mode: a query rounds a column that lands inside a character
to the nearest boundary, an edit refuses it.

Rename Copy Section

Rename edits only the document it was asked about. It rewrites the binding, the name on
its type annotation, and every reference, taking the occurrences from the CIR so shadowing
is respected. Type errors do not stop it: checking replaces rejected code with runtime errors,
and every query here reads through those replacements to the code as written, so occurrences
inside rejected code are renamed, listed, and highlighted like any other.

It refuses rather than producing a partial rewrite, because editing every occurrence but one
silently breaks the program. It refuses when:

• the document could not be built, so there is no CIR to read occurrences from
• the position names something other than a plain local binding—a type, a tag, a record
  field, or a destructuring pattern
• the new name is not a single Roc identifier
• the new name would change what the name means: case separates types from values, and the
  !, _ and $ markers carry meaning, so foo cannot be renamed to foo!
• another binding of the new name is live where the renamed one is, which would capture a
  reference or shadow a binding

Cross-module limits Copy Section

Neither references nor rename looks past the requested document. References will miss uses in
other modules, and rename edits only the one file, so renaming an exported name breaks its
importers. The editor cannot warn about either, so it is on the author to check.

How to implement new LSP capabilities Copy Chapter

The core functionalities of the LSP have been implemented in a way so that transport.zig and
protocol.zig shouldn't have to be modified as more capabilities are added. When handling a new
LSP method, like textDocument/completion for example, the handler should be added in the handlers
directory and its call should be added either in request (if it expects a response) or notification
(if it doesn't expect a response). textDocument/completion for example would go here :

const request_handlers = std.StaticStringMap(HandlerPtr).initComptime(.{
    .{ "initialize", &InitializeHandler.call },
    .{ "shutdown", &ShutdownHandler.call },
    .{ "textDocument/completion", &CompletionHandler.call },
});

When adding a new capability, if the server is ready to support it, you need to add the capabilities to
the capabilities.zig file for the initialize response to tell the client the capabilities is available :

pub fn buildCapabilities() ServerCapabilities {
    return .{
        .textDocumentSync = .{
            .openClose = true,
            .change = @backingInt(ServerCapabilities.TextDocumentSyncKind.incremental),
        },
    };
}

Here we tell the client that textDocumentSync is available in accordance to the LSP specifications data
structure. The Server struct holds the state, meaning in has the knowledge of the project files, the
documentation, the type inference, the syntax, etc. Every handler has access to it. These points of knowledge
are ideally separated in different fields of the server. For example, the opened buffer and other desired files
are stored in a DocumentStore which is a struct containing a StringHashMap, accessible through the Server.

Starting the server Copy Chapter

Build the Roc toolchain and run:

roc experimental-lsp

Normally you would just let your editor handle this.

Debugging Copy Chapter

Because the LSP takes control of the standard input and output, an optional flag was added.

roc experimental-lsp --debug-transport

Passing the --debug-transport flag will create a fresh lsp-debug-<random>.log in your Roc cache directory
(~/.cache/roc on Linux, ~/Library/Caches/roc on macOS, %APPDATA%\Roc on Windows; the server
prints the exact path to stderr on startup). A mirror of the raw JSON-RPC traffic will be appended
to the log file. Watching the file will allow a user to see incoming and outgoing message between
the server and the editor

tail -f /path/printed/by/the/server
---
[1763992681773] OUT (128 bytes)
{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"positionEncoding":"utf-16"},"serverInfo":{"name":"roc-lsp","version":"0.1"}}}
---
[1763992681828] IN (52 bytes)
{"jsonrpc":"2.0","method":"initialized","params":{}}
---

Additional debug channels can be enabled with --debug-build, --debug-syntax, and --debug-server
which log build environment activity, syntax/type checking, and server lifecycle details respectively
to the same session log file. Logs are created exclusively with owner-only permissions
on Unix; existing files and symlinks are never reopened. Transport logs contain
full document contents.

Workspace trust Copy Chapter

By default, opening or changing a document does not compile it. Formatting,
folding ranges, and selection ranges remain available; diagnostics and semantic
features require the client to send this in its initialize params:

"initializationOptions": { "trustedWorkspace": true }

Enable this only after the user trusts the workspace: checking can download URL
packages and execute compile-time Roc code inside the server. Clients must derive
trust from their own user-controlled trust mechanism, never repository settings.
Restart the server when trust changes. Trust applies to the entire server session,
including every opened document and transitive dependency; use separate sessions
for untrusted folders. Clients without a trust integration remain in syntax-only
mode. Semantic requests return a trust-required error in that mode.

Editor examples Copy Chapter

Neovim (lua + nvim-lspconfig) Copy Section

The plan is to eventually just add the lsp to the Mason package manager, but for the meantime a manual
setup is possible. Your config might vary, but it'll look something like this:

local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")

if not configs.roc_lsp then
  configs.roc_lsp = {
    default_config = {
      name = 'roc_lsp',
      cmd = { '/path/to/roc', 'experimental-lsp', '--debug-transport' },
      filetypes = { 'roc' },
      root_markers = { 'main.roc', 'app.roc' },
      single_file_support = true,
    },
  }
end

lspconfig.roc_lsp.setup({
  capabilities = require("cmp_nvim_lsp").default_capabilities(),
})

-- If using Mason, you might have to remove the ensure_installed check
ensure_installed = vim.tbl_filter(function(name)
  return name ~= 'roc_lsp'
end, ensure_installed)

VS Code Copy Section

TODO

Zed Copy Section

TODO

Overview (`src/machine_code_shim/README.md`) Copy Section

Machine-code run shim

This archive loads the compiler's explicit run-image contract inside a platform
process. Its build-time verifier seals the host boundary: only declared Roc and
C/OS ABI imports and the three shim entrypoints may participate in platform
symbol resolution.

Compiler-generated 32-bit arithmetic and ARM AAPCS helpers use the active Zig
toolchain's implementations, compiled into the shim with local binding. They
must neither depend on the host's compiler-rt nor interpose its definitions.
Source references retain the implementations, while assembler-local aliases
preserve libcall names through LLVM's late libcall generation. Whole public
compiler-rt archives are not shim inputs.

Linux ARM instruction publication uses the kernel cache-flush ABI. The Linux
ARM shim emits no exception-unwind tables: its host crash contract aborts and
its std options disable stack tracing, so it must not depend on EHABI
personalities or pretend to implement them with empty routines. This policy
does not change Windows unwind metadata or other architectures' stack walking.

zig build check-selected-machine-code-shim -Dtarget=x86-linux-musl (or
arm-linux-musleabihf) checks the actual archive and links it with deliberate
strong host/compiler-runtime collisions. run-check-machine-code-shim-archive
covers all supported object formats. Run optimized checks too: libcall creation
and dead-code elimination differ from Debug.

Overview (`src/parse/README.md`) Copy Section

Parse

Converts Roc source code into an Abstract Syntax Tree (AST) through tokenization and parsing.

Purpose Copy Chapter

The parse module is the first stage of the Roc compiler pipeline, transforming raw source code into a structured representation that can be processed by subsequent stages (canonicalization, type checking, etc.).

Overview (`src/playground_wasm/README.md`) Copy Section

Roc WASM Playground Interface Control Document

Overview Copy Chapter

The Roc Playground provides a WebAssembly interface to the compiler, providing analysis of .roc code in web browsers and JavaScript environments. It implements a state machine architecture to support both single-file compilation analysis and interactive REPL (Read-Eval-Print Loop) sessions.

This playground protocol remains available for compiler exploration. Embedders
that only need a REPL should use the smaller-scope interface documented in
src/repl_wasm/README.md; that module has no compiler-introspection modes.

The playground supports:

• Single-file compilation: Load and analyze complete Roc source files
• Interactive REPL: Evaluate expressions and definitions incrementally
• Compiler introspection: Query tokens, AST, CIR, types, and hover information
• Diagnostic reporting: Comprehensive error and warning information
• State management: Clean separation between compilation and REPL modes

State Machine Copy Chapter

The playground operates as a finite state machine with four states:

START --(INIT)-> READY --(LOAD_SOURCE)-> LOADED
                   |                       |
                   |                       |
                   +--(INIT_REPL)--> REPL_ACTIVE
                   ^                       |
                   |                       |
                   +--------(RESET)--------+

State Descriptions Copy Section

• START: Initial state, awaiting initialization
• READY: Initialized and ready to compile source code or start REPL
• LOADED: Source compiled, ready for queries about compilation stages
• REPL_ACTIVE: REPL session active, ready for interactive evaluation

WASM Exports Copy Chapter

Core Functions Copy Section

// Initialize the WASM module
init(): void

// Process a message and get response
processMessage(
    messagePtr: number,     // Pointer to JSON message
    messageLen: number,     // Length of message
    responsePtr: number,    // Pointer to response buffer
    responseBufferSize: number  // Size of response buffer
): number  // Returns actual response length

// Memory management
allocate(size: number): number | null    // Returns pointer or null
deallocate(ptr: number, size: number): void

// Utilities
getCurrentState(): number    // Returns current state as integer
cleanup(): void             // Clean up all resources

Message Protocol Copy Chapter

All communication uses JSON messages. Each message must have a type field.

Message Types Copy Section

1. INIT

State: START → READY
Purpose: Initialize the compiler and get version information

Request:

{"type": "INIT"}

Response:

{
  "status": "SUCCESS",
  "message": "debug-813709ba"
}

2. LOAD_SOURCE

State: READY → LOADED
Purpose: Compile Roc source code through all compiler stages

Request:

{
  "type": "LOAD_SOURCE",
  "filename": "Demo.roc",
  "source": "Demo := [].{\n    foo = 42\n    bar = \"baz\"\n}\n"
}

Response:

{
  "status": "SUCCESS",
  "message": "LOADED",
  "diagnostics": {
    "summary": {"errors": 0, "warnings": 0},
    "debug_counts": { ... },
    "list": [],
    "html": "<div class=\"reports\"></div>"
  }
}

3. QUERY_TOKENS

State: LOADED
Purpose: Get tokenization results as formatted HTML

Request:

{"type": "QUERY_TOKENS"}

Response:

{
  "status": "SUCCESS",
  "data": "<div class=\"token-list\">...</div>"
}

4. QUERY_AST

State: LOADED
Purpose: Get Abstract Syntax Tree as formatted HTML

Request:

{"type": "QUERY_AST"}

Response:

{
  "status": "SUCCESS",
  "data": "<div class=\"ast-tree\">...</div>"
}

5. QUERY_CIR

State: LOADED
Purpose: Get Canonical Intermediate Representation as formatted HTML

Request:

{"type": "QUERY_CIR"}

Response:

{
  "status": "SUCCESS",
  "data": "<div class=\"cir-display\">...</div>"
}

6. QUERY_TYPES

State: LOADED
Purpose: Get type information as formatted HTML

Request:

{"type": "QUERY_TYPES"}

Response:

{
  "status": "SUCCESS",
  "data": "<div class=\"types-display\">...</div>"
}

7. QUERY_FORMATTED

State: LOADED
Purpose: Get formatted Roc code

Request:

{"type": "QUERY_FORMATTED"}

Response:

{
  "status": "SUCCESS",
  "data": "Demo := [].{\n\tfoo = 42\n\tbar = \"baz\"\n}\n"
}

8. GET_HOVER_INFO

State: LOADED or REPL_ACTIVE
Purpose: Get hover information for an identifier at a specific source position

Request:

{
  "type": "GET_HOVER_INFO",
  "identifier": "x",
  "line": 1,
  "ch": 5
}

Response:

{
  "status": "SUCCESS",
  "hover_info": {
    "name": "x",
    "type_str": "Num *",
    "definition_region": {
      "start_line": 1,
      "start_column": 1,
      "end_line": 1,
      "end_column": 7
    },
    "docs": null
  }
}

Note: In REPL_ACTIVE state, this works with the last REPL evaluation's ModuleEnv.

9. INIT_REPL

State: READY → REPL_ACTIVE
Purpose: Initialize a REPL session for interactive evaluation

Request:

{"type": "INIT_REPL"}

Response:

{
  "status": "SUCCESS",
  "message": "REPL initialized",
  "repl_info": {
    "compiler_version": "debug-813709ba",
    "state": "REPL_ACTIVE"
  }
}

10. REPL_STEP

State: REPL_ACTIVE
Purpose: Submit a line of input to the REPL for evaluation

Request:

{
  "type": "REPL_STEP",
  "input": "x = 42"
}

Response (Definition):

{
  "status": "SUCCESS",
  "result": {
    "output": "assigned `x`",
    "type": "definition",
    "compiler_available": true
  }
}

Response (Expression):

{
  "status": "SUCCESS",
  "result": {
    "output": "43",
    "type": "expression",
    "compiler_available": true
  }
}

Response (Error):

{
  "status": "SUCCESS",
  "result": {
    "output": "Evaluation error: error.ZeroSizedType",
    "type": "error",
    "error_stage": "evaluation",
    "error_details": "error.ZeroSizedType",
    "compiler_available": false
  }
}

Result Types:

• "definition": Input was a variable assignment (e.g., x = 42)
• "expression": Input was an expression that was evaluated
• "error": Input caused a compilation or evaluation error

Error Information (when type is "error"):

• error_stage: Indicates which compiler stage produced the error
  • "parse": Syntax/parsing error
  • "canonicalize": Canonicalization error
  • "typecheck": Type checking error
  • "layout": Layout computation error
  • "evaluation": Runtime evaluation error
  • "interpreter": Interpreter initialization error
  • "runtime": General runtime error
  • "unknown": Error stage could not be determined
• error_details: Additional error details, typically the specific error name or message

Compiler Availability:

• compiler_available: true: Compiler queries (QUERY_CIR, QUERY_TYPES, QUERY_FORMATTED, GET_HOVER_INFO) are available
• compiler_available: false: Compiler queries are not available (usually due to errors)

11. CLEAR_REPL

State: REPL_ACTIVE
Purpose: Clear all REPL definitions while keeping the REPL session active

Request:

{"type": "CLEAR_REPL"}

Response:

{
  "status": "SUCCESS",
  "message": "REPL cleared",
  "repl_info": {
    "compiler_version": "debug-813709ba",
    "state": "REPL_ACTIVE"
  }
}

12. RESET

State: LOADED or REPL_ACTIVE → READY
Purpose: Clean up compilation state and return to READY

Request:

{"type": "RESET"}

Response:

{
  "status": "SUCCESS",
  "message": "debug-813709ba"
}

Response Status Codes Copy Chapter

• SUCCESS: Operation completed successfully
• ERROR: Operation failed due to internal error
• INVALID_STATE: Message not valid for current state
• INVALID_MESSAGE: Malformed or unrecognized message

Diagnostic Information Copy Chapter

The LOAD_SOURCE response includes comprehensive diagnostic information:

Summary Copy Section

• errors: Total number of compilation errors
• warnings: Total number of warnings

Debug Counts Copy Section

Per-stage diagnostic counts:

• tokenize: Tokenization errors/warnings
• parse: Parse errors/warnings
• can: Canonicalization errors/warnings
• type: Type checking errors/warnings

Diagnostic List Copy Section

Array of diagnostic objects with:

• severity: "error", "warning", or "info"
• message: Human-readable diagnostic message
• region: Source location with start/end line/column

HTML Output Copy Section

Pre-formatted HTML for displaying diagnostics in web interfaces.

REPL Functionality Copy Chapter

The playground now supports interactive REPL (Read-Eval-Print Loop) sessions that allow users to:

• Define variables: x = 42 → "assigned x"
• Evaluate expressions: x + 1 → "43"
• Redefine variables: Automatically updates dependent expressions
• Error recovery: Invalid input doesn't corrupt REPL state
• Compiler integration: Access compiler diagnostics and introspection

REPL Features Copy Section

• State Persistence: Definitions remain available across multiple evaluations
• Dependency Tracking: When a variable is redefined, dependent expressions automatically use the new value
• Error Recovery: Invalid input doesn't corrupt the REPL state
• Compiler Integration: Full access to compiler diagnostics and introspection
• Clean State Management: Clear separation between REPL and single-file compilation modes

Compiler Queries in REPL Mode Copy Section

When in REPL_ACTIVE state, the following compiler query messages work with the last REPL evaluation:

• QUERY_CIR: Returns CIR for the last REPL evaluation

• QUERY_TYPES: Returns types for the last REPL evaluation

• GET_HOVER_INFO: Returns hover info for the last REPL evaluation

• These queries are only available when compiler_available: true in the REPL response.

Integration Notes Copy Chapter

1. Initialization: Always call init() before processing messages
2. State Awareness: Track the current state to send appropriate messages
3. Memory Management: Always pair allocate with deallocate calls
4. Error Recovery: Handle both WASM errors and compilation errors gracefully
5. Buffer Sizing: Ensure response buffers are large enough for expected output
6. REPL State Management: Use RESET to switch between REPL and single-file modes

Example Usage Copy Chapter

Basic REPL Session Copy Section

// Initialize REPL
const initResponse = await sendMessage({type: "INIT_REPL"});

// Add definition
const defResponse = await sendMessage({
    type: "REPL_STEP", 
    input: "x = 42"
});
// Response: {result: {output: "assigned `x`", type: "definition"}}

// Evaluate expression
const exprResponse = await sendMessage({
    type: "REPL_STEP", 
    input: "x + 1"
});
// Response: {result: {output: "43", type: "expression"}}

// Query CIR of last evaluation
const cirResponse = await sendMessage({type: "QUERY_CIR"});
// Response: CIR representation of the last evaluation

Error Handling and Recovery Copy Section

// Submit invalid syntax - Parse error
const parseError = await sendMessage({
    type: "REPL_STEP", 
    input: "x = = 42"  // Invalid syntax
});
// Response: {
//   result: {
//     output: "Parse error: Expected expression",
//     type: "error",
//     error_stage: "parse",
//     error_details: "Expected expression",
//     compiler_available: false
//   }
// }

// Submit type error
const typeError = await sendMessage({
    type: "REPL_STEP",
    input: "\"hello\" + 42"  // Type mismatch
});
// Response: {
//   result: {
//     output: "Type check expr error: TypeMismatch",
//     type: "error",
//     error_stage: "typecheck",
//     error_details: "TypeMismatch",
//     compiler_available: false
//   }
// }

// Submit evaluation error
const evalError = await sendMessage({
    type: "REPL_STEP",
    input: "x +"  // Incomplete expression
});
// Response: {
//   result: {
//     output: "Evaluation error: error.ZeroSizedType",
//     type: "error",
//     error_stage: "evaluation",
//     error_details: "error.ZeroSizedType",
//     compiler_available: false
//   }
// }

// REPL state remains intact after errors, continue with valid input
const validResponse = await sendMessage({
    type: "REPL_STEP", 
    input: "x = 42"  // Should still work
});
// Response: {result: {output: "assigned `x`", type: "definition"}}

Using Error Information for Better UX Copy Section

// Process REPL response with enhanced error handling
function handleReplResponse(response) {
    const result = response.result;
    
    if (result.type === "error") {
        // Use error_stage to provide stage-specific help
        switch (result.error_stage) {
            case "parse":
                console.error("Syntax error:", result.output);
                showSyntaxHighlight(result.error_details);
                break;
            
            case "typecheck":
                console.error("Type error:", result.output);
                showTypeHints(result.error_details);
                break;
            
            case "evaluation":
                console.error("Runtime error:", result.output);
                showDebugInfo(result.error_details);
                break;
            
            default:
                console.error("Error:", result.output);
        }
        
        // Check if compiler is still available for queries
        if (result.compiler_available) {
            // Can still query CIR, types, etc.
            enableCompilerQueries();
        } else {
            disableCompilerQueries();
        }
    } else if (result.type === "definition") {
        console.log("Defined:", result.output);
    } else if (result.type === "expression") {
        console.log("Result:", result.output);
    }
}

Dependency Updates Copy Section

// Define variables
await sendMessage({type: "REPL_STEP", input: "x = 10"});
await sendMessage({type: "REPL_STEP", input: "y = x + 5"});
const result1 = await sendMessage({type: "REPL_STEP", input: "y"});
// Response: {result: {output: "15", type: "expression"}}

// Redefine x
await sendMessage({type: "REPL_STEP", input: "x = 20"});
const result2 = await sendMessage({type: "REPL_STEP", input: "y"});
// Response: {result: {output: "25", type: "expression"}}
// Shows that y automatically uses the new value of x

Build Copy Chapter

zig build build-playground

Output: zig-out/bin/playground.wasm

This module bundles the whole compiler, so a plain zig build builds it at
ReleaseSmall rather than Debug: a Debug build is ~85 MB and needs roughly
12 GiB of RAM to link. Any explicitly requested mode is still honored, so
-Doptimize=Debug does give you a Debug module. The playground integration
tests (zig build run-test-playground) run against this same artifact.

Overview (`src/repl_wasm/README.md`) Copy Section

Roc REPL WebAssembly module

repl.wasm is a self-contained, pure REPL. It does not expose the playground's
compiler-inspection state machine or the echo platform. One WebAssembly instance
owns one in-memory session.

Host ABI Copy Chapter

• roc_repl_alloc(len) -> ptr
• roc_repl_free(ptr, len)
• roc_repl_process(ptr, len) -> response_ptr
• roc_repl_free_response(response_ptr)

roc_repl_process accepts UTF-8 JSON. Its result begins with a four-byte
little-endian payload length followed by the UTF-8 JSON response. The module
exports its linear memory as memory.

Every request is an envelope with protocol, id, op, and optional params:

{"protocol":1,"id":1,"op":"eval","params":{"source":"x = 41\nx + 1"}}

Every response echoes protocol and id and contains either ok: true with a
result, or ok: false with a stable structured error. Unknown request
fields are rejected so misspelled parameters cannot silently change behavior.
The installed protocol.d.ts describes the complete version 1 request and
response shapes for JavaScript and TypeScript embedders.

The protocol contains no frontend presentation strings. In particular,
definition results do not return text such as assigned foo; they return
kind, definition_kind, name, type, committed, and revision fields.
For example:

{
  "source": "foo = \"bar\"",
  "kind": "definition",
  "definition_kind": "value",
  "name": "foo",
  "status": "ok",
  "committed": true,
  "revision": 1,
  "type": "Str",
  "diagnostics": [],
  "events": []
}

Operations and scope Copy Chapter

Evaluation is left-to-right. Each snippet reports whether it changed session
state through committed; expressions always report committed: false.
The batch result reports completed, stop_reason, committed_count, and the
final session revision. Earlier successful definitions remain available when
a later snippet fails.

Revisions are unsigned 32-bit counters scoped to one WASM instance, so they are
exact JavaScript numbers. Hosts must not compare revisions across instances.

Expression values, checked types, definition metadata, diagnostics, and ordered
dbg events are separate fields. Diagnostics have a stable code, severity,
human-readable message, and nullable region. A failed compile-time expect
or user-written crash is a checking diagnostic and does not poison the next
request.

Version 1 enumerates blocking diagnostics only; non-blocking compiler warnings
are not part of the current contract. This is reported by the capabilities
response rather than being left implicit.

Compile-time evaluation Copy Chapter

REPL expressions are explicit compile-time roots. Pure expressions produce an
inspected value, and dbg observations become ordered structured events.
Effectful expressions are rejected with an Effectful Compile Time Expression
diagnostic; the WebAssembly module does not expose a platform-effect boundary.

Text offsets and completion Copy Chapter

Source strings are UTF-8. All protocol offsets are zero-based UTF-8 byte
offsets; capabilities.offset_unit and every completion response state this
explicitly. A cursor beyond the source or inside a multi-byte code point is an
invalid_cursor request error.

Completion is deliberately scoped to names stored in the current REPL session.
It does not claim contextual field, tag, keyword, or builtin completion. The
scope is reported by capabilities.completion_scope. A completion response
contains prefix, cursor, replacement, items, and whether checked type
details are currently available. A standalone annotation is a valid
intermediate state; names remain completable while details_available is
false.

Frontend boundary Copy Chapter

ReplSession.stepLanguageWithConfig accepts Roc syntax and returns a typed
language result. Terminal commands are parsed by the CLI frontend and passed as
typed commands to executeCommandWithConfig; they are not recognized by the
WASM protocol. The browser demo renders only structured fields and never parses
compiler display text.

The module has no filesystem, network, package resolver, stdin, history store,
or platform effects. Hosts own persistence and cancellation. The demo uses a
Web Worker; Stop terminates the worker, creates a new module instance, and
replays the exact structured definition_source returned by get_state.

The demo keeps the complete editable notebook source in one textarea. A line
containing only #%% separates cells; Ctrl/Command-Enter evaluates the active
cell and advances to the next one. Completion requests contain only the active
cell source and translate browser UTF-16 cursor positions to protocol UTF-8
byte offsets. Syntax highlighting is intentionally deferred: a plain textarea
keeps selection, composition, accessibility, and cell-boundary behavior
correct without introducing a second synchronized text layer.

Overview (`src/reporting/README.md`) Copy Section

Reporting

Error reporting, diagnostics, and user feedback for the Roc compiler.

Overview Copy Chapter

The reporting module provides comprehensive error reporting and diagnostic information throughout the compilation process. It ensures that users receive clear, actionable feedback when things go wrong.

Purpose Copy Chapter

This module provides:

• Error Reporting: Structured error messages with source locations and context
• Diagnostics: Detailed information about compilation issues and warnings
• Source Location: Precise tracking of where errors occur in source code
• User-Friendly Messages: Clear explanations that help developers fix issues
• Consistent Formatting: Uniform error presentation across all compiler stages

The reporting module is used by parse, canonicalize, check, and other stages to provide consistent, helpful feedback to users when compilation fails or produces warnings.

Rendering architecture Copy Chapter

Compiler stages build a Report containing a Document; they do not format
individual output targets. renderer.zig traverses DocumentElement through
one walker, renderElementAs, for terminal, Markdown, HTML, and language-server
output. Report summaries and primary-source selection use projections of that same
walker. A source-layout hook supplies report framing for top-level secondary
blocks while nested blocks retain their document style.

Each target supplies a style with annotation delimiters, text escaping,
indentation, and hooks for source and structural formatting. Annotation style
tables are exhaustive: terminal styles select fields from ColorPalette in
style.zig, while Markdown, HTML, and language-server styles declare their
markup in renderer.zig. Adding an annotation requires its semanticName and
an entry in each target's style table. HTML classes come from semanticName;
../snapshot_tool/snapshot.css owns their colors, and the snapshot tool tests
check that every annotation has a CSS selector.

source_region.zig owns shared source layout. Layout iterates numbered source
rows and computes their underline spans without allocating; target hooks add
escaping, gutters, and markup around those computed rows. Report snippets use
Snippet to expand leading tabs, dedent source, and transform caret coordinates
together. This keeps the primary and secondary report snippets aligned using
the same calculations. Title uppercasing is shared with the snapshot tool
through the exported writeShouted helper.

report_sexpr.zig serializes the semantic report structure independently of
presentation layout. Ordinary compiler snapshots store that canonical form in
PROBLEMS. The type=reporting fixtures in test/snapshots/reporting/ pin the
canonical report alongside all four rendered forms; they complement the
exhaustive model-variant unit corpus.

Rendering checks Copy Chapter

parity_test.zig enumerates the document and annotation variants at compile
time, so extending the model requires extending its fixtures. The suite checks
visible text, source rows and line counts, underline spans, nested annotations,
and exact output pins across all four targets. It also exercises the report
entrypoints and HTML escaping.

Run the reporting suite with zig build run-test-zig-module-reporting. Run the
CSS coverage test with zig build run-test-zig-snapshot-tool -- --test-filter "snapshot CSS covers". Changes to shared rendering should also preserve the
tracked snapshot corpus and terminal diagnostic bytes unless an output change
is intentional.

Overview (`src/snapshot_tool/README.md`) Copy Section

Snapshot Tool

This directory contains a tool for snapshot testing the Roc compiler.

Snapshot testing is a method used to verify the behavior of the compiler's different stages. The tool generates "golden snapshot" files, which are baseline outputs that are known to be correct.

During testing, the tool runs the compiler and compares its output against these golden files. If there are any differences, the test fails. This is an effective way to detect regressions and unintended changes in the compiler's behavior across a large number of test cases.

The golden snapshots are committed to the repository and are therefore tracked by Git and checked along with any changes to the codebase.

Diagnostics Copy Chapter

Diagnostic coverage is split between semantic and presentation snapshots:

• The PROBLEMS section of ordinary snapshots contains the canonical,
  presentation-independent S-expression form of each reporting.Report
  (serialized by src/reporting/report_sexpr.zig), so those snapshots change
  only when diagnostic semantics change.
• type=reporting snapshots (in test/snapshots/reporting/) render the same
  semantic reports through every user-facing renderer: REPORT (canonical
  S-expression), CLI, MARKDOWN, HTML, and LSP; they are the only place
  where renderer-specific layout and markup are pinned.

See test/snapshots/README.md for details.

Overview (`src/target/README.md`) Copy Section

Target Architecture Documentation

This document defines the different machines and targets involved in building and running the Roc compiler, and compiling Roc programs. Understanding these distinctions is critical for correct cross-compilation support.

Machines and Targets Copy Chapter

There are six distinct machine contexts to consider:

1. Build Host Copy Section

The machine that compiles the Roc CLI itself (runs zig build).

• When it matters: Build scripts, compile-time constants in build.zig
• In code: Available via @import("builtin") during Roc CLI compilation
• Example: Your development MacBook running zig build

2. CLI Target Copy Section

The architecture the Roc CLI binary is compiled FOR. This determines what machine can run the resulting roc binary.

• When it matters: Cross-compiling the Roc CLI itself (rare)
• Usually: Same as Build Host (native compilation)
• In code: The -Dtarget= flag to zig build, or native by default
• Example: Building the CLI on x64 Linux to run on arm64 Linux

3. Shim Target Copy Section

The architecture each embedded interpreter shim is compiled FOR. The Roc CLI embeds multiple pre-compiled interpreter shims for different targets.

• When it matters: The interpreter shim's own memory layout and operations
• In code: @import("builtin").cpu.arch inside interpreter shim code
• Key insight: When a shim runs, builtin.cpu.arch reflects what it was compiled FOR
• Examples:
  • Native shim: compiled for CLI Target (runs directly)
  • wasm32-freestanding shim: compiled for wasm32 (runs in wasm runtime)

4. CLI Runtime Copy Section

The machine actually executing the Roc CLI.

• When it matters: Runtime behavior, file I/O, process spawning
• Usually: Same as CLI Target
• In code: Runtime detection via std.Target.current or OS APIs
• Example: The CI server running roc build

5. Compilation Target Copy Section

The target architecture for the Roc APPLICATION being compiled. This is what the user specifies when they want to cross-compile their Roc program.

• When it matters: Generated code layout, struct sizes, pointer widths
• In code: --target= flag to roc build, represented as RocTarget
• Examples:
  • roc build --target=wasm32 app.roc → Compilation Target is wasm32
  • roc build app.roc → Compilation Target defaults to first compatible as specified by the platform header, usually a native executable (CLI Runtime) but could build a static or shared library e.g. app.wasm.

6. App Runtime Copy Section

The machine/environment where the compiled Roc application will eventually execute.

• When it matters: The generated binary's behavior
• Relationship: Must be compatible with Compilation Target
• Examples:
  • wasm32 target → runs in browser or wasm runtime
  • x64linux target → runs on x64 Linux machines

CPU Level Copy Chapter

Each of the machines above is a CPU as well as an OS and architecture, and Roc
names two floors per architecture: .default and the v1 baseline (see
CpuLevel). The two are separate concerns from the six contexts above, and they
interact in one place that is easy to get wrong.

The Roc CLI is built for the architecture baseline so that one released binary
runs on every CPU of its architecture. That makes builtin.cpu a statement
about the CLI Target, not about the CLI Runtime: it cannot tell you
whether the machine executing roc has AVX2. Only a runtime query can, which is
what host_cpu.zig does.

So anything generated to run on the CLI Runtime—compile-time execution,
in-memory dev runs, and the Compilation Target chosen when the user passes no
--target—takes its CPU level from host_cpu.level(). Anything generated for
a Compilation Target the user named takes its level from that target, because
the App Runtime is then someone else's machine.

Key Relationships Copy Chapter

Build Host ──compiles──▶ CLI Target (Roc CLI binary)
                              │
                              │ embeds multiple
                              ▼
                    ┌─────────────────────┐
                    │  Interpreter Shims  │
                    │  - native shim      │◀── Shim Target (each has its own)
                    │  - wasm32 shim      │
                    │  - ...              │
                    └─────────────────────┘
                              │
                              │ runs on
                              ▼
                    CLI Runtime (user's machine)
                              │
                              │ compiles Roc app for
                              ▼
                    Compilation Target (--target flag)
                              │
                              │ produces binary for
                              ▼
                    App Runtime (where app runs)

Common Scenarios Copy Chapter

Native Development (Most Common) Copy Section

All targets are the same architecture:

• Build Host = CLI Target = CLI Runtime = Compilation Target = App Runtime
• Example: Developing on arm64 Mac, building apps to run on arm64 Mac

Cross-Compiling Roc Apps Copy Section

CLI runs natively, but compiles for a different target:

• Build Host = CLI Target = CLI Runtime (e.g., x64 Linux)
• Compilation Target = App Runtime (e.g., wasm32)
• Example: roc build --target=wasm32 app.roc on a Linux server

Cross-Compiling the CLI Itself Copy Section

Building the Roc CLI for a different machine:

• Build Host (e.g., x64 Linux CI) ≠ CLI Target (e.g., arm64 Mac)
• Example: CI building release binaries for multiple platforms

Overview (`src/types/README.md`) Copy Section

Types

Core type system implementation for the Roc language.

Overview Copy Chapter

The types module provides the foundational type system that underpins the entire Roc compiler. It defines the representation of all Roc types, including primitive types, algebraic data types, functions, and type variables used during type inference.

Purpose Copy Chapter

This module serves as the backbone for:

• Type Representation: Defining how all Roc types are stored and manipulated in memory
• Type Operations: Providing utilities for type comparison, substitution, and manipulation
• Type Variables: Managing type variables used during Hindley-Milner type inference
• Built-in Types: Implementing the core Roc type system (numbers, strings, lists, etc.)

The types module is used extensively by the canonicalize, check, and eval stages of the compiler to ensure type safety and provide the necessary type information for compilation and execution.

Overview (`test/downstream-compiler/README.md`) Copy Section

Downstream compiler consumer

This separate Zig executable uses only dependency.module(...) to import Roc's
compiler. It checks a small application, lowers its platform entrypoint to LIR,
builds and reads a LIR image, and executes the entrypoint with the interpreter,
asserting that the returned U64 is 42.

Run from the repository root:

zig build build-test-downstream-package
zig build run-test-downstream-package

The build helper snapshots the compiler sources, runs zig fetch (which applies
Roc's build.zig.zon .paths), and generates a consumer manifest with a URL and
hash for the resulting package archive. It builds in a separate directory;
there are no relative imports of the compiler checkout. The run step only
executes the built consumer. MiniCI includes both phases.

The manifest is generated because its dependency hash must describe the current
compiler sources. In a real downstream project, pin a published commit instead:

zig fetch --save=roc 'git+https://github.com/roc-lang/roc.git#<full-commit-sha>'

Use this fixture's build.zig as an example of importing the named modules.
See src/compile/README.md for the embedding contract. The platform needs no
native host library because this test executes its entrypoint in-process.

Overview (`test/fuzzing/README.md`) Copy Section

Fuzzing

The typed source generators must not hardcode userspace Roc names.

All generated type names, tag names, field names, function names, local names,
module names, and filenames must come from the fuzzer's symbol generator. Do not
add fixture modules, canned domain models, semantic identifiers, or raw Roc
snippets that bake in userspace names.

Do not add catalog-style fuzzers made from handwritten scenario emitters. Fuzzers
should generate small typed language constructs and compose them randomly, so
new features multiply the reachable program space instead of adding one more
fixed example.

Builtin names are the only exception. Hardcoding Bool, Str, List, Try,
Ok, Err, and public builtin associated function names is allowed when the
generated program is deliberately exercising builtin behavior.

Generated platform/app fuzzers must also generate app-provided names, platform
aliases, and platform wrapper names. External ABI symbol strings and target names
are platform data, not userspace Roc identifiers.

On macOS, AFL++ may fail with shmget() failed under the default System V
shared-memory limits. Prefix AFL commands with AFL_MAP_SIZE=2097152 unless the
machine has already been configured with afl-system-config.

Overview (`test/int/README.md`) Copy Section

Test Platform

This directory contains a primitive test platform for Roc and demonstrates how to pass multiple arguments from the host.

• Function signature: I64, I64 -> I64
• Description: Takes two random integers from the host and returns their product

zig build

# Run (ignore cached files)
./zig-out/bin/roc --no-cache test/int/app.roc

Overview (`test/snapshots/README.md`) Copy Section

Snapshots

Snapshot tests that validate compiler behavior by capturing the output of each compilation stage for specific Roc code examples.

Snapshot tests provide comprehensive validation of the compilation pipeline by showing how source code is transformed through each stage: tokenization, parsing, canonicalization, and type checking etc.

Each snapshot file contains the expected output and helps us to detect regressions when compiler behavior changes unexpectedly.

Semantic diagnostics vs renderer output Copy Chapter

Diagnostics are covered by two different kinds of snapshot, split so that
semantic changes and presentation changes never show up in the same files:

• Ordinary snapshots (type=file, snippet, expr, ...) capture diagnostic
  semantics. Their PROBLEMS section contains the canonical S-expression
  serialization of each reporting.Report (see
  src/reporting/report_sexpr.zig): severity, title, source regions, and the
  full document structure (text, annotations, source excerpts, underlines).
  It contains no renderer-specific details: no box-drawing characters, ANSI
  escapes, wrapping, or markup. NIL means the compile produced no reports.
  These snapshots answer: did the compiler produce the correct diagnostic?

• Reporting snapshots (type=reporting, in reporting/) pin renderer
  output. Each one compiles its SOURCE normally, then renders the same
  semantic reports through every user-facing format, one section per renderer:
  REPORT (the canonical S-expression), CLI (plain terminal layout),
  MARKDOWN, HTML, and LSP. Layout, wrapping, punctuation, and markup are
  pinned here and only here.

A renderer-only change must only affect files in reporting/; a change to
diagnostic semantics shows up in ordinary snapshots (and possibly in
reporting/ too). Note that snapshot post-processing globally rewrites the
removed header keyword to mod, which also applies inside the S-expression
output.

Usage Copy Chapter

• Generate all snapshots: zig build run-snapshot-tool
• Update specific snapshot: zig build run-snapshot-tool -- <file_path>
• Update expected from problems: zig build run-snapshot-tool -- <file_path> --update-expected
• Embed carriage-return source bytes: add source_escapes=true to META and write each carriage return as \r in SOURCE
• Debug REPL evaluation with trace: zig build run-snapshot-tool -- <repl_snapshot.md> --trace-eval

Trace Debugging Copy Section

The --trace-eval flag enables detailed interpreter tracing for debugging REPL snapshots:

# Debug build (trace support enabled by default)
zig build run-snapshot-tool -- src/snapshots/repl/repl_record_field_access.md --trace-eval

Requirements:

• Only works with REPL snapshots (type=repl)
• Can only be used with a single snapshot file
• Trace output is automatically enabled in debug builds
• For release builds, use -Dtrace-eval=true to enable tracing

Overview (`test/str/README.md`) Copy Section

Test Platform

This directory contains a primitive test platform for Roc and demonstrates passing a string to and from the host.

• Function signature: Str -> Str
• Description: Takes a string from the host and returns a processed string

zig build

# Run (ignore cached files)
./zig-out/bin/roc --no-cache test/str/app.roc

Overview (`.github/actions/flaky-retry/README.md`) Copy Section

Flaky Retry Action

A GitHub Action that retries a command if it fails with a specific error string.

Inputs Copy Chapter

• command (required): The command to run
• error_string_contains (required): Retry only if error output contains this string
• retry_count (optional): Number of times to retry on failure (default: 3)

Usage Copy Chapter

- name: Run flaky test
  uses: ./.github/actions/flaky-retry
  with:
    command: 'zig build my_flaky_cmd'
    error_string_contains: 'connection timeout'
    retry_count: 5

Behavior Copy Chapter

• Runs the specified command
• If the command succeeds (exit code 0), the action succeeds immediately
• If the command fails (non-zero exit code):
  • Checks if the error output contains the specified string
  • If it does, retries up to retry_count times
  • If it doesn't, fails immediately without retrying
• After all retries are exhausted, the action fails with the last exit code

Overview (`src/backend/llvm/README.md`) Copy Section

Roc LLVM Backend

This directory contains the LLVM code generation backend for the Roc compiler. It takes monomorphized IR and compiles it to native object code using LLVM.

Overview Copy Chapter

The LLVM backend follows this pipeline:

Monomorphized IR  →  LLVM IR Builder  →  LLVM Bitcode  →  Object Code (.o)  →  Executable

1. Monomorphized IR: The input from the Roc compiler's earlier stages (type checking, monomorphization)
2. LLVM IR Builder (Builder.zig): Constructs LLVM IR in memory
3. Bitcode Writer (bitcode_writer.zig): Serializes the IR to LLVM bitcode format
4. LLVM Backend (vendor/llvm_compile_bindings.zig): Parses bitcode and compiles to native object code
5. Linker: Links object code with platform host to produce final executable

Files Copy Chapter

Building with LLVM Copy Chapter

LLVM is always enabled. The build system will automatically download pre-built LLVM libraries from roc-bootstrap for supported platforms.

# Standard build (downloads LLVM automatically)
zig build

# Use a custom LLVM installation
zig build -Dllvm-path=/path/to/llvm

Supported Platforms Copy Section

Pre-built LLVM is available for:

• x86_64-linux-musl / x86_64-linux-gnu
• aarch64-linux-musl / aarch64-linux-gnu
• x86_64-macos
• aarch64-macos
• x86_64-windows
• aarch64-windows

For other platforms, use -Dllvm-path to specify a custom LLVM installation.

Usage: Compiling Monomorphized IR to Executable Copy Chapter

Step 1: Generate LLVM IR from Monomorphized IR Copy Section

The Builder.zig module constructs LLVM IR. Here's the general pattern:

const llvm = @import("backend/llvm/Builder.zig");
const ir = @import("backend/llvm/ir.zig");

// Create a new LLVM module builder
var builder = llvm.Builder.init(allocator);
defer builder.deinit();

// Set target triple (e.g., "x86_64-linux-gnu", "aarch64-macos-none")
builder.setTargetTriple(target_triple);

// Define types
const i64_type = builder.intType(64);
const void_type = builder.voidType();

// Create a function
const main_fn = builder.addFunction(
    "main",                           // function name
    builder.functionType(i64_type, &.{}),  // return i64, no params
);

// Create entry basic block
const entry_block = builder.appendBasicBlock(main_fn, "entry");
builder.positionAtEnd(entry_block);

// Add instructions
const result = builder.buildAdd(lhs, rhs, "sum");
builder.buildRet(result);

Step 2: Serialize to Bitcode Copy Section

Once the LLVM module is built, serialize it to bitcode:

const bitcode_writer = @import("backend/llvm/bitcode_writer.zig");

// Get bitcode as bytes
const bitcode = builder.toBitcode(allocator);
defer allocator.free(bitcode);

// Or write directly to a file
try builder.writeBitcodeToFile("output.bc");

Step 3: Compile Bitcode to Object Code Copy Section

Use the bindings.zig module to compile bitcode to a native object file:

const bindings = @import("backend/llvm/bindings.zig");

// High-level convenience function
const error_msg = bindings.compileBitcodeToObject(
    bitcode,                    // []const u8 - LLVM bitcode bytes
    "x86_64-linux-gnu",         // target triple
    "generic",                  // CPU name (or null for default)
    null,                       // CPU features (or null)
    "output.o",                 // output object file path
    false,                      // is_debug (false = optimized)
);

if (error_msg) |msg| {
    std.debug.print("LLVM error: {s}\n", .{std.mem.span(msg)});
    return error.LlvmCompilationFailed;
}

Step 4: Link to Executable Copy Section

Link the object file with the platform host library to create the final executable:

const embedded_lld = @import("embedded_lld");

// Using LLD (LLVM's linker) for ELF targets
const args = &.{
    "ld.lld",
    "output.o",
    "libhost.a",           // platform host library
    "-o", "my_program",
};
try embedded_lld.link(allocator, .elf, args, .{});

For different platforms, pass the appropriate linker format:

• Linux: .elf
• macOS: .macho
• Windows: .coff
• WebAssembly: .wasm

Low-Level API Copy Chapter

For more control, use the lower-level bindings directly:

/* Detailed source-code truncated for AI context efficiency. */

Target Triples Copy Chapter

Common target triples for Roc:

Optimization Levels Copy Chapter

The CodeGenOptLevel enum controls LLVM's optimization:

For size optimization, set emit_options.is_small = true to get -Oz behavior.

Debugging Copy Chapter

To debug LLVM IR generation:

1. Emit LLVM IR text: Set emit_options.llvm_ir_filename = "output.ll" to get human-readable IR
2. Emit bitcode: Set emit_options.bitcode_filename = "output.bc" to inspect with llvm-dis
3. Use debug builds: Set is_debug = true to preserve debug info and disable optimizations

Architecture Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Attribution Copy Chapter

The LLVM bitcode generation code has been adapted from the Zig compiler at https://codeberg.org/ziglang/zig and licensed under the MIT license. Thanks, Zig team!

Overview (`src/lsp/completion/README.md`) Copy Section

LSP Completion System

This document describes how code completion works in the Roc LSP, covering the
request flow, context detection, completion types, key data structures, and
testing.

File Map Copy Chapter

All paths are relative to src/lsp/.

Supporting compiler modules (outside `src/lsp/`) Copy Section

Request Flow Copy Chapter

Editor sends textDocument/completion
        │
        ▼
handlers/completion.zig  handler().call()
  ├─ parse JSON params → (uri, line, character)
  ├─ look up document text from doc_store
  └─ call syntax_checker.getCompletionsAtPosition(uri, text, line, character)
        │
        ▼
syntax.zig  SyntaxChecker.getCompletionsAtPosition()
  1. Lock mutex (completions are single-threaded)
  2. createFreshBuildEnv() → BuildEnv
  3. BuildSession.init() → builds the file
  4. Obtain a ModuleEnv (see "Module Env Priority" below)
  5. detectCompletionContext(source, line, character) → CompletionContext
  6. computeOffset(source, line, character) → cursor_offset
  7. Create CompletionBuilder
  8. switch (context) → call the appropriate builder methods
  9. Return CompletionResult { items, is_incomplete }
        │
        ▼
handlers/completion.zig
  └─ serialise CompletionResult as JSON-RPC response

Module Env Priority Copy Section

The system tries three sources for a ModuleEnv, in order:

1. Snapshot env—cached from the last successful build of this file.
   Best for completions because the user is usually mid-edit and the current
   build may fail.
2. Previous build env—the last globally-successful build. Fallback when
   no snapshot exists for this file.
3. Current build—used only when the build just succeeded with no reports.

When a snapshot or previous env is used, the flag used_snapshot is set to
true. This matters because CIR byte offsets from a snapshot do not match the
current source text, so CIR-based type lookups (findFieldAccessReceiverTypeVar) are
skipped in favour of name-based lookups.

The module_lookup_env variable tracks which BuildEnv backs the chosen
ModuleEnv, keeping module member lookups consistent.

Completion Context Detection Copy Chapter

completion/context.zig :: detectCompletionContext(source, line, character)

The function converts line/character to a byte offset, then scans backward:

1. Skip any partial identifier the user is currently typing.
2. Skip whitespace.
3. Inspect the character immediately before the cursor:

CompletionContext union Copy Section

pub const CompletionContext = union(enum) {
    after_module_dot: []const u8,              // the module name
    after_value_dot: struct {
        access_chain: []const u8,              // e.g. "myrec.subrec"
        chain_start: u32,                      // byte offset of chain start
        receiver_segment_start: u32,           // byte offset of segment before dot
        dot_offset: u32,                       // byte offset of the '.'
    },
    after_receiver_dot: struct {
        dot_offset: u32,
        call_chain: ?[]const u8,               // e.g. "Record2.SubVal" or "testFunc"
        chain_start: u32,
    },
    after_colon,
    expression,
};

Completion Types Copy Chapter

Each completion context triggers a different set of builder methods. Here is
every kind of completion the system can produce, grouped by context.

1. Module Member Completions—`after_module_dot` Copy Section

Trigger: Str., List., Json., or MyNominalType.

What happens:

1. resolveModuleAlias(module_env, name)—if the module was imported with
   import Json as J, this maps J back to Json.
2. builder.addModuleMemberCompletions(env, resolved_name, module_env_opt)—
   walks all exposed_items from the target module's ModuleEnv. For builtin
   type names (recognised via isBuiltinType), it uses the special
   builtin_module.env. Items are classified as function (lowercase) or
   class (uppercase).
3. builder.addTagCompletionsForNominalType(module_env, name, null)—if the
   name is also a nominal type in the current module, adds its tag constructors
   (e.g., Color.Red, Color.Green).

CompletionItemKind: function, class, enum_member

2. Incomplete Value-Dot Completions—`after_value_dot` Copy Section

Trigger: myRecord., myrec.subrec.

What happens (simplified):

1. Try resolveAccessChainTypeVar() to resolve dotted chains like
   Module.value.subfield by walking segment-by-segment through the type
   system.
2. If that fails (common with snapshots), fall back:
   • CIR-based: cir_queries.findFieldAccessReceiverTypeVar() or findTypeAtOffset()
   • Name-based: addRecordFieldCompletions(name, offset) and
     addMethodCompletions(name, offset)
3. Once a types.Var is in hand:
   • addFieldsFromTypeVar()—unwraps aliases/nominals up to 8 levels, then
     iterates record fields. Each field gets a detail string showing its type.
   • addMethodsFromTypeVar()—independently looks up the type identity in
     method_idents. It does not inspect record fields.

At value. the source is incomplete: selecting a field and stopping produces
value.field, while adding an argument list produces the distinct method syntax
value.method(args). Offering both completion kinds at this unfinished prefix
does not merge their lookup or resolution.

CompletionItemKind: field, method

3. Incomplete Receiver-Dot Completions—`after_receiver_dot` Copy Section

Trigger: getValue()., Str.join(items)., testFunc("hi").

What happens:

1. Try CIR-based lookup: findFieldAccessReceiverTypeVar() at cursor_offset, with
   fallback to findTypeAtOffset(dot_offset - 1).
2. If using a snapshot or CIR failed, parse the call_chain textually and
   resolve via resolveAccessChainTypeVar(), then call
   extractReturnType() to unwrap the function return type.
3. Run field completion and method completion independently for the resolved
   receiver type.

CompletionItemKind: field, method

4. Type Annotation Completions—`after_colon` Copy Section

Trigger: x : , foo : , a function signature parameter annotation

What happens:

1. addTypeCompletions(module_env)—iterates all_statements for
   s_alias_decl and s_nominal_decl, adding each type name.
2. addModuleNameCompletions(module_env)—iterates all_statements for
   s_import and adds imported module names/aliases.
3. addTypeCompletionsFromEnv(env)—same as (1) but across all modules
   in the BuildEnv.
4. addModuleNameCompletionsFromEnv(env)—adds all module names from
   BuildEnv coordinator packages and calls addBuiltinModuleNameCompletions()
   which adds every entry in BUILTIN_TYPES.

This means typing x : suggests: user-defined type aliases and nominals,
imported module names, all loaded module names, and all 21 builtin types
(Str, List, Bool, U8–U128, I8–I128, F32, F64, Dec, Num,
Dict, Set, Box, Try).

CompletionItemKind: class (types), module (module names)

5. Expression Completions—`expression` Copy Section

Trigger: beginning of a line, after =, after if, any general expression
position.

What happens:

1. addLocalCompletions(module_env, cursor_offset)—builds a ScopeMap from
   CIR, then adds every binding visible at the cursor. Also adds top-level
   defs (from all_defs) and statement-level defs (from all_statements).
   Closures/lambdas get kind function; everything else gets variable.
2. addModuleNameCompletions(module_env)—imported module names.
3. addAmbientTagCompletions(module_env)—structural tags from the type
   store (e.g. Ok, Err if they appear in the module).
4. addTypeCompletions(module_env)—alias and nominal type names.
5. addModuleNameCompletionsFromEnv(env)—all module names + builtins.

CompletionItemKind: variable, function, module, enum_member, class

6. Tag Completions (nominal) Copy Section

Added in the after_module_dot context when the dot-prefix is a nominal type.
addTagCompletionsForNominalType() finds the s_nominal_decl matching the
name, checks opaqueness, then extracts tags from the backing tag_union type
annotation. Each tag gets a formatted signature detail like SubVal(Str).

CompletionItemKind: enum_member

7. Ambient/Structural Tag Completions Copy Section

Added in the expression context. addAmbientTagCompletions() iterates
module_env.types.tags and adds every tag name. These are structural tags that
appear without a module prefix.

CompletionItemKind: enum_member

Key Types Copy Chapter

CompletionItem Copy Section

Defined in handlers/completion.zig:175:

pub const CompletionItem = struct {
    label: []const u8,                // Display text (e.g. "concat", "Str", "name")
    kind: ?u32 = null,                // CompletionItemKind as u32
    detail: ?[]const u8 = null,       // Type signature shown beside label
    documentation: ?[]const u8 = null,
    sortText: ?[]const u8 = null,     // Custom sort key
    insertText: ?[]const u8 = null,   // Text inserted on accept (if different from label)
};

CompletionItemKind Copy Section

Matches the LSP spec (subset actually used by the builder):

CompletionBuilder Copy Section

Defined in completion/builder.zig:33. Key fields:

pub const CompletionBuilder = struct {
    allocator: Allocator,
    items: *std.ArrayList(CompletionItem),
    seen_labels: std.StringHashMap(void),   // deduplication
    builtin_module_env: ?*ModuleEnv,         // for Str.concat, List.map, etc.
};

ModuleEnv (abbreviated) Copy Section

From src/canonicalize/ModuleEnv.zig. Fields used by completions:

BuildEnv (abbreviated) Copy Section

ScopeMap and Binding Copy Section

scope_map.zig. Reconstructs lexical scopes from CIR:

pub const Binding = struct {
    ident: Ident.Idx,
    pattern_idx: CIR.Pattern.Idx,
    visible_from: u32,
    visible_to: u32,
    is_parameter: bool,
};

ScopeMap.build(module_env) traverses all defs, statements, and nested
expressions to populate a list of Bindings sorted by visible_from.
isVisibleAt(binding, offset) checks if a binding is in scope at a cursor
position.

Builder Method Reference Copy Chapter

Every public add* method on CompletionBuilder:

BUILTIN_TYPES Copy Chapter

Defined in completion/builtins.zig. These 21 names are added as module-kind
completions by addBuiltinModuleNameCompletions():

Str  List  Dict  Set  Box
Bool Try
U8  U16  U32  U64  U128
I8  I16  I32  I64  I128
F32  F64
Dec  Num

isBuiltinType(name) does a case-sensitive linear scan of this list. It is
used to:

• Route method lookups through the builtin ModuleEnv instead of the user's.
• Add builtin module names to completion lists.
• Recognise when addModuleMemberCompletions should use builtin_module.env.

Testing Copy Chapter

Test files Copy Section

Handler test structure (handler_integration_tests.zig) Copy Section

Each test follows this pattern:

1. Create a temp directory and a .roc file path + URI.
2. Build a sequence of framed JSON-RPC messages:
   • initialize (id: 1)
   • initialized
   • textDocument/didOpen with Roc source as the text field
   • textDocument/completion (id: 2) with a specific line/character
   • shutdown (id: 3)
   • exit
3. Feed all messages into a fixedBufferStream reader.
4. Create a Server and call server.run().
5. Collect all JSON-RPC responses from the writer buffer.
6. Find the response with id: 2.
7. Assert result.isIncomplete and result.items exist.
8. Scan items for expected labels (e.g., found_str, found_u64).

Existing handler test cases Copy Section

Syntax test structure (syntax_test.zig) Copy Section

These tests call getCompletionsAtPosition() directly on a SyntaxChecker:

1. Create a SyntaxChecker with a temp working directory.
2. Write a .roc file with specific source.
3. Call syntax_checker.getCompletionsAtPosition(uri, source, line, char).
4. Assert on the returned CompletionResult.items—check specific labels,
   kinds, and detail strings.

Running tests Copy Section

# All completion-related LSP tests
zig build run-test-zig-module-lsp_integration -- --test-filter "completion"

# Just context detection unit tests
zig build run-test-zig -- --test-filter "detectCompletionContext"

# Just builder helper tests
zig build run-test-zig -- --test-filter "stripModulePrefix"

# Just builtin type tests
zig build run-test-zig -- --test-filter "isBuiltinType"

# Fast LSP unit tests
zig build run-test-zig-module-lsp_unit

# Compiler-backed LSP integration tests
zig build run-test-zig-module-lsp_integration

Writing a new completion test Copy Section

For a handler-level integration test, follow the pattern in
handler_integration_tests.zig:

test "completion handler returns X in Y context" {
    // 1. Setup: allocator, tmp dir, file path, URI
    // 2. Build JSON-RPC message sequence with your Roc source
    //    - The source goes in the didOpen "text" field
    //    - The completion position goes in the completion "position" field
    // 3. Run server
    // 4. Find response with your request id
    // 5. Scan items for expected labels
}

For a mid-level test in syntax_test.zig, call
getCompletionsAtPosition(uri, source, line, character) and inspect the
returned items directly.

For a unit test of context detection, add a test to completion/context.zig:

test "detectCompletionContext: your new case" {
    const source = "your source text here";
    const ctx = detectCompletionContext(source, line, character);
    try std.testing.expect(ctx == .your_expected_variant);
}

Common Tasks Copy Chapter

Adding a new completion source to an existing context Copy Section

Find the switch (context) in syntax.zig:1890 and add your
builder.add*() call in the appropriate branch. If no suitable builder method
exists, add one to completion/builder.zig.

Adding a new completion context Copy Section

1. Add a variant to CompletionContext in completion/context.zig.
2. Update detectCompletionContext() to recognise the new trigger.
3. Add a branch in the switch (context) in syntax.zig.
4. Add context detection unit tests and at least one handler integration test.

Adding a new completion item kind Copy Section

The CompletionItemKind enum in handlers/completion.zig already has all 25
LSP kinds. Pick the appropriate one when creating items in the builder.

Overview (`src/postcheck/monotype/README.md`) Copy Section

Monotype lowering

This directory specializes checked Roc programs into fully concrete types and
lowers them into the program representation consumed by evaluation and code
generation.

Body lowering treats its instantiation graph as the authority for every
TypeId it inspects. This ownership boundary prevents body-local type state
from being confused with coordinator-owned program types, and allows completed
specialization work to cross into the final program only through ordered
commit and explicit type relocation.

Langref Style Guide (`docs/langref-style-guide.md`) Copy Section

Language Reference Style Guide

This is how to write pages for the language reference. Every
page should read as if the same person wrote it.

(This file lives outside docs/langref/ because every Markdown file in that
directory gets published as a langref page.)

Talk to the Reader Copy Chapter

Write to "you," the way you'd explain something to a colleague who already knows
how to program. Use contractions (can't, it's, doesn't, you'd). The langref is
detailed, but it's not a spec written in legalese.

• Yes: "Another way to think of an expression is that you can always assign it to a name—so, you can always put it after an = sign."
• No: "An expression is any construct that may appear on the right-hand side of an assignment."

Avoid instruction-manual phrasing like "Use X to…" or "Prefer X when…" as the main
way of explaining something. Explain what X does, and the reader will know when to
use it.

Define Terms Plainly, Where They're Introduced Copy Chapter

Introduce a term in italics in the sentence that defines it, using everyday words.
"X is where…" and "X is something that…" are fine.

• "A block expression is an expression with some optional statements before the expression."
• "Dispatch is where the same call expression can result in a different function being run, depending on the types of its arguments and/or return value."

When a concept has a standard name in computer science, link the name to
Wikipedia (or to a paper) instead of re-explaining it: "Heap-allocated Roc values
are automatically reference-counted."

Bold a word when you're defining several properties at once in a bulleted list:

• "Structural means that you don't have to choose a name for the type…"
• "Extensible means that the type can accumulate new tags based on how it's used…"

Avoid Compiler-Internals Vocabulary Copy Chapter

Readers know programming, not the compiler's internals. Don't use words like
unification, inhabited, materialize, lowering, backing row, monotype, solver, or
"lift" unless the page is specifically about that concept and has defined it
first. Describe what the reader can observe: what compiles, what's an error, and
what happens at runtime.

Explain Why, Including the Tradeoff Copy Chapter

Say why something is the way it is, and what was weighed against what. That's
most of what makes a reference worth reading instead of just trying things in the
REPL.

• "That's because it's much more useful to have { x } be a block expression, for situations like else { x }, than syntax sugar for a single-field record like { x: x }. Single-field records are much less common than blocks in conditional branches."
• "(If it did not give an error at compile time, it would either crash or loop infinitely at runtime.)"
• "By design, Roc has no way to express reference cycles, so none of these solutions are necessary."

"By design" is the phrase for a deliberate omission. Use it when something is
missing on purpose, and say what the purpose was.

Compare to Other Languages When It Helps Copy Chapter

Briefly, and without judging: "Like most programming languages, Roc uses strict
evaluation and does not support lazy evaluation like some non-strict languages do
(such as Haskell)." or "Other languages support reference cycles, which create
problems for reference counting systems."

Small, Annotated Examples Copy Chapter

Prefer several tiny examples over one big one. Lists of one-line examples work well:

• "In x = Foo, Foo is a tag."
• "In y = Foo(4), Foo is a tag with a payload of 4."

In code blocks, use comments to point at the interesting line:
# This line will never be reached. or Purple # ERROR! to_color returns ..[] and so does not accept new tags.

Show the error case right next to the working case: "This is allowed: … However,
this gives a shadowing error: …"

Nothing tests the langref's code blocks automatically, so check every example
(and every claim about what's an error) with a current build of roc before
publishing it.

Say Who Something Is For Copy Chapter

Different readers care about different things. Say so directly: "This is rarely
useful to application authors, but it is useful to platform authors." Caveats that
only matter to one audience go in a block quote starting with "Note that":

Note that platform authors can choose to implement features based on memory
addresses, since platforms have access to lower-level languages…

Be Definitive Copy Chapter

When a list is complete, say so: "There are no other types of expressions in the
language." When something is an error, say "This gives an error at compile time,"
not "This is generally not permitted."

Describe the language as it is. Don't describe how it used to work, and don't
describe planned features as if they exist.

Performance Sections Copy Chapter

Every page whose subject exists at runtime gets a section on performance. It
should explain the representation in enough detail that the reader could predict
what a piece of code costs:

• Where the bytes live (inline vs. on the heap), how big things are on 64-bit and
  32-bit targets, and whether there's a reference count.
• What an operation copies, allocates, or mutates in place, and what decides
  which one happens (usually opportunistic mutation).
• What the compiler does for you, so the reader knows what they don't need to
  hand-optimize (for example, record fields are reordered to minimize padding, so
  reordering them yourself does nothing).
• What the reader can do differently when performance matters, with an example.

Only state things the compiler actually does today. If something is planned but
not implemented, leave it out.

Mechanics Copy Chapter

• Em dashes have no spaces around them (value—regardless). Tidy enforces this.
• Headings are Title Case.
• Link other langref pages with extensionless relative links: [records](records).
• Code fences use roc.
• Paragraphs are short: usually one to three sentences.
• Don't end every paragraph with "See X for more." Link the words where they're
  used instead.

Llvm Codegen Comparison (`docs/llvm-codegen-comparison.md`) Copy Section

LLVM Code Generation Comparison: Zig vs Legacy Rust

This document compares the new Zig LLVM evaluator (src/eval/llvm_evaluator.zig) with the legacy Rust LLVM code generation (crates/compiler/gen_llvm/).

Scale Comparison Copy Chapter

Architectural Differences Copy Chapter

Input IR Copy Section

Legacy Rust:

• Works on Mono IR (roc_mono::ir) - already monomorphized
• All types are concrete, all functions are specialized
• Lambda sets resolved to concrete function pointers
• Input is Stmt and Expr enums from monomorphization phase

New Zig:

• Works on CIR (Canonical IR) - pre-monomorphization
• Types still have polymorphism
• Direct from canonicalization phase
• Input is CIR.Expr from can.CIR

LLVM API Copy Section

Legacy Rust:

// Uses inkwell (Rust LLVM bindings)
use inkwell::context::Context;
use inkwell::builder::Builder;
use inkwell::module::Module;
use inkwell::values::{FunctionValue, BasicValueEnum};

// Creates full LLVM infrastructure
let context = Context::create();
let module = context.create_module("roc_app");
let builder = context.create_builder();

New Zig:

// Uses Zig's standard library LLVM bindings
const LlvmBuilder = std.zig.llvm.Builder;

// Lightweight builder that serializes to bitcode
var builder = LlvmBuilder.init(.{
    .allocator = allocator,
    .name = "roc_repl_eval",
    .target = &builtin.target,
    .triple = getLlvmTriple(),
}) catch return error.OutOfMemory;

Purpose Copy Section

Legacy Rust:

• Full AOT (Ahead-of-Time) compiler backend
• Produces object files for linking
• Used by roc build and the default roc command
• Targets all supported platforms

New Zig:

• JIT evaluation for REPL
• Produces bitcode for immediate execution
• Used by roc repl with --opt flags
• Single-expression evaluation only

Feature Comparison Copy Chapter

Expression Support Copy Section

Statement Support Copy Section

Type Support Copy Section

Low-Level Operations Copy Section

Legacy Rust (lowlevel.rs - 2,897 lines) supports all operations:

match op {
    StrConcat => { /* full impl */ }
    StrJoinWith => { /* full impl */ }
    StrStartsWith | StrEndsWith => { /* full impl */ }
    StrToNum => { /* handles all numeric types */ }
    ListLen | ListGetUnsafe | ListSet => { /* full impl */ }
    ListConcat | ListAppend | ListPrepend => { /* full impl */ }
    ListMap | ListMap2 | ListMap3 | ListMap4 => { /* higher-order */ }
    NumAdd | NumSub | NumMul | NumDiv => { /* all widths */ }
    NumAbs | NumNeg | NumSin | NumCos => { /* math ops */ }
    NumToStr => { /* for all numeric types */ }
    // ... 100+ more operations
}

New Zig (llvm_evaluator.zig) supports basic operations:

// Only handles simple builtin calls by ident matching
if (func_ident == idents.not and args.len == 1) { /* bool not */ }
if (func_ident == idents.abs and args.len == 1) { /* numeric abs */ }
if (func_ident == idents.negate and args.len == 1) { /* negate */ }
if (func_ident == idents.abs_diff and args.len == 2) { /* abs_diff */ }

Memory Management Copy Section

Legacy Rust (refcounting.rs - 1,808 lines):

• Full reference counting implementation
• Increment/decrement for all refcounted types
• Deallocation with alignment handling
• Reset/reuse optimization for unique references
• Special handling for lists, strings, recursive structures

pub fn increment_refcount_layout<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    layout_interner: &STLayoutInterner<'a>,
    layout_ids: &mut LayoutIds<'a>,
    value: BasicValueEnum<'ctx>,
    layout: InLayout<'a>,
) { /* recursive increment */ }

pub fn decrement_refcount_layout<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    layout_interner: &STLayoutInterner<'a>,
    layout_ids: &mut LayoutIds<'a>,
    value: BasicValueEnum<'ctx>,
    layout: InLayout<'a>,
) { /* recursive decrement with deallocation */ }

New Zig:

• No reference counting (single expression evaluation)
• No memory management needed for REPL use case

Comparison Operations Copy Section

Legacy Rust (compare.rs - 1,509 lines):

• Generic equality for all types
• Recursive comparison for structs, unions, lists
• Special handling for floats (NaN)
• String comparison via bitcode

pub fn generic_eq<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    layout_interner: &STLayoutInterner<'a>,
    layout_ids: &mut LayoutIds<'a>,
    lhs_val: BasicValueEnum<'ctx>,
    rhs_val: BasicValueEnum<'ctx>,
    lhs_layout: InLayout<'a>,
    rhs_layout: InLayout<'a>,
) -> BasicValueEnum<'ctx> { /* handles all types */ }

New Zig:

• Integer/float comparison via LLVM icmp/fcmp
• String comparison returns UnsupportedType

Bitcode Integration Copy Section

Legacy Rust (bitcode.rs - 1,351 lines):

• Calls into pre-compiled Zig bitcode for builtins
• Platform-specific ABI handling (Windows i128, macOS arm64)
• Wraps list/string operations
• Handles Dec arithmetic

pub fn call_bitcode_fn<'ctx>(
    env: &Env<'_, 'ctx, '_>,
    args: &[BasicValueEnum<'ctx>],
    fn_name: &str,
) -> BasicValueEnum<'ctx> {
    // Call into compiled Zig code
    // Handle platform ABI differences
}

New Zig:

• Generates standalone functions
• No external bitcode dependencies for evaluated expressions

Debug Information Copy Section

Legacy Rust:

• Full DWARF debug info generation
• Source locations, line numbers
• Variable names and types
• Integration with DebugInfoBuilder

New Zig:

• No debug info (REPL evaluation doesn't need it)

Optimization Copy Section

Legacy Rust:

• Uses LLVM PassManager
• Configurable optimization levels
• Inlining, constant folding, etc.

New Zig:

• No optimization passes
• Relies on LLVM JIT's basic optimizations

Control Flow Comparison Copy Chapter

If Expressions Copy Section

Legacy Rust - Full CFG with basic blocks:

// Creates then_block, else_block, merge_block
// Uses conditional branch and phi nodes
env.builder.new_build_conditional_branch(cond, then_block, else_block);
// ... build then block ...
// ... build else block ...
// Merge with phi

New Zig - Full CFG with basic blocks and phi nodes:

// Creates merge block, then evaluates each branch
const merge_block = ctx.wip.block(num_incoming, "if_merge");

// For each branch: create then/else blocks, emit conditional branch
_ = ctx.wip.brCond(cond_i1, then_block, else_block, .none);

// Emit then block, branch to merge
ctx.wip.cursor = .{ .block = then_block };
const then_val = try ctx.emitExpr(branch.body);
_ = ctx.wip.br(merge_block);

// Merge with phi node
ctx.wip.cursor = .{ .block = merge_block };
const wip_phi = ctx.wip.phi(result_type, "if_result");
wip_phi.finish(phi_values[0..phi_count], phi_blocks[0..phi_count], ctx.wip);

Switch/Match Copy Section

Legacy Rust - Full switch implementation:

fn build_switch_ir<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    // ...
    switch_args: SwitchArgsIr<'a, 'ctx>,
) -> BasicValueEnum<'ctx> {
    // Build switch instruction with cases
    // Handle join points for complex control flow
}

New Zig:

• Returns UnsupportedType for match expressions

Union/Tag Handling Copy Chapter

Legacy Rust Copy Section

Handles all union layouts (UnionLayout enum):

• NonRecursive - Tags stored by value
• Recursive - Heap-allocated with pointer tagging
• NonNullableUnwrapped - Single recursive variant
• NullableWrapped - Optional-like with null pointer
• NullableUnwrapped - Single non-null variant

fn build_tag<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    layout_interner: &STLayoutInterner<'a>,
    scope: &Scope<'a, 'ctx>,
    union_layout: &UnionLayout<'a>,
    tag_id: u8,
    arguments: &[Symbol],
    // ...
) -> BasicValueEnum<'ctx> {
    match union_layout {
        UnionLayout::NonRecursive(_) => { /* stack allocation */ }
        UnionLayout::Recursive(_) => { /* heap allocation with refcount */ }
        // ... all variants
    }
}

New Zig Copy Section

Only handles simple tags:

fn emitZeroArgTag(ctx: *ExprContext, tag: anytype) ExprError!LlvmBuilder.Value {
    // For Bool tags, True is 1 and False is 0
    const value: i128 = if (tag.name == ctx.module_env.idents.true_tag) 1 else 0;
    return (ctx.builder.intConst(.i8, value) catch return error.CompilationFailed).toValue();
}

Higher-Order Functions Copy Chapter

Legacy Rust - Full support:

pub(crate) fn run_higher_order_low_level<'a, 'ctx>(
    env: &Env<'a, 'ctx, '_>,
    layout_interner: &STLayoutInterner<'a>,
    layout_ids: &mut LayoutIds<'a>,
    scope: &Scope<'a, 'ctx>,
    layout: InLayout<'a>,
    op: &HigherOrderLowLevel<'a>,
    // ...
) -> BasicValueEnum<'ctx> {
    // Handles List.map, List.map2, List.walk, etc.
    // Generates loops with function pointer calls
}

New Zig:

• No higher-order function support
• Returns UnsupportedType for lambdas

Summary Copy Chapter

The new Zig evaluator is a work in progress that aims to achieve full feature parity with the legacy Rust implementation. Current status:

Implemented:

• Basic scalar types (integers, floats, Dec, Bool)
• Binary and unary operations
• If expressions with proper CFG (basic blocks, conditional branches, phi nodes)
• Simple records and field access
• Multi-branch if-else chains

Not yet implemented:

• Switch/match expressions
• Reference counting and memory management
• All union layouts (only Bool tags work)
• Closures and lambda sets
• Higher-order functions
• Full low-level operation set
• Debug information
• Optimization passes

The legacy Rust code is a full production compiler backend that serves as the reference implementation for feature parity.

Mini Tutorial New Compiler (`docs/mini-tutorial-new-compiler.md`) Copy Section

Mini Tutorial for Roc

Roc is still a work in progress and has not reached a 0.1 release, so expect missing features and bugs.

Helpful resources:

• Standard library docs
• Examples
• Language reference
• Roc syntax overview
• Learn roc by doing, with exercism

If you want help, the best place to get it is Roc Zulip. You're welcome to ask any questions in #beginners.

With those disclaimers in mind, let's get into the adventure!

Hello, World Copy Chapter

First, follow the installation guide to install a nightly build.
It includes an executable named roc (or roc.exe on Windows). You'll know it is available on your PATH
if roc version works.

Next, copy/paste this into a new file named main.roc:

main! = |_args| {
    echo!("Hello, World!")
    Ok({})
}

You can run this with:

roc main.roc

You should see this:

Hello, World!

Hooray!

Tip: If you don't provide a path to a .roc file, roc will default to "main.roc" - so since your Roc program is named main.roc, you can run your program by just running roc in the future.

The REPL Copy Chapter

You can also try Roc expressions and definitions without creating a file by running roc repl.

roc repl

Inside the REPL, enter an expression to evaluate it:

1 + 1

You can define names and use them in later inputs:

x = 1 + 1
x * 2

The REPL also works well with piped input. In piped mode it prints only evaluation output to stdout; prompts, the welcome banner, and the goodbye message are not printed.

In PowerShell, send multiple input lines with an array:

@("x = 1 + 1", "x * 2") | roc repl

You should see:

assigned `x`
4.0

In Unix shells, use printf for the same thing:

printf 'x = 1 + 1\nx * 2\n' | roc repl

Diagnostics from piped input are written to stderr, so tools can read successful results from stdout separately from parse and type errors. If you want plain diagnostics without ANSI color codes, use roc repl --no-color or set NO_COLOR environment variable.

The `main!` function Copy Chapter

Let's take a look at main! next:

main! = |_args| {
    echo!("Hello, World!")
    Ok({})
}

This defines our program's entrypoint. The code inside the curly braces will run when we do roc main.roc.

Pure and effectful functions Copy Chapter

That |_args| { ... } is Roc syntax for an anonymous function with one argument, named _args. (If it had multiple arguments,
it would look like |arg1, arg2| { ... } instead.) Functions in Roc are ordinary values, just
like numbers, strings, or booleans; we can pass them around, put them in collections, and use = to name them.

We named it main! (and not the traditional main) because it's a function that runs the
side effect of printing to
stdout.
In Roc, we call functions that can run side effects effectful functions, and by convention
we always name them with a ! at the end of their names. In contrast,
pure functions don't have a ! at the end of their names.

Constants Copy Section

This line defines a new constant called name:

name = "Rocco"

Constants should not be reassigned or shadowed, if you try to do name = again in the same scope,
roc will give a compile-time warning with exit code 2. That way, you can quickly write something with
shadowing if you want but the non-zero exit code prevents it from ending up in production code because CI will fail.

String interpolation Copy Section

The string "Hello, ${name}!" will evaluate to "Hello, Rocco!".

In an ordinary string interpolation, each interpolated expression must also produce a string; Roc does not automatically convert other types. For example, if you wanted to print an integer you'd need to call to_str on it like so:

echo!("Number of things: ${thing_count.to_str()}")

You can put any expression you like inside a string interpolation. If you really wanted to, you could do something like this:

echo!("Answer: ${((numerator / denominator) + 1).negate().to_str()}")

...but at that point it'd probably be easier to read if you extracted that expression into a constant.

`for` and `fold` Copy Chapter

Sometimes code is easier to understand in a functional style, and other times it's easier to understand
in an imperative style. Roc has support for both styles, even though its APIs are designed around immutable
values and a functional style.

Expect Copy Section

To see both styles, let's write a function called digits_to_num which takes a list of digits and returns the number they represent. When we're done, we'll be able to run roc test and see these expects pass:

expect digits_to_num([1, 2, 3]) == 123
expect digits_to_num([4, 2]) == 42
expect digits_to_num([7]) == 7

expect is Roc's lightweight testing keyword. You can put a boolean expression after it, and if that expression
evaluates to True, the test will pass, and if it evaluates to False, the test will fail. When you run roc test,
it runs all of top-level expects in your files, as well as all the files they import (unless they belong to downloaded packages).

A file run with roc test does not need a main! function (or an app header, which will be introduced shortly).

Another useful command is roc fmt, which formats your source code according to standard Roc style. By design, roc fmt has no configuration options at all.

`for` style Copy Section

Here's an imperative-style implementation of digits_to_num, using a for loop and reassignable vars:

digits_to_num = |digits| {
    var $num = 0
    
    for digit in digits {
        $num = ($num * 10) + digit
    }
  
    $num
}

Unlike a constant, a var like $num can be reassigned. Similarly to how effectful functions have names
ending in ! to distinguish them from pure functions, vars begin with $ to distinguish them from constants.
This means any time you see something beginning with $, you know it might be reassigned somewhere (such as
in a for loop), whereas if you don't see the $, there's no need to think about that possibility.

Note that vars can only be reassigned inside the function where they were declared. This code would give an error:

var $count = 0

things.for_each!(|thing| {
    $count = $count + 1
    
    # other logic goes here
})

The error would say that $count can't be reassigned inside a different function from where it was declared with var.

As such, if you see a for_each! being used instead of a for loop, that tells you whatever logic inside is guaranteed
not to modify any vars in the outer scope—whereas if you see a for loop, you know that it might be modifying vars.

`fold` style Copy Section

You can also implement digits_to_num in a functional style using fold:

digits_to_num = |digits| digits.fold(0, |num, digit| (num * 10) + digit)

Blocks Copy Section

Note that there are no curly braces in the digits_to_num definition. That's because every Roc function has one expression
after its arguments (e.g. you can write |arg| arg.to_str()), but that expression can be a block if you like.
Here's an example of a block expression:

answer = {
    foo = 43
    inner_constant = foo - 1
    
    echo!("Inner constant: ${inner_constant.to_str()}")
    
    inner_constant.abs()
}

Block expressions go inside curly braces. They end with an expression (like inner_constant.abs() here),
and the entire block evaluates to whatever that expression evaluates to. This is why, when we use curly
braces in functions, the function returns whatever is at the end of the curly braces—that's just how blocks work!

Statements and expressions Copy Section

Everything before the expression at the end of a block is a statement. The difference between statements
and expressions is:

• An expression evaluates to a value.
• A statement does not.

for loops and constant declarations like inner_constant = are statements. Since statements don't evaluate to
values, you can't do things like pass them as function arguments. You couldn't write echo!(for ...) or
echo!(inner_constant = ...) - you'd get a compile-time error if you did.

Blocks are expressions, so you could write something like this inside an effectful function:

echo!({
    var $total = 0
    for number in 1..=10 {
        $total = $total + number
    }

    $total.to_str()
})

An easy way to think of it is that blocks are a way to incorporate statements into your expressions.

`return` statements Copy Section

Roc's return keyword works the same way it works in most languages: it causes the function to immediately return.

digits_to_num = |digits| {
    if digits.is_empty() {
        return 0
    }

    # ...the rest of the function would go here
}

If you use this in a block, you may get a warning if any statements or expressions come after it in the block,
as they will not be executed!

`crash` statements Copy Section

Roc's crash keyword does what it says: it crashes the currently-running Roc application.

digits_to_num = |digits| {
    if digits.is_empty() {
        crash "Expected a nonempty list."
    }

    # ...the rest of the function would go here
}

crash is not for error handling.

The reason Roc has a crash keyword is for scenarios where it's expected that no error will ever happen (like in unreachable branches), or where graceful error handling is infeasible (like running out of memory).

Errors that are recoverable should be represented using normal Roc types (like Try) and then handled without crashing. For example, by having the application report that something went wrong, and then continue running from there.

What happens after a crash is determined by the platform. Some may gracefully recover and have some way of continuing the process, but others may terminate the process immediately.

Just like return, if you use crash in a block, you may get a warning if any statements or expressions
come after it in the block, as they will not be executed!

`expect` statements Copy Section

We mentioned expect earlier - if you put these at the top level of your file, they will be run whenever roc test runs.

You can also put them in blocks, in which case they will work essentially like a crash when you're doing roc test or
a debug build of roc, but when you do roc --opt=speed, they will be skipped.

digits_to_num = |digits| {
    if digits.is_empty() {
        return 0
    }
        
    # From here on, we assume digits is nonempty!
    expect !digits.is_empty() 

    # ...the rest of the function would go here
}

Importantly, these are not production assertions!
The point is that these are checks of things you assume will be true, and if they turn out not to be true,
you would like to be alerted about the assumption proving false during development or when running test. It is the
responsibility of other code to handle (or not) the situation where these assumptions turn out to be false.

For example, here are three different ways you can handle an assumption turning out to be false in production:

• Detect it and gracefully recover from it, because that's the best experience for people using the software
• Do not attempt to detect it, because doing so is either impractical to implement or too costly in terms of runtime performance; accept that if it happens, it will be bad, but trying to detect it defensively would be worse overall
• Detect it and crash the program using the crash keyword

All three of these have different tradeoffs, and different situations can reasonably call for one over the others.

The point of expect working the way it does is that it does not run in --opt=speed builds at all,
so it does not have production tradeoffs! You can use it as often as you like, and the consequences will
only be felt during development.

`dbg` statements Copy Section

You can use the dbg keyword for the classic technique of printline debugging, like so:

main! = |_args| {
    x = 5
    
    dbg x
    # dbg(x) works too
    
    Ok({})
}

Although printing is an I/O operation, the dbg statement can be used even in pure functions. It works in two different ways:

• Roc evaluates top-level constants at compile time. If evaluating one calls a pure function containing dbg, you'll see the dbg output at compile time. (Evaluating known expressions ahead of time is called constant folding.)
• At runtime, dbg may work differently depending on where you're running the program. For example, in this command-line application it will be printed to stderr. However, when running a Roc program that's compiled to WebAssembly and running in the browser, it would likely appear in the browser console instead.

Note that Roc's compile-time evaluation means there is no guarantee that a given dbg will run at runtime or at compile time.

Conditionals and Collections Copy Chapter

`if` expressions Copy Section

In Roc, if can be used as an expression like so:

name = if str.is_empty() "n/a" else str

You can optionally use blocks to make the different branches stand out more:

name = if str.is_empty() {
    "n/a" 
} else {
    str
}

Records Copy Section

You can also create records, like so:

record = if str.is_empty() {
    { name: "n/a", has_name: Bool.False }
} else {
    { name: str, has_name: Bool.True }
}

You can "update" a record by creating a new one that has some of its fields changed:

new_record = { ..record, name: "New Name" }

You can also destructure a record to bring some of its fields into scope as constants:

{ name, has_name } = record

Lists Copy Section

In Roc, a List looks like this:

animals = ["bird", "crab", "lizard"]

Method Calling Copy Section

You can get the length of the list by calling List.len(animals), or as a shortcut, you can just call animals.len().

Both of them do the same thing. When you call .len(), Roc's type inference knows that the type of animals is List,
so it translates that animals.len() call into List.len(animals) at compile time. .len() is known as a method because
it's a function that is associated with a particular type (in this case, List).

Pattern Matching Copy Section

You can get the first element in the list using animals.first(), but you can also do it using pattern matching:

points = match animals {
    ["bird", "crab", "lizard"] => 10 # exact match
    ["bird", "crab", ..] => 5 # partial match
    ["bird", ..] => 1 # partial match
    [first, second, "lizard", ..] => count_points(first, second)
    _ => 0 # default
}

Patterns can nest as deeply as you like; if you had a list of lists of strings, you could do a pattern like [first_list, ["bird", ..], ..] => etc.

The default branch (_ =>) at the end is necessary so that it's always clear what value points should become,
since lists can be any length and have lots of different contents.

Tags Copy Section

All items in a list must have compatible types.

The following will give a compile error because it's a list with both strings and numbers in it:

animals = ["eagle", 1]

That said, you can tag each of them like so:

birds_or_numbers = [Bird("eagle"), Number(1)]

Pattern matching on tags

You can use pattern matching to access the contents of tags:

label = match birds_or_numbers {
    [Bird(bird), Number(num)] => "${bird} number ${num.to_str()}"
    _ => "" # default
}

`Try` Copy Section

Roc does not have null, nil, undefined, or anything similar. Instead, it uses the tags Ok and Err to
represent whether an operation succeeded or failed:

numbers = [1, 2 ,3 ]
number = match numbers.first() {
    Ok(first) => first + 1
    Err(ListWasEmpty) => 0
}

Here, ListWasEmpty is a tag that isn't wrapping anything. The List.first method is just returning it inside the Err
to describe what the failure was. This both makes the code more self-documenting and also lets you distinguish between
different error types.

For example:

num_or_err = if numbers.is_empty() {
    I64.from_str("1")
} else {
    numbers.first()
}

answer = match num_or_err {
    Ok(num) => num + 1
    Err(ListWasEmpty) => 0
    Err(BadNumStr) => -1
}

Here we have an extra Err branch, because List.first can return Err(ListWasEmpty) if the list was empty,
whereas I64.from_str can return Err(BadNumStr).

Note: I64 is a number type—specifically, a 64-bit integer. Roc also supports 8-bit, 16-bit, 32-bit, and 128-bit integers, and they can be either signed (like I64) or unsigned (like U64). For non-integer types, Roc has F32 and F64 for the classic 32-bit and 64-bit binary floating point numbers, and also Dec for a 128-bit fixed-point decimal. If you don't specify a number type, Roc uses Dec as the default number—which is why in Roc, 0.1 + 0.2 == 0.3 is True, whereas in most languages it isn't.

Exhaustiveness

Neither of these match expressions had a default _ => branch. They didn't need it because they are already exhaustive,
which means they have covered all possible cases. If a match on a known type omits a possible case, the compiler reports
a non-exhaustive match error. If you add _ => after earlier branches have already covered every case, the compiler warns
that the pattern is redundant.

Roc code tends to avoid _ => default branches because these exhaustiveness errors can be helpful for telling you when
you've forgotten to handle something. For example, in our second match above, if we'd written _ => 0 instead of
Err(ListWasEmpty) => 0, we would have been silently handling the Err(BadNumStr) case using the same logic. That might
not have been what we wanted! By writing out Err(ListWasEmpty) instead of _ =>, the compiler would let us know if we
were forgetting to handle any cases that could come up at runtime.

`Try` methods

Both List.first and I64.from_str are returning an extremely common Roc type, named Try. We define and pattern-match
Str values using "…", List values using […], and Try values using Ok and Err. So if I had a function that
accepted a Try with strings for both its Ok and Err types, then I could pass it Ok("foo") or Err("bar").

Just like Str and List, Try has methods. Here's an example of one:

number = numbers.first().ok_or(0)

Underscore patterns

The Try.ok_or method is defined like this:

ok_or = |try, fallback| match try {
    Ok(val) => val
    Err(_) => fallback
}

It returns the value inside the Ok tag, or else the provided fallback value if the Try was an Err tag instead of Ok.

The underscore pattern inside Err(_) => essentially means to ignore that part of the pattern. You can put underscores
anywhere in any pattern, including for the entire pattern. This method doesn't want to match a more specific pattern
(like Err(ListWasEmpty) => earlier) because it wants to be flexible. If it matched a more restrictive pattern, like
Err(ListWasEmpty) =>, then you couldn't use .ok_or with I64.from_str because it returns Err(BadNumStr).

The `?` postfix operator

It's common to want to early-return an Err from a Try. It's so common, Roc has a dedicated operator for it:

increment_first = |strings| {
    first_str = strings.first()?
    first_num = I64.from_str(first_str)?
    
    Ok(first_num + 1)
}

The ? postfix operator is syntax sugar for "if this is an Ok, evaluate to its value; otherwise, return the Err."

The desugared version of the above function would be:

increment_first = |strings| {
    first_str = match strings.first() {
        Ok(val) => val
        Err(err) => return Err(err)
    }
    
    first_num = match I64.from_str(first_str) {
        Ok(val) => val
        Err(err) => return Err(err)
    }
    
    Ok(first_num + 1)
}

The ? version is quite a bit more concise!

Types Copy Chapter

So far we haven't seen any types. That's because although Roc is a statically type-checked language, it infers the types
of everything you write. All type annotations in Roc are optional, but the compiler still infers every type, so you'll
still get compile-time errors if you mix up types. Technically, Roc has sound, decidable, principal static type inference. All Roc values are semantically immutable, making them free of data races as well.

Roc has a "nonblocking compilation" design philosophy. This means that roc will still run your program and roc test
will still run your tests when possible, even if you have compile-time errors—including static type mismatches. The
diagnostics are still printed and the command exits with a nonzero status, so CI will treat the run as a failure.
This lets you try code despite known problems, although reaching invalid code at runtime may cause it to crash.

Use roc check && roc if you want to check for errors first and run the program only when there are none.

Type Annotations Copy Section

You can write type annotations above any constant or var, like so:

name : Str
name = "Sam"

is_empty : Bool
is_empty = name.is_empty()

Parameterized types Copy Section

We noted earlier how all items in a List must have compatible types. That's represented in the List type
using a type parameter like so:

strings : List(Str)
strings = ["a", "b", "c"]

integers : List(I64)
integers = [1, 2, 3]

Pure and effectful function types Copy Section

Pure functions use a thin arrow (->) and effectful functions use a thick arrow (=>) to separate parameter types from
return types:

average : Dec, Dec -> Dec
average = |a, b| (a + b) / 2

# Note that you don't have to write out 2.0 to perform decimal division in Roc; you can just write 2 like normal!

read_str! : Path => Try(Str, ReadFileErr)
read_str! = |path| # ...

Try type is a parameterized type with two type parameters. The first one is the Ok type and the second one is the Err type.

Type variables Copy Section

Type variables allow you to write functions that work with any type. They are written as lowercase identifiers (like a, b, elem, etc.) in type annotations:

# This function works for a list of any type
type_var : List(a) -> List(a)
type_var = |lst| lst

The type variable a indicates that the function accepts a List containing elements of any type, and returns a List containing elements of that same type.

You can also constrain type variables to types that have specific methods using where:

stringify : a -> Str where [a.to_str : a -> Str]
stringify = |value| value.to_str()

This function works for any type a that has a to_str method which takes an a and returns a Str.

Structural types Copy Section

Tag union types

It's very common to see a Try with a tag union for its error type, even if it only has one tag in it. This allows
multiple errors to neatly combine into a tag union of all the possible errors that could occur, so you can pattern
match on them later like we saw with I64.from_str and List.first.

Nominal types Copy Section

As we saw with ListWasEmpty and BadNumStr, tags don't have to wrap anything. You can also use them as enumerations, like so:

Color := [Red, Green, Blue]

This is a nominal type definition.

Upgrading from alpha-4 Copy Chapter

If you've been writing Roc before it was mainstream and you want to upgrade your code from alpha-4, compare the two all syntax examples:

• alpha-4 all syntax example
• current all syntax example

Dependencies Copy Chapter

The initial Hello World example is a headerless app. Headerless apps automatically use Roc's built-in
Echo Platform, which provides the unqualified echo! function and is intentionally minimal.
Other Roc apps select a platform explicitly. For example, this header uses
basic-cli, a platform for command-line applications:

app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.22.2/9zUBxb1LtXYVc4eR4hAtd1WQDwBYDhM6HQdZz1UFCm2m.tar.zst" }

Let's break the header down:

• app means this .roc file specifies a Roc application - an executable, as opposed to a bundle of reusable code like a package
• [main!] specifies the application's entrypoint. Some applications have multiple entrypoints, but it's most common to have just one—and also it's most common for that one to be named main!
• { pf: platform "https://..." } specifies the application's platform. If we wanted to add other dependencies, this is where we'd specify them - e.g. we might write uni: "https://..." to add a dependency on unicode to process Unicode strings, at which point we'd be able to do things like import uni.Grapheme and so on.