The Runtime Preamble and Its Linkage (internals)

Every Turmeric program needs a C runtime: panics, the DK continuation machine, fibers and the scheduler, STM, the reference counter and cycle collector, regions, HAMT, strings, and more. This guide is for contributors who change that runtime, or who are debugging a build that linked the wrong copy of it. It covers:

• where the runtime's C text is written;
• how a program's preamble is assembled and gated;
• the several copies of the runtime that exist at once;
• which copy each build path actually compiles or links;
• the S2 split runtime that lets a build skip compiling the preamble;
• how to change any of this safely.

User-facing knobs (--runtime=, TUR_RUNTIME, TUR_PREAMBLE_SPLIT) are described in the tur compile / link guide. This guide is the mechanism underneath them.

Trust the code over the comments. Where a comment and this guide disagree, read the code. If the code disagrees with this guide, fix the guide. The comments that said a missing runtime archive disengages the split were corrected on 2026-10-21 (stale-comments-runtime-preamble).

"Split" means four different things in this codebase. This guide is about the first one.

---

The short version

1. The runtime is mostly text the compiler writes. emit_runtime_preamble (src/compiler/emit_module.c) is a single function of about 4,600 lines, mostly buf_puts calls. It writes the runtime into the top of every emitted translation unit, ending at the marker /* ==== tur: end of fixed runtime preamble ==== */. The DK machine and its relatives come from string emitters in src/compiler/emit_dk_runtime.c. The region runtime and the r7rs collector are real .c files pasted in verbatim.
2. Gates decide what a program's preamble contains. Whole-program scans (preamble_uses_*) and flags set during elaboration (g_needs_*) turn blocks on. So do process-wide switches such as regions, #lang r7rs and Saffron.
3. Postures decide linkage.
   • In single-file mode, the runtime is static in the program's TU.
   • In separate compilation, one owner TU (TUR_RT_OWNER) defines the state.
   • In archive posture (DEDUP-4b), the reference counter, the collector and the region runtime are only declared, and libturt_runtime.a supplies them.
