Compiler / C99 ABI and libsilk.a

C99 ABI and libsilk.a

This document defines the C99 ABI and the interface of the libsilk.a static library.

The installed archive bundles the Zig compiler runtime helpers used internally by the compiler, including quad-precision arithmetic. Linking a C99 embedder with the platform C linker does not require a Zig installation or a separately located compiler runtime archive.

Goals#

  • Provide a stable C ABI for embedders.
  • Mirror the external-declaration semantics described in ext.
  • Keep the ABI small, explicit, and well-documented.

No open-world interface-object ABI#

Silk’s ordinary interface feature is a language-level conformance mechanism. In the compiler, runtime interface values are implemented only through the closed-world compilation strategy documented in interfaces:

  • the compiler discovers the conformers visible in the current build,
  • lowers an interface-typed runtime value to a concrete union of those conformers,
  • and rewrites interface method calls into ordinary dispatch over that union.

This document does not define a generic C ABI for arbitrary Silk interface values. In particular, libsilk.a does not promise:

  • a public SilkInterface object,
  • a stable (data pointer, vtable pointer) trait-object layout,
  • or an open-world ABI where separately compiled libraries can exchange unknown future conformers through one stable interface-object representation.

Practical consequence:

  • embedders must treat ordinary interface values as an internal compiler lowering choice, not as a stable cross-language interchange format,
  • exported and imported ABI surfaces should use concrete structs, enums/unions, scalars, strings, ranges, handles, and other explicitly documented ABI shapes,
  • and if an embedding boundary needs dynamic dispatch, that dispatch contract must be designed explicitly in the ABI itself, for example as a concrete function-table struct chosen by the API author.

Library & Headers#

Embedders should prefer #include <silk/silk.h>. The flat include/silk.h wrapper remains available for compatibility during the transition.

Each silk_compiler_build and silk_compiler_build_to_bytes call separates temporary type-checker storage from the AST storage retained through code generation. Checker buffers are reclaimed during checking instead of accumulating for the entire build. All remaining scratch storage is released when the call returns, including on errors; the compiler-owned last-error message remains valid until the next operation or compiler destruction. Module-set checker allocation exhaustion is reported as out of memory while type checking, without a language-feature diagnostic code.

Compiler memory consumption depends on the input and loaded modules. The C99 regression suite exercises ordinary prelude-backed builds under a 2 GiB address-space limit on Linux; this is a regression bound, not a public memory quota or a guarantee for arbitrary programs.

Linking When Static Z3 Is Bundled#

When the host-native vendor/lib/<host-layout>/libz3.a archive is present, libsilk.a includes built-in Z3 to support Formal Silk verification without requiring a runtime Z3 dynamic library. The built-in Z3 static library is built as C++, so downstream embedders linking against libsilk.a MUST also link the system C++ runtime and any required system libraries:

cc -std=c99 -Wall -Wextra \
   -I/path/to/include your_app.c \
   -L/path/to/lib -lsilk \
   -lstdc++ -lpthread -lm

The silk cc wrapper adds these flags automatically when linking on linux/x86_64.

If the static host archive is absent, libsilk.a still builds. Formal Silk verification then requires a dynamic Z3 override via silk_compiler_set_z3_lib or SILK_Z3_LIB.

The header must define:

  • Core bridged types (e.g. SilkString, and any other structs or enums used by the ABI).
  • Opaque handle types (SilkCompiler, SilkModule, SilkError) and their lifetime rules.
  • Entry points for:
  • initializing and shutting down compiler/runtime state,
  • configuring compilation (target triple, stdlib name, optimization level),
  • adding source buffers,
  • compiling Silk source to executables, libraries, or object files,
  • serializing AMDGPU AQL dispatch packets for embedder-owned runtime paths,
  • interacting with diagnostics and error reporting.

Initial C Header Shape (include/silk/silk.h)#

The initial C header provided in the Silk compiler repository defines:

  • SilkString mirroring the internal Silk string layout:
  • Note: SilkString is also the C ABI shape for Silk regexp values (bytecode-backed { ptr, len }), but the bytes are opaque and not required to be null-terminated.
typedef struct SilkString {
    char   *ptr;
    int64_t len;
} SilkString;
  • SilkBytes for owned binary buffers returned by in-memory build APIs:

    typedef struct SilkBytes {
        uint8_t *ptr;
        int64_t  len;
    } SilkBytes;
    
  • SilkRange mirroring the Silk range primitive:

    typedef struct SilkRange {
        int64_t  start;
        int64_t  end;
        uint64_t flags;
    } SilkRange;
    

Notes:

  • The linux/x86_64 backend subset passes and returns range values as three 8-byte scalar slots (start, end, flags).

  • flags is a bitfield:

  • bit 0: has_end (when unset, end is ignored),

  • bit 1: inclusive (only valid when has_end is set).

  • Generated C callback values use the c_fn (P...) -> R language type and occupy one native code-pointer slot. A Silk fn (P...) -> R value occupies two internal slots (func_ptr, env_ptr) and is not itself C-compatible. An explicit signature-identical fn-to-c_fn cast checks that env_ptr is zero before exposing the code pointer; a nonzero environment traps. This conversion does not change the public libsilk API or the generated C callback calling convention.

  • unsafe fn and unsafe c_fn use the same machine calling conventions as their safe counterparts. unsafe is a Silk compile-time call effect and does not add fields, hidden parameters, or public libsilk ABI state.

  • 128-bit scalar primitives (i128 / u128 / f128) used by generated C headers for exported Silk interfaces:

    typedef struct SilkU128 {
        uint64_t lo;
        uint64_t hi;
    } SilkU128;
    
    typedef struct SilkI128 {
        uint64_t lo;
        int64_t  hi;
    } SilkI128;
    
    typedef struct SilkF128 {
        uint64_t lo;
        uint64_t hi;
    } SilkF128;
    

