Turmeric ↔ C Integration Guide

(extern-c function-name [arg-types...] return-type)

;; libc file I/O (stdlib/io.tur)
(extern-c fopen  [^cstr ^cstr] :ptr)
(extern-c fclose [^ptr]        :int)
(extern-c fread  [^ptr ^int ^int ^ptr] :int)

;; libc memory (stdlib/io.tur)
(extern-c malloc [^ptr size]  :ptr)
(extern-c free   [^ptr p]     :void)

;; libc RNG (stdlib/random.tur)
(extern-c rand  [^]       :int)
(extern-c srand [^int]    :void)
(extern-c time  [^ptr]    :ptr)

(extern-c printf [^cstr] :int)
(printf "count=%lld\n" count)   ;; extra args pass through unchecked

(extern-c stderr [^] :ptr)   ;; FILE* stderr -- accessed as (stderr)
(extern-c rand   [^] :int)   ;; int rand(void)

(defn file-size [f]
  ```c
  FILE* file = (FILE*)f;
  long pos = ftell(file);
  fseek(file, 0, SEEK_END);
  long size = ftell(file);
  fseek(file, pos, SEEK_SET);
  return (int)size;
  ```)

(defn tur-int-carrier-eq? [a : int b : int] : bool (= a b))

(definstance MapKey [int] (mk-box [x] x)
  ;; expands to the current mangled spelling of `tur-int-carrier-eq?`
  (mk-cmp [x] : int ```c return (int64_t)(intptr_t)__TUR_CNAME_tur-int-carrier-eq?__; ```)
  (mk-owned? [x] 0))

The source name between __TUR_CNAME_ and the trailing __ may contain sigils (-, ?, !, =, ...); it is terminated by the first __.

The splice resolves to the callee's exact emitted C name. When the name resolves to a binding visible in scope, the expansion matches that binding's full C identifier -- including the module prefix a global defined inside a named module carries (geom__helper_qu), and any (export-as "...") C alias. So a sibling defn inside (defmodule geom ...) is spliced correctly:

(defmodule geom
  (defn helper? [a : int b : int] : int (if (= a b) 1 0))
  (defn use-it [] : int
    ;; expands to geom__helper_qu (prefix included)
    ```c return (int)__TUR_CNAME_helper?__(7, 7); ```))

When the name does not resolve to a visible binding, the splice falls back to the mangle-only spelling (no module prefix). This preserves the escape hatch for referencing an unprefixed global in another translation unit that the current module does not import -- e.g. stdlib carrier helpers referenced across files without an explicit import.

Capability structs -- The idiomatic pattern for C APIs

The stdlib uses capability structs to wrap C APIs behind a Turmeric-visible interface. This pattern keeps the unsafe pointer juggling isolated:

;; stdlib/random.tur -- capability struct wrapping libc rand()
(defn Real-Random []
  ```c
  typedef struct Random Random;
  struct Random {
      int (*next_int)(int min, int max);
      int (*next_float)(void);
  };

  static int random_next_int(int min, int max) {
      static int seeded = 0;
      if (!seeded) { srand((unsigned int)time(NULL)); seeded = 1; }
      return min + rand() % (max - min + 1);
  }

  static int random_next_float(void) {
      static int seeded = 0;
      if (!seeded) { srand((unsigned int)time(NULL)); seeded = 1; }
      return rand() % 10000;
  }

  Random* rng = (Random*)malloc(sizeof(Random));
  rng->next_int  = random_next_int;
  rng->next_float = random_next_float;
  return (void*)rng;
  ```)

(defn Real-Random-free [rng]
  ```c free(rng); ```)

(defopaque Device :ptr<void>)

;; Fallible C constructor: a *typed* (Result Device int), built with the typed
;; builders. No re-declaration of the result struct layout, no hand cast.
(defn open-device [id : int] : (Result Device int)
  ```c
  #include <stdlib.h>
  if (id < 0) return tur_err_int(22);      /* EINVAL */
  void *h = malloc(device_size());
  return tur_ok_ptr(h);
  ```)

;; And the consumer is plain Turmeric -- ok?/err?/ok-val all work:
(defn use-device [id : int] : int
  (let [r (open-device id)]
    (if (ok? r) (device-tag (ok-val r)) -1)))

The same shape works for (Option Device) via tur_some_ptr / tur_none.

See inline-c-results-guide.md for the full helper table, a worked rtmidi-shaped example, the _Static_assert layout guard, the two anti-patterns this replaces, and the _int/_ptr-only limitation.

See tests/fixtures/inline-c-result-builder/ (typed builders) and tests/fixtures/inline-c-typed-result-option/ (the carrier-level tur_box_* builders) for end-to-end examples.

Calling Turmeric from C

Turmeric does not yet produce a linkable .a or .so. However, there are two practical ways to use compiled Turmeric code inside a larger C project:

Include the emitted .c directly

./build/tur emit-c mylib.tur > generated/mylib.c

Then add generated/mylib.c (and src/runtime.c) to your C build. Declare the Turmeric-emitted top-level defn functions with extern in a hand-written header, and call them from your C code.

Name mangling is reversible and injective (#275): a top-level (defn my-function ...) becomes my_function in C, but sigils encode through escape digraphs -- - → _hy, / → _sl, _ → _un, with ?, !, = and friends covered analogously -- so any Turmeric global name round-trips cleanly to C and back. Closures and anonymous functions get mangled names like tur__closure_N. See name-mangling-guide.md for the full table and the demangler. Inside an inline-C body, prefer the __TUR_CNAME_<source-name>__ splice (Inline C blocks) over hand-spelling the mangled name; the splice tracks the live mangler so a future scheme change does not silently break your code.

#[used] -- retaining a symbol reached only from C

The compiler keeps a definition with external C linkage when it is reachable through the Turmeric export/import + call graph. A defn whose mangled symbol is reached only through a raw extern reference is invisible to that analysis:

• a hand-written cross-module inline-C bridge that calls another module's unexported helper by its mangled name, or
• a C-ABI callback taken by address (an Arrow C Data Interface release function, a qsort comparator, a signal handler) and stored in a struct field or passed to a C API -- never called from Turmeric.

Such a defn is demoted to static under separate compilation (and dropped entirely by the single-main whole-program build shortcut, which inlines only the entry module's transitive Turmeric imports), so the extern reference dangles at link time. Mark it #[used] to force external linkage and keep its module in the build:

;; sort.tur -- unexported helper reached by a bridge in group.tur
(defn #[used] __so-take [col : int perm : int n : int] : int
  ```c
  ... ```)

;; interop.tur -- C-ABI callback stored by address, never called from Turmeric
(defn #[used] ip-release-schema [schema : int] : void
  ```c
  ... ```)

#[used] goes before the name, like #[no-unwind], and the two compose in either order: (defn #[used] #[no-unwind] name [...] ...). Prefer the __TUR_CNAME_<source-name>__ splice (above) over hand-spelling the mangled name in the extern declaration that reaches a #[used] symbol.

Subprocess / build-step integration

Use ./build/tur build as a build step that produces an executable, then have your C application invoke it as a subprocess. This is the zero-coupling option: the Turmeric binary handles I/O independently.

Linking runtime.c

Whichever approach you use, if the generated code uses defer you must compile and link src/runtime.c. Its public surface is small:

/* src/runtime.h */

typedef void (*defer_fn_t)(void *env);

#define TUR_FRAME_MAX_DEFERS 32

typedef struct tur_frame {
    defer_fn_t defers[TUR_FRAME_MAX_DEFERS];
    void *envs[TUR_FRAME_MAX_DEFERS];
    int n;
    struct tur_frame *parent;
    bool may_capture;          /* unused in v1 */
    struct EffectRow *effect_row; /* unused in v1 */
} tur_frame;

void tur_frame_init(tur_frame *f, tur_frame *parent);
int  tur_frame_push_defer(tur_frame *f, defer_fn_t thunk, void *env);
void tur_frame_fire_lifo(tur_frame *f);
void tur_frame_fire_chain(tur_frame *f);

Memory Management

Turmeric has three memory tiers. Understanding which tier a value lives in is essential when crossing the C boundary.

Arena (compile-time only)

The compiler itself uses a bump-allocator arena (src/arena.h). This is compiler-internal only -- generated programs do not use it.

Reference counting -- rc<T>

rc<T> is Turmeric's primary heap type. In generated C it is represented as a pointer to an RcControlBlock followed immediately by the value. The control block holds a strong count and a weak count.

/* src/rc.h */
struct RcControlBlock {
    uint64_t strong_count;
    uint64_t weak_count;
    void    *value;
    RcDropFn drop_fn;      /* NULL → use free() */
    TypeKind value_type_kind;
    GcColor  color;        /* Bacon-Rajan cycle collector */
    bool     may_contain_cycles;
};

Pitfall: If you receive an rc<T> across the C boundary (as a void *), you are holding a raw pointer into Turmeric's reference-counting machinery. Calling free() on it directly will corrupt the control block. Always let Turmeric code manage rc<T> lifetimes; pass scalars or opaque void * capability structs across the boundary instead.

Pitfall: Cycles in rc<T> graphs are broken by the Bacon-Rajan cycle collector, but only Turmeric-managed rc<T> nodes are tracked. If you create a cycle that involves a raw C pointer (e.g. a C struct that holds a void * back to an rc<T>), the cycle collector will not see it and memory will leak.

Weak pointers -- weak<T>

A weak<T> holds only the control block pointer (strong count = 0 is allowed). upgrade returns a value wrapped in Option; if the strong count has reached zero it returns nil. Weak pointers crossing the C boundary have the same concern as rc<T> -- do not free() them directly.

Manual heap (malloc/free via extern-c)

When an inline C block or extern-c call allocates memory with malloc, that memory is invisible to the cycle collector and the borrow checker. You must free() it manually, typically with a matching extern-c free call or an inline block. The stdlib consistently pairs allocating functions with a corresponding *-free function (see Real-Random-free above).

defer is the right tool here:

(let [buf (malloc 1024)]
  (defer (free buf))
  ;; ... use buf ...
  )  ;; free fires here, even if an exception is thrown

(let [f (fopen "data.bin" "rb")]
  (defer (fclose f))
  ;; ... read from f ...
  )   ;; fclose(f) called here

(try
  (throw 42)
  (catch [e :int]
    (println e))
  (finally
    (println "always")))

(defn run-twice [^fat f x : int] : int
  ```c
  /* f is int64_t; TUR_APPLY1 reads the thunk from slot 0 of the
     fat-closure box and invokes it with x. */
  int64_t a = TUR_APPLY1(f, (int64_t)x);
  int64_t b = TUR_APPLY1(f, a);
  return (int)b;
  ```)

If your C side is a plain extern-c callback (a hand-written int64_t (*)(int64_t) function pointer), declare it normally and pass it in -- the ^fat parameter auto-shims a bare fn-pointer into a one-cell fat box on the way in. Do not spell the handle as void * in inline-C; the codegen agrees on int64_t, and the unsafe-block capture scan (#264) inspects ascriptions, so a wrong carrier type can hide a real capture from the checker. See fat-closure-annotation-guide.md for the deeper rationale and ^fat on return types.

First-class :fn values shipped (#272); the prior hedges in this guide about "closures cannot cross the boundary" are obsolete -- the rule is that they cross as int64_t and must be annotated at the boundary.

Build and Linking

Building the compiler

make           # debug build -- -Og, ASan+UBSan, -DTUR_DEBUG=1
make release   # -O2, -DNDEBUG

The compiler binary is build/tur.

Compiler flags for generated code

The compiler invokes $(CC) (defaulting to cc) with:

-Wall -Wextra -Werror -Wno-unused-parameter -std=c99 -pedantic

Plus, in debug mode: -Og -g -fsanitize=address,undefined -DTUR_DEBUG=1
In release mode: -O2 -DNDEBUG

Pitfall: -Werror is on. Any warning in your inline C block or in a header it includes will be a build error. Common sources of warnings in inline C:

• Implicit function declarations (missing #include).
• Signed/unsigned comparisons when mixing int64_t with size_t.
• int vs long mismatches when calling libc functions that return size_t.

Cast liberally and include headers explicitly.

Linking external libraries

extern-c imports must be resolvable at link time. Pass extra linker flags via the LDFLAGS environment variable:

LDFLAGS="-lraylib -framework OpenGL" make release

For system libraries (-lm, -lpthread, etc.) add them to LDFLAGS in your build script or Makefile wrapper.

Multi-file builds

./build/tur build src/main.tur   # compiles main.tur and any (require ...) deps

Each required module emits its own .c + .h pair. A generated _main.c #includes all modules and defines main(). extern-c declarations in one module are visible to C but not automatically shared between Turmeric modules -- repeat the declaration in each module that needs it, or factor them into a shared .tur file.

Common Pitfalls Summary

Worked Example -- Wrapping a C Library

This example wraps a hypothetical libmath C library with a Turmeric module.

libmath.h (your C header):

typedef struct Vec2 { double x, y; } Vec2;
Vec2  vec2_add(Vec2 a, Vec2 b);
double vec2_len(Vec2 v);
Vec2 *vec2_alloc(double x, double y);  /* heap-allocated, caller frees */
void  vec2_free(Vec2 *v);

math_wrap.tur (Turmeric wrapper):

;; Declare the functions we need
(extern-c vec2_alloc [^float ^float] :ptr)
(extern-c vec2_free  [^ptr]          :void)

;; vec2_add and vec2_len operate on struct values, which we pass through
;; inline C since struct-by-value is not in the type system yet
(defn vec2-add [a b]
  ```c
  #include "libmath.h"
  Vec2 *pa = (Vec2 *)a;
  Vec2 *pb = (Vec2 *)b;
  Vec2 *result = (Vec2 *)malloc(sizeof(Vec2));
  *result = vec2_add(*pa, *pb);
  return (void *)result;
  ```)

(defn vec2-len [v]
  ```c
  #include "libmath.h"
  Vec2 *pv = (Vec2 *)v;
  return vec2_len(*pv);
  ```)

(defn demo []
  (let [a (vec2_alloc 3.0 4.0)]
    (defer (vec2_free a))
    (let [len (vec2-len a)]
      (println len))))   ;; prints 5.0