GitHub Try it

No matching guides.

Home

Categories

Language

Ecosystem

Community

Guides

Tutorials, how-tos, and in-depth feature guides for Turmeric

Advanced Control Flow

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: defgadt, 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 with tools/gendocs.py
  • Compiler Flags -- Diagnostic and debug flags accepted by tur; list of removed -X feature flags
  • Experimental Feature Flags -- The --enable=<name> surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and the tur experiments command.
  • 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 docs commands
  • Test Runner Contract -- Test framework API and contract
  • 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

  • Compiler Internals -- End-to-end walkthrough of the tur compiler pipeline and source layout in src/, aimed at contributors extending the type system or adding new passes
  • 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
  • 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 definstance lowers to a C dictionary struct + singleton, how method-field C types are resolved, and the closure-handle convention for methods whose return type is itself a function.

Concurrency and Async

Contributor

  • 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)
  • 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-ecs and the tur-ecs-raylib companion -- 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; how StorageOps unifies them; and how the Sized* 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.
  • 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
  • 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 format CLI 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 how tur dap replays 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

Functional Patterns

Getting Started

  • Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
  • Quickstart & Interactive REPL Tutorial Plan -- Authoring plan and step outline for the quickstart.md prose guide and repl-tutorial.md 22-step interactive tutorial
  • 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 repl interactive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration
  • Interactive REPL Tutorial -- 22-step interactive tutorial to follow at tur repl or the web REPL
  • Syntax Guide -- How to read and write Turmeric -- s-expression and sweet-expression syntax

Guide

  • "Saffron -- the dynamically typed dialect" -- "#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."

Integration / Godot

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 / Option from 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 -- Running untrusted Turmeric code safely inside a C host using turi_env_new_sandboxed, capability flags, and resource limits

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 with stdlib/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
  • 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
  • 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
  • Structs -- Defining and using struct types with defstruct
  • Sum Types and Either -- Declaring binary and n-ary sum types with defdata, pattern matching with match, exhaustiveness behaviour and the #fx{NonExhaustive} opt-out, the FFI layout, and the stdlib Either module.
  • Symbols Guide -- First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table
  • Typing Handles, Callbacks, and Results -- Avoiding :int Stand-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 -- 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)
  • 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

Performance

  • 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

Standard Library

  • 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.

Tutorials

Type Safety

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