Notes:

  • SilkF128 stores the IEEE‑754 binary128 bit pattern. It is not C long double.

  • These types are passed and returned as two integer-like 8-byte slots in the linux/x86_64 backend subset.

  • Package export symbol helpers for C/Objective-C bridge headers:

    SILK_C_ABI_EXPORT_FN(lumen_trail, silk_ios_daily_score)
    /* expands to lumen_trail_silk_ios_daily_score */
    
    SILK_PACKAGE_EXPORT_FN(lumen_trail, silk_ios_daily_score)
    /* expands to __silk_export_fn__lumen_trail__silk_ios_daily_score */
    
    SILK_PACKAGE_EXPORT_DATA(my_pkg, answer)
    /* expands to __silk_export_data__my_pkg__answer */
    

Notes:

  • The macro arguments must be C identifier tokens.

  • For nested Silk packages, pass the spelling that matches the selected symbol family. SILK_C_ABI_EXPORT_FN uses the clean C ABI package spelling with namespace separators collapsed to one _, so package ui::model is passed as ui_model. SILK_PACKAGE_EXPORT_FN and SILK_PACKAGE_EXPORT_DATA use the reserved default Silk package spelling where each : becomes _, so the same package is passed as ui__model.

  • SILK_C_ABI_EXPORT_FN matches exported functions declared as export attr(abi=c) fn ... or attr(abi=c) export fn ... in a named package.

  • SILK_PACKAGE_EXPORT_FN and SILK_PACKAGE_EXPORT_DATA match the default Silk package export symbols that keep the reserved __silk_export_*__ prefixes.

  • These helpers are spelling aids for named-package bridge headers. They do not change Silk import/export semantics, and they do not make named-package exports part of the generated --c-header surface.

  • Opaque handles:

    typedef struct SilkCompiler SilkCompiler;
    typedef struct SilkModule   SilkModule;
    typedef struct SilkError    SilkError;
    
  • An output-kind enum:

    typedef enum SilkOutputKind {
        SILK_OUTPUT_EXECUTABLE = 0,
        SILK_OUTPUT_STATIC_LIBRARY = 1,
        SILK_OUTPUT_SHARED_LIBRARY = 2,
        SILK_OUTPUT_OBJECT = 3,
    } SilkOutputKind;
    
  • ABI version query:

    void silk_abi_get_version(int *out_major,
                              int *out_minor,
                              int *out_patch);
    
  • AMDGPU AQL packet helpers:

    #define SILK_AMDGPU_AQL_DISPATCH_PACKET_SIZE 64
    
    typedef enum SilkAmdGpuAqlFenceScope {
        SILK_AMDGPU_AQL_FENCE_SCOPE_NONE = 0,
        SILK_AMDGPU_AQL_FENCE_SCOPE_AGENT = 1,
        SILK_AMDGPU_AQL_FENCE_SCOPE_SYSTEM = 2,
    } SilkAmdGpuAqlFenceScope;
    
    typedef struct SilkAmdGpuAqlDispatchPacketConfig {
        uint16_t dimensions;
        uint16_t workgroup_size_x;
        uint16_t workgroup_size_y;
        uint16_t workgroup_size_z;
        uint32_t grid_size_x;
        uint32_t grid_size_y;
        uint32_t grid_size_z;
        uint32_t private_segment_size;
        uint32_t group_segment_size;
        uint32_t max_flat_workgroup_size;
        uint64_t kernel_object;
        uint64_t kernarg_address;
        uint64_t completion_signal;
        uint8_t  barrier;
        int32_t  acquire_fence_scope;
        int32_t  release_fence_scope;
    } SilkAmdGpuAqlDispatchPacketConfig;
    
    bool silk_amdgpu_aql_dispatch_packet_build(
        const SilkAmdGpuAqlDispatchPacketConfig *config,
        uint8_t                                *out_packet);
    
  • Compiler lifecycle:

    SilkCompiler *silk_compiler_create(void);
    void          silk_compiler_destroy(SilkCompiler *compiler);
    
  • Configuration:

    bool silk_compiler_set_stdlib(SilkCompiler *compiler, SilkString stdlib_name);
    bool silk_compiler_set_std_root(SilkCompiler *compiler, SilkString std_root);
    bool silk_compiler_set_nostd(SilkCompiler *compiler, bool nostd);
    bool silk_compiler_set_debug(SilkCompiler *compiler, bool debug);
    bool silk_compiler_set_noheap(SilkCompiler *compiler, bool noheap);
    bool silk_compiler_set_target(SilkCompiler *compiler, SilkString target_triple);
    bool silk_compiler_set_z3_lib(SilkCompiler *compiler, SilkString path);
    bool silk_compiler_set_std_archive(SilkCompiler *compiler, SilkString path);
    bool silk_compiler_add_needed_library(SilkCompiler *compiler, SilkString soname);
    bool silk_compiler_add_runpath(SilkCompiler *compiler, SilkString path);
    bool silk_compiler_set_soname(SilkCompiler *compiler, SilkString soname);
    bool silk_compiler_set_optimization_level(SilkCompiler *compiler, int level);
    bool silk_compiler_set_c_header(SilkCompiler *compiler, SilkString path);
    

silk_compiler_set_std_root configures the filesystem stdlib root directory used to auto-load std::... packages when modules contain import std::...;. The std_root string is copied. When set, it overrides SILK_STD_ROOT and the working-directory/default search behavior described below.

silk_compiler_set_nostd disables this stdlib auto-loading behavior when set to true. When nostd is enabled, import std::...; declarations must be satisfied by explicitly adding the corresponding std sources as modules (for example via silk_compiler_add_source_buffer); the compiler will not consult SILK_STD_ROOT or the filesystem std root search paths.

silk_compiler_set_debug enables the same debug build mode as the CLI (silk --debug): debug-mode lowering for supported native outputs, and additional Z3 debug output plus .smt2 reproduction scripts on failing Formal Silk obligations (written under .silk/z3/ or $SILK_WORK_DIR/z3).

silk_compiler_set_noheap enables the same no-heap mode as the CLI (silk --noheap): heap-backed allocation is disabled for the supported subset. --noheap is incompatible with --debug; the ABI rejects configurations that enable both.