4. Several copies of the runtime exist:
   • the preamble emitted into each program;
   • the host runtime compiled into tur and libturi.a (tur_core);
   • libturt_runtime.a;
   • libturt_preamble.a;
   • the bare src/runtime/*.c sources that stdlib's __tur_autolink__ markers name.
5. The S2 split generates, from one canonical emission (every gate on), three committed files under src/runtime/generated/: the runtime as one TU, its declarations, and an embedded copy of the declarations plus a hash. At build time the compiler re-emits the canonical text and hashes it. On a match, it swaps the program's preamble for the declarations. On a mismatch, it keeps the whole preamble. That is never wrong, only slower, so a stale artifact goes unnoticed unless a probe checks for it. CI has those probes.
6. Per-thread state that both halves of a split program touch lives in src/runtime/tur_tls.c. Each half reaches it in whichever of three spellings its compiler can manage.

---

Source map

---

Where the runtime's C text comes from

Three ways it is authored

The collector is the awkward case. src/runtime/{rc,gc,rc_free_queue}.c is the maintained copy. emit_runtime_preamble also carries a hand-written replica as string emitters, which a program runs only when it does not link the archive (see Postures). tools/gc-copy-diff.py measures the drift between the two. On 2026-10-16 it reported 29 identical functions, 30 divergent ones, and 16 that exist only in the runtime.

What a preamble looks like, in order

The order is load-bearing. Several comments in emit_runtime_preamble record a build that broke because a block moved.

Two things are emitted after the marker by every caller, deliberately:

• emit_hoisted_includes: the #include lines elaboration lifted out of inline-C bodies. They are per-program, so inside the marked span they would make the span differ from the canonical text, and the split would disengage for every C-binding spice. That is exactly what jit-s2-split-disengages-on-hoisted-inline-c-include was.
• emit_panic_site_slot: the tur_cur_site thread-local. A thread-local inside the span is reached through a host accessor call in a split build, which would cost two calls around every vec-get. Below the marker it is a native thread-local under gcc/clang.

The end marker is emitted unconditionally, in every mode, so any consumer can split any emitted C at it. Nothing in the compiler except the split reads it.

Feature gates

Most of the preamble is unconditional. The gated parts are switched by four kinds of input:

The CPS scans are computed once, as the cps_uses_* constants partway through emit_runtime_preamble, and every later gate reads those constants. The scans look for the presence of a form, not at whether the CT-IR backend lowered it. That way a delimited form in a function the backend evicted still gets its prelude (see the CPS/DK internals guide).

Every scan gate is written g_rt_split_all_gates || shared || <scan>. shared forces the block on for tur_runtime.h, which has to serve every module. g_rt_split_all_gates forces it on for the canonical S2 text.

---

Postures: how the same text links three ways

emit_runtime_preamble(out, program, shared) writes one text, but how its definitions link depends on the mode.

Single-file (shared == false, emit_program). One self-contained TU. Globals are static (emit_rt_global writes static <body>), and most runtime functions are written static literally. Two groups have external linkage: the dozen or so functions spelled with the rt_fn prefix (the STM API among them), which is empty in this mode, and the rc/GC API (rcgc_api). The output is meant to be byte-identical to what it was before the other postures existed, which is why so many helpers take a shared flag and do nothing when it is false.

Shared (shared == true, emit_shared_runtime_header -> tur_runtime.h). This is used by project builds and --shared libraries:

• cmd_build_multi_files writes tur_runtime.h plus a one-line owner TU, tur_runtime.c, which #defines TUR_RT_OWNER and includes the header.
• emit_rt_global defines each global only under TUR_RT_OWNER and declares it extern everywhere else.
• Ordinary runtime functions are replicated static into every module (rt_fn is static in this mode). They all operate on the one set of globals.
• The rc/GC family is defined once, inside the owner guard, at TUR_RT_LOCAL (hidden) visibility, so a .so does not export its collector. emit_rcgc_prototypes gives the other modules the declarations (DEDUP-3). The pasted region runtime sits inside the same owner guard.
• program is NULL, and every scan gate is forced on.

Archive (g_rcgc_from_archive, DEDUP-4b). The rc/GC and region definitions are left out, and the program links libturt_runtime.a instead:

• emit_rt_defs_begin records the buffer length, and emit_rt_defs_end truncates back to it, so the definitions are not just disabled but gone.
• emit_rcgc_global omits each global outright instead of declaring it extern. The two copies disagree on some types (rc_free_queue is an array in one and a struct in the other), and an extern with the wrong type links silently.
• emit_region_runtime_bodies writes a one-line comment instead of the pasted sources.
• emit_rcgc_prototypes spells the allocator's value_type parameter as uint8_t to match rc.c. The replica spells it int.

resolve_rcgc_from_archive (src/driver/pipeline.c) chooses the archive posture before emission. The checks run in this order, and the first that applies wins:

1. TUR_RCGC_FROM_ARCHIVE=0 -> replica.
2. --runtime=source -> replica.
3. Not emitting for a link tur performs itself (g_emit_for_link false: bare tur emit-c, --shared), and no TUR_RCGC_FROM_ARCHIVE=1 -> replica.
4. Otherwise -> archive, if and only if locate_runtime_lib finds libturt_runtime.a. =1 does not get around this: with no archive on disk you still get the replica.

emit_rcgc_from_archive() reports the decision back, so the link step can put the archive on the line. cmd_build_multi_files re-probes for it. Its omission was the "DEDUP-4b project half" bug: every multi-module executable failed with undefined reference to tur_region_shutdown.

Split units (the r7rs prelude split). emit_split_once_fns runs blocks that are the same in every unit, such as the DK machine, the deep-stack helper and r7gc.c, through emit_split_export_static_fns. The library unit then defines them once and the later units get prototypes. Outside a split it writes the text unchanged.

Thread-locals in emit_module.c go through emit_rt_tls, which writes #if defined(__GNUC__) || defined(__clang__) with the native variable, and #else with an extern accessor from tur_tls.c and a #define of the name. The emit_dk_runtime.c preludes spell the same two arms out by hand. See Per-thread state.

---

The copies of the runtime

Notes on this table:

• tur_rt_split.c replaced the host's own older copies of the same subsystems (runtime.c, cps_prompt.c, stm.c, scheduler.c, timer_wheel.c). Keeping both in tur_core would have been a duplicate-symbol error, and would have let the JIT's dlsym bind a program to the wrong one (see the comment beside it in src/CMakeLists.txt). The host runtime is the generated preamble.
• A static archive member is extracted only to resolve an undefined symbol. That is why libturt_runtime.a can carry rc.c and gc.c safely: a replica-posture program defines those symbols itself and never pulls the members in. It is also why libturt_preamble.a is its own archive. A program with the whole preamble defines its symbols, and pulling in one member of tur_rt_split.c would collide on all the rest.
• libturt_preamble.a is one object. Without --gc-sections (ELF) or -dead_strip (Mach-O), the first reference pulls in the whole preamble. A one-line program grew from 23 KB to 93 KB stripped before the section flags went in. MinGW links without --gc-sections today.
• cmake --build build --target tur builds neither archive. Programs built by a tur from such a tree run the replica and the whole preamble, and recompile the bare sources.

Which copy each build path uses

"Fixed runtime" means the part of the preamble above the marker, other than rc/GC and regions.

apply_runtime_lib_mode runs only when the program's autolink markers name a bare .c source. That is effectively always: a one-line program reaches hamt.c and trail.c through the stdlib it auto-loads. TUR_SHOW_CC=1 prints the final cc line, which shows every row of this table directly.

The GC guide covers the rc/GC column from the collector's side, including why a .so keeps its own.

---

The S2 split runtime

The fixed part of the preamble is the same in every program, but every program compiled it again: about 4,200 lines of a 9,300-line TU for a one-line program in archive posture, measured 2026-10-16. S2 compiles it once. It started as a JIT optimization (jit-guide) and became the cc path's default on Linux and Windows on 2026-10-02 (plan).

The canonical text

emit_rt_split_source produces the preamble that the artifacts describe. It is single-file linkage, feature-complete, and ends at the marker. Before it emits, it saves and forces this state, and afterwards it restores it:

Knobs (--backtrack-depth, experiments, dialect flags) are deliberately not normalized. The text reflects the current process, so the hash catches them. That is why a #lang r7rs or Saffron program always declines: its g_opt_r7rs / g_opt_dynamic_any blocks change the text.

tur emit-rt-split prints this text, and tur emit-rt-split --hash prints its xxHash64 (tur_hamt_hash_xxh64, the same function the guard uses). cmd_emit_rt_split also forces the archive posture before calling.

The generator

tools/gen-runtime-split.py --tur ./build/tur [--out src/runtime/generated] runs tur emit-rt-split twice (the text and the hash), splits the text at the marker, and walks the preamble line by line. The main rules:

Every rule in that table was added after a failure:

• tur_frame_* were inlined into the decls half because, behind an opaque call, a 536-byte tur_frame could no longer be optimized away. The stack frame of every scope with a defer grew about 6.7x, and a Windows fixture overflowed its 2 MiB stack.
• tur_closure_headers_enabled gets the guard because each simpler fix broke something. Declaring it extern broke the JIT's jit_sync_config_globals handshake, which needs a data item in the program. Making it weak broke the PE/COFF link.
• The thread-local guard rewrite exists because a hosted gcc build took the native branch and gave the program private copies of tur_panicking and tur_current_fiber. That broke every fiber, async, panic and catch-unwind fixture at once.

The preamble's choice between #include "hamt.h" and loose extern declarations differs from program to program. That is why project includes are guarded out of the hosted decls, and why jit_try_split_preamble copies the program's own quoted includes back in. See cc-path-split-windows-and-hamt-findings.

The three committed files

The generator writes with newline='\n', so a regeneration on Windows is not a whole-file CRLF diff.

Engaging: jit_try_split_preamble

One function serves cmd_jit, the REPL's JIT image build, and cmd_build. It returns false (the caller keeps the whole TU) when:

1. TUR_JIT_NO_SPLIT is set;
2. the hash of a fresh canonical emission under the current process state differs from tur_rt_split_hash;
3. the start or end marker is missing from the program's TU.

Note what the hash covers. It does not hash the program's own preamble, which has fewer gates on. It checks that this compiler, in this process state, still produces the text the artifacts were generated from. The swap then replaces the program's preamble with the full declarations region, which declares a superset of what the program's preamble defined.

On success the output is:

1. whatever came before the start marker (hoisted user text);
2. the embedded decls region;
3. every quoted #include "..." line the replaced span contained;
4. everything after the end marker.

Under TUR_JIT_TIMING=1 each decline prints a tab-separated line, TUR_JIT_TIMING split disengaged <reason>, to stderr.

On the cc path (cmd_build_once):

• --runtime=split always tries the swap and prints a message when it declines. It is refused for --target wasm.
• --runtime=auto tries it when preamble_split_auto_applies() holds and the build is not an r7rs prelude split. That requires:
  • TUR_PREAMBLE_SPLIT is not 0;
  • the host is Linux or Windows, unless TUR_PREAMBLE_SPLIT=1;
  • not --debug;
  • no -fsanitize in TUR_CC_FLAGS;
  • the program's own preamble is in archive posture;
  • libturt_runtime.a and libturt_preamble.a sit side by side.
• __tur_include__ hoisting runs after the swap. Hoisting first put #include "hamt.h" inside the span the swap deletes.
• The link line gets -lturt_preamble -L<dir> plus --gc-sections or -dead_strip. The compile gets -DTUR_RT_SPLIT_HOSTED, which selects the extern / direct-read / no-project-include arms of the decls.

The archive's hash is not checked. A libturt_preamble.a from another build, sitting beside a newer tur, would link rather than decline. The plan lists this under "Left".

Per-thread state: tur_tls.c

c2mir parses _Thread_local and then treats the variable as an ordinary global, and it has no __thread at all. So every runtime thread-local that code compiled by c2mir might touch has a slot in src/runtime/tur_tls.c. The slot is a real __thread variable in the host, with an accessor that returns its address:

__thread int tur_tls_panicking = 0;
int *tur_tls_panicking_ptr (void) { return &tur_tls_panicking; }

Slots are typed void *, int, bool, int64_t, size_t, intptr_t, jmp_buf or aligned raw bytes. The emitted macro casts back to the preamble-private type. A name reaches its storage in one of three ways:

TUR_TLS_FRESH (clang, gcc on Windows, the sanitizers) is a separate mechanism layered on top. These compilers keep a thread-local's address live across a call, and a fiber can resume on another thread. So a thread-local that moves with a fiber is read through a noinline accessor with a memory-clobbering asm. See fiber-tls-address-reuse.

The generator reads tur_tls.c with a regex instead of keeping its own table. Keep each slot to the two-line shape above: a __thread definition, then a one-return accessor. The generator exits with an error on a static __thread.

The generator's TLS table (name -> type and accessor) decides which preamble thread-locals the runtime TU routes to that storage. A thread-local outside the table becomes a separate native variable in tur_rt_split.c, while the program half still reaches tur_tls.c's slot through its #else / direct arm. That gives two storages. It is harmless only while no program-half code touches the name. Today the call/cc escape set (tur_escape_live*) and the r7rs dynamic environment (tur_r7rs_dyn) are outside the table. The r7rs prelude's inline-C reads both, and only r7rs programs reach that code, which never take the split.

CI checks

The split fails closed, so CI checks that it is actually taken. Each of these probes was added after the split silently disengaged and nobody noticed:

tests/run.sh asks the same question (one probe build) and folds the resolved preamble mode into its stamp cache key. Before that, an A/B run of the two paths reported green for a run that never happened (report).

---

Changing the preamble safely

Any change to the text above the marker changes the canonical hash. That includes text in emit_dk_runtime.c, in a pasted src/runtime source, or in a knob's default. Without a regeneration, the split disengages on every platform, and only CI's probes notice.

The steps

1. Edit the emitter.

2. Rebuild all targets, so both archives exist: cmake --build build -j, not --target tur.

3. Regenerate, from the repository root (the default --out is relative):

   python3 tools/gen-runtime-split.py --tur ./build/tur
   

   It prints the line counts, the hash, and the static prototypes it kept.

4. Rebuild again. tur_core and libturt_preamble.a compile the new files. The canonical text does not depend on them, so one regeneration is enough; it does not need a second pass.

5. Check that it engages:

   # must equal the 0x...ull constant in tur_rt_split_embed.c
   ./build/tur emit-rt-split --hash
   printf '(defn main [] : int 0)\n' > /tmp/p.tur
   # JIT: probe == committed
   TUR_JIT_SPLIT_DEBUG=1 ./build/tur jit /tmp/p.tur 2>&1 | grep split-debug
   # cc (Linux/Windows): the link line names -lturt_preamble
   TUR_SHOW_CC=1 ./build/tur build /tmp/p.tur -o /tmp/p 2>&1 \
     | grep -c turt_preamble
   

6. Regenerate the fixture snapshots with the loop in CLAUDE.md ("Fixture Snapshots"). The tests/fixtures/*/expected.c files are bare tur emit-c output: the whole preamble, in replica posture. Any preamble change moves all 157 of them. Commit them in the same PR.

