Developing Spices Guide

(defpackage tur-mylib
  :name        "tur-mylib"
  :version     "0.1.0"
  :description "A brief description of my library"
  :license     "MIT"
  :authors     ["Your Name <you@example.com>"]
  :repository  "https://github.com/you/tur-mylib"

  :exports {
    "mylib/core" ["some-fn" "another-fn"]
    "mylib/util" ["helper-fn"]
  })

:exports {
  "mylib/types" ["Coord" "Rect" "Color"]
  "mylib/draw"  ["draw-rect" "draw-circle" "draw-line"]
  "mylib/io"    ["read-file" "write-file"]
}

Each key ("mylib/types") becomes an importable path for consumers:

(import mylib/types :refer [Coord Rect])
(import mylib/draw  :refer [draw-rect])

;; src/mylib/types.tur
(defmodule mylib/types
  (export Widget WidgetResult)
  (defstruct Widget [value :int])
  ...)

;; src/mylib/core.tur
(defmodule mylib/core
  (export make-widget widget-value)
  (import mylib/types :refer [Widget WidgetResult])

  (defn make-widget [v :int] :Widget ...)
  (defn widget-value [w :Widget] :int ...))

tur check, tur emit-c, and tur build all resolve intra-spice imports automatically through the auto-spice include path -- no -I flags needed. See Per-file Commands Inside a Spice.

Anti-pattern: cross-file type stubs

An older pattern copies function bodies across files so each file compiles in isolation without imports:

;; src/mylib/io.tur -- ANTI-PATTERN
;; Stub copy of make-widget from core.tur; real body is return NULL.
(defn make-widget [v :int] #{Unsafe} :Widget
  ```c
  return NULL;
  ```)

(defn read-widget [path :cstr] :Widget ...)  ;; real implementation

This pattern fails in three ways:

• Silent breakage: stubs with return NULL or no-op bodies mean any code path that hits the stub produces garbage or does nothing -- with no diagnostic.
• Linker errors when combined: two files that both define make-widget as a static C function produce duplicate-symbol link failures the moment they are compiled together (via (load ...) or tur build).
• Per-file checks appear clean: each file is self-contained so tur check/tur emit-c on a single file passes while the combined build fails.

The scscm spice used this pattern across all five of its source files. It was eliminated in the 2026-05 import refactor by converting each file to defmodule + import. See scscm-spice-import-refactor-plan.md for the full migration. If you encounter the stub pattern in other spices, the fix is the same: add a (defmodule ...) + (export ...) header and replace each stub block with (import <module> :refer [...]).

Depending on Other Spices

Add Turmeric spice dependencies the same way any project does:

tur add https://github.com/rjungemann/turmeric-spices \
  --ref math-v0.1.0 --subdir spices/math --name math

This produces:

:spices {
  "math" {:url    "https://github.com/rjungemann/turmeric-spices"
          :ref    "math-v0.1.0"
          :subdir "spices/math"}
}

:spices {
  "test" {:url    "https://github.com/rjungemann/turmeric-spices"
          :ref    "test-v0.1.0"
          :subdir "spices/test"
          :optional true}
}

;; turmeric-spices/build.tur
(defpackage turmeric-spices
  :members ["spices/watch" "spices/notebook" ...])

Then notebook can (import watch/watch ...) directly -- the resolver walks up to the workspace build.tur, finds that watch is a listed member, and adds its src/ to the search path automatically.

# No tur fetch or symlink, and no lock entry required:
cd spices/notebook
tur check src/notebook/cli.tur   # resolves watch/watch via workspace

The first time an undeclared sibling import resolves, tur prints a one-time advisory:

warning: import 'watch/watch' resolved via workspace sibling
         'spices/watch'; declare it in :spices for release builds.
         (set TUR_DEBUG_RESOLVER=1 for full resolver tracing)

To confirm a name is a workspace member before importing:

tur add --workspace watch   # exits 0, prints "no manifest entry needed"
tur add --workspace typo    # fails if 'typo' is not in :members

Option B: explicit :path dep (works outside workspaces too)

Add a :path entry pointing at the sibling spice directory:

tur add ../watch --path

This writes to build.tur:

:spices {
  "watch" {:path "../watch"}
}

:spices {
  "watch" {:url    "https://github.com/rjungemann/turmeric-spices"
           :ref    "watch-v0.1.0"
           :subdir "spices/watch"}
}

:cmake-deps {
  "sqlite3" {:url     "https://github.com/sqlite/sqlite"
             :ref     "version-3.47.2"
             :options {:BUILD_SHARED_LIBS "OFF"}}
}

;; src/db.tur
(include-c "sqlite3.h")

(extern-c sqlite3_open   [:cstr :ptr] :int)
(extern-c sqlite3_close  [:ptr]       :int)
(extern-c sqlite3_exec   [:ptr :cstr :ptr :ptr :ptr] :int)
(extern-c sqlite3_errmsg [:ptr] :cstr)