silk_compiler_set_optimization_level selects the optimization level (0-3), matching the CLI -O flag. The default is level 0 unless overridden. Level 1+ enables lowering-time pruning of unused extern symbols before code generation. For IR-backed native executable builds, it also prunes unreachable functions from the executable entrypoint (function-level dead-code elimination), typically reducing output size and over-linking when using the prebuilt libsilk_std.a archive to satisfy auto-loaded import std::...; modules. The CLI also exposes silk build --strip-unused to force analogous reachability-based pruning at -O0 for executable/static/shared outputs; the current C ABI does not yet expose a separate setter for that flag.

silk_compiler_set_target selects the code generation target. The target_triple string is copied. The implementation recognizes the same targets as the CLI (silk build --list-targets), including:

  • linux-x86_64 (default), and common x86_64-*-linux-* triples such as x86_64-linux-gnu and x86_64-unknown-linux-gnu,
  • linux-aarch64,
  • android-aarch64,
  • macos-x86_64,
  • macos-aarch64,
  • ios-aarch64,
  • ios-simulator-aarch64,
  • ios-simulator-x86_64,
  • windows-x86_64,
  • windows-aarch64,
  • wasm32-unknown-unknown,
  • wasm32-wasi (and other wasm32 triples containing wasi),
  • amdgcn-amd-amdhsa-gfx942,
  • amdgcn-amd-amdhsa-gfx1100,
  • amdgcn-amd-amdhsa-gfx1151.

For linux-aarch64 and linux-aarch64-musl, SILK_OUTPUT_EXECUTABLE first attempts the direct AArch64 IR backend. Its AAPCS64 subset covers integer and f32/f64 scalar constants, numeric/raw casts, arithmetic, bitwise operations, shifts, comparisons, stack/data memory, function/data addresses, CFG branches, direct/indirect helpers, and external scalar function/data imports. Integer parameters/results use x0…x7, floating-point parameters/results use v0…v7, and the two register banks advance independently. Additional classified arguments spill to the aligned caller stack. External C calls return one or two flattened scalar slots in the classified result registers; larger C aggregate results use the AAPCS64 indirect-result pointer in x8. Compiler-internal Silk calls keep their eight-slot result-register contract and use hidden caller-provided storage only for larger results. External imports or configured needed/runpath metadata select a dynamically linked GNU- or musl-interpreted PIE. Executable/shared output can select and relocate the required bundled-runtime archive closure and consume explicit AArch64 relocatable-object/archive inputs without an external linker. SILK_OUTPUT_OBJECT, SILK_OUTPUT_STATIC_LIBRARY, and SILK_OUTPUT_SHARED_LIBRARY use the same scalar selector to emit EM_AARCH64 ELF64 objects, indexed GNU archives, and loadable ET_DYN shared objects. Object/archive output carries AArch64 relocations; shared output supports exported data, external scalar imports, embedded-pointer relocations, and configured needed/runpath/soname metadata. When compilation runs natively on Linux AArch64, .c/.h inputs, link-only C executables, -L plus -l/-l:<file>, and relocation-free inline assembly are supported. Framework options remain Apple-only, and unrecognized raw linker flags remain outside the Linux AArch64 in-process linker. A program that reduces to a constant main can still use the target-aware const-main fallback. For main(argc: int, argv: u64), the entry stub passes the Linux process argument count in x0 and the raw argv-list pointer in x1. Direct and constant-fallback ELF images declare an explicit read/write, non-executable stack with PT_GNU_STACK.

For wasm32 targets, only SILK_OUTPUT_EXECUTABLE is supported. The output bytes are a final WebAssembly module (.wasm) produced by the IR-backed wasm backend (src/backend_wasm_ir.zig), with a smaller constant-only fallback for programs that fit the constant subset.

For AMDGPU targets, SILK_OUTPUT_OBJECT emits an AMDHSA .hsaco code object for the source-kernel subset: exactly one exported root-package void function with up to 32 immutable u64 parameters whose body is empty or contains only supported compiler-backed GPU call statements. Low-level __silk_amdgpu_* calls retain integer-literal operands; the semantic std::gpu::device::store_u32_at_global_x and std::gpu::device::classify_u32_at_global_x helpers accept direct kernel parameter names. Dependency-package exports do not count as kernels. The function name becomes the AMDHSA kernel metadata name and the descriptor symbol is kernel_name.kd. Metadata register counts are derived from the highest SGPR/VGPR referenced by the accepted source intrinsics, with 32 SGPRs and 64 VGPRs as minimum values. backend amdgpu documents the canonical source-intrinsic declaration sets and authoring diagnostics.

The provider-neutral mixed CPU/GPU executable option is a silk build --gpu-target CLI surface, not a libsilk compiler-setting function. This GPU-v1 work does not change the C99 ABI. Embedders retain the documented standalone AMDGPU object and AQL packet APIs.

The wasm backend is still early-stage, but it is no longer limited to single-module constant programs:

  • Multi-module builds (packages + file imports) are supported.
  • ext foo = fn (...) -> ...; declarations become imported functions under env.foo for wasm32-unknown-unknown, analogous to extern symbols in C.
  • String and other constant data are emitted into wasm data segments.

Entrypoint conventions:

  • wasm32-unknown-unknown:
  • when a valid executable main exists, it is exported as main for embedder use,
  • when no main exists, an export-only module is emitted that exports each supported export fn from the root package.
  • wasm32-wasi:
  • requires fn main () -> int (the main(argc, argv) form is not supported yet for WASI),
  • programs that need process arguments must read them from WASI inside main() (for example via std::args::{argc,argv,current}),
  • emits an exported _start () -> void wrapper that calls main and then imports/calls WASI proc_exit,
  • export-only modules are supported for embedding (export-only modules do not include _start).