7. If you touched the rc/GC text, run tools/gc-copy-diff.py (add --diff for the hunks), and port the change to src/runtime/{rc,gc,rc_free_queue}.c, or the other way round. Compiled programs that link the archive run the .c files. Bare emit-c, --shared and archive-less builds run the replica.

8. Commit the emitter change, the three generated files and the snapshots together.

Adding a gate

A new per-program flag that changes text above the marker has to be added to the forced set, the rt_split_forced[] table above emit_rt_split_source (one row: the flag and its canonical value; the loop saves, forces and restores it), and the artifacts regenerated. Otherwise every program that sets the flag hashes differently and silently loses the split. g_needs_dlfcn is the live example. call-ptr and dlopen set it, it is not forced, and so those programs keep the whole preamble (on 2026-10-16 jit-ffi-call-ptr hashed to f0aa6e93ec129085 against a committed ac7ad1dcc6c613ab). The plan records this. The CI probe cannot catch it, because its one-liner sets no flags.

A gate that is really a knob (it should change behavior, not just which code is present) stays out of the forced set. Programs built with that knob then decline, which is correct.

If a gated block would be wrong in the canonical text, branch on rt_split_canonical_emission(). The regex.h block does this, so the committed TU never contains the Windows #error.

Adding a thread-local

1. Emit it with emit_rt_tls, giving the native definition, the extern declaration, the name, the accessor's return type, the accessor's name and a cast. The helper also registers it as an r7rs-gc root, through r7gc_note_tls_root.
2. Add the two-line slot to src/runtime/tur_tls.c. That file is in both tur_core and TURT_RUNTIME_SOURCES.
3. Add the name to the TLS table in tools/gen-runtime-split.py if the runtime half and the program half can both touch it.
4. If it belongs to the running code rather than the thread, swap it in tur_fiber_block_resume and give it a TUR_TLS_FRESH accessor. tur_panicking belongs to the thread and does not.
5. Regenerate.

