Developing Spices Guide

A spice is a Turmeric package that other projects depend on. This guide covers every step of authoring one: project structure, declaring exports, wrapping C libraries with :cmake-deps, testing, versioning, and publishing.

See Consuming Spices if you only need to add an existing spice to your project.

When to Create a Spice

Create a spice when you want to:

• Share a library across multiple projects.
• Wrap a C library and expose it as a clean Turmeric API.
• Contribute to the official turmeric-spices monorepo.
• Distribute a library that others can add with tur add.

For code shared only within a single project, use the module system -- no separate package is needed.

Scaffolding the Project

tur new tur-mylib --lib
cd tur-mylib

This creates:

tur-mylib/
  build.tur        -- package manifest
  tur.lock         -- empty lock file (commit to VCS)
  src/
    lib.tur        -- stub exported function
  .gitignore
  README.md

By convention, name the package with a tur- prefix. Consumers drop the prefix as the import alias: tur-geom becomes geom, tur-math becomes math.

The build.tur Manifest

A complete library manifest:

(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"]
  })

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"]
  }

Key manifest fields

Declaring Exports

The :exports map controls what is visible to consumers. Only listed symbols are part of the public API; everything else is private.

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

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

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

Internal helpers that should not be exposed are simply omitted from :exports.

Source Layout

Follow this layout so that module paths and file paths align without extra configuration:

tur-mylib/
  build.tur
  tur.lock
  src/
    types.tur       -- exports "mylib/types"
    draw.tur        -- exports "mylib/draw"
    io.tur          -- exports "mylib/io"
    internal/
      helpers.tur   -- not exported; only imported by other src files
  tests/
    types_test.tur
    draw_test.tur

The module path "mylib/types" resolves to src/types.tur. A nested path "mylib/net/http" resolves to src/net/http.tur.

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 {
  "math" {:url    "https://github.com/rjungemann/turmeric-spices"
          :ref    "math-v0.1.0"
          :subdir "spices/math"}
}

Mark spices that are only needed for tests :optional true so consumers are not forced to fetch them:

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

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

Wrapping a C Library with :cmake-deps

The :cmake-deps block tells tur build to fetch and compile a C library via CMake, then inject the resulting include dirs and link flags into the compilation step. You write only Turmeric; CMake is an implementation detail.

Declaring the dependency

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

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

:options sets CMake cache variables (-DKEY=VALUE). Common patterns:

• Disable shared libs: :BUILD_SHARED_LIBS "OFF"
• Disable examples or tests: :BUILD_EXAMPLES "OFF", :YYJSON_BUILD_TESTS "OFF"
• Control feature sets: depends on the upstream library's own CMake options

Declaring C symbols in Turmeric

Use include-c to pull in the C header and extern-c to declare symbols:

;; 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))))))))

;; 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))))

extern-c trusts the signature you give it -- double-check it against the actual C header. No -I or -L flags are needed in your source; tur build injects them from cmake/spice-deps-manifest.json.

Inline C for small wrappers

When a binding is simpler to write directly in C, use an inline-C block:

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

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

;;; 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)
  ...)

;;; 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 ...)

;; 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)))

tur add https://github.com/rjungemann/turmeric-spices \
  --ref test-v0.1.0 --subdir spices/test --name 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)

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()

Run the test suite:

tur test

For the full testing API see test-runner-contract.md.

Versioning

• Use semver: MAJOR.MINOR.PATCH.
• Git tags must be vMAJOR.MINOR.PATCH for standalone repos (v0.1.0).
• For spices inside the turmeric-spices monorepo use the per-spice tag format <spice>-vMAJOR.MINOR.PATCH (math-v0.1.0, sqlite-v0.2.1).
• Pre-releases: v0.2.0-alpha.1.
• Bump MAJOR for breaking API changes, MINOR for additive changes, PATCH for bug fixes.

Publishing

As a standalone repository

git tag v0.1.0
git push && git push --tags

Consumers then add your spice with:

tur add https://github.com/you/tur-mylib --ref v0.1.0

Contributing to turmeric-spices

The turmeric-spices monorepo accepts spices that meet the bar for the ecosystem. To contribute:

1. Fork the monorepo and add your spice under spices/<name>/.
2. Add it to the workspace root build.tur :members list.
3. Include a README.md and at least one test file.
4. Open a pull request.

After merging, tag the spice's first release:

git tag math-v0.1.0
git push --tags

Consumers use --subdir spices/<name> when adding:

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

Spice registry (future)

Once pkg.turmeric-lang.org launches, tur publish will register the package and consumers will use tur add spice/<name> without a Git URL.

Per-file Commands Inside a Spice

