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 Guide | 2026-10-22 | |
| 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 |
| Advanced Type System -- Design Rationale | 2026-10-24 | 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-10-24 | Bare-function arrow combinators and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/ |
| Backtracking Guide | 2026-10-24 | Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur |
| Binding Forms Guide | 2026-10-24 | def in a body, letrec, and named-let -- the three local binding idioms that complement let and defn |
| C Integration Guide | 2026-10-24 | Foreign function interface (FFI) and C interop |
| Channels and Select Guide | 2026-10-24 | Buffered channels for inter-fiber communication and multi-channel select |
| CLI Arguments Guide | 2026-10-24 | Passing arguments to scripts with *args* and parsing them with stdlib/args.tur |
| Compiler Internals | 2026-10-24 | 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 |
| Developing Spices Guide | 2026-10-24 | Creating, testing, and publishing Turmeric spice packages |
| Effect Rows (internals) | 2026-10-24 | 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-24 | Algebraic effects, dependency injection, custom control flow |
| Who Frees What in Emitted Code | 2026-10-24 | 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 |
| Error Handling Guide | 2026-10-24 | Result, Option, panic, contract macros (assert!, require!, ensure!) |
| libturi -- C Embedding API Reference | 2026-10-24 | C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a |
| Experimental Feature Flags | 2026-10-24 | The --enable=<name> surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and the tur experiments command. |
| HTTP Server with stdlib/httpd | 2026-10-24 | Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive |
JIT Execution Engine Guide (tur jit) | 2026-10-24 | 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) |
| Macros Guide | 2026-10-24 | 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 |
| Numeric Tower Guide | 2026-10-24 | Exact Rational and hand-written Complex arithmetic, the #rat{...} / #cx{...} literals, and Num-typeclass operator overloading |
Opaque Types (defopaque) | 2026-10-24 | 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 |
| Operators | 2026-10-24 | Arithmetic, comparison, logical and bitwise operators -- which types each takes, how integers wrap and divide, and the float-only forms |
| Quickstart | 2026-10-24 | Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects |
| R7RS Scheme -- #lang r7rs | 2026-10-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. |
| How #lang r7rs Is Implemented | 2026-10-24 | 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 Types | 2026-10-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 repl -- REPL Reference | 2026-10-24 | Reference guide for the tur repl interactive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration |
| Running the Tests | 2026-10-24 | 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 |
| Session Types Guide | 2026-10-24 | Model protocols as types, whether the protocol has two participants, or more |
| Sized Types | 2026-10-24 | Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations |
| Structs | 2026-10-24 | Defining and using struct types with defstruct |
| Structured Concurrency Guide | 2026-10-24 | TaskGroup for scoped task spawning and Future/Promise for asynchronous results |
| Substructural Types | 2026-10-24 | ^linear, ^affine, ^relevant type disciplines |
| Tourist Web Stack End-to-End | 2026-10-24 | Build a complete web application with tourist routing, httpd, TLS, sessions, and template rendering -- the full stack wired together |
| Tur Serve Guide | 2026-10-24 | |
| Building for the Web with Emscripten | 2026-10-24 | Compile a Turmeric project to WebAssembly and run it in a browser |
| CPS and the DK Continuation Machine | 2026-10-23 | 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 |
| Datalog Tutorial Pt. 2: Minimal Implementation | 2026-10-23 | Create a database and a query system to go with it |
| Delimited Control Operators: shift/reset vs shift0/escape | 2026-10-23 | How shift/reset, shift0/reset0, call/cc, and escape differ -- prompt re-installation, where the captured value returns, and which to reach for |
| Elaborator Internals | 2026-10-23 | 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 |
| C Emitter Architecture | 2026-10-23 | 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 |
| GADTs Cookbook | 2026-10-23 | GADTs cookbook: practical patterns and recipes |
| GADTs -- A Practical Guide | 2026-10-23 | GADTs: refined constructors (defdata with : Result), type refinement, equality witnesses, union types, gradual typing |
| Generators and Lazy Sequences Guide | 2026-10-23 | Zero-overhead generators with gen/yield, lazy Seq combinators, and the Range type |
| Godot Binding Guide | 2026-10-23 | 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 |
| Higher-Ranked Types | 2026-10-23 | Higher-ranked types: rank-2/3 polymorphic function parameters |
| Introducing Saffron | 2026-10-23 | 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. |
| Using Turmeric with mise or asdf | 2026-10-23 | Install and switch Turmeric compiler versions with the asdf-turmeric plugin (works for both mise and asdf) |
| Package Manager Internals | 2026-10-23 | 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 |
| Release Process | 2026-10-23 | 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-23 | How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release. |
| Syntax Guide | 2026-10-23 | How to read and write Turmeric -- s-expression and sweet-expression syntax |
| The turi Interpreter (internals) | 2026-10-23 | 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 |
Turmeric Version Manager (tvm) | 2026-10-23 | Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager. |
| Value Representations | 2026-10-23 | 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 |
| Borrow Checking and Lifetimes Guide | 2026-10-22 | How Turmeric's borrow checker and lifetime elision work, and how to fix the errors they report |
| Consuming Spices Guide | 2026-10-22 | Adding, fetching, and using spice packages in a Turmeric project |
| Diagnostics Internals | 2026-10-22 | 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 |
| Existential Types | 2026-10-22 | Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries |
| Dynamic FFI | 2026-10-22 | Calling C libraries at runtime -- dlopen/dlsym, call-ptr, extern-c under the interpreter, and the JIT thunk engine |
| Higher-Kinded Types | 2026-10-22 | Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model) |
| Ownership Guide | 2026-10-22 | 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 |
| Parser Combinators Tutorial | 2026-10-22 | Build a small parser in pure Turmeric using algebraic data types, GADTs, higher-order combinators, and pattern matching |
| Approaches to Polymorphism | 2026-10-22 | 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 |
| Regions (RM3) Internals | 2026-10-22 | 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 |
| Type-Level Rows | 2026-10-22 | 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 |
| Saffron -- the dynamically typed dialect | 2026-10-22 | #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. |
| Separate Compilation and Module Loading | 2026-10-22 | 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 |
| Sized Primitive Types | 2026-10-22 | Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting |
Sum Types and Either | 2026-10-22 | 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. |
| Tur Run Guide | 2026-10-22 | Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just |
| Union and Intersection Types Guide | 2026-10-22 | Union (A | B) and intersection (A & B) types, any, gradual typing |
| Vim Guide | 2026-10-22 | Vim / Neovim syntax highlighting installation and configuration |
| The Build Driver | 2026-10-21 | 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 |
| Datalog Tutorial Pt. 1: Concepts | 2026-10-21 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 3: Query API | 2026-10-21 | Create a database and a query system to go with it |
| Datalog Tutorial Pt. 4: Indexing | 2026-10-21 | Create a database and a query system to go with it |
| Dynamic Vars Guide | 2026-10-21 | Thread-local, dynamically-scoped mutable cells with defdynamic and binding |
| Files and Processes | 2026-10-21 | 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) |
| Module System Guide | 2026-10-21 | Module system, namespacing, exports |
| Monomorphization ABI Guide | 2026-10-21 | 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 | 2026-10-21 | How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies. |
| Package Management Guide (Spice) | 2026-10-21 | Creating projects, adding spices, build.tur, tur.lock, CLI reference |
| Performance Guide | 2026-10-21 | Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology |
| The Runtime Preamble and Its Linkage | 2026-10-21 | 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 |
| Test Suite Portability & Performance Guide | 2026-10-21 | macOS / Bash 3.2 gotchas, background-terminal SIGTTOU guards, inline-C math wrapper shadowing, and stamp-cache patterns for the test harnesses |
| turi <-> tur Parity Guide | 2026-10-21 | 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. |
| Autodoc Guide | 2026-10-19 | Writing ;;; docstrings and generating API docs with tools/gendocs.py |
| Async/Await Guide | 2026-10-17 | Async/await with fibers and delimited continuations |
| Data Literals Guide | 2026-10-17 | Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...] |
| Debugging Turmeric Programs | 2026-10-17 | 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-17 | Running Turmeric development in a devcontainer from VS Code or the CLI |
| Diagnosing the Compiler | 2026-10-17 | 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 |
| Language Server (LSP) Guide | 2026-10-17 | Configuring editors to use the Turmeric language server for diagnostics |
| Markdown Guide | 2026-10-17 | 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 |
| Offline Docs Guide | 2026-10-17 | 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 |
| Refinement Solver Internals | 2026-10-17 | 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 |
| Security Guide | 2026-10-17 | 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 |
| Typeclass Dictionary Internals | 2026-10-17 | 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. |
| VS Code Extension | 2026-10-17 | VS Code extension installation and configuration |
| ECS Guide | 2026-10-16 | 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. |
| Garbage Collection | 2026-10-16 | 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 |
| HAMT Guide | 2026-10-16 | Persistent hash maps with structural sharing (HAMT) |
| Strings Guide | 2026-10-16 | 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 |
| Cellular Automata with Comonads | 2026-10-15 | Cellular automata with comonads |
| Deploying Turmeric Services to Cloudflare | 2026-10-15 | 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). |
| Compiler Flags | 2026-10-15 | Diagnostic and debug flags accepted by tur; list of removed -X feature flags |
| Contract Types Guide | 2026-10-15 | Contract types: #refine{ x : T | p }, :pre/:post annotations, FFI contracts |
| Custom Effects Tutorial | 2026-10-15 | Writing custom effects |
Fat-Closure Annotation Guide (^fat) | 2026-10-15 | When and why to mark function-typed parameters and return positions ^fat, and what breaks without it |
| Range Reader Shorthand Plan | 2026-10-15 | Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time |
| Reactor Guide | 2026-10-15 | Lightweight evented I/O with tur/reactor |
| Reader Forms Reference | 2026-10-15 | Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions |
| Serializable Continuations Guide | 2026-10-15 | Serializable continuations for persistent workflows and cross-process computation |
| Snake Game Tutorial | 2026-10-15 | Building the snake game example |
| tur-stats Guide | 2026-10-15 | Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes |
| STM Guide | 2026-10-15 | Software transactional memory -- API reference and mechanics |
| Software Transactional Memory (STM) Tutorial | 2026-10-15 | STM tutorial: concepts, patterns, and worked examples |
| Turmeric Style Guide | 2026-10-15 | Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style |
| Test Runner Contract | 2026-10-15 | Test framework API and contract |
| Thread Pool | 2026-10-15 | Bounded POSIX worker-thread pool with back-pressure for fan-out work over ptr<void> items |
| Typeclass Guide | 2026-10-15 | Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations. |
| Web Continuations Tutorial | 2026-10-15 | Multi-page web forms using serializable continuations (guestbook example) |
| Web Stack Guide | 2026-10-15 | Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric |
| WebSockets | 2026-10-15 | Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices |
| Memory Usage Guide | 2026-10-14 | 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 |
| Type Erasure to int64_t | 2026-10-14 | Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses |
| Effects vs. Monads | 2026-10-11 | When to reach for an effect handler and when to reach for a monad value |
| HTTPD Async Guide | 2026-10-10 | 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-10-10 | 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. |
Returning Result / Option from Inline-C | 2026-10-07 | 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 | 2026-10-07 | 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 |
| Working through SICP with Turmeric | 2026-10-07 | 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. |
| Formatter Guide | 2026-10-05 | tur format CLI and web REPL Format button |
| Frame Guide | 2026-10-05 | In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface |
| Semigroups, Monoids, and Lattices | 2026-10-05 | 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. |
| Interactive REPL Tutorial | 2026-10-05 | 22-step interactive tutorial to follow at tur repl or the web REPL |
| Runtime Schema Validation | 2026-10-05 | Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors. |
| Threading and Concurrency Primitives Guide | 2026-10-05 | OS threads, Arc<T>, Mutex<T>, Atomic<T>, channels |
| tur/logic -- Logic Programming Guide | 2026-10-05 | How to use and extend tur/logic for miniKanren-style relational programming in Turmeric |
| tur-watch Guide | 2026-10-05 | Cross-platform filesystem watching with debounce and coalescing for CLI tools |
| Type Annotation Syntax | 2026-10-05 | Compound type annotation syntax: (-> a b), (vec T), forall, and more |
| Stateful Refinements | 2026-10-03 | 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 |
| Web Continuations Guide | 2026-10-03 | Compact reference: one continuation per page, the continuation store, routing model |
| Backtrackable State Guide | 2026-10-02 | 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 |
| Currying Guide | 2026-10-02 | Haskell-style partial application and over-application of Turmeric functions |
| ECS Storage Guide -- Dense, Sparse, Tag | 2026-10-02 | 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. |
| ECS -- tur-ecs vs apecs vs aztecs | 2026-10-02 | 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. |
| Wiring a ResourceFormatLoader for the Turmeric/Godot Binding | 2026-10-02 | Why and how the turmeric-godot GDExtension has to register its own ResourceFormatLoader so .tur files load through Godot's resource pipeline |
| HTTPS with stdlib/httpd + tur-tls | 2026-10-02 | How to terminate TLS on an httpd-new server using the tur-tls spice |
| Lens Guide | 2026-10-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. |
| Mutable Globals Guide | 2026-10-02 | def ^mut, what the compiler checks about a global write, and the concurrency story -- including what it deliberately does not cover |
| Notebook Guide | 2026-10-02 | Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode |
| Tourist Session Middleware | 2026-10-02 | Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file) |
tur compile and tur link | 2026-10-02 | 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 |
Typing Handles, Callbacks, and Results -- Avoiding :int Stand-Ins | 2026-10-02 | 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. |
| Application Image Dumps | 2026-09-25 | Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style. |
| Using a Turmeric Library from CMake | 2026-09-25 | How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using tur emit-cmake |
| Checkpointing and Persistent Workflows | 2026-09-17 | Cloneable continuations for persistent workflows and checkpointing |
| Logic Programming Guide | 2026-09-17 | Backtracking, logic programming, constraint solving with cloneable continuations |
| Tourist Routing Composition | 2026-09-17 | Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications |
| Symbols Guide | 2026-09-16 | First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table |
Time-Travel Tracing Guide (tur trace) | 2026-09-02 | 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 |
| AI Assistant Integration Guide | 2026-08-20 | Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot |
| Bibliography | 2026-08-20 | Academic papers, theses, and technical references cited across Turmeric design documents and guides |
| Function Arity Style Guide | 2026-08-20 | When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each |
| MiniKanren Part 1: Relations and Queries | 2026-08-20 | Logic programming with miniKanren -- relations, composition, and bidirectional queries |
| Uniqueness Types | 2026-08-20 | ^unique: at-most-one-reference ownership |
| JSON Guide | 2026-06-24 | Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON |
| State Machines Guide | 2026-06-24 | Five different approaches to modeling state machines in turmeric |
| Tur New Guide | 2026-06-24 | Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI |
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-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