Spelling rules: c2mir, Windows, and two halves

The preamble is compiled by gcc, clang, MinGW gcc, emcc and c2mir, and a split program has two halves that may be compiled by different front ends.

Adding a host runtime file

A .c file a compiled program calls by name, as opposed to text the emitter pastes, belongs in both TUR_CORE_SOURCES (so the JIT and the interpreter can resolve it) and TURT_RUNTIME_SOURCES (so a cc build can link it). Two archived reports are about a file that was in only one list: symbols.c missing from libturi.a (libturi-symbols-basename-collision), and contract_handler.c missing from the lean archive (o0-build-cannot-link-contract-handler, hidden at -O2 because dead-code elimination removed the only reference).

---

Pitfalls from the archive

---

Debugging

To find why a hash differs, dump the probe from the failing invocation (TUR_JIT_SPLIT_DEBUG=/abs/path) and diff it against plain tur emit-rt-split. The first differing block names the gate or knob.

---

Bugs found while writing this guide

Each was reproduced against the compiler this guide describes and filed in docs/reported/. When one is fixed and archived, update the passage above that describes it and drop it from this list.

• regions-off-source-runtime-link-failure -- TUR_REGIONS=0 fails to link when the runtime comes from source

Maintenance

Update this guide in the same PR when you:

• add or remove a linkage posture, or a runtime archive or its members;
• add a state input to emit_rt_split_source's forced set, or change a generator rule;
• add a tur_tls.c slot or a TLS table entry;
• change what preamble_split_auto_applies or resolve_rcgc_from_archive checks;
• add or retire a CI probe.

The line counts and hashes quoted here are dated measurements. Refresh them with tur emit-rt-split | wc -l and tur emit-rt-split --hash when the shape they illustrate changes. Cite functions, not line numbers.