Use detlef.h to embed a native runtime; use detlef_sdk.h to write packages for native hosts and Wasm. Add sdk/c/include/ to the compiler's include path. Headers and runtime binaries must come from the same release.

Language concepts

See the language manual for evaluation, values and types, and scoping. These concepts explain how callbacks and controls evaluate arguments and access variables.

Embed a runtime

Build the shared library with cargo build -p detlef-ffi, then link the host against it. The host example shows execution, callbacks, and record registration in one program.

Task	Reference
Create a runtime, enter access, load packages	Runtime Lifecycle
Find status codes, handle kinds, selectors, and boolean flags	ABI Types
Execute source and manage variables	Variables
Register functions, controls, and standard I/O	Callbacks and Registration
Work inside a native function	Limited Function Access
Read and construct values	Handles and Values and Objects
Use C-string conveniences	Embedding Helpers

Selector and boolean types use fixed-width integer storage in C and C++. The reference displays their enum values; click a type in a signature to see its allowed constants. For example, detlef_descriptor_create() takes a DetlefDescriptorKind.

Build a package

The courier example exposes a fictional parcel shop's tariff through courier_quote(weight_grams, express). It demonstrates typed arguments, input validation, and a CourierQuote record result using one source and registration table for native and Wasm builds. Its manifest selects the target artifacts. With Clang and its Wasm linker installed, run from the repository root:

python sdk/c/tools/build-sdk-package.py examples/packages/courier/package.c examples/packages/courier/metadata.toml -o target/courier.dtfpkg

Adapt the manifest's native target to the host platform. Load the resulting archive with detlef_runtime_load_package(), or JavaScript's Runtime.loadPackage(). To try the Node package host, build the Wasm bindings and run:

python crates/detlef-wasm/build.py --target nodejs

node examples/js/package_host.mjs target/courier.dtfpkg

The C package host loads the same archive. Both hosts evaluate courier_quote(1200, true) and print the returned record.

Task	Reference
Define types, records, and callables	Package Types and Package Registration
Evaluate arguments and construct results	Package Arguments, Primitive Values, Package Objects
Keep a value beyond its callback	Package Value Ownership
Evaluate source from a control or report errors	Package Context