tur build <dir> and tur run (project mode) know about the spice they live in because they start by reading build.tur. The per-file subcommands tur check, tur emit-c, tur emit-h, and tur run <file> get the same behavior automatically -- they walk up from the input file looking for a sibling build.tur and add that spice's src/ to the include path. If the manifest declares :spices dependencies, those deps' src/ directories are added too.

This means editors, format-on-save hooks, LSP clients, and quick "compile this one file" loops work without per-spice configuration:

cd spices/frame
tur check src/frame/frame.tur     # resolves intra-spice imports
tur emit-c src/frame/schema.tur   # same
tur run src/frame/quickstart.tur  # builds and executes

The walk-up is capped at 16 ancestor directories, so a stray build.tur far above your working tree won't accidentally win.

-I for extra directories

Explicit -I <dir> flags still work and take priority over auto-discovered paths -- useful for fixtures, vendored copies, or when you want to test against a different version of a dep:

tur check -I vendor/alternate src/main.tur

-I accepts both the spaced (-I path) and concatenated (-Ipath) forms.

--no-auto-spice escape hatch

If you need to compile a file as if no spice exists around it (rare -- typically only useful for resolver-fixture tests or when an unrelated build.tur is in the ancestor chain), pass --no-auto-spice:

tur --no-auto-spice check tests/fixtures/resolver/input.tur

This restores the pre-auto-discovery behavior: only the input file's own directory, the stdlib, and any explicit -I paths are searched.

When auto-discovery does not apply

• tur build <dir> -- already configures itself from the directory's build.tur.
• tur build <file> -- the single-file build doesn't auto-discover; use tur run <file> if you want the same convenience for a one-off invocation, or pass -I explicitly.
• tur format <file> -- the formatter doesn't resolve imports, so include paths are irrelevant.

Supporting CMake Consumers

If you want C and C++ projects to consume your spice via CMake or CPM without knowing anything about Turmeric, run:

tur emit-cmake

This reads build.tur and generates CMakeLists.txt, <name>Config.cmake, and helper modules. Commit those files, tag the release, and a CPM consumer can add your library with:

CPMAddPackage(
  NAME    tur-mylib
  URL     https://github.com/you/tur-mylib/archive/refs/tags/v0.1.0.tar.gz
  VERSION 0.1.0
)
target_link_libraries(my_app PRIVATE tur-mylib::all)

For the complete step-by-step see Using a Turmeric library from CMake.

Emscripten / WASM Support

Once tur build --target wasm lands, all cmake-deps spices will get WASM builds automatically when the underlying C library supports Emscripten. To make your spice Emscripten-compatible:

• Prefer C libraries with documented Emscripten support (yyjson, mbedTLS, PCRE2, and the SQLite amalgamation all qualify).
• Avoid libraries that require native threads or sockets without WASM fallbacks.
• Use #ifdef __EMSCRIPTEN__ in inline-C blocks to handle differences (e.g. skipping native TLS when the browser provides its own TLS stack).

Global Spices as Libraries (v2)

A spice installed globally with tur install is currently usable as a command-line tool only: its :bin entries are symlinked into ~/.local/bin/ and become available as tur-<cmd> (or via the tur <cmd> fallthrough). The same install is not automatically visible as a library to other projects -- the global spices/ root is left out of the default module-resolution path to preserve build reproducibility.

A future v2 will let a project opt in to consuming a globally-installed spice as a library by naming it in its build.tur:

:spices {
  "notebook" {:global true}
}

tur fetch would then validate the global install exists at a matching version and record its resolved SHA in tur.lock. A project-level :global-policy knob would decide whether a missing global install gets auto-installed or errors out.

This is deferred; until it ships, a spice that wants to be reused as a library should be added the normal way with tur add. See the global-spice-install plan for the full design sketch.

Release Checklist

• [ ] tur build --release passes with no warnings
• [ ] tur test passes
• [ ] All public symbols are listed in :exports
• [ ] Each exported symbol has a ;;; docstring (summary + params + returns + example)
• [ ] cmake-deps spices build cleanly on macOS and Linux
• [ ] tur emit-cmake succeeds if you intend to support CMake consumers
• [ ] Generated CMake files are committed if supporting CMake consumers
• [ ] CHANGELOG.md entry written
• [ ] Git tag pushed: git tag v0.1.0 && git push --tags

See Also

• Consuming spices -- adding and using spices in a project
• Package management guide -- full build.tur manifest reference and tur CLI
• C integration guide -- extern-c, include-c, inline-C blocks
• CMake/CPM integration notes -- cmake-deps internals, generated files, hash locking, security
• Using a Turmeric library from CMake -- step-by-step guide for tur emit-cmake
• Test runner contract -- full testing API