silk_compiler_add_needed_library records a dynamic loader dependency for executable and shared library outputs (emitted as DT_NEEDED). The soname string is copied; the function may be called multiple times (duplicates are ignored). For static library and object outputs, the value is ignored. Linux AArch64 executable output emits a dynamically linked PIE when DT_NEEDED metadata or external scalar imports are present. GNU targets use /lib/ld-linux-aarch64.so.1; musl targets use /lib/ld-musl-aarch64.so.1. DT_NEEDED entries starting with libsilk_rt are rejected: bundled runtime helpers are linked statically from the target/libc-matched archive and must not become runtime loader dependencies. Linux AArch64 glibc and musl outputs use distinct archives so C-library structure layouts and constants cannot cross the target ABI boundary. The AArch64 musl archive supplies the async runtime's private AAPCS64 context switch, so generated async executables do not import musl's unimplemented getcontext, makecontext, or swapcontext declarations. On Linux x86_64 and Linux AArch64, when an executable or shared library imports external system symbols, the compiler automatically adds the selected libc as a DT_NEEDED dependency (libc.so.6 for glibc, libc.so for musl), so embedders do not need to manually add libc when using hosted std:: modules like std::io and std::fs. Additional non-libc dependencies must still be declared via silk_compiler_add_needed_library.

silk_compiler_add_runpath records a dynamic loader search path element for executable and shared library outputs (emitted as DT_RUNPATH). The path string is copied; the function may be called multiple times (duplicates are ignored) and the final DT_RUNPATH string is formed by joining all entries with ':'. Linux AArch64 dynamically linked executables and shared libraries preserve the resulting value as DT_RUNPATH.

silk_compiler_set_soname configures the shared library soname recorded as DT_SONAME for shared library outputs. The soname string is copied; passing an empty string clears the configured soname (no DT_SONAME entry). For executable, static library, and object outputs, the value is ignored.

silk_compiler_set_z3_lib configures a Z3 dynamic library override for Formal Silk verification (equivalent to the CLI --z3-lib <path>). Passing an empty string clears the override and returns to the normal Z3 selection rules (including honoring SILK_Z3_LIB).

silk_compiler_set_std_archive configures a stdlib archive override (equivalent to the CLI --std-lib <path>). Passing an empty string clears the override and returns to the normal stdlib archive selection rules (including honoring SILK_STD_LIB).

On Linux AArch64, both executable build APIs reject an explicitly selected archive that leaves referenced generated Silk functions, methods, or data unresolved. The error names the missing symbol. Automatically discovered incomplete archives instead fall back to compiling std sources, including consumer-specific generic specializations. Ordinary native dynamic imports remain supported; no C99 signatures or layouts change.

silk_compiler_set_c_header configures C header generation for non-executable outputs (equivalent to the CLI --c-header <path>). The header is written when silk_compiler_build succeeds for SILK_OUTPUT_OBJECT, SILK_OUTPUT_STATIC_LIBRARY, or SILK_OUTPUT_SHARED_LIBRARY. C header generation is not supported for silk_compiler_build_to_bytes.

  • Source management:

    SilkModule *silk_compiler_add_source_buffer(SilkCompiler *compiler,
                                                SilkString    name,
                                                SilkString    contents);
    
  • Building artifacts:

    bool silk_compiler_build(SilkCompiler   *compiler,
                             SilkOutputKind  kind,
                             SilkString      output_path);
    

For embedders that need filesystem-free compilation (for example sandboxed hosts or WASM-like environments), the ABI also provides an in-memory build API that returns an owned byte buffer:

bool silk_compiler_build_to_bytes(SilkCompiler   *compiler,
                                  SilkOutputKind  kind,
                                  SilkBytes      *out_bytes);

void silk_bytes_free(SilkBytes *bytes);

The returned bytes are target-specific: for example an ELF64 binary on linux-x86_64, a .wasm module on wasm32 targets, or an AMDHSA .hsaco code object on AMDGPU object outputs.

Ownership rules:

  • On success, silk_compiler_build_to_bytes fills *out_bytes with a pointer and length describing the produced artifact, and returns true.
  • The returned out_bytes->ptr is owned by libsilk.a and must be freed by calling silk_bytes_free(&bytes). Callers must not free the pointer with free() (or any other allocator).
  • silk_bytes_free is a no-op when passed NULL or when bytes->ptr is NULL; it always clears the struct to { NULL, 0 }.

Note: the compiler may still consult the filesystem to auto-load std::... modules unless silk_compiler_set_nostd(compiler, true) has been set.

AMDGPU runtime packet helper:

  • silk_amdgpu_aql_dispatch_packet_build serializes a host-endian SilkAmdGpuAqlDispatchPacketConfig into a 64-byte HSA AQL kernel-dispatch packet.
  • The packet bytes use the HSA field offsets documented in backend amdgpu: header at 0..2, setup at 2..4, workgroup sizes at 4..10, grid sizes at 12..24, segment sizes at 24..32, kernel_object at 32..40, kernarg_address at 40..48, and completion_signal at 56..64.
  • The function returns false for null pointers, invalid fence-scope values, dimensions outside 1..3, zero workgroup or grid sizes, grids smaller than workgroups, non-1 unused dimensions, or flat work-group sizes larger than max_flat_workgroup_size. A zero max_flat_workgroup_size in the C config selects the conservative default of 1024 work-items. When out_packet is non-null, it is zeroed before validation, so failed calls leave no stale packet bytes.
  • The helper is independent of SilkCompiler and does not read or write the compiler last-error state.
  • The helper only builds the packet. Queue creation, executable loading, signal allocation, and doorbell submission remain the embedder or future ROCR runtime driver's responsibility.

Bundled POSIX runtime descriptor control:

  • include/silk/rt.h declares int silk_rt_fs_fcntl_int(int fd, int cmd, int arg) in the runtime support library. It forwards integer-valued fcntl commands to libc with the host's variadic convention and preserves libc's return value and errno. Pointer-valued commands are outside this helper's contract. Silk binds its three parameters as i32, including on Apple ARM64. This adds no entry point to the SilkCompiler API or change to its object layouts.