(defn db-open [path :cstr] (result :ptr)
  (let [db-ptr (make-ptr)]
    (let [rc (sqlite3_open path db-ptr)]
      (if (= rc 0)
        (ok (deref-ptr db-ptr))
        (err (cstr->str (sqlite3_errmsg (deref-ptr db-ptr))))))))

(defn db-last-insert-rowid [db :ptr] :int
  ```c
  return (int)sqlite3_last_insert_rowid((sqlite3*)db);
  ```)

The closing ``` and its enclosing ) must be on the same line. See the inline-C style rule for why.

:cmake-name and :targets overrides

When the CMake find_package name or target name differs from the key in :cmake-deps, supply overrides:

:cmake-deps {
  "sqlite" {:url        "https://github.com/sqlite/sqlite"
            :ref        "version-3.47.2"
            :cmake-name "SQLite3"
            :targets    ["SQLite::SQLite3"]}
}

System-first resolution with :prefer-system

Heavy native libraries (mbedTLS, raylib, sqlite, libpq) are often already installed system-wide via Homebrew / apt / dnf. Building them from source on every clean tur fetch is slow. Add :prefer-system true to try CMake's find_package first and fall back to the source build only when no system copy is found:

:cmake-deps {
  "mbedtls" {:prefer-system true                ;; try find_package first
             :cmake-name    "MbedTLS"           ;; name passed to find_package
             :cmake-version "3.0"               ;; optional minimum version
             :targets       ["MbedTLS::mbedtls"
                             "MbedTLS::mbedx509"
                             "MbedTLS::mbedcrypto"]
             :url           "https://github.com/Mbed-TLS/mbedtls"  ;; fallback
             :ref           "v3.6.2"
             :options       {:ENABLE_PROGRAMS "OFF"
                             :USE_STATIC_MBEDTLS_LIBRARY "ON"}}
}

Behaviour:

• :prefer-system true requires :cmake-name -- it is the name handed to find_package. Omitting it is a hard manifest error.
• :cmake-version is optional; when present it becomes the minimum version in find_package(<name> <version> QUIET).
• When the system copy is found, the dep's include/link flags come from the imported target's INTERFACE_INCLUDE_DIRECTORIES and $<TARGET_FILE_DIR:...> -- skipping both the clone and the source build. Otherwise the existing FetchContent block runs exactly as before.
• The generated spice-deps-manifest.json records "resolved_via": "system" or "fetch" per dep, and tur.lock records :resolved-via "system" (with no git SHA -- the system package manager owns the version) or the usual :url/:ref/:resolved row for the fetch path.

:prefer-system is opt-in; deps without it keep their FetchContent-only behaviour unchanged.

Forcing the source build (--refetch)

To pin a build to the source copy and bypass any system package -- useful for reproducible CI artefacts -- pass --refetch (or set TUR_FETCH_FORCE_FETCH=1 in the environment):

tur fetch --refetch          # ignore system copies, always build from source

This disables the find_package short-circuit for every :prefer-system dep in the manifest.

Caveats. A binary linked against a Homebrew/apt shared library will fail at runtime on a machine without that library installed; pin the source build (or --refetch) for portable artefacts. See tur-fetch-system-first-plan.md for the design rationale and open questions.

For the full :cmake-deps field reference, the generated SpiceDeps.cmake format, the spice-deps-manifest.json schema, and hash locking, see the CMake/CPM integration notes.

Vendoring C Sources (:c-sources / :c-includes)

:cmake-deps is the right tool for a real native library that already has a CMake (or system-package) presence. But some C is too small for that ceremony: a single-file header library (stb_image, miniaudio), a four-file FFT (KissFFT), a hand-tuned kernel. For those, vendor the .c straight into the spice and let the spice build compile and link it -- no CMake, no fetch step.

Add two keys under :build-opts:

(defpackage tur-signal
  :name "tur-signal"
  :build-opts #fx{
    :c-includes ["c/kissfft"]            ;; -I dirs (manifest-relative)
    :c-sources  ["c/kissfft/kiss_fft.c"  ;; .c files compiled + linked
                 "c/kissfft/kiss_fftr.c"
                 "c/glue/fft_shim.c"]
  }
  :exports #map{ "signal/fft" [fft-forward fft-inverse] })

Rules

• Manifest-relative paths only. Both :c-sources and :c-includes resolve relative to the directory holding build.tur. An absolute path is a hard error -- if you need a system include path, declare a :link-libs / :cmake-deps dependency instead.
• Validated at manifest load. Each :c-sources entry must exist on disk and end in .c, .cc, or .cpp; each :c-includes entry must be an existing directory. A typo fails the build immediately with a diagnostic pointing at the offending entry, not with an opaque cc error later.
• :c-includes reach the spice's own C only. The -I dirs are visible both to the vendored .c and to inline-C blocks in this spice's .tur modules (so an inline-C block can #include "kissfft/kiss_fftr.h"). They are not exported to consumers -- vendored headers are an implementation detail.
• :c-sources propagate across :spices deps. If spice B vendors a .c and spice A depends on B, building A links B's vendored sources into A's binary automatically. Consumers see B only through its .tur exports, so a consumer's inline-C should extern-declare any vendored symbol it calls rather than relying on B's private headers.
• C++ is accepted but not auto-configured. .cc / .cpp entries are allowed (some vendor libraries are C++ wearing a C name), but the build does not switch to a C++ driver for you -- add -x c++ to :c-flags if needed.
• No platform conditionals. Every listed source is compiled on every platform; gate platform-specific code with #ifdef inside the source, as vendor libraries already do.

Layout: vendored C goes under c/, never src/

The manifest-driven build walks src/ looking for .tur modules; do not put .c files there. Keep vendored C in its own c/ tree:

tur-signal/
  build.tur
  src/
    signal/fft.tur        ;; .tur modules (walked by the build)
  c/
    kissfft/
      kiss_fft.c          ;; vendored sources (listed in :c-sources)
      kiss_fft.h          ;; vendored headers (dir listed in :c-includes)
    glue/
      fft_shim.c

When to reach for this vs :cmake-deps

Vendor a .c when the library is small, single-purpose, and has no native package-manager presence -- you would otherwise be copy-pasting a header into an inline-C block anyway. Reach for :cmake-deps when the library is large, has its own build system, or is commonly installed system-wide (where :prefer-system saves a source build). If a library needs CMake or autotools to configure itself, it is not a vendoring candidate.

Writing the Public API

Every exported symbol should have a ;;; docstring immediately above its definition. The standard format (from CLAUDE.md):

;;; db-open -- open an SQLite database file.
;;;
;;; Parameters:
;;;   path -- filesystem path to the database file (created if absent)
;;;
;;; Returns:
;;;   (ok db) on success, (err message) if the file cannot be opened
;;;
;;; Example:
;;;   (match (db-open "app.db")
;;;     (ok db) (println "opened")
;;;     (err m) (println "failed:" m))
;;;
;;; Since: Phase P2
(defn db-open [path :cstr] (result :ptr)
  ...)

Exported symbols without docstrings will be omitted from tur run docs output.

Module docstring (optional)

A spice module can optionally include a module-level docstring at the very top of the file, before the first defn, defmacro, defstruct, definstance, or defopaque. Place a contiguous ;;; block followed by a ;; comment line (which acts as the separator):

;;; myspice/db -- SQLite database bindings.
;;;
;;; Thin wrapper around libsqlite3; provides open/close/query/exec with
;;; result-typed error handling.
;;;
;;; Since: Phase P2
;; ---- SQLite bindings ----
(extern-c sqlite3_open ...)

Without a module docstring the page renders with no description block -- the per-symbol cards still appear normally.

Style: avoid cons ... 0 chains in examples

In README quick-starts and docstring examples, do not show runtime list values as (cons x (cons y 0)) chains. The trailing 0 is the nil-of-list footgun -- new readers have no way to tell that 0 means "end of list," and the chain itself reads in reversed nesting order.

Use the list macro instead. It expands to the same tcons/tnil cells, so it's a drop-in for any API that today takes a :int cons list:

;; Avoid
(group-by f (cons "g" 0))
(plot (cons (axes) (cons (function f) 0)))

;; Prefer
(group-by f (list "g"))
(plot (list (axes) (function f)))

Pair-cons ((cons key value) with no trailing 0) is fine -- a two-element pair is a clear, idiomatic data shape. The footgun is the nil-terminated chain.

If your spice API can take a Vec instead of a cons list, prefer that and document it with (vec-of ...). The end goal is for cons to disappear from quick-start surfaces entirely.

Typed variadic rest parameters

A & rest :T parameter type-checks against T even when T is a user-defined type -- a defopaque newtype, struct, ADT, or type application. The rest element type is resolved to its full type and each argument is checked by identity at the call site, so you can give a variadic API a real handle type instead of an untyped :int:

(defopaque Route :int)

;; Each rest arg must be a Route; a raw :int or a different opaque is rejected.
(defn launch [& routes :Route] :ptr<void>
  ...)

The old workaround of declaring the rest as :int and casting handles back inside the body is no longer needed. For an interface that mixes distinct handle types (e.g. middlewares and routes), use two explicit :list<T> parameters rather than one untyped rest -- a single & rest is one homogeneous element type by design.

Testing Your Spice

Add tur-test as an optional dependency and place test files in tests/:

tur add https://github.com/rjungemann/turmeric-spices \
  --ref test-v0.1.0 --subdir spices/test --name test

A test file using tur-test:

(import test/assert :refer [assert-eq assert-ok assert-err])
(import test/suite  :refer [describe it])
(import test/runner :refer [run-all])
(import mylib/core  :refer [some-fn])

(describe "some-fn"
  (it "returns the expected value"
    (assert-eq (some-fn 10) 42))
  (it "returns err for invalid input"
    (assert-err (some-fn nil))))

(run-all)