Guides
There are currently 176 tutorials, how-tos, and in-depth feature guides for Turmeric.
Visit the Spices page for spice-specific guides.
For docs for the Trowel editor, go here.
| Operators | 2026-10-22 | Arithmetic, comparison, logical and bitwise operators -- which types each takes, how integers wrap and divide, and the float-only forms |
| tur serve | 2026-10-22 | Serve a directory over HTTP with tur serve, the Turmeric spelling of python3 -m http.server |
| Unsafe Code | 2026-10-22 | The (unsafe ...) block, raw pointers and raw memory, bit reinterpretation, and when to reach for something safer |
| The Build Driver | 2026-10-16 | How the tur driver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, how cc is chosen and invoked, tur run and project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables |
| CPS and the DK Continuation Machine | 2026-10-16 | How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it |
| Diagnostics Internals | 2026-10-16 | How the compiler reports errors and warnings -- the DiagCode enum and its four tables, the diag_emit family, spans through sweet-exp, macros and loaded files, the terminal/JSON/LSP/embed sinks, tur explain, the errors/ fixture harness, and a checklist for adding a code |
| Effect Rows (internals) | 2026-10-16 | How effect rows are represented, parsed, inferred and checked -- the EffectRow kinds, the EffectEnv registry, the elaborator's effect checks, the effect-row pass and its fixpoint, capabilities and Unsafe, --dump-effects, and where codegen reads the rows |
| Elaborator Internals | 2026-10-16 | How the elaborator turns reader Forms into the typed Expr IR -- the Elab state and scope model, the two-pass top-level driver and the synthesized main, call-site-local type inference, the Expr and Type data model, what the elaborator records for later passes, incremental sessions, macros, and the checklist for adding a form |
| Who Frees What in Emitted Code | 2026-10-16 | How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak |
| C Emitter Architecture | 2026-10-16 | How the C emitter turns an elaborated program into one translation unit -- the emit_value/emit_stmt contract, EmitCtx, the phase order of emit_program, ABI specializations, the side tables call sites consult, inline C, function definitions, and how to add an emit arm |
| Markdown Guide | 2026-10-16 | Parse CommonMark and GitHub Flavored Markdown into a document tree with tur/markdown, render it as HTML, walk its blocks and inlines, and what is implemented so far |
| Package Manager Internals | 2026-10-16 | How tur reads build.tur, resolves :spices and workspace siblings, writes and honours tur.lock, generates and consumes the :cmake-deps CMake project, and threads :build-opts into the C compile -- with the traps each stage leaves for spice authors |
| How #lang r7rs Is Implemented | 2026-10-16 | How a #lang r7rs file becomes a Turmeric program -- dialect selection, the Scheme-to-Turmeric lowering and its rename table, the value representation, libraries and the split build, call/cc and the dynamic environment, the conservative collector, SRFIs, and the harnesses that cover them |
| Regions (RM3) Internals | 2026-10-16 | How region brackets work on the compiled path -- arena generations, rewind vs retire, the static walk and the runtime escape note, the store-hook rule and every place it is applied, the CPS and call/cc interactions, and the tools that tell a rewind from a retire |
| The Runtime Preamble and Its Linkage | 2026-10-16 | Where the C runtime every compiled program needs comes from -- the emitted preamble, its feature gates and linkage postures, the runtime archives, the S2 split runtime and its generator, tur_tls.c -- which copy each build path links, and how to change any of it without silently losing the fast path |
| Separate Compilation and Module Loading | 2026-10-16 | How the compiler finds, loads and resolves modules, which builds split a program into one C translation unit per module, what goes into each module's .h and .c, who owns a generic specialization or an instance across TUs, and how to read the link errors when the split goes wrong |
| The turi Interpreter (internals) | 2026-10-16 | How the tree-walking interpreter works -- its entry points, the shared front end it runs, value and frame representations, the explicit-stack driver, native overrides and inline-C, the two effect runtimes, what memory it gives back and what it keeps, process-global hazards, and how to add a form or native |
| Zipper Guide | 2026-10-14 | Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor). |
| Tourist Web Stack End-to-End | 2026-10-13 | Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together |
| Parsec Reference Guide | 2026-10-11 | Reference for the stdlib parser-combinator library tur/parsec -- core types, primitive parsers, sequencing, choice, repetition, optional values, mapping, runners, and common patterns |
| Parsec Tutorial | 2026-10-11 | A step-by-step introduction to the stdlib parser-combinator library tur/parsec -- characters, sequencing with do-m, choice, repetition, optional pieces, and mapping results into real values |
| Memory Usage Guide | 2026-10-05 | What each language feature costs in heap memory, measured -- scalars, structs, sums, lists, Vec, MutableMap, Map, String, rc, closures, function-value calls, effects and regions -- what frees it, and strategies for using less |
| Release Process | 2026-10-05 | How Turmeric releases are cut -- the three cut-*-release commands, their shared nine-step flow, the ordering constraints that make a failed cut recoverable, and what the release workflow does once the tag is pushed. |
| Running the Tests | 2026-10-05 | Which harness runs what, how to narrow a run to the tests you care about, the fixture marker files, and how to reproduce a red CI job locally |
| Borrow Checking and Lifetimes Guide | 2026-10-04 | How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report |
| Channels and Select Guide | 2026-10-04 | Buffered channels for inter-fiber communication and multi-channel select |
| Debugging Turmeric Programs | 2026-10-04 | Finding out why a program does not compile, panics, crashes or prints the wrong thing -- reading diagnostics, tur explain, the tur debug stepper, editor debugging over DAP, tur build --debug under lldb/gdb, sanitizers for inline C, and tur demangle |
| Diagnosing the Compiler | 2026-10-04 | How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures |
| Files and Processes | 2026-10-04 | Read and write files, walk directories, manage symlinks and permissions, read stdin line by line, run child processes, handle signals, speak TCP and work with calendar dates through the typed fs / io / process / net / time / os stdlib -- every failure is a (Result T IoError) |
| Loop Invariants Guide | 2026-10-04 | Proving loop properties with :invariant annotations on while loops |
| Regular Expressions Guide | 2026-10-04 | Pure-Turmeric POSIX ERE regex engine -- compile, match, find, and replace |
| Structured Concurrency Guide | 2026-10-04 | TaskGroup for scoped task spawning and Future/Promise for asynchronous results |
| Working through SICP with Turmeric | 2026-10-03 | Run the code from Structure and Interpretation of Computer Programs in Turmeric's Scheme dialect: installing, the interpreter and the REPL, the few definitions the book assumes, chapter-by-chapter notes, and the rough edges to know about. |
| Security Guide | 2026-09-29 | What Turmeric promises to handle safely -- the trust boundary for each input, the promise made at it, and where the implementation does not yet keep that promise |
| R7RS Scheme -- #lang r7rs | 2026-09-24 | #lang r7rs runs R7RS-small Scheme on the Turmeric compiler and runtime, compiled or interpreted, and lets Scheme and Turmeric modules import each other. This guide covers getting started, what is there, how it differs from the standard, and the tooling. |
| Introducing Saffron | 2026-09-14 | A first tour of Saffron, the dynamically typed dialect of Turmeric: Try Turmeric in the browser, printing, flow control, functions, ADTs, typeclasses, and algebraic effects -- every example in both s-expression and sweet-expression syntax. |
| Semigroups, Monoids, and Lattices | 2026-09-12 | The algebraic combining vocabulary in stdlib/typeclass-lattice.tur -- Semigroup, Monoid, the join/meet lattice classes, the selection newtypes that carry them, mconcat, and the law predicates. |
| Saffron -- the dynamically typed dialect | 2026-09-08 | #lang saffron makes any the default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up. |
Time-Travel Tracing Guide (tur trace) | 2026-08-30 | Recording an interpreted run and scrubbing it -- what the .turtrace format holds, what the step cap protects, and how tur dap replays a recording so a debugger can step backwards |
| Backtrackable State Guide | 2026-08-28 | Trailed mutable cells from stdlib/trail.tur -- take a mark, mutate freely, then undo or keep the writes; scopes, the Bt capability, and why a search loop wants this instead of a persistent structure |
| Offline Docs Guide | 2026-08-26 | How the guides and API reference reach you without a network -- the docs pack, Try Turmeric's in-app docs browser, and the tur doc / tur docs commands |
| Dynamic FFI | 2026-08-17 | Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine |
| Macros Guide | 2026-08-17 | defmacro as a compile-time function from syntax to syntax -- quasiquote and splicing, manual hygiene, procedural defmacro*, macro-time imports, and why an expansion is type checked exactly like hand-written code |
| Mutable Globals Guide | 2026-08-05 | def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover |
JIT Execution Engine Guide (tur jit) | 2026-07-31 | How the in-process MIR JIT is built -- what MIR is, how the engine is wired into this project, and what it does differently from the cc path (the fallback contract, the permanent constraints, and the inline-C rules that only bite under the JIT) |
| Value Representations | 2026-07-30 | Every representation a Turmeric value can travel in, the boundaries where the compiler must bridge between them, and the failure shapes -- cc errors, link errors, segfaults -- when a bridge is missing |
| Numeric Tower Guide | 2026-07-29 | Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading |
| Type-Level Rows | 2026-07-28 | The #row{...} reader form and the kind-[*] row type -- writing rows, row-kinded (^&) parameters, the row algebra (concat/union/intersect/canon), erasure, and what rows deliberately cannot do |
| Ownership Guide | 2026-07-26 | Which ownership strategy to reach for -- persistent-immutable, single-owner mutable, linear/affine handles, rc<T> for genuine sharing, and weak<T> to break the resulting cycles |
| Refinement Solver Internals | 2026-07-26 | How the compiler proves a refinement predicate at compile time -- the obligation pipeline, the normalized verification condition, the staged in-house solver (no SMT dependency), memoization, caps, and how to debug an obligation |
| Stateful Refinements | 2026-07-26 | Refining predicates over mutable state -- the frozen region and the #reads w annotation that grants congruence, why a trusted annotation is sound here, and how the guarded crossings codegen |
| Refinement Types | 2026-07-24 | #refine{ x : T | p } predicates the compiler tries to prove statically, emitting a runtime check only where the proof fails -- the predicate language, named refinements, diagnostics, and the documented limits |
tur compile and tur link | 2026-07-22 | Splitting the monolithic tur build into a cacheable object compile plus a cheap link -- tur compile, tur link, --split-build, and how --runtime= decides the way the runtime gets linked |
| Strings Guide | 2026-07-20 | The three string tiers -- borrowed cstr, borrowed str view, and owned refcounted String -- which to reach for, #s"..." literals, zero-copy StringSlice, the lifetime rules, and the dangling-pointer pitfalls |
| Garbage Collection | 2026-07-07 | How memory is managed in Turmeric -- reference counting, the Bacon-Rajan cycle collector, arenas, and what is (and isn't) GC-managed in the compiled and interpreted paths |
| Lens Guide | 2026-07-02 | First-class functional lenses (view / set / over) via stdlib/lens.tur, which ships the profunctor-by-record encoding. The classic van Laarhoven form is also expressible by hand. |
| Test Suite Portability & Performance Guide | 2026-07-02 | macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses |
| Typeclass Guide | 2026-06-27 | Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations. |
| Godot Binding Guide | 2026-06-25 | Attaching .tur scripts to Godot 4 nodes -- install, the curated and generated ClassDB facades, typed godot-call variants, value marshalling, the editor plugin and debugger, AOT mode, and the known gaps |
| Wiring a ResourceFormatLoader for the Turmeric/Godot Binding | 2026-06-24 | Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline |
Returning Result / Option from Inline-C | 2026-06-24 | Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int |
| Using Turmeric with mise or asdf | 2026-06-24 | Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf) |
| Autodoc Guide | 2026-06-23 | Writing ;;; docstrings and generating API docs with tools/gendocs.py |
| Currying Guide | 2026-06-23 | Haskell-style partial application and over-application of Turmeric functions |
| Experimental Feature Flags | 2026-06-23 | The --enable=<name> surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and the tur experiments command. |
| Thread Pool | 2026-06-23 | Bounded POSIX worker-thread pool with back-pressure for fan-out work over ptr<void> items |
| Tourist Session Middleware | 2026-06-23 | Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file) |
Turmeric Version Manager (tvm) | 2026-06-23 | Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager. |
| WebSockets | 2026-06-23 | Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices |
| ECS Storage Guide -- Dense, Sparse, Tag | 2026-06-20 | How tur-ecs's three component-storage backends -- Dense, Sparse, Tag -- differ in layout, cost, and ergonomics; when to pick each; how StorageOps unifies them; and how the Sized* variants thread a capacity through the type. |
| Monomorphization ABI Guide | 2026-06-20 | How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read __spec_* symbols in error messages, and what the small residual ABI bridge does. |
Typing Handles, Callbacks, and Results -- Avoiding :int Stand-Ins | 2026-06-20 | How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit. |
| turi <-> tur Parity Guide | 2026-06-14 | Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable. |
| ECS -- tur-ecs vs apecs vs aztecs | 2026-06-12 | A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land. |
| ECS Guide | 2026-06-11 | Building games and simulations with tur-ecs and the tur-ecs-raylib companion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop. |
| Application Image Dumps | 2026-06-10 | Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style. |
| Function Arity Style Guide | 2026-06-07 | When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each |
| Name Mangling Guide | 2026-06-05 | How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies. |
Opaque Types (defopaque) | 2026-06-04 | Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines |
Sum Types and Either | 2026-06-04 | Declaring binary and n-ary sum types with defdata, pattern matching with match, exhaustiveness behaviour and the ^non-exhaustive opt-out, the FFI layout, and the stdlib Either module. |
| Typeclass Dictionary Internals | 2026-06-03 | How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how definstance lowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics. |
Fat-Closure Annotation Guide (^fat) | 2026-06-02 | When and why to mark function-typed parameters and return positions ^fat, and what breaks without it |
| HTTPD Async Guide | 2026-06-02 | Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop |
| HTTP Middleware Catalog (stdlib/httpd) | 2026-06-02 | Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files, security headers, request ids, trusted proxies, ETags, timeouts -- plus the request-attribute side channel and the composition helpers. |
| Parser Combinators Tutorial | 2026-06-02 | Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching |
| Approaches to Polymorphism | 2026-06-02 | A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for |
| Tourist Routing Composition | 2026-06-02 | Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications |
| AI Assistant Integration Guide | 2026-06-01 | Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot |
| Symbols Guide | 2026-06-01 | First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table |
| Syntax Guide | 2026-06-01 | How to read and write Turmeric -- s-expression and sweet-expression syntax |
| Data Literals Guide | 2026-05-31 | Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...] |
| Delimited Control Operators: shift/reset vs shift0/escape | 2026-05-31 | How shift/reset, shift0/reset0, call/cc, and escape differ -- prompt re-installation, where the captured value returns, and which to reach for |
| HTTP Server with stdlib/httpd | 2026-05-31 | Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive |
| HTTPS with stdlib/httpd + tur-tls | 2026-05-31 | How to terminate TLS on an httpd-new server using the tur-tls spice |
| JSON Guide | 2026-05-31 | Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON |
| Runtime Schema Validation | 2026-05-31 | Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors. |
| Binding Forms Guide | 2026-05-30 | def in a body, letrec, and named-let -- the three local binding idioms that complement let and defn |
| Reactor Guide | 2026-05-30 | Lightweight evented I/O with tur/reactor |
| tur-watch Guide | 2026-05-30 | Cross-platform filesystem watching with debounce and coalescing for CLI tools |
| Web Stack Guide | 2026-05-30 | Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric |
| Tur New Guide | 2026-05-29 | Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI |
| Tur Run Guide | 2026-05-29 | Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just |
| Releases and Installation | 2026-05-27 | How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release. |
| Sized Primitive Types | 2026-05-27 | Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting |
| Turmeric Style Guide | 2026-05-27 | Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style |
| Type Erasure to int64_t | 2026-05-27 | Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses |
| Notebook Guide | 2026-05-26 | Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode |
| tur-stats Guide | 2026-05-26 | Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes |
| Frame Guide | 2026-05-25 | In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface |
| tur/logic -- Logic Programming Guide | 2026-05-25 | How to use and extend tur/logic for miniKanren-style relational programming in Turmeric |
| Existential Types | 2026-05-23 | Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries |
| Advanced Type System -- Design Rationale | 2026-05-22 | Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped |
| Arrows and Signal Processing | 2026-05-22 | Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/ |
| Bibliography | 2026-05-22 | Academic papers, theses, and technical references cited across Turmeric design documents and guides |
| CLI Arguments Guide | 2026-05-22 | Passing arguments to scripts with *args* and parsing them with stdlib/args.tur |
| Deploying Turmeric Services to Cloudflare | 2026-05-22 | Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts). |
| Consuming Spices Guide | 2026-05-22 | Adding, fetching, and using spice packages in a Turmeric project |
| Dev Container | 2026-05-22 | Running Turmeric development in a devcontainer from VS Code or the CLI |
| Developing Spices Guide | 2026-05-22 | Creating, testing, and publishing Turmeric spice packages |
| Generators and Lazy Sequences Guide | 2026-05-22 | Zero-overhead generators with gen/yield, lazy Seq combinators, and the Range type |
| Language Server (LSP) Guide | 2026-05-22 | Configuring editors to use the Turmeric language server for diagnostics |
| Range Reader Shorthand Plan | 2026-05-22 | Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time |
| Reader Forms Reference | 2026-05-22 | Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions |
| Sandboxing Guide | 2026-05-22 | Restricting Turmeric code inside a C host with turi_env_new_sandboxed, capability flags, the native classification table, and resource limits -- and the memory-safety gap that keeps it from being a boundary against hostile code |
| Performance Guide | 2026-05-21 | Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology |
| Sized Types | 2026-05-21 | Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations |
| Structs | 2026-05-21 | Defining and using struct types with defstruct |
| Building for the Web with Emscripten | 2026-05-21 | Compile a Turmeric project to WebAssembly and run it in a browser |
| Datalog Tutorial Pt. 1: Concepts | 2026-05-19 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 2: Minimal Implementation | 2026-05-19 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 3: Query API | 2026-05-19 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 4: Indexing | 2026-05-19 | Create a database and a query system to go with it |
| Dynamic Vars Guide | 2026-05-19 | Thread-local, dynamically-scoped mutable cells with defdynamic and binding |
| Session Types Guide | 2026-05-19 | Model protocols as types, whether the protocol has two participants, or more |
| Compiler Flags | 2026-05-18 | Diagnostic and debug flags accepted by tur; list of removed -X feature flags |
| Compiler Internals | 2026-05-18 | The map of the tur compiler -- the pipeline and pass schedule, the src/ layout, and one paragraph per subsystem with a link to its deep-dive guide; the entry point for contributors |
| Contract Types Guide | 2026-05-18 | Contract types: #refine{ x : T | p }, :pre/:post annotations, FFI contracts |
| Quickstart | 2026-05-18 | Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects |
| Interactive REPL Tutorial | 2026-05-18 | 22-step interactive tutorial to follow at tur repl or the web REPL |
| State Machines Guide | 2026-05-18 | Five different approaches to modeling state machines in turmeric |
| Union and Intersection Types Guide | 2026-05-18 | Union (A | B) and intersection (A & B) types, any, gradual typing |
| Vim Guide | 2026-05-18 | Vim / Neovim syntax highlighting installation and configuration |
| GADTs Cookbook | 2026-05-17 | GADTs cookbook: practical patterns and recipes |
| GADTs -- A Practical Guide | 2026-05-17 | GADTs: refined constructors (defdata with : Result), type refinement, equality witnesses, union types, gradual typing |
| Substructural Types | 2026-05-16 | ^linear, ^affine, ^relevant type disciplines |
| Type Annotation Syntax | 2026-05-16 | Compound type annotation syntax: (-> a b), (vec T), forall, and more |
| Uniqueness Types | 2026-05-16 | ^unique: at-most-one-reference ownership |
| Effects vs. Monads | 2026-05-15 | When to reach for an effect handler and when to reach for a monad value |
| Formatter Guide | 2026-05-15 | tur format CLI and web REPL Format button |
| Package Management Guide (Spice) | 2026-05-15 | Creating projects, adding spices, build.tur, tur.lock, CLI reference |
| Using a Turmeric Library from CMake | 2026-05-15 | How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using tur emit-cmake |
| VS Code Extension | 2026-05-15 | VS Code extension installation and configuration |
| Web Continuations Guide | 2026-05-15 | Compact reference: one continuation per page, the continuation store, routing model |
| Web Continuations Tutorial | 2026-05-15 | Multi-page web forms using serializable continuations (guestbook example) |
| Higher-Ranked Types | 2026-05-14 | Higher-ranked types: rank-2/3 polymorphic function parameters |
| Async/Await Guide | 2026-05-13 | Async/await with fibers and delimited continuations |
| Backtracking Guide | 2026-05-13 | Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur |
| Cellular Automata with Comonads | 2026-05-13 | Cellular automata with comonads |
| Checkpointing and Persistent Workflows | 2026-05-13 | Cloneable continuations for persistent workflows and checkpointing |
| Effects System Guide | 2026-05-13 | Algebraic effects, dependency injection, custom control flow |
| libturi -- C Embedding API Reference | 2026-05-13 | C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a |
| HAMT Guide | 2026-05-13 | Persistent hash maps with structural sharing (HAMT) |
| Logic Programming Guide | 2026-05-13 | Backtracking, logic programming, constraint solving with cloneable continuations |
| tur repl -- REPL Reference | 2026-05-13 | Reference guide for the tur repl interactive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration |
| Serializable Continuations Guide | 2026-05-13 | Serializable continuations for persistent workflows and cross-process computation |
| STM Guide | 2026-05-13 | Software transactional memory -- API reference and mechanics |
| Software Transactional Memory (STM) Tutorial | 2026-05-13 | STM tutorial: concepts, patterns, and worked examples |
| Threading and Concurrency Primitives Guide | 2026-05-13 | OS threads, Arc<T>, Mutex<T>, Atomic<T>, channels |
| Higher-Kinded Types | 2026-05-12 | Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model) |
| Module System Guide | 2026-05-12 | Module system, namespacing, exports |
| C Integration Guide | 2026-05-11 | Foreign function interface (FFI) and C interop |
| Custom Effects Tutorial | 2026-05-11 | Writing custom effects |
| Error Handling Guide | 2026-05-11 | Result, Option, panic, contract macros (assert!, require!, ensure!) |
| MiniKanren Part 1: Relations and Queries | 2026-05-11 | Logic programming with miniKanren -- relations, composition, and bidirectional queries |
| Snake Game Tutorial | 2026-05-10 | Building the snake game example |
| Test Runner Contract | 2026-05-10 | Test framework API and contract |
| Experimental Feature Flags | 2026-10-30 | The --enable=<name> surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and the tur experiments command. |
| Garbage Collection | 2026-10-29 | How memory is managed in Turmeric -- reference counting, the Bacon-Rajan cycle collector, arenas, and what is (and isn't) GC-managed in the compiled and interpreted paths |
JIT Execution Engine Guide (tur jit) | 2026-10-29 | How the in-process MIR JIT is built -- what MIR is, how the engine is wired into this project, and what it does differently from the cc path (the fallback contract, the permanent constraints, and the inline-C rules that only bite under the JIT) |
| Module System Guide | 2026-10-29 | Module system, namespacing, exports |
| Package Manager Internals | 2026-10-29 | How tur reads build.tur, resolves :spices and workspace siblings, writes and honours tur.lock, generates and consumes the :cmake-deps CMake project, and threads :build-opts into the C compile -- with the traps each stage leaves for spice authors |
| Performance Guide | 2026-10-29 | Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology |
| Test Suite Portability & Performance Guide | 2026-10-29 | macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses |
| Advanced Type System -- Design Rationale | 2026-10-28 | Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped |
| Borrow Checking and Lifetimes Guide | 2026-10-28 | How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report |
| The Build Driver | 2026-10-28 | How the tur driver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, how cc is chosen and invoked, tur run and project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables |
| C Integration Guide | 2026-10-28 | Foreign function interface (FFI) and C interop |
| Channels and Select Guide | 2026-10-28 | Buffered channels for inter-fiber communication and multi-channel select |
| Compiler Flags | 2026-10-28 | Diagnostic and debug flags accepted by tur; list of removed -X feature flags |
| Compiler Internals | 2026-10-28 | The map of the tur compiler -- the pipeline and pass schedule, the src/ layout, and one paragraph per subsystem with a link to its deep-dive guide; the entry point for contributors |
| Consuming Spices Guide | 2026-10-28 | Adding, fetching, and using spice packages in a Turmeric project |
| Datalog Tutorial Pt. 1: Concepts | 2026-10-28 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 2: Minimal Implementation | 2026-10-28 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 4: Indexing | 2026-10-28 | Create a database and a query system to go with it |
| Developing Spices Guide | 2026-10-28 | Creating, testing, and publishing Turmeric spice packages |
| Effect Rows (internals) | 2026-10-28 | How effect rows are represented, parsed, inferred and checked -- the EffectRow kinds, the EffectEnv registry, the elaborator's effect checks, the effect-row pass and its fixpoint, capabilities and Unsafe, --dump-effects, and where codegen reads the rows |
| Effects System Guide | 2026-10-28 | Algebraic effects, dependency injection, custom control flow |
| Elaborator Internals | 2026-10-28 | How the elaborator turns reader Forms into the typed Expr IR -- the Elab state and scope model, the two-pass top-level driver and the synthesized main, call-site-local type inference, the Expr and Type data model, what the elaborator records for later passes, incremental sessions, macros, and the checklist for adding a form |
| Who Frees What in Emitted Code | 2026-10-28 | How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak |
| C Emitter Architecture | 2026-10-28 | How the C emitter turns an elaborated program into one translation unit -- the emit_value/emit_stmt contract, EmitCtx, the phase order of emit_program, ABI specializations, the side tables call sites consult, inline C, function definitions, and how to add an emit arm |
| Dynamic FFI | 2026-10-28 | Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine |
| Formatter Guide | 2026-10-28 | tur format CLI and web REPL Format button |
| GADTs -- A Practical Guide | 2026-10-28 | GADTs: refined constructors (defdata with : Result), type refinement, equality witnesses, union types, gradual typing |
Returning Result / Option from Inline-C | 2026-10-28 | Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int |
| Introducing Saffron | 2026-10-28 | A first tour of Saffron, the dynamically typed dialect of Turmeric: Try Turmeric in the browser, printing, flow control, functions, ADTs, typeclasses, and algebraic effects -- every example in both s-expression and sweet-expression syntax. |
| Lens Guide | 2026-10-28 | First-class functional lenses (view / set / over) via stdlib/lens.tur, which ships the profunctor-by-record encoding. The classic van Laarhoven form is also expressible by hand. |
| Macros Guide | 2026-10-28 | defmacro as a compile-time function from syntax to syntax -- quasiquote and splicing, manual hygiene, procedural defmacro*, macro-time imports, and why an expansion is type checked exactly like hand-written code |
| Memory Usage Guide | 2026-10-28 | What each language feature costs in heap memory, measured -- scalars, structs, sums, lists, Vec, MutableMap, Map, String, rc, closures, function-value calls, effects and regions -- what frees it, and strategies for using less |
| Monomorphization ABI Guide | 2026-10-28 | How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read __spec_* symbols in error messages, and what the small residual ABI bridge does. |
| Mutable Globals Guide | 2026-10-28 | def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover |
| Numeric Tower Guide | 2026-10-28 | Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading |
| Offline Docs Guide | 2026-10-28 | How the guides and API reference reach you without a network -- the docs pack, Try Turmeric's in-app docs browser, and the tur doc / tur docs commands |
Opaque Types (defopaque) | 2026-10-28 | Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines |
| Ownership Guide | 2026-10-28 | Which ownership strategy to reach for -- persistent-immutable, single-owner mutable, linear/affine handles, rc<T> for genuine sharing, and weak<T> to break the resulting cycles |
| Parsec Reference Guide | 2026-10-28 | Reference for the stdlib parser-combinator library tur/parsec -- core types, primitive parsers, sequencing, choice, repetition, optional values, mapping, runners, and common patterns |
| Parsec Tutorial | 2026-10-28 | A step-by-step introduction to the stdlib parser-combinator library tur/parsec -- characters, sequencing with do-m, choice, repetition, optional pieces, and mapping results into real values |
| R7RS Scheme -- #lang r7rs | 2026-10-28 | #lang r7rs runs R7RS-small Scheme on the Turmeric compiler and runtime, compiled or interpreted, and lets Scheme and Turmeric modules import each other. This guide covers getting started, what is there, how it differs from the standard, and the tooling. |
| How #lang r7rs Is Implemented | 2026-10-28 | How a #lang r7rs file becomes a Turmeric program -- dialect selection, the Scheme-to-Turmeric lowering and its rename table, the value representation, libraries and the split build, call/cc and the dynamic environment, the conservative collector, SRFIs, and the harnesses that cover them |
| Reactor Guide | 2026-10-28 | Lightweight evented I/O with tur/reactor |
| Reader Forms Reference | 2026-10-28 | Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions |
| Refinement Solver Internals | 2026-10-28 | How the compiler proves a refinement predicate at compile time -- the obligation pipeline, the normalized verification condition, the staged in-house solver (no SMT dependency), memoization, caps, and how to debug an obligation |
| Refinement Types | 2026-10-28 | #refine{ x : T | p } predicates the compiler tries to prove statically, emitting a runtime check only where the proof fails -- the predicate language, named refinements, diagnostics, and the documented limits |
| Regions (RM3) Internals | 2026-10-28 | How region brackets work on the compiled path -- arena generations, rewind vs retire, the static walk and the runtime escape note, the store-hook rule and every place it is applied, the CPS and call/cc interactions, and the tools that tell a rewind from a retire |
| Running the Tests | 2026-10-28 | Which harness runs what, how to narrow a run to the tests you care about, the fixture marker files, and how to reproduce a red CI job locally |
| Saffron -- the dynamically typed dialect | 2026-10-28 | #lang saffron makes any the default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up. |
| Runtime Schema Validation | 2026-10-28 | Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors. |
| Separate Compilation and Module Loading | 2026-10-28 | How the compiler finds, loads and resolves modules, which builds split a program into one C translation unit per module, what goes into each module's .h and .c, who owns a generic specialization or an instance across TUs, and how to read the link errors when the split goes wrong |
| Session Types Guide | 2026-10-28 | Model protocols as types, whether the protocol has two participants, or more |
| State Machines Guide | 2026-10-28 | Five different approaches to modeling state machines in turmeric |
| Structs | 2026-10-28 | Defining and using struct types with defstruct |
| Structured Concurrency Guide | 2026-10-28 | TaskGroup for scoped task spawning and Future/Promise for asynchronous results |
| Substructural Types | 2026-10-28 | ^linear, ^affine, ^relevant type disciplines |
Sum Types and Either | 2026-10-28 | Declaring binary and n-ary sum types with defdata, pattern matching with match, exhaustiveness behaviour and the ^non-exhaustive opt-out, the FFI layout, and the stdlib Either module. |
| Threading and Concurrency Primitives Guide | 2026-10-28 | OS threads, Arc<T>, Mutex<T>, Atomic<T>, channels |
| Tourist Session Middleware | 2026-10-28 | Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file) |
| The turi Interpreter (internals) | 2026-10-28 | How the tree-walking interpreter works -- its entry points, the shared front end it runs, value and frame representations, the explicit-stack driver, native overrides and inline-C, the two effect runtimes, what memory it gives back and what it keeps, process-global hazards, and how to add a form or native |
| turi <-> tur Parity Guide | 2026-10-28 | Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable. |
| Type Erasure to int64_t | 2026-10-28 | Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses |
Typing Handles, Callbacks, and Results -- Avoiding :int Stand-Ins | 2026-10-28 | How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit. |
| Uniqueness Types | 2026-10-28 | ^unique: at-most-one-reference ownership |
| Value Representations | 2026-10-28 | Every representation a Turmeric value can travel in, the boundaries where the compiler must bridge between them, and the failure shapes -- cc errors, link errors, segfaults -- when a bridge is missing |
| Zipper Guide | 2026-10-28 | Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor). |
| Arrows and Signal Processing | 2026-10-27 | Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/ |
| Backtrackable State Guide | 2026-10-27 | Trailed mutable cells from stdlib/trail.tur -- take a mark, mutate freely, then undo or keep the writes; scopes, the Bt capability, and why a search loop wants this instead of a persistent structure |
| Backtracking Guide | 2026-10-27 | Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur |
| Binding Forms Guide | 2026-10-27 | def in a body, letrec, and named-let -- the three local binding idioms that complement let and defn |
| Cellular Automata with Comonads | 2026-10-27 | Cellular automata with comonads |
| CLI Arguments Guide | 2026-10-27 | Passing arguments to scripts with *args* and parsing them with stdlib/args.tur |
| Deploying Turmeric Services to Cloudflare | 2026-10-27 | Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts). |
| CPS and the DK Continuation Machine | 2026-10-27 | How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it |
| Custom Effects Tutorial | 2026-10-27 | Writing custom effects |
| Data Literals Guide | 2026-10-27 | Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...] |
| Delimited Control Operators: shift/reset vs shift0/escape | 2026-10-27 | How shift/reset, shift0/reset0, call/cc, and escape differ -- prompt re-installation, where the captured value returns, and which to reach for |
| Dynamic Vars Guide | 2026-10-27 | Thread-local, dynamically-scoped mutable cells with defdynamic and binding |
| ECS Storage Guide -- Dense, Sparse, Tag | 2026-10-27 | How tur-ecs's three component-storage backends -- Dense, Sparse, Tag -- differ in layout, cost, and ergonomics; when to pick each; how StorageOps unifies them; and how the Sized* variants thread a capacity through the type. |
| Effects vs. Monads | 2026-10-27 | When to reach for an effect handler and when to reach for a monad value |
| Error Handling Guide | 2026-10-27 | Result, Option, panic, contract macros (assert!, require!, ensure!) |
| libturi -- C Embedding API Reference | 2026-10-27 | C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a |
| Existential Types | 2026-10-27 | Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries |
Fat-Closure Annotation Guide (^fat) | 2026-10-27 | When and why to mark function-typed parameters and return positions ^fat, and what breaks without it |
| Files and Processes | 2026-10-27 | Read and write files, walk directories, manage symlinks and permissions, read stdin line by line, run child processes, handle signals, speak TCP and work with calendar dates through the typed fs / io / process / net / time / os stdlib -- every failure is a (Result T IoError) |
| Function Arity Style Guide | 2026-10-27 | When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each |
| GADTs Cookbook | 2026-10-27 | GADTs cookbook: practical patterns and recipes |
| Generators and Lazy Sequences Guide | 2026-10-27 | Zero-overhead generators with gen/yield, lazy Seq combinators, and the Range type |
| HAMT Guide | 2026-10-27 | Persistent hash maps with structural sharing (HAMT) |
| Higher-Kinded Types | 2026-10-27 | Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model) |
| Higher-Ranked Types | 2026-10-27 | Higher-ranked types: rank-2/3 polymorphic function parameters |
| HTTPD Async Guide | 2026-10-27 | Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop |
| HTTP Server with stdlib/httpd | 2026-10-27 | Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive |
| HTTP Middleware Catalog (stdlib/httpd) | 2026-10-27 | Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files, security headers, request ids, trusted proxies, ETags, timeouts -- plus the request-attribute side channel and the composition helpers. |
| HTTPS with stdlib/httpd + tur-tls | 2026-10-27 | How to terminate TLS on an httpd-new server using the tur-tls spice |
| Application Image Dumps | 2026-10-27 | Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style. |
| JSON Guide | 2026-10-27 | Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON |
| Semigroups, Monoids, and Lattices | 2026-10-27 | The algebraic combining vocabulary in stdlib/typeclass-lattice.tur -- Semigroup, Monoid, the join/meet lattice classes, the selection newtypes that carry them, mconcat, and the law predicates. |
| Logic Programming Guide | 2026-10-27 | Backtracking, logic programming, constraint solving with cloneable continuations |
| Operators | 2026-10-27 | Arithmetic, comparison, logical and bitwise operators -- which types each takes, how integers wrap and divide, and the float-only forms |
| Package Management Guide (Spice) | 2026-10-27 | Creating projects, adding spices, build.tur, tur.lock, CLI reference |
| Approaches to Polymorphism | 2026-10-27 | A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for |
| Quickstart | 2026-10-27 | Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects |
| Range Reader Shorthand Plan | 2026-10-27 | Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time |
| Interactive REPL Tutorial | 2026-10-27 | 22-step interactive tutorial to follow at tur repl or the web REPL |
| Sized Primitive Types | 2026-10-27 | Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting |
| Sized Types | 2026-10-27 | Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations |
| tur-stats Guide | 2026-10-27 | Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes |
| STM Guide | 2026-10-27 | Software transactional memory -- API reference and mechanics |
| Software Transactional Memory (STM) Tutorial | 2026-10-27 | STM tutorial: concepts, patterns, and worked examples |
| Strings Guide | 2026-10-27 | The three string tiers -- borrowed cstr, borrowed str view, and owned refcounted String -- which to reach for, #s"..." literals, zero-copy StringSlice, the lifetime rules, and the dangling-pointer pitfalls |
| Turmeric Style Guide | 2026-10-27 | Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style |
| Symbols Guide | 2026-10-27 | First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table |
| Syntax Guide | 2026-10-27 | How to read and write Turmeric -- s-expression and sweet-expression syntax |
| Tourist Web Stack End-to-End | 2026-10-27 | Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together |
| tur/logic -- Logic Programming Guide | 2026-10-27 | How to use and extend tur/logic for miniKanren-style relational programming in Turmeric |
| tur-watch Guide | 2026-10-27 | Cross-platform filesystem watching with debounce and coalescing for CLI tools |
| Type Annotation Syntax | 2026-10-27 | Compound type annotation syntax: (-> a b), (vec T), forall, and more |
| Typeclass Guide | 2026-10-27 | Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations. |
| Typeclass Dictionary Internals | 2026-10-27 | How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how definstance lowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics. |
| Web Stack Guide | 2026-10-27 | Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric |
| WebSockets | 2026-10-27 | Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices |
| AI Assistant Integration Guide | 2026-10-26 | Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot |
| Async/Await Guide | 2026-10-26 | Async/await with fibers and delimited continuations |
| Autodoc Guide | 2026-10-26 | Writing ;;; docstrings and generating API docs with tools/gendocs.py |
| Checkpointing and Persistent Workflows | 2026-10-26 | Cloneable continuations for persistent workflows and checkpointing |
| Contract Types Guide | 2026-10-26 | Contract types: #refine{ x : T | p }, :pre/:post annotations, FFI contracts |
| Currying Guide | 2026-10-26 | Haskell-style partial application and over-application of Turmeric functions |
| Datalog Tutorial Pt. 3: Query API | 2026-10-26 | Create a database and a query system to go with it |
| Debugging Turmeric Programs | 2026-10-26 | Finding out why a program does not compile, panics, crashes or prints the wrong thing -- reading diagnostics, tur explain, the tur debug stepper, editor debugging over DAP, tur build --debug under lldb/gdb, sanitizers for inline C, and tur demangle |
| Dev Container | 2026-10-26 | Running Turmeric development in a devcontainer from VS Code or the CLI |
| Diagnosing the Compiler | 2026-10-26 | How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures |
| Diagnostics Internals | 2026-10-26 | How the compiler reports errors and warnings -- the DiagCode enum and its four tables, the diag_emit family, spans through sweet-exp, macros and loaded files, the terminal/JSON/LSP/embed sinks, tur explain, the errors/ fixture harness, and a checklist for adding a code |
| ECS Guide | 2026-10-26 | Building games and simulations with tur-ecs and the tur-ecs-raylib companion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop. |
| ECS -- tur-ecs vs apecs vs aztecs | 2026-10-26 | A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land. |
| Frame Guide | 2026-10-26 | In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface |
| Godot Binding Guide | 2026-10-26 | Attaching .tur scripts to Godot 4 nodes -- install, the curated and generated ClassDB facades, typed godot-call variants, value marshalling, the editor plugin and debugger, AOT mode, and the known gaps |
| Wiring a ResourceFormatLoader for the Turmeric/Godot Binding | 2026-10-26 | Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline |
| Loop Invariants Guide | 2026-10-26 | Proving loop properties with :invariant annotations on while loops |
| Language Server (LSP) Guide | 2026-10-26 | Configuring editors to use the Turmeric language server for diagnostics |
| Markdown Guide | 2026-10-26 | Parse CommonMark and GitHub Flavored Markdown into a document tree with tur/markdown, render it as HTML, walk its blocks and inlines, and what is implemented so far |
| MiniKanren Part 1: Relations and Queries | 2026-10-26 | Logic programming with miniKanren -- relations, composition, and bidirectional queries |
| Using Turmeric with mise or asdf | 2026-10-26 | Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf) |
| Name Mangling Guide | 2026-10-26 | How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies. |
| Notebook Guide | 2026-10-26 | Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode |
| Parser Combinators Tutorial | 2026-10-26 | Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching |
| Regular Expressions Guide | 2026-10-26 | Pure-Turmeric POSIX ERE regex engine -- compile, match, find, and replace |
| Release Process | 2026-10-26 | How Turmeric releases are cut -- the three cut-*-release commands, their shared nine-step flow, the ordering constraints that make a failed cut recoverable, and what the release workflow does once the tag is pushed. |
| Releases and Installation | 2026-10-26 | How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release. |
| tur repl -- REPL Reference | 2026-10-26 | Reference guide for the tur repl interactive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration |
| Type-Level Rows | 2026-10-26 | The #row{...} reader form and the kind-[*] row type -- writing rows, row-kinded (^&) parameters, the row algebra (concat/union/intersect/canon), erasure, and what rows deliberately cannot do |
| The Runtime Preamble and Its Linkage | 2026-10-26 | Where the C runtime every compiled program needs comes from -- the emitted preamble, its feature gates and linkage postures, the runtime archives, the S2 split runtime and its generator, tur_tls.c -- which copy each build path links, and how to change any of it without silently losing the fast path |
| Sandboxing Guide | 2026-10-26 | Restricting Turmeric code inside a C host with turi_env_new_sandboxed, capability flags, the native classification table, and resource limits -- and the memory-safety gap that keeps it from being a boundary against hostile code |
| Security Guide | 2026-10-26 | What Turmeric promises to handle safely -- the trust boundary for each input, the promise made at it, and where the implementation does not yet keep that promise |
| Serializable Continuations Guide | 2026-10-26 | Serializable continuations for persistent workflows and cross-process computation |
| Working through SICP with Turmeric | 2026-10-26 | Run the code from Structure and Interpretation of Computer Programs in Turmeric's Scheme dialect: installing, the interpreter and the REPL, the few definitions the book assumes, chapter-by-chapter notes, and the rough edges to know about. |
| Snake Game Tutorial | 2026-10-26 | Building the snake game example |
| Stateful Refinements | 2026-10-26 | Refining predicates over mutable state -- the frozen region and the #reads w annotation that grants congruence, why a trusted annotation is sound here, and how the guarded crossings codegen |
| Test Runner Contract | 2026-10-26 | Test framework API and contract |
| Thread Pool | 2026-10-26 | Bounded POSIX worker-thread pool with back-pressure for fan-out work over ptr<void> items |
Time-Travel Tracing Guide (tur trace) | 2026-10-26 | Recording an interpreted run and scrubbing it -- what the .turtrace format holds, what the step cap protects, and how tur dap replays a recording so a debugger can step backwards |
| Tourist Routing Composition | 2026-10-26 | Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications |
tur compile and tur link | 2026-10-26 | Splitting the monolithic tur build into a cacheable object compile plus a cheap link -- tur compile, tur link, --split-build, and how --runtime= decides the way the runtime gets linked |
| Tur New Guide | 2026-10-26 | Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI |
| Tur Run Guide | 2026-10-26 | Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just |
| tur serve | 2026-10-26 | Serve a directory over HTTP with tur serve, the Turmeric spelling of python3 -m http.server |
Turmeric Version Manager (tvm) | 2026-10-26 | Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager. |
| Union and Intersection Types Guide | 2026-10-26 | Union (A | B) and intersection (A & B) types, any, gradual typing |
| Unsafe Code | 2026-10-26 | The (unsafe ...) block, raw pointers and raw memory, bit reinterpretation, and when to reach for something safer |
| Using a Turmeric Library from CMake | 2026-10-26 | How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using tur emit-cmake |
| Vim Guide | 2026-10-26 | Vim / Neovim syntax highlighting installation and configuration |
| VS Code Extension | 2026-10-26 | VS Code extension installation and configuration |
| Web Continuations Guide | 2026-10-26 | Compact reference: one continuation per page, the continuation store, routing model |
| Web Continuations Tutorial | 2026-10-26 | Multi-page web forms using serializable continuations (guestbook example) |
| Building for the Web with Emscripten | 2026-10-26 | Compile a Turmeric project to WebAssembly and run it in a browser |
| Bibliography | 2026-08-20 | Academic papers, theses, and technical references cited across Turmeric design documents and guides |
Advanced Control Flow
- Backtrackable State Guide -- Trailed mutable cells from
stdlib/trail.tur-- take a mark, mutate freely, then undo or keep the writes; scopes, theBtcapability, and why a search loop wants this instead of a persistent structure - Backtracking Guide -- Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur
- Checkpointing and Persistent Workflows -- Cloneable continuations for persistent workflows and checkpointing
- Delimited Control Operators: shift/reset vs shift0/escape -- How shift/reset, shift0/reset0, call/cc, and escape differ -- prompt re-installation, where the captured value returns, and which to reach for
- Effects System Guide -- Algebraic effects, dependency injection, custom control flow
- Logic Programming Guide -- Backtracking, logic programming, constraint solving with cloneable continuations
- Serializable Continuations Guide -- Serializable continuations for persistent workflows and cross-process computation
- State Machines Guide -- Five different approaches to modeling state machines in turmeric
- tur/logic -- Logic Programming Guide -- How to use and extend tur/logic for miniKanren-style relational programming in Turmeric
- Web Continuations Guide -- Compact reference: one continuation per page, the continuation store, routing model
Advanced Types
- Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped
- Existential Types -- Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries
- GADTs Cookbook -- GADTs cookbook: practical patterns and recipes
- GADTs -- A Practical Guide -- GADTs: refined constructors (
defdatawith: Result), type refinement, equality witnesses, union types, gradual typing - Opaque Types (
defopaque) -- Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines
CLI Tools
- Autodoc Guide -- Writing
;;;docstrings and generating API docs withtools/gendocs.py - Compiler Flags -- Diagnostic and debug flags accepted by
tur; list of removed-Xfeature flags - Experimental Feature Flags -- The
--enable=<name>surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and thetur experimentscommand. - Application Image Dumps -- Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style.
- Offline Docs Guide -- How the guides and API reference reach you without a network -- the docs pack, Try Turmeric's in-app docs browser, and the
tur doc/tur docscommands - Test Runner Contract -- Test framework API and contract
tur compileandtur link-- Splitting the monolithictur buildinto a cacheable object compile plus a cheap link --tur compile,tur link,--split-build, and how--runtime=decides the way the runtime gets linked- Tur New Guide -- Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI
- Tur Run Guide -- Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just
- tur serve -- Serve a directory over HTTP with
tur serve, the Turmeric spelling ofpython3 -m http.server - tur-watch Guide -- Cross-platform filesystem watching with debounce and coalescing for CLI tools
- Turmeric Version Manager (
tvm) -- Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager.
Compiler Internals
- The Build Driver -- How the
turdriver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, howccis chosen and invoked,tur runand project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables - Compiler Internals -- The map of the tur compiler -- the pipeline and pass schedule, the src/ layout, and one paragraph per subsystem with a link to its deep-dive guide; the entry point for contributors
- CPS and the DK Continuation Machine -- How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it
- Diagnostics Internals -- How the compiler reports errors and warnings -- the DiagCode enum and its four tables, the diag_emit family, spans through sweet-exp, macros and loaded files, the terminal/JSON/LSP/embed sinks, tur explain, the errors/ fixture harness, and a checklist for adding a code
- Effect Rows (internals) -- How effect rows are represented, parsed, inferred and checked -- the EffectRow kinds, the EffectEnv registry, the elaborator's effect checks, the effect-row pass and its fixpoint, capabilities and Unsafe, --dump-effects, and where codegen reads the rows
- Elaborator Internals -- How the elaborator turns reader Forms into the typed Expr IR -- the Elab state and scope model, the two-pass top-level driver and the synthesized main, call-site-local type inference, the Expr and Type data model, what the elaborator records for later passes, incremental sessions, macros, and the checklist for adding a form
- Who Frees What in Emitted Code -- How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak
- C Emitter Architecture -- How the C emitter turns an elaborated program into one translation unit -- the emit_value/emit_stmt contract, EmitCtx, the phase order of emit_program, ABI specializations, the side tables call sites consult, inline C, function definitions, and how to add an emit arm
- Garbage Collection -- How memory is managed in Turmeric -- reference counting, the Bacon-Rajan cycle collector, arenas, and what is (and isn't) GC-managed in the compiled and interpreted paths
- Name Mangling Guide -- How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies.
- Ownership Guide -- Which ownership strategy to reach for -- persistent-immutable, single-owner mutable, linear/affine handles, rc<T> for genuine sharing, and weak<T> to break the resulting cycles
- Package Manager Internals -- How tur reads build.tur, resolves :spices and workspace siblings, writes and honours tur.lock, generates and consumes the :cmake-deps CMake project, and threads :build-opts into the C compile -- with the traps each stage leaves for spice authors
- How #lang r7rs Is Implemented -- How a #lang r7rs file becomes a Turmeric program -- dialect selection, the Scheme-to-Turmeric lowering and its rename table, the value representation, libraries and the split build, call/cc and the dynamic environment, the conservative collector, SRFIs, and the harnesses that cover them
- Refinement Solver Internals -- How the compiler proves a refinement predicate at compile time -- the obligation pipeline, the normalized verification condition, the staged in-house solver (no SMT dependency), memoization, caps, and how to debug an obligation
- Regions (RM3) Internals -- How region brackets work on the compiled path -- arena generations, rewind vs retire, the static walk and the runtime escape note, the store-hook rule and every place it is applied, the CPS and call/cc interactions, and the tools that tell a rewind from a retire
- The Runtime Preamble and Its Linkage -- Where the C runtime every compiled program needs comes from -- the emitted preamble, its feature gates and linkage postures, the runtime archives, the S2 split runtime and its generator, tur_tls.c -- which copy each build path links, and how to change any of it without silently losing the fast path
- Separate Compilation and Module Loading -- How the compiler finds, loads and resolves modules, which builds split a program into one C translation unit per module, what goes into each module's .h and .c, who owns a generic specialization or an instance across TUs, and how to read the link errors when the split goes wrong
- The turi Interpreter (internals) -- How the tree-walking interpreter works -- its entry points, the shared front end it runs, value and frame representations, the explicit-stack driver, native overrides and inline-C, the two effect runtimes, what memory it gives back and what it keeps, process-global hazards, and how to add a form or native
- turi <-> tur Parity Guide -- Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable.
- Type Erasure to int64_t -- Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses
- Typeclass Dictionary Internals -- How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how
definstancelowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics. - Value Representations -- Every representation a Turmeric value can travel in, the boundaries where the compiler must bridge between them, and the failure shapes -- cc errors, link errors, segfaults -- when a bridge is missing
Concurrency and Async
- Async/Await Guide -- Async/await with fibers and delimited continuations
- Channels and Select Guide -- Buffered channels for inter-fiber communication and multi-channel select
- Dynamic Vars Guide -- Thread-local, dynamically-scoped mutable cells with defdynamic and binding
- Reactor Guide -- Lightweight evented I/O with tur/reactor
- Session Types Guide -- Model protocols as types, whether the protocol has two participants, or more
- STM Guide -- Software transactional memory -- API reference and mechanics
- Software Transactional Memory (STM) Tutorial -- STM tutorial: concepts, patterns, and worked examples
- Structured Concurrency Guide -- TaskGroup for scoped task spawning and Future/Promise for asynchronous results
- Thread Pool -- Bounded POSIX worker-thread pool with back-pressure for fan-out work over ptr<void> items
- Threading and Concurrency Primitives Guide -- OS threads,
Arc<T>,Mutex<T>,Atomic<T>, channels
Contributor Notes
- Diagnosing the Compiler -- How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures
- JIT Execution Engine Guide (
tur jit) -- How the in-process MIR JIT is built -- what MIR is, how the engine is wired into this project, and what it does differently from the cc path (the fallback contract, the permanent constraints, and the inline-C rules that only bite under the JIT) - Release Process -- How Turmeric releases are cut -- the three cut-*-release commands, their shared nine-step flow, the ordering constraints that make a failed cut recoverable, and what the release workflow does once the tag is pushed.
- Running the Tests -- Which harness runs what, how to narrow a run to the tests you care about, the fixture marker files, and how to reproduce a red CI job locally
- Test Suite Portability & Performance Guide -- macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses
Data Structures and Libraries
- ECS Guide -- Building games and simulations with
tur-ecsand thetur-ecs-raylibcompanion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop. - ECS Storage Guide -- Dense, Sparse, Tag -- How
tur-ecs's three component-storage backends --Dense,Sparse,Tag-- differ in layout, cost, and ergonomics; when to pick each; howStorageOpsunifies them; and how theSized*variants thread a capacity through the type. - ECS -- tur-ecs vs apecs vs aztecs -- A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land.
- Files and Processes -- Read and write files, walk directories, manage symlinks and permissions, read stdin line by line, run child processes, handle signals, speak TCP and work with calendar dates through the typed fs / io / process / net / time / os stdlib -- every failure is a (Result T IoError)
- Frame Guide -- In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface
- HAMT Guide -- Persistent hash maps with structural sharing (HAMT)
- JSON Guide -- Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON
- Markdown Guide -- Parse CommonMark and GitHub Flavored Markdown into a document tree with
tur/markdown, render it as HTML, walk its blocks and inlines, and what is implemented so far - Parsec Reference Guide -- Reference for the stdlib parser-combinator library tur/parsec -- core types, primitive parsers, sequencing, choice, repetition, optional values, mapping, runners, and common patterns
- Regular Expressions Guide -- Pure-Turmeric POSIX ERE regex engine -- compile, match, find, and replace
- Runtime Schema Validation -- Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors.
- tur-stats Guide -- Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes
Editor and IDE
- AI Assistant Integration Guide -- Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot
- Dev Container -- Running Turmeric development in a devcontainer from VS Code or the CLI
- Formatter Guide --
tur formatCLI and web REPL Format button - Language Server (LSP) Guide -- Configuring editors to use the Turmeric language server for diagnostics
- Notebook Guide -- Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode
- Time-Travel Tracing Guide (
tur trace) -- Recording an interpreted run and scrubbing it -- what the .turtrace format holds, what the step cap protects, and howtur dapreplays a recording so a debugger can step backwards - Vim Guide -- Vim / Neovim syntax highlighting installation and configuration
- VS Code Extension -- VS Code extension installation and configuration
Error Handling
- Contract Types Guide -- Contract types:
#refine{ x : T | p },:pre/:postannotations, FFI contracts - Error Handling Guide --
Result,Option,panic, contract macros (assert!,require!,ensure!)
Functional Patterns
- Arrows and Signal Processing -- Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/
- Effects vs. Monads -- When to reach for an effect handler and when to reach for a monad value
- Generators and Lazy Sequences Guide -- Zero-overhead generators with
gen/yield, lazySeqcombinators, and theRangetype - Semigroups, Monoids, and Lattices -- The algebraic combining vocabulary in stdlib/typeclass-lattice.tur -- Semigroup, Monoid, the join/meet lattice classes, the selection newtypes that carry them, mconcat, and the law predicates.
- Lens Guide -- First-class functional lenses (view / set / over) via stdlib/lens.tur, which ships the profunctor-by-record encoding. The classic van Laarhoven form is also expressible by hand.
- Zipper Guide -- Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor).
Getting Started
- Introducing Saffron -- A first tour of Saffron, the dynamically typed dialect of Turmeric: Try Turmeric in the browser, printing, flow control, functions, ADTs, typeclasses, and algebraic effects -- every example in both s-expression and sweet-expression syntax.
- Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
- R7RS Scheme -- #lang r7rs -- #lang r7rs runs R7RS-small Scheme on the Turmeric compiler and runtime, compiled or interpreted, and lets Scheme and Turmeric modules import each other. This guide covers getting started, what is there, how it differs from the standard, and the tooling.
- Releases and Installation -- How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release.
- tur repl -- REPL Reference -- Reference guide for the
tur replinteractive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration - Interactive REPL Tutorial -- 22-step interactive tutorial to follow at
tur replor the web REPL - Saffron -- the dynamically typed dialect -- #lang saffron makes
anythe default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up. - Syntax Guide -- How to read and write Turmeric -- s-expression and sweet-expression syntax
Integration / Godot
- Godot Binding Guide -- Attaching
.turscripts to Godot 4 nodes -- install, the curated and generated ClassDB facades, typedgodot-callvariants, value marshalling, the editor plugin and debugger, AOT mode, and the known gaps - Wiring a ResourceFormatLoader for the Turmeric/Godot Binding -- Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline
Interoperability
- C Integration Guide -- Foreign function interface (FFI) and C interop
- libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
- Dynamic FFI -- Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine
- Returning
Result/Optionfrom Inline-C -- Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int - Sandboxing Guide -- Restricting Turmeric code inside a C host with turi_env_new_sandboxed, capability flags, the native classification table, and resource limits -- and the memory-safety gap that keeps it from being a boundary against hostile code
- Unsafe Code -- The (unsafe ...) block, raw pointers and raw memory, bit reinterpretation, and when to reach for something safer
Language Basics
- Binding Forms Guide -- def in a body, letrec, and named-let -- the three local binding idioms that complement let and defn
- CLI Arguments Guide -- Passing arguments to scripts with
*args*and parsing them withstdlib/args.tur - Currying Guide -- Haskell-style partial application and over-application of Turmeric functions
- Data Literals Guide -- Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...]
- Fat-Closure Annotation Guide (
^fat) -- When and why to mark function-typed parameters and return positions^fat, and what breaks without it - Function Arity Style Guide -- When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each
- Macros Guide --
defmacroas a compile-time function from syntax to syntax -- quasiquote and splicing, manual hygiene, proceduraldefmacro*, macro-time imports, and why an expansion is type checked exactly like hand-written code - Module System Guide -- Module system, namespacing, exports
- Mutable Globals Guide -- def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover
- Numeric Tower Guide -- Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading
- Operators -- Arithmetic, comparison, logical and bitwise operators -- which types each takes, how integers wrap and divide, and the float-only forms
- Range Reader Shorthand Plan -- Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time
- Reader Forms Reference -- Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions
- Strings Guide -- The three string tiers -- borrowed
cstr, borrowedstrview, and owned refcountedString-- which to reach for,#s"..."literals, zero-copyStringSlice, the lifetime rules, and the dangling-pointer pitfalls - Structs -- Defining and using struct types with
defstruct - Sum Types and
Either-- Declaring binary and n-ary sum types withdefdata, pattern matching withmatch, exhaustiveness behaviour and the^non-exhaustiveopt-out, the FFI layout, and the stdlibEithermodule. - Symbols Guide -- First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table
- Typing Handles, Callbacks, and Results -- Avoiding
:intStand-Ins -- How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit.
Networking and Web
- Deploying Turmeric Services to Cloudflare -- Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts).
- HTTPD Async Guide -- Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop
- HTTP Server with stdlib/httpd -- Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive
- HTTP Middleware Catalog (stdlib/httpd) -- Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files, security headers, request ids, trusted proxies, ETags, timeouts -- plus the request-attribute side channel and the composition helpers.
- HTTPS with stdlib/httpd + tur-tls -- How to terminate TLS on an httpd-new server using the tur-tls spice
- Tourist Routing Composition -- Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications
- Tourist Session Middleware -- Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file)
- Tourist Web Stack End-to-End -- Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together
- Web Stack Guide -- Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric
- WebSockets -- Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices
Package Management
- Consuming Spices Guide -- Adding, fetching, and using spice packages in a Turmeric project
- Developing Spices Guide -- Creating, testing, and publishing Turmeric spice packages
- Using Turmeric with mise or asdf -- Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf)
- Package Management Guide (Spice) -- Creating projects, adding spices,
build.tur,tur.lock, CLI reference - Using a Turmeric Library from CMake -- How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using
tur emit-cmake
Performance
- Memory Usage Guide -- What each language feature costs in heap memory, measured -- scalars, structs, sums, lists, Vec, MutableMap, Map, String, rc, closures, function-value calls, effects and regions -- what frees it, and strategies for using less
- Monomorphization ABI Guide -- How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read
__spec_*symbols in error messages, and what the small residual ABI bridge does. - Performance Guide -- Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology
Reference
- Bibliography -- Academic papers, theses, and technical references cited across Turmeric design documents and guides
- Turmeric Style Guide -- Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style
Refinement Types
- Loop Invariants Guide -- Proving loop properties with :invariant annotations on while loops
Security
- Security Guide -- What Turmeric promises to handle safely -- the trust boundary for each input, the promise made at it, and where the implementation does not yet keep that promise
Troubleshooting
- Debugging Turmeric Programs -- Finding out why a program does not compile, panics, crashes or prints the wrong thing -- reading diagnostics,
tur explain, thetur debugstepper, editor debugging over DAP,tur build --debugunder lldb/gdb, sanitizers for inline C, andtur demangle
Tutorials
- Cellular Automata with Comonads -- Cellular automata with comonads
- Custom Effects Tutorial -- Writing custom effects
- Datalog Tutorial Pt. 1: Concepts -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 2: Minimal Implementation -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 3: Query API -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 4: Indexing -- Create a database and a query system to go with it
- MiniKanren Part 1: Relations and Queries -- Logic programming with miniKanren -- relations, composition, and bidirectional queries
- Parsec Tutorial -- A step-by-step introduction to the stdlib parser-combinator library tur/parsec -- characters, sequencing with do-m, choice, repetition, optional pieces, and mapping results into real values
- Parser Combinators Tutorial -- Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching
- Working through SICP with Turmeric -- Run the code from Structure and Interpretation of Computer Programs in Turmeric's Scheme dialect: installing, the interpreter and the REPL, the few definitions the book assumes, chapter-by-chapter notes, and the rough edges to know about.
- Snake Game Tutorial -- Building the snake game example
- Web Continuations Tutorial -- Multi-page web forms using serializable continuations (guestbook example)
- Building for the Web with Emscripten -- Compile a Turmeric project to WebAssembly and run it in a browser
Type Safety
- Borrow Checking and Lifetimes Guide -- How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report
- Refinement Types --
#refine{ x : T | p }predicates the compiler tries to prove statically, emitting a runtime check only where the proof fails -- the predicate language, named refinements, diagnostics, and the documented limits - Stateful Refinements -- Refining predicates over mutable state -- the
frozenregion and the#reads wannotation that grants congruence, why a trusted annotation is sound here, and how the guarded crossings codegen - Substructural Types --
^linear,^affine,^relevanttype disciplines - Uniqueness Types --
^unique: at-most-one-reference ownership
Type System
- Higher-Kinded Types -- Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model)
- Higher-Ranked Types -- Higher-ranked types: rank-2/3 polymorphic function parameters
- Approaches to Polymorphism -- A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for
- Type-Level Rows -- The
#row{...}reader form and the kind-[*]row type -- writing rows, row-kinded (^&) parameters, the row algebra (concat/union/intersect/canon), erasure, and what rows deliberately cannot do - Sized Primitive Types -- Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting
- Sized Types -- Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations
- Type Annotation Syntax -- Compound type annotation syntax:
(-> a b),(vec T),forall, and more - Typeclass Guide -- Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations.
- Union and Intersection Types Guide -- Union (
A | B) and intersection (A & B) types,any, gradual typing
abi 5
- C Emitter Architecture -- How the C emitter turns an elaborated program into one translation unit -- the emit_value/emit_stmt contract, EmitCtx, the phase order of emit_program, ABI specializations, the side tables call sites consult, inline C, function definitions, and how to add an emit arm
- Fat-Closure Annotation Guide (
^fat) -- When and why to mark function-typed parameters and return positions^fat, and what breaks without it - Monomorphization ABI Guide -- How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read
__spec_*symbols in error messages, and what the small residual ABI bridge does. - Type Erasure to int64_t -- Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses
- Value Representations -- Every representation a Turmeric value can travel in, the boundaries where the compiler must bridge between them, and the failure shapes -- cc errors, link errors, segfaults -- when a bridge is missing
async 4
- Async/Await Guide -- Async/await with fibers and delimited continuations
- HTTPD Async Guide -- Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop
- Reactor Guide -- Lightweight evented I/O with tur/reactor
- Structured Concurrency Guide -- TaskGroup for scoped task spawning and Future/Promise for asynchronous results
backtracking 3
- Backtrackable State Guide -- Trailed mutable cells from
stdlib/trail.tur-- take a mark, mutate freely, then undo or keep the writes; scopes, theBtcapability, and why a search loop wants this instead of a persistent structure - Backtracking Guide -- Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur
- Logic Programming Guide -- Backtracking, logic programming, constraint solving with cloneable continuations
build-system 11
tur compileandtur link-- Splitting the monolithictur buildinto a cacheable object compile plus a cheap link --tur compile,tur link,--split-build, and how--runtime=decides the way the runtime gets linked- Developing Spices Guide -- Creating, testing, and publishing Turmeric spice packages
- Package Management Guide (Spice) -- Creating projects, adding spices,
build.tur,tur.lock, CLI reference - Package Manager Internals -- How tur reads build.tur, resolves :spices and workspace siblings, writes and honours tur.lock, generates and consumes the :cmake-deps CMake project, and threads :build-opts into the C compile -- with the traps each stage leaves for spice authors
- Separate Compilation and Module Loading -- How the compiler finds, loads and resolves modules, which builds split a program into one C translation unit per module, what goes into each module's .h and .c, who owns a generic specialization or an instance across TUs, and how to read the link errors when the split goes wrong
- Snake Game Tutorial -- Building the snake game example
- The Build Driver -- How the
turdriver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, howccis chosen and invoked,tur runand project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables - The Runtime Preamble and Its Linkage -- Where the C runtime every compiled program needs comes from -- the emitted preamble, its feature gates and linkage postures, the runtime archives, the S2 split runtime and its generator, tur_tls.c -- which copy each build path links, and how to change any of it without silently losing the fast path
- Tur New Guide -- Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI
- Tur Run Guide -- Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just
- Using a Turmeric Library from CMake -- How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using
tur emit-cmake
caching 2
tur compileandtur link-- Splitting the monolithictur buildinto a cacheable object compile plus a cheap link --tur compile,tur link,--split-build, and how--runtime=decides the way the runtime gets linked- The Build Driver -- How the
turdriver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, howccis chosen and invoked,tur runand project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables
channels 2
- Channels and Select Guide -- Buffered channels for inter-fiber communication and multi-channel select
- Session Types Guide -- Model protocols as types, whether the protocol has two participants, or more
codegen 11
- C Emitter Architecture -- How the C emitter turns an elaborated program into one translation unit -- the emit_value/emit_stmt contract, EmitCtx, the phase order of emit_program, ABI specializations, the side tables call sites consult, inline C, function definitions, and how to add an emit arm
- CPS and the DK Continuation Machine -- How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it
- How #lang r7rs Is Implemented -- How a #lang r7rs file becomes a Turmeric program -- dialect selection, the Scheme-to-Turmeric lowering and its rename table, the value representation, libraries and the split build, call/cc and the dynamic environment, the conservative collector, SRFIs, and the harnesses that cover them
- Monomorphization ABI Guide -- How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read
__spec_*symbols in error messages, and what the small residual ABI bridge does. - Name Mangling Guide -- How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies.
- Regions (RM3) Internals -- How region brackets work on the compiled path -- arena generations, rewind vs retire, the static walk and the runtime escape note, the store-hook rule and every place it is applied, the CPS and call/cc interactions, and the tools that tell a rewind from a retire
- The Runtime Preamble and Its Linkage -- Where the C runtime every compiled program needs comes from -- the emitted preamble, its feature gates and linkage postures, the runtime archives, the S2 split runtime and its generator, tur_tls.c -- which copy each build path links, and how to change any of it without silently losing the fast path
- Type Erasure to int64_t -- Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses
- Typeclass Dictionary Internals -- How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how
definstancelowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics. - Value Representations -- Every representation a Turmeric value can travel in, the boundaries where the compiler must bridge between them, and the failure shapes -- cc errors, link errors, segfaults -- when a bridge is missing
- Who Frees What in Emitted Code -- How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak
collections 4
- Data Literals Guide -- Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...]
- Generators and Lazy Sequences Guide -- Zero-overhead generators with
gen/yield, lazySeqcombinators, and theRangetype - HAMT Guide -- Persistent hash maps with structural sharing (HAMT)
- Sized Types -- Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations
comparison 4
- Approaches to Polymorphism -- A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for
- ECS -- tur-ecs vs apecs vs aztecs -- A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land.
- Effects vs. Monads -- When to reach for an effect handler and when to reach for a monad value
- State Machines Guide -- Five different approaches to modeling state machines in turmeric
compiler-flags 3
- Compiler Flags -- Diagnostic and debug flags accepted by
tur; list of removed-Xfeature flags - Experimental Feature Flags -- The
--enable=<name>surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and thetur experimentscommand. - The Build Driver -- How the
turdriver turns a command line into a binary -- command dispatch and the global-flag parsers, the compile entry points and the real pass schedule, howccis chosen and invoked,tur runand project mode, every cache and what invalidates it, the build-directory ladder, and the driver's environment variables
composition 3
- Arrows and Signal Processing -- Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/
- Lens Guide -- First-class functional lenses (view / set / over) via stdlib/lens.tur, which ships the profunctor-by-record encoding. The classic van Laarhoven form is also expressible by hand.
- Parser Combinators Tutorial -- Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching
continuations 10
- Application Image Dumps -- Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style.
- Async/Await Guide -- Async/await with fibers and delimited continuations
- Checkpointing and Persistent Workflows -- Cloneable continuations for persistent workflows and checkpointing
- CPS and the DK Continuation Machine -- How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it
- Delimited Control Operators: shift/reset vs shift0/escape -- How shift/reset, shift0/reset0, call/cc, and escape differ -- prompt re-installation, where the captured value returns, and which to reach for
- Effects System Guide -- Algebraic effects, dependency injection, custom control flow
- Logic Programming Guide -- Backtracking, logic programming, constraint solving with cloneable continuations
- Serializable Continuations Guide -- Serializable continuations for persistent workflows and cross-process computation
- Web Continuations Guide -- Compact reference: one continuation per page, the continuation store, routing model
- Web Continuations Tutorial -- Multi-page web forms using serializable continuations (guestbook example)
contributing 6
- Compiler Internals -- The map of the tur compiler -- the pipeline and pass schedule, the src/ layout, and one paragraph per subsystem with a link to its deep-dive guide; the entry point for contributors
- Diagnosing the Compiler -- How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures
- JIT Execution Engine Guide (
tur jit) -- How the in-process MIR JIT is built -- what MIR is, how the engine is wired into this project, and what it does differently from the cc path (the fallback contract, the permanent constraints, and the inline-C rules that only bite under the JIT) - Release Process -- How Turmeric releases are cut -- the three cut-*-release commands, their shared nine-step flow, the ordering constraints that make a failed cut recoverable, and what the release workflow does once the tag is pushed.
- Running the Tests -- Which harness runs what, how to narrow a run to the tests you care about, the fixture marker files, and how to reproduce a red CI job locally
- Test Suite Portability & Performance Guide -- macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses
data-types 5
- GADTs -- A Practical Guide -- GADTs: refined constructors (
defdatawith: Result), type refinement, equality witnesses, union types, gradual typing - GADTs Cookbook -- GADTs cookbook: practical patterns and recipes
- Opaque Types (
defopaque) -- Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines - Structs -- Defining and using struct types with
defstruct - Sum Types and
Either-- Declaring binary and n-ary sum types withdefdata, pattern matching withmatch, exhaustiveness behaviour and the^non-exhaustiveopt-out, the FFI layout, and the stdlibEithermodule.
dataframes 2
- Frame Guide -- In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface
- tur-stats Guide -- Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes
datalog 4
- Datalog Tutorial Pt. 1: Concepts -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 2: Minimal Implementation -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 3: Query API -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 4: Indexing -- Create a database and a query system to go with it
debugging 3
- Debugging Turmeric Programs -- Finding out why a program does not compile, panics, crashes or prints the wrong thing -- reading diagnostics,
tur explain, thetur debugstepper, editor debugging over DAP,tur build --debugunder lldb/gdb, sanitizers for inline C, andtur demangle - Diagnosing the Compiler -- How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures
- Time-Travel Tracing Guide (
tur trace) -- Recording an interpreted run and scrubbing it -- what the .turtrace format holds, what the step cap protects, and howtur dapreplays a recording so a debugger can step backwards
diagnostics 3
- Compiler Flags -- Diagnostic and debug flags accepted by
tur; list of removed-Xfeature flags - Debugging Turmeric Programs -- Finding out why a program does not compile, panics, crashes or prints the wrong thing -- reading diagnostics,
tur explain, thetur debugstepper, editor debugging over DAP,tur build --debugunder lldb/gdb, sanitizers for inline C, andtur demangle - Diagnostics Internals -- How the compiler reports errors and warnings -- the DiagCode enum and its four tables, the diag_emit family, spans through sweet-exp, macros and loaded files, the terminal/JSON/LSP/embed sinks, tur explain, the errors/ fixture harness, and a checklist for adding a code
dialects 4
- Introducing Saffron -- A first tour of Saffron, the dynamically typed dialect of Turmeric: Try Turmeric in the browser, printing, flow control, functions, ADTs, typeclasses, and algebraic effects -- every example in both s-expression and sweet-expression syntax.
- R7RS Scheme -- #lang r7rs -- #lang r7rs runs R7RS-small Scheme on the Turmeric compiler and runtime, compiled or interpreted, and lets Scheme and Turmeric modules import each other. This guide covers getting started, what is there, how it differs from the standard, and the tooling.
- Saffron -- the dynamically typed dialect -- #lang saffron makes
anythe default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up. - Working through SICP with Turmeric -- Run the code from Structure and Interpretation of Computer Programs in Turmeric's Scheme dialect: installing, the interpreter and the REPL, the few definitions the book assumes, chapter-by-chapter notes, and the rough edges to know about.
docs 3
- Autodoc Guide -- Writing
;;;docstrings and generating API docs withtools/gendocs.py - Notebook Guide -- Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode
- Offline Docs Guide -- How the guides and API reference reach you without a network -- the docs pack, Try Turmeric's in-app docs browser, and the
tur doc/tur docscommands
ecs 3
- ECS -- tur-ecs vs apecs vs aztecs -- A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land.
- ECS Guide -- Building games and simulations with
tur-ecsand thetur-ecs-raylibcompanion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop. - ECS Storage Guide -- Dense, Sparse, Tag -- How
tur-ecs's three component-storage backends --Dense,Sparse,Tag-- differ in layout, cost, and ergonomics; when to pick each; howStorageOpsunifies them; and how theSized*variants thread a capacity through the type.
effects 7
- CPS and the DK Continuation Machine -- How the compiled path lowers effects and delimited control -- the coloring analysis, the CT-IR, the emitter's DK-threading ABI, the DK heap-continuation machine, who frees what, and the tools for debugging it
- Custom Effects Tutorial -- Writing custom effects
- Effect Rows (internals) -- How effect rows are represented, parsed, inferred and checked -- the EffectRow kinds, the EffectEnv registry, the elaborator's effect checks, the effect-row pass and its fixpoint, capabilities and Unsafe, --dump-effects, and where codegen reads the rows
- Effects System Guide -- Algebraic effects, dependency injection, custom control flow
- Effects vs. Monads -- When to reach for an effect handler and when to reach for a monad value
- Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
- State Machines Guide -- Five different approaches to modeling state machines in turmeric
embedding 3
- libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
- Sandboxing Guide -- Restricting Turmeric code inside a C host with turi_env_new_sandboxed, capability flags, the native classification table, and resource limits -- and the memory-safety gap that keeps it from being a boundary against hostile code
- turi <-> tur Parity Guide -- Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable.
ffi 7
- C Integration Guide -- Foreign function interface (FFI) and C interop
- Contract Types Guide -- Contract types:
#refine{ x : T | p },:pre/:postannotations, FFI contracts - Dynamic FFI -- Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine
- libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
- Returning
Result/Optionfrom Inline-C -- Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int - Unsafe Code -- The (unsafe ...) block, raw pointers and raw memory, bit reinterpretation, and when to reach for something safer
- Using a Turmeric Library from CMake -- How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using
tur emit-cmake
fibers 2
- Async/Await Guide -- Async/await with fibers and delimited continuations
- Channels and Select Guide -- Buffered channels for inter-fiber communication and multi-channel select
functions 4
- Binding Forms Guide -- def in a body, letrec, and named-let -- the three local binding idioms that complement let and defn
- Currying Guide -- Haskell-style partial application and over-application of Turmeric functions
- Fat-Closure Annotation Guide (
^fat) -- When and why to mark function-typed parameters and return positions^fat, and what breaks without it - Function Arity Style Guide -- When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each
game-development 5
- Cellular Automata with Comonads -- Cellular automata with comonads
- ECS Guide -- Building games and simulations with
tur-ecsand thetur-ecs-raylibcompanion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop. - Godot Binding Guide -- Attaching
.turscripts to Godot 4 nodes -- install, the curated and generated ClassDB facades, typedgodot-callvariants, value marshalling, the editor plugin and debugger, AOT mode, and the known gaps - Snake Game Tutorial -- Building the snake game example
- Wiring a ResourceFormatLoader for the Turmeric/Godot Binding -- Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline
godot 2
- Godot Binding Guide -- Attaching
.turscripts to Godot 4 nodes -- install, the curated and generated ClassDB facades, typedgodot-callvariants, value marshalling, the editor plugin and debugger, AOT mode, and the known gaps - Wiring a ResourceFormatLoader for the Turmeric/Godot Binding -- Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline
gradual-typing 2
- Saffron -- the dynamically typed dialect -- #lang saffron makes
anythe default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up. - Union and Intersection Types Guide -- Union (
A | B) and intersection (A & B) types,any, gradual typing
httpd 8
- Deploying Turmeric Services to Cloudflare -- Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts).
- HTTP Middleware Catalog (stdlib/httpd) -- Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files, security headers, request ids, trusted proxies, ETags, timeouts -- plus the request-attribute side channel and the composition helpers.
- HTTP Server with stdlib/httpd -- Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive
- HTTPD Async Guide -- Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop
- HTTPS with stdlib/httpd + tur-tls -- How to terminate TLS on an httpd-new server using the tur-tls spice
- Tourist Web Stack End-to-End -- Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together
- tur serve -- Serve a directory over HTTP with
tur serve, the Turmeric spelling ofpython3 -m http.server - Web Stack Guide -- Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric
inline-c 3
- C Integration Guide -- Foreign function interface (FFI) and C interop
- Returning
Result/Optionfrom Inline-C -- Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int - Typing Handles, Callbacks, and Results -- Avoiding
:intStand-Ins -- How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit.
installation 4
- Dev Container -- Running Turmeric development in a devcontainer from VS Code or the CLI
- Releases and Installation -- How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release.
- Turmeric Version Manager (
tvm) -- Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager. - Using Turmeric with mise or asdf -- Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf)
interpreter 3
- libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
- The turi Interpreter (internals) -- How the tree-walking interpreter works -- its entry points, the shared front end it runs, value and frame representations, the explicit-stack driver, native overrides and inline-C, the two effect runtimes, what memory it gives back and what it keeps, process-global hazards, and how to add a form or native
- turi <-> tur Parity Guide -- Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable.
io 5
- CLI Arguments Guide -- Passing arguments to scripts with
*args*and parsing them withstdlib/args.tur - Files and Processes -- Read and write files, walk directories, manage symlinks and permissions, read stdin line by line, run child processes, handle signals, speak TCP and work with calendar dates through the typed fs / io / process / net / time / os stdlib -- every failure is a (Result T IoError)
- Reactor Guide -- Lightweight evented I/O with tur/reactor
- tur serve -- Serve a directory over HTTP with
tur serve, the Turmeric spelling ofpython3 -m http.server - tur-watch Guide -- Cross-platform filesystem watching with debounce and coalescing for CLI tools
iteration 3
- Generators and Lazy Sequences Guide -- Zero-overhead generators with
gen/yield, lazySeqcombinators, and theRangetype - Range Reader Shorthand Plan -- Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time
- Zipper Guide -- Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor).
jit 2
- Dynamic FFI -- Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine
- JIT Execution Engine Guide (
tur jit) -- How the in-process MIR JIT is built -- what MIR is, how the engine is wired into this project, and what it does differently from the cc path (the fallback contract, the permanent constraints, and the inline-C rules that only bite under the JIT)
logic-programming 3
- Logic Programming Guide -- Backtracking, logic programming, constraint solving with cloneable continuations
- MiniKanren Part 1: Relations and Queries -- Logic programming with miniKanren -- relations, composition, and bidirectional queries
- tur/logic -- Logic Programming Guide -- How to use and extend tur/logic for miniKanren-style relational programming in Turmeric
lsp 3
- AI Assistant Integration Guide -- Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot
- Language Server (LSP) Guide -- Configuring editors to use the Turmeric language server for diagnostics
- VS Code Extension -- VS Code extension installation and configuration
macros 3
- Elaborator Internals -- How the elaborator turns reader Forms into the typed Expr IR -- the Elab state and scope model, the two-pass top-level driver and the synthesized main, call-site-local type inference, the Expr and Type data model, what the elaborator records for later passes, incremental sessions, macros, and the checklist for adding a form
- Macros Guide --
defmacroas a compile-time function from syntax to syntax -- quasiquote and splicing, manual hygiene, proceduraldefmacro*, macro-time imports, and why an expansion is type checked exactly like hand-written code - Reader Forms Reference -- Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions
memory 5
- Garbage Collection -- How memory is managed in Turmeric -- reference counting, the Bacon-Rajan cycle collector, arenas, and what is (and isn't) GC-managed in the compiled and interpreted paths
- Memory Usage Guide -- What each language feature costs in heap memory, measured -- scalars, structs, sums, lists, Vec, MutableMap, Map, String, rc, closures, function-value calls, effects and regions -- what frees it, and strategies for using less
- Ownership Guide -- Which ownership strategy to reach for -- persistent-immutable, single-owner mutable, linear/affine handles, rc<T> for genuine sharing, and weak<T> to break the resulting cycles
- Regions (RM3) Internals -- How region brackets work on the compiled path -- arena generations, rewind vs retire, the static walk and the runtime escape note, the store-hook rule and every place it is applied, the CPS and call/cc interactions, and the tools that tell a rewind from a retire
- Who Frees What in Emitted Code -- How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak
memory-safety 2
- Borrow Checking and Lifetimes Guide -- How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report
- Unsafe Code -- The (unsafe ...) block, raw pointers and raw memory, bit reinterpretation, and when to reach for something safer
middleware 3
- HTTP Middleware Catalog (stdlib/httpd) -- Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files, security headers, request ids, trusted proxies, ETags, timeouts -- plus the request-attribute side channel and the composition helpers.
- HTTP Server with stdlib/httpd -- Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive
- Tourist Session Middleware -- Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file)
modules 2
- Module System Guide -- Module system, namespacing, exports
- Separate Compilation and Module Loading -- How the compiler finds, loads and resolves modules, which builds split a program into one C translation unit per module, what goes into each module's .h and .c, who owns a generic specialization or an instance across TUs, and how to read the link errors when the split goes wrong
monads 4
- Backtracking Guide -- Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur
- Effects vs. Monads -- When to reach for an effect handler and when to reach for a monad value
- Higher-Kinded Types -- Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model)
- Parsec Tutorial -- A step-by-step introduction to the stdlib parser-combinator library tur/parsec -- characters, sequencing with do-m, choice, repetition, optional pieces, and mapping results into real values
mutable-state 5
- Backtrackable State Guide -- Trailed mutable cells from
stdlib/trail.tur-- take a mark, mutate freely, then undo or keep the writes; scopes, theBtcapability, and why a search loop wants this instead of a persistent structure - Dynamic Vars Guide -- Thread-local, dynamically-scoped mutable cells with defdynamic and binding
- Mutable Globals Guide -- def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover
- Stateful Refinements -- Refining predicates over mutable state -- the
frozenregion and the#reads wannotation that grants congruence, why a trusted annotation is sound here, and how the guarded crossings codegen - Uniqueness Types --
^unique: at-most-one-reference ownership
numerics 5
- Numeric Tower Guide -- Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading
- Operators -- Arithmetic, comparison, logical and bitwise operators -- which types each takes, how integers wrap and divide, and the float-only forms
- Sized Primitive Types -- Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting
- Sized Types -- Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations
- tur-stats Guide -- Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes
ownership 9
- Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped
- Borrow Checking and Lifetimes Guide -- How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report
- Opaque Types (
defopaque) -- Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines - Ownership Guide -- Which ownership strategy to reach for -- persistent-immutable, single-owner mutable, linear/affine handles, rc<T> for genuine sharing, and weak<T> to break the resulting cycles
- Session Types Guide -- Model protocols as types, whether the protocol has two participants, or more
- Strings Guide -- The three string tiers -- borrowed
cstr, borrowedstrview, and owned refcountedString-- which to reach for,#s"..."literals, zero-copyStringSlice, the lifetime rules, and the dangling-pointer pitfalls - Substructural Types --
^linear,^affine,^relevanttype disciplines - Uniqueness Types --
^unique: at-most-one-reference ownership - Who Frees What in Emitted Code -- How the direct-style C the compiler emits releases memory -- the ownership model and move tracking, drop glue, the by-value recursive spine drops (scope exit, lend, own-discharge), scope-exit frees and the shapes they decline, closure environments, carrier and element boxes, the rc<T> surface, and the workflow for confirming and pinning a leak
parsing 6
- JSON Guide -- Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON
- Markdown Guide -- Parse CommonMark and GitHub Flavored Markdown into a document tree with
tur/markdown, render it as HTML, walk its blocks and inlines, and what is implemented so far - Parsec Reference Guide -- Reference for the stdlib parser-combinator library tur/parsec -- core types, primitive parsers, sequencing, choice, repetition, optional values, mapping, runners, and common patterns
- Parsec Tutorial -- A step-by-step introduction to the stdlib parser-combinator library tur/parsec -- characters, sequencing with do-m, choice, repetition, optional pieces, and mapping results into real values
- Parser Combinators Tutorial -- Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching
- Regular Expressions Guide -- Pure-Turmeric POSIX ERE regex engine -- compile, match, find, and replace
performance 5
- Datalog Tutorial Pt. 4: Indexing -- Create a database and a query system to go with it
- ECS Storage Guide -- Dense, Sparse, Tag -- How
tur-ecs's three component-storage backends --Dense,Sparse,Tag-- differ in layout, cost, and ergonomics; when to pick each; howStorageOpsunifies them; and how theSized*variants thread a capacity through the type. - Memory Usage Guide -- What each language feature costs in heap memory, measured -- scalars, structs, sums, lists, Vec, MutableMap, Map, String, rc, closures, function-value calls, effects and regions -- what frees it, and strategies for using less
- Monomorphization ABI Guide -- How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read
__spec_*symbols in error messages, and what the small residual ABI bridge does. - Performance Guide -- Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology
persistent-data 3
- HAMT Guide -- Persistent hash maps with structural sharing (HAMT)
- Lens Guide -- First-class functional lenses (view / set / over) via stdlib/lens.tur, which ships the profunctor-by-record encoding. The classic van Laarhoven form is also expressible by hand.
- Zipper Guide -- Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor).
polymorphism 10
- Approaches to Polymorphism -- A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for
- Existential Types -- Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries
- GADTs -- A Practical Guide -- GADTs: refined constructors (
defdatawith: Result), type refinement, equality witnesses, union types, gradual typing - GADTs Cookbook -- GADTs cookbook: practical patterns and recipes
- Higher-Kinded Types -- Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model)
- Higher-Ranked Types -- Higher-ranked types: rank-2/3 polymorphic function parameters
- Type Annotation Syntax -- Compound type annotation syntax:
(-> a b),(vec T),forall, and more - Type-Level Rows -- The
#row{...}reader form and the kind-[*]row type -- writing rows, row-kinded (^&) parameters, the row algebra (concat/union/intersect/canon), erasure, and what rows deliberately cannot do - Typeclass Guide -- Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations.
- Union and Intersection Types Guide -- Union (
A | B) and intersection (A & B) types,any, gradual typing
queries 5
- Datalog Tutorial Pt. 1: Concepts -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 2: Minimal Implementation -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 3: Query API -- Create a database and a query system to go with it
- Frame Guide -- In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface
- MiniKanren Part 1: Relations and Queries -- Logic programming with miniKanren -- relations, composition, and bidirectional queries
refinement-types 6
- Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped
- Contract Types Guide -- Contract types:
#refine{ x : T | p },:pre/:postannotations, FFI contracts - Loop Invariants Guide -- Proving loop properties with :invariant annotations on while loops
- Refinement Solver Internals -- How the compiler proves a refinement predicate at compile time -- the obligation pipeline, the normalized verification condition, the staged in-house solver (no SMT dependency), memoization, caps, and how to debug an obligation
- Refinement Types --
#refine{ x : T | p }predicates the compiler tries to prove statically, emitting a runtime check only where the proof fails -- the predicate language, named refinements, diagnostics, and the documented limits - Stateful Refinements -- Refining predicates over mutable state -- the
frozenregion and the#reads wannotation that grants congruence, why a trusted annotation is sound here, and how the guarded crossings codegen
releases 2
- Release Process -- How Turmeric releases are cut -- the three cut-*-release commands, their shared nine-step flow, the ordering constraints that make a failed cut recoverable, and what the release workflow does once the tag is pushed.
- Releases and Installation -- How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release.
repl 3
- Interactive REPL Tutorial -- 22-step interactive tutorial to follow at
tur replor the web REPL - Notebook Guide -- Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode
- tur repl -- REPL Reference -- Reference guide for the
tur replinteractive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration
result-option 5
- Error Handling Guide --
Result,Option,panic, contract macros (assert!,require!,ensure!) - Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
- Returning
Result/Optionfrom Inline-C -- Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int - Sum Types and
Either-- Declaring binary and n-ary sum types withdefdata, pattern matching withmatch, exhaustiveness behaviour and the^non-exhaustiveopt-out, the FFI layout, and the stdlibEithermodule. - Typing Handles, Callbacks, and Results -- Avoiding
:intStand-Ins -- How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit.
saffron 2
- Introducing Saffron -- A first tour of Saffron, the dynamically typed dialect of Turmeric: Try Turmeric in the browser, printing, flow control, functions, ADTs, typeclasses, and algebraic effects -- every example in both s-expression and sweet-expression syntax.
- Saffron -- the dynamically typed dialect -- #lang saffron makes
anythe default type, so parameters and returns need no annotations. This guide covers what changes, what stays, the eight dynamic operations, the checked boundary with typed Turmeric, and the one feature Saffron gives up.
scheme 3
- How #lang r7rs Is Implemented -- How a #lang r7rs file becomes a Turmeric program -- dialect selection, the Scheme-to-Turmeric lowering and its rename table, the value representation, libraries and the split build, call/cc and the dynamic environment, the conservative collector, SRFIs, and the harnesses that cover them
- R7RS Scheme -- #lang r7rs -- #lang r7rs runs R7RS-small Scheme on the Turmeric compiler and runtime, compiled or interpreted, and lets Scheme and Turmeric modules import each other. This guide covers getting started, what is there, how it differs from the standard, and the tooling.
- Working through SICP with Turmeric -- Run the code from Structure and Interpretation of Computer Programs in Turmeric's Scheme dialect: installing, the interpreter and the REPL, the few definitions the book assumes, chapter-by-chapter notes, and the rough edges to know about.
security 3
- HTTPS with stdlib/httpd + tur-tls -- How to terminate TLS on an httpd-new server using the tur-tls spice
- Sandboxing Guide -- Restricting Turmeric code inside a C host with turi_env_new_sandboxed, capability flags, the native classification table, and resource limits -- and the memory-safety gap that keeps it from being a boundary against hostile code
- Security Guide -- What Turmeric promises to handle safely -- the trust boundary for each input, the promise made at it, and where the implementation does not yet keep that promise
serialization 5
- Application Image Dumps -- Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style.
- Checkpointing and Persistent Workflows -- Cloneable continuations for persistent workflows and checkpointing
- JSON Guide -- Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON
- Runtime Schema Validation -- Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors.
- Serializable Continuations Guide -- Serializable continuations for persistent workflows and cross-process computation
session-types 2
- Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, why dependent types remain deferred, and how refinement types went from deferred to shipped
- Session Types Guide -- Model protocols as types, whether the protocol has two participants, or more
spices 5
- Consuming Spices Guide -- Adding, fetching, and using spice packages in a Turmeric project
- Developing Spices Guide -- Creating, testing, and publishing Turmeric spice packages
- Package Management Guide (Spice) -- Creating projects, adding spices,
build.tur,tur.lock, CLI reference - Package Manager Internals -- How tur reads build.tur, resolves :spices and workspace siblings, writes and honours tur.lock, generates and consumes the :cmake-deps CMake project, and threads :build-opts into the C compile -- with the traps each stage leaves for spice authors
- Tur New Guide -- Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI
strings 3
- Regular Expressions Guide -- Pure-Turmeric POSIX ERE regex engine -- compile, match, find, and replace
- Strings Guide -- The three string tiers -- borrowed
cstr, borrowedstrview, and owned refcountedString-- which to reach for,#s"..."literals, zero-copyStringSlice, the lifetime rules, and the dangling-pointer pitfalls - Symbols Guide -- First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table
style 5
- Autodoc Guide -- Writing
;;;docstrings and generating API docs withtools/gendocs.py - Formatter Guide --
tur formatCLI and web REPL Format button - Function Arity Style Guide -- When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each
- Turmeric Style Guide -- Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style
- Typing Handles, Callbacks, and Results -- Avoiding
:intStand-Ins -- How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit.
syntax 7
- Data Literals Guide -- Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...]
- Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
- Range Reader Shorthand Plan -- Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time
- Reader Forms Reference -- Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions
- Syntax Guide -- How to read and write Turmeric -- s-expression and sweet-expression syntax
- Type Annotation Syntax -- Compound type annotation syntax:
(-> a b),(vec T),forall, and more - Vim Guide -- Vim / Neovim syntax highlighting installation and configuration
testing 4
- Diagnosing the Compiler -- How Turmeric contributors narrow a suspected compiler bug -- ruling out the environment, finding the failing stage, the dump flags, three-way back-end comparison, the float and leak checkers, the source fuzzers, and the test-harness traps that produce false failures
- Running the Tests -- Which harness runs what, how to narrow a run to the tests you care about, the fixture marker files, and how to reproduce a red CI job locally
- Test Runner Contract -- Test framework API and contract
- Test Suite Portability & Performance Guide -- macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses
threads 4
- Dynamic Vars Guide -- Thread-local, dynamically-scoped mutable cells with defdynamic and binding
- Mutable Globals Guide -- def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover
- Thread Pool -- Bounded POSIX worker-thread pool with back-pressure for fan-out work over ptr<void> items
- Threading and Concurrency Primitives Guide -- OS threads,
Arc<T>,Mutex<T>,Atomic<T>, channels
tourist 4
- Tourist Routing Composition -- Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications
- Tourist Session Middleware -- Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file)
- Tourist Web Stack End-to-End -- Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together
- Web Stack Guide -- Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric
type-checking 4
- Effect Rows (internals) -- How effect rows are represented, parsed, inferred and checked -- the EffectRow kinds, the EffectEnv registry, the elaborator's effect checks, the effect-row pass and its fixpoint, capabilities and Unsafe, --dump-effects, and where codegen reads the rows
- Elaborator Internals -- How the elaborator turns reader Forms into the typed Expr IR -- the Elab state and scope model, the two-pass top-level driver and the synthesized main, call-site-local type inference, the Expr and Type data model, what the elaborator records for later passes, incremental sessions, macros, and the checklist for adding a form
- Refinement Solver Internals -- How the compiler proves a refinement predicate at compile time -- the obligation pipeline, the normalized verification condition, the staged in-house solver (no SMT dependency), memoization, caps, and how to debug an obligation
- Typeclass Dictionary Internals -- How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how
definstancelowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics.
typeclasses 9
- Approaches to Polymorphism -- A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for
- Arrows and Signal Processing -- Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/
- Cellular Automata with Comonads -- Cellular automata with comonads
- Existential Types -- Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries
- Higher-Kinded Types -- Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model)
- Numeric Tower Guide -- Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading
- Semigroups, Monoids, and Lattices -- The algebraic combining vocabulary in stdlib/typeclass-lattice.tur -- Semigroup, Monoid, the join/meet lattice classes, the selection newtypes that carry them, mconcat, and the law predicates.
- Typeclass Dictionary Internals -- How the compiler resolves a typeclass method call to an instance (receiver- and return-directed), what the call records, how constrained generics reach the right instance (monomorphization, dict clones, captured dictionaries), superclasses, default methods, HKT instances on the by-value path, instances across modules, how
definstancelowers to a C dictionary struct + singleton, the closure-handle convention, and the failure shapes with their diagnostics. - Typeclass Guide -- Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations.
version-management 3
- Releases and Installation -- How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release.
- Turmeric Version Manager (
tvm) -- Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager. - Using Turmeric with mise or asdf -- Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf)
vscode 3
- AI Assistant Integration Guide -- Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot
- Dev Container -- Running Turmeric development in a devcontainer from VS Code or the CLI
- VS Code Extension -- VS Code extension installation and configuration
wasm 2
- Building for the Web with Emscripten -- Compile a Turmeric project to WebAssembly and run it in a browser
- Deploying Turmeric Services to Cloudflare -- Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts).
web 4
- Building for the Web with Emscripten -- Compile a Turmeric project to WebAssembly and run it in a browser
- Web Continuations Guide -- Compact reference: one continuation per page, the continuation store, routing model
- Web Continuations Tutorial -- Multi-page web forms using serializable continuations (guestbook example)
- WebSockets -- Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices
zippers 2
- Cellular Automata with Comonads -- Cellular automata with comonads
- Zipper Guide -- Generic zippers with stdlib/zip.tur -- a typed clojure.zip over any tree (ZipLoc), the Plated typeclass, and an element cursor over any container (ZipCursor).
other 1
- Bibliography -- Academic papers, theses, and technical references cited across Turmeric design documents and guides