Current Apple host-backed note:

  • the CLI / driver now supports non-const ios-aarch64, ios-simulator-aarch64, and ios-simulator-x86_64 executable, object, static-library, and shared-library builds on Apple Silicon macOS for the pure-Silk scalar/library subset, including reachable float-to-int lowering and portable bundled runtime helper families (number / regex / unicode / filesystem / dns / process / signal / term / pty / readline / task-pool / async),
  • silk_compiler_build(...) and silk_compiler_build_to_bytes(...) now support that same iOS host-backed artifact subset on Apple Silicon macOS,
  • the remaining explicit E4001 iOS limitation is narrower: it now applies only to narrower unsupported bundled runtime-internal helper families, while portable bundled helpers, hosted async/task linkage, and float-to-int now link on this path.

At the current stage of implementation:

  • silk_compiler_build always performs full front‑end validation for all modules added via silk_compiler_add_source_buffer:

  • it lexes and parses each module into an internal representation,

  • it applies attr(...) declarations against the selected target before monomorphization and type checking, matching the CLI pipeline; this is required for attr(device=gpu) functions and target-gated declarations to retain their intended execution contract through both filesystem and in-memory output APIs,

  • it then type‑checks the set of modules as a unit, taking into account package/import relationships and exported constants, according to the language grammar and semantics documented under docs/language/,

  • if Formal Silk syntax is present (for example #require, #assure, #assert, #invariant, #variant, #monovariant, #const), it also runs the Z3-backed verifier and fails the build if verification fails (E3001..E3008),

  • the verifier is skipped for stdlib modules (std::...),

  • when the host-native archive is present, Z3 is linked from the built-in static archive vendor/lib/<host-layout>/libz3.a,

  • the verifier honors SILK_Z3_LIB (environment variable) to override the Z3 dynamic library at runtime,

  • it fails fast on the first front‑end error.

  • when packages/imports are present:

  • import declarations must refer to packages that exist in the current module set (otherwise a resolver error is reported, such as "unknown imported package"),

  • exported let bindings with explicit type annotations in an imported package are treated as ordinary, unqualified names in the importing modules for type‑checking purposes (for example, import util; and export let answer: int = 42; in util allows let x: int = answer; in app),

  • imported exported functions (export fn) are callable across packages for the scalar subset (both unqualified foo() and qualified pkg::foo() call forms are accepted initially), and functions in the same package share a call namespace across modules in the same module set,

  • duplicate exported names within a single package are reported as a resolver error ("duplicate exported symbol").

  • standard library import resolution (first slice):

  • when a module contains import std::...;, the compiler will attempt to auto-load the referenced std::... package modules from a configured stdlib root so embedders do not need to provide std sources explicitly in the common case,

  • the stdlib root is selected via:

  • silk_compiler_set_std_root when set, otherwise

  • SILK_STD_ROOT (environment variable) when set, otherwise

  • a std/ directory in the current working directory (development default), otherwise

  • ../share/silk/std relative to the current executable (installed default).

  • package-to-path mapping is deterministic:

  • std::foo::bar resolves to the file <std_root>/foo/bar.slk,

  • if the embedder explicitly provides a std::... module via silk_compiler_add_source_buffer, that module is treated as authoritative for its package (auto-loading does not replace already-provided packages).

  • standard library archive linking (linux/x86_64 and linux/aarch64, current archive layout):

  • the toolchain can build a target-specific stdlib static archive (libsilk_std.a) containing one ELF object per std module (for example via make stdlib),

  • the archive must match the selected target architecture; native Linux x86_64 and AArch64 staged builds produce their corresponding archive,

  • for supported executable builds, the compiler treats auto-loaded std::... modules as external during code generation and resolves their exported functions from the archive when available (while still type-checking the std sources as part of the module set),

  • archive discovery (in order):

  • SILK_STD_LIB when set, otherwise

  • build/lib/silk/std/libsilk_std.a when using the in-repo std/ root, otherwise

  • ../lib/silk/std/libsilk_std.a relative to the current executable, otherwise

  • ../lib/libsilk_std.a relative to the current executable (legacy installed layout), otherwise

  • common installed-layout heuristics derived from the selected stdlib root,

  • walk up from the current working directory to find libsilk_std.a, lib/libsilk_std.a, or lib/silk/std/libsilk_std.a,

  • when no suitable archive is found (or on unsupported targets), the compiler falls back to compiling the reachable std sources into the build as part of module-set code generation.

  • When a front‑end error occurs (e.g. parse error, type mismatch, invalid control‑flow such as break/continue/return in the wrong context, or other semantic violations), the call returns false and silk_compiler_last_error/silk_error_format provide a human‑readable description (such as "unexpected token while parsing module", "type mismatch", "invalid break statement", "invalid return statement", "missing return statement", etc.).

  • For executable outputs (kind == SILK_OUTPUT_EXECUTABLE), the compiler also enforces an entrypoint precondition on the front‑end:

  • there MUST be exactly one top‑level function with one of the forms

    fn main() -> int {... }
    
    fn main(argc: int, argv: u64) -> int {... }
    

with a declared result type of int, and either:

  • no parameters, or

  • exactly two parameters whose types are int and u64,

  • otherwise silk_compiler_build fails with an error message such as "no valid main function for executable output" or "multiple main functions for executable output".

  • When all modules pass front‑end validation (including the executable entrypoint requirement, where applicable), code generation behavior depends on kind:

  • for non-executable outputs (SILK_OUTPUT_OBJECT, SILK_OUTPUT_STATIC_LIBRARY, SILK_OUTPUT_SHARED_LIBRARY):

  • main is optional, but when more than one valid executable main exists in the module set, silk_compiler_build fails with "multiple main functions for non-executable output",

  • when multiple packages are present in the module set, only exports from the root package (the package of the first module added to the compiler via silk_compiler_add_source_buffer) are emitted as globally-visible symbols for that output; other packages are compiled as dependencies and their export declarations are treated as internal for that output.

  • within the linux/x86_64 IR subset, string and regexp values are supported at ABI boundaries in a C-friendly SilkString { ptr, len } layout:

  • string/regexp parameters lower to two integer-like scalars in order (u64 pointer, then i64 byte length) and consume the normal integer argument locations (registers then stack),

  • string/regexp results return as two integer-like scalars in rax/rdx,

  • regexp values remain opaque runtime-engine bytecode views: downstream C code may forward them, but must not construct them as if the byte layout were a stable public format,

  • regex literals and other borrowed regexp views are not caller-owned heap objects; only std::regex::RegExp.compile(...) produces runtime-owned regex bytecode,

  • when std::regex executes a foreign ABI-supplied regexp, the bundled runtime first validates the bytecode header/control-flow shape and reports malformed inputs as EXEC_ERR_INVALID_INPUT instead of entering the engine blindly,

  • when Silk code later frees or drops a regexp through the regex runtime, only those runtime-owned compiled values are released; borrowed/literal/foreign views are ignored safely,

  • the bundled runtime allocator override used by runtime regex compilation is process-global but internally synchronized; concurrent silk_rt_set_allocator(...) calls can affect which hook future runtime allocations use, but any individual allocation returned by silk_rt_malloc_bytes(...) keeps the realloc/free hooks that created it for its full lifetime, and foreign, forged, stale pre-realloc, or already-freed helper pointers that do not correspond to a live bundled-runtime allocation are ignored instead of steering helper realloc/free calls,

  • within function bodies, the compiler supports a small string/regexp expression subset:

  • string: string literals, let bindings of string, return of a string value, direct calls to string-returning helpers, and ==/!=/</<=/>/>= comparisons over string values (producing bool),

  • regexp: regex literals (/pattern/flags), let bindings of regexp, return of a regexp value, and direct calls between helpers that accept/return regexp,

  • other string operations (concatenation, indexing, etc.) are not implemented yet; higher-level regex matching lives in std::regex and is routed through ext calls.

  • within the linux/x86_64 IR subset, i128/u128/f128 values are supported at ABI boundaries using the stable C99 { lo, hi } struct shapes:

  • parameters lower to two integer-like scalars (u64 lo, then u64/i64 hi) and consume integer argument locations,

  • results return as two integer-like scalars in rax/rdx,

  • f128 values are transported as raw IEEE binary128 bits in the two lanes (not via SSE registers),

  • module-level constant-evaluable wide bindings and inferred local wide arithmetic use this same lane representation; source placement and a redundant local type annotation do not alter the ABI or lowering.

  • within the linux/x86_64 IR subset, a limited struct subset is supported at ABI boundaries:

  • within function bodies and internal helper calls, struct declarations with 0+ fields of supported value types are supported (scalar primitives, string, nested structs, and supported optionals),

  • at ABI boundaries for exported/FFI functions, only ABI-safe structs are supported: after slot-flattening, all scalar slots must be i64/u64/f64 (until packed ABI mapping for smaller fields is implemented),

  • ordinary borrowed references/slices are rejected up front on ext declarations and unnamed C-facing root-package export fn signatures; only opaque handle references (&Handle where Handle is struct Name;) may cross the external ABI boundary,

  • named-package Silk object exports may accept slice parameters (T[]) in the compiler-owned package ABI; these lower to two integer-like scalars (u64 pointer, then i64 element count) and are not emitted through C header generation,

  • at the C ABI surface, exported function parameters support 1+ slot ABI-safe structs by lowering the struct to its scalar slots in order; downstream C callers should declare separate parameters for 3+ slot structs (by-value C struct parameters are ABI-compatible only for the 1–2 slot cases), while exported function returns support 1+ slot ABI-safe structs (3+ slot returns use the native backend’s sret return path and are ABI-compatible with returning an equivalent C struct by value),

  • in all cases, the compiler lowers a struct value into N scalar slots in field order and assigns argument/result locations according to System V AMD64 integer/SSE classification for those slots.

  • named-package exported functions use the default package-qualified symbol __silk_export_fn__pkg__name unless the declaration uses export attr(abi=c) fn ... / attr(abi=c) export fn ...; C ABI exports omit the reserved prefix and emit clean C symbols by collapsing package :: namespace separators to _ and placing a single _ between the package namespace and function name; declaration-level attr(abi=c) is supported only on top-level exported functions, with functions nested inside inline module Name { ... } blocks rejected until that export path is implemented end to end; clean C ABI symbols that collide with another C ABI export or any other function symbol emitted for the selected output are rejected before object or library emission; library outputs apply this check to the root package's public C ABI symbols and the dependency functions as they are actually emitted into that output, including internal raw dependency symbols,

  • named-package exported data uses the default package-qualified symbol __silk_export_data__pkg__name,

  • C/Objective-C bridge headers should spell those symbols through SILK_C_ABI_EXPORT_FN(pkg, name), SILK_PACKAGE_EXPORT_FN(pkg, name), or SILK_PACKAGE_EXPORT_DATA(pkg, name) from silk/silk.h instead of hardcoding generated spellings,

  • within the linux/x86_64 IR subset, optionals (T?) are supported at ABI boundaries for the supported payload subset (scalar payloads, string?, and optionals of ABI-safe structs):

  • an optional lowers to a Bool tag followed by the payload scalar slots: (tag, payload0, payload1, ...) with tag=0 for None and tag=1 for Some(...),

  • nested optionals (T??) lower by treating the payload slots as the full inner optional representation (for example int?? lowers as (tag0, tag1, i64 payload)),

  • optional parameters are passed as these scalar slots in order (so downstream C callers should declare separate parameters, treating tag as an integer-like 0/1 value),

  • optional results return as the same scalar slots (1–2 slots in registers; 3+ slots via a hidden sret pointer as described above).

  • for object outputs (SILK_OUTPUT_OBJECT):

  • on linux/x86_64 and linux/aarch64, the compiler can emit an ELF64 relocatable object (ET_REL) for each backend's documented IR subset; on Apple Silicon macOS hosts, macos-aarch64, ios-aarch64, ios-simulator-aarch64, and ios-simulator-x86_64 can emit a Mach-O 64-bit relocatable object for the same host-backed library subset, emitting supported functions (scalar-returning, void-returning, and a limited string subset) and supported exported constants (export let/export const; scalar exports require an explicit type annotation and a literal initializer, and string exports may omit : string when the initializer is a string literal), and marking export fn declarations, supported exported constants, and a valid executable main (when present) as global symbols,

  • when the module set contains no supported globally-visible symbols (no supported export fn, no supported export let constants, and no valid executable main), silk_compiler_build still succeeds and writes a valid relocatable object with no globally-visible symbols,

  • for programs outside that subset (or on unsupported targets), silk_compiler_build returns false with an E4001 / E4002 formatted diagnostic (via silk_compiler_last_error / silk_error_format) and does not write an output file.

  • on amdgcn-amd-amdhsa-gfx942, amdgcn-amd-amdhsa-gfx1100, and amdgcn-amd-amdhsa-gfx1151, the compiler emits an AMDHSA .hsaco for exactly one exported source kernel in the AMDGPU intrinsic-call subset. The intrinsic declarations and user-facing diagnostics are documented in backend amdgpu. Arbitrary Silk IR lowering is not part of this C ABI output path yet.

  • when lowering cannot isolate a narrower statement / expression span, that E4001 diagnostic falls back to the offending function declaration and names that function directly.

  • for static library outputs (SILK_OUTPUT_STATIC_LIBRARY):

  • on linux/x86_64 and linux/aarch64, the compiler can emit a static library archive (.a) containing an object file for each backend's documented IR subset; on Apple Silicon macOS hosts, macos-aarch64, ios-aarch64, ios-simulator-aarch64, and ios-simulator-x86_64 can emit a Mach-O static archive via Apple libtool -static for the same host-backed library subset, emitting supported functions (scalar-returning, void-returning, and a limited string subset) and supported exported constants (export let/export const; scalar exports require an explicit type annotation and a literal initializer, and string exports may omit : string when the initializer is a string literal), and marking export fn declarations, supported exported constants, and a valid executable main (when present) as global symbols,

  • when the module set contains no supported globally-visible symbols (no supported export fn, no supported export let constants, and no valid executable main), silk_compiler_build still succeeds and writes a valid archive containing an object file with no globally-visible symbols,

  • for programs outside that subset (or on unsupported targets), silk_compiler_build returns false with an E4001 / E4002 formatted diagnostic (via silk_compiler_last_error / silk_error_format) and does not write an output file.

  • for shared library outputs (SILK_OUTPUT_SHARED_LIBRARY):

  • on linux/x86_64 and linux/aarch64, the compiler can emit an ELF64 shared library (ET_DYN, typically with a .so filename) for each backend's documented IR subset; on Apple Silicon macOS hosts, macos-aarch64, ios-aarch64, ios-simulator-aarch64, and ios-simulator-x86_64 can emit a Mach-O dylib for the same host-backed library subset, emitting supported functions (scalar-returning, void-returning, and a limited string subset) and supported exported constants (export let/export const; scalar exports require an explicit type annotation and a literal initializer, and string exports may omit : string when the initializer is a string literal), and marking export fn declarations, supported exported constants, and a valid executable main (when present) as dynamic global symbols,

  • when the module set contains no supported globally-visible symbols (no supported export fn, no supported export let constants, and no valid executable main), silk_compiler_build still succeeds and writes a valid shared library with an empty export set,

  • for programs outside that subset (or on unsupported targets), silk_compiler_build returns false with an E4001 / E4002 formatted diagnostic (via silk_compiler_last_error / silk_error_format) and does not write an output file.

  • for executable outputs (SILK_OUTPUT_EXECUTABLE):

  • the implementation supports a minimal constant‑expression backend:

  • the program must satisfy the entrypoint rule above,

  • the body of main must be one of the following shapes:

  • zero or more let statements whose initializers are constant integer expressions, followed by exactly one return statement that returns a constant integer expression built only from:

  • integer literals,

  • the arithmetic operators +, -, *, /, and %,

  • and references to immutable let bindings (top‑level or local to main, or imported exported scalar constants from imported packages) whose initializers are themselves constant integer expressions in this same sense (no side‑effecting operations); imported exported constants must be declared as export let or export const with the shape export <binding> name: <scalar> = <literal>; (explicit scalar type and literal initializer),

  • on linux/x86_64, direct calls to simple helper functions of the form

           ```silk
           fn helper (x, y) -> int {
             [let...;]
             return <expr>;
           }
           ```
    

where:

  • parameters may be annotated as scalar types (defaulting to int when unannotated),

  • arguments at each call site are drawn from the same scalar expression subset as <expr> (including bool, char, Instant, Duration, fixed-width integers, and f32/f64 on linux/x86_64), with optionals (T?) supported for scalar payloads, string?, and optionals of the POD struct subset via None / Some(...) and ?? coalescing, and

  • in module-set builds, helper calls may target:

  • functions defined in the same package (across multiple modules), and

  • imported exported functions (export fn) from any packages imported by the module that contains main (both foo() and pkg::foo() call forms are accepted initially for imported exports),

  • the helper body either:

  • consists only of scalar let bindings and a final return, or

  • ends in a simple if / else of the form:

               ```silk
               if <cond> {
                 [let...;]
                 return <expr>;
               } else {
                 [let...;]
                 return <expr>;
               }
               ```
    

where <cond> is a boolean expression built from comparisons over scalar expressions and boolean literals, and both branches end in return; such calls are lowered to IR Call instructions and compiled to native code together with main, using the System V AMD64 scalar calling convention on linux/x86_64 (integer-like scalars in rdi..r9, f32/f64 in xmm0..xmm7, with additional arguments spilled to the stack); helpers may have more than six integer parameters, and this path is exercised in both Zig tests and C tests (see c-tests/build_exec_helper_params*.c), or

  • a final if statement whose condition is a boolean expression:

  • for the purely constant subset, the condition is a compile‑time boolean literal (true or false) and each branch body itself satisfies the same “constant lets + return constant integer expression” rule, and

  • on linux/x86_64, a slightly richer branching main shape is also supported in which the body is exactly:

           ```silk
           fn main () -> int {
             if <cond> {
               [let...;]
               return <expr>;
             } else {
               [let...;]
               return <expr>;
             }
           }
           ```
    

where <cond> is built from integer comparisons (==, !=, <, <=, >, >=) over integer expressions from the same constant subset; this shape is lowered to IR using BrCond and compiled to native code by the IR→ELF backend so that the condition is evaluated at runtime, or

  • one or more trivial constant while loops that appear before the final return, each of which has:

  • a condition that is a compile‑time boolean literal (true or false),

  • for while false { ... }, a body that is ignored by the constant backend, and

  • for while true { ... }, a body consisting of zero or more constant let statements followed by a break;, with no other control‑flow; loop invariants (#invariant) and variants (#variant) may be present but are treated as metadata and do not affect constant evaluation,

  • examples of supported forms include:

       ```silk
       fn main() -> int { return 0; }
       fn main() -> int { return 1; }
       fn main() -> int { return 1 + 2 * 3; }
    
       let answer: int = 21 * 2;
    
       fn main() -> int {
         return answer;
       }
    
       // Two-module imported constant example (module-set builds only):
       //
       // util.slk
       package util;
       export let answer: int = 42;
       //
       // app.slk
       package app;
       import util;
       fn main () -> int { return answer; }
    
       // Two-module imported function example (module-set builds only):
       //
       // util.slk
       package util;
       export fn add (x: int, y: int) -> int { return x + y; }
       //
       // app.slk
       package app;
       import util;
       fn main () -> int { return add(40, 2); }
    
       fn main () -> int {
         let a: int = 21;
         let b: int = a * 2;
         return b;
       }
    
       fn main () -> int {
         if true {
           return 0;
         } else {
           return 1;
         }
       }
    
       fn main () -> int {
         while true {
           break;
         }
         return 0;
       }
       ```
    
  • when these conditions hold and output_path names a valid path, silk_compiler_build:

  • evaluates the constant integer expression in the body of main,

  • emits a tiny native executable image directly using a Silk‑owned backend (no C stub, no external C compiler),

  • when the IR-backed target path does not apply, this backend writes a minimal target-specific executable that terminates the process with the evaluated main value:

  • ELF64 for linux-x86_64, linux-aarch64, and android-aarch64,

  • Mach-O 64-bit for macos-x86_64, macos-aarch64, ios-aarch64, ios-simulator-aarch64, and ios-simulator-x86_64,

  • PE32+ for windows-x86_64 and windows-aarch64,

  • returns true on success with no last error recorded.

  • when the program is front‑end valid but outside this subset (e.g. main contains non‑constant expressions, references to non‑constant values, or calls that fall outside the simple helper‑call subset described above), or when the backend cannot produce an executable for the current platform or output path, the call returns false and records either an E4001 / E4002 diagnostic (for unsupported constructs or backend failures) or a descriptive string for I/O/argument errors as the last error.

  • Error reporting:

    SilkError *silk_compiler_last_error(SilkCompiler *compiler);
    
    size_t silk_error_format(const SilkError *error,
                             char            *buffer,
                             size_t           buffer_len);
    
  • silk_error_format returns a human-readable diagnostic message. When the compiler can associate the error with a source span, the formatted message includes the module name/path plus line/column and a caret snippet.

  • The text format and initial stable error code set are specified in diagnostics. Embedders should treat the formatted message as user-facing text (not a stable machine-readable protocol).

Ownership, lifetime, and thread-safety guarantees for these APIs must be clearly documented and kept in sync with the implementation.

ABI rules:

  • All exposed functions must be C99-compatible.
  • Data layouts must be stable and match the Silk side.
  • Ownership and lifetime of any pointers passed across the boundary must be explicitly documented.

In addition, the embedding ABI must clearly distinguish:

  • functions that consume Silk‑owned values (e.g. SilkString whose storage is owned by the runtime) versus
  • functions that take ownership of data supplied by the embedder (and are responsible for freeing it via documented APIs).

Any deviation from the mappings documented in ext must be justified here and reflected in tests.

Process containment runtime#

The Linux abort runtime declares libc prctl with a C int first argument and return value (i32 in Silk), followed by four u64 argument slots on the Linux 64-bit targets. A matching user ext prctl declaration shares that external symbol with std::abort.

The C99 runtime header <silk/rt.h> exposes process containment helpers: silk_rt_process_set_dumpable(int64_t), silk_rt_process_close_inherited_fds(void), and silk_rt_process_resource_limits(uint64_t, uint64_t), each returning int64_t zero on success or native errno on failure. Dumpability and descriptor-table closure require Linux; other hosts return ENOTSUP. Resource limits use POSIX rlimit; zero/unrepresentable inputs are invalid. Limit updates can partially succeed and must be used in a disposable pre-exec child. No helper allocates.

Resource limits and privilege readback#

The runtime C99 header exports silk_rt_process_data_limit(uint64_t) (returning errno or zero), silk_rt_process_get_dumpable(void) and silk_rt_process_get_no_new_privileges(void) (nonnegative state or negative errno), and silk_rt_process_set_no_new_privileges(int64_t) (errno or zero). Queries/setters specific to Linux report ENOTSUP on other hosts. silk_rt_process_get_resource_limit(int64_t pid, int64_t resource, uint64_t *out) writes soft/hard values to two caller-owned words only on success. Resource selectors 0/1/2/3 mean CPU/data/address-space/core; infinity is UINT64_MAX. It returns errno or zero; invalid selectors, negative PIDs, and null output are EINVAL. Nonzero PID readback requires Linux. Existing runtime symbols and signatures remain unchanged.

See Also#

  • libsilk(7) — C99 ABI manpage for embedders.
  • silk/silk.h — canonical public C header shipped with the library.

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.