c: libkore.so, the runtime and host of an independent C program

.github/workflows/ci.yml

@@ -62,6 +62,8 @@ jobs:
           sudo apt-get update -qq
           sudo apt-get install -y llvm
           python3 tools/check-alloc-symbols.py --arch ${{ matrix.arch }}
+      - name: Link libkore.so and check its exported ABI
+        run: python3 tools/check-program.py --arch ${{ matrix.arch }}
   miri:
     runs-on: ubuntu-latest
     timeout-minutes: 30

Cargo.toml

@@ -8,7 +8,7 @@ repository = "https://github.com/MicroPerceptron/libkore"
 
 [workspace]
 resolver = "3"
-members = ["tests/consumer", "crates/ffi", "crates/entry", "crates/wasi", "crates/lua", "crates/host"]
+members = ["tests/consumer", "crates/ffi", "crates/c", "crates/entry", "crates/wasi", "crates/lua", "crates/host"]
 exclude = ["native"]
 
 [features]
@@ -35,4 +35,4 @@ kore-driver = { path = "native/crates/driver", optional = true }
 # root: the offline volume procedure (and the filesystem service closure it
 # drives) that host programs such as vKore consume; it never enters a Kore
 # executable's graph.
-owner-paths = { kore-start = "crates/start", kore-abi = "crates/abi", kore-app = "crates/app", kore-rt = "crates/rt", kore-dagfs = "crates/dagfs", kore-driver = "crates/driver", kore-late = "crates/late", kore-vol = "tools/kore-vol" }
+owner-paths = { kore-start = "crates/start", kore-abi = "crates/abi", kore-app = "crates/app", kore-rt = "crates/rt", kore-c-shim = "crates/c-shim", kore-dagfs = "crates/dagfs", kore-driver = "crates/driver", kore-late = "crates/late", kore-ld = "crates/ld", kore-vol = "tools/kore-vol" }

Makefile

@@ -17,7 +17,7 @@ check:
 	python3 tools/check-native.py
 
 fmt:
-	cargo fmt -p kore-std -p libkore-consumer -p kore-ffi -p kore-entry -p kore-wasi -p kore-lua -p kore-host --check
+	cargo fmt -p kore-std -p libkore-consumer -p kore-ffi -p kore-c -p kore-entry -p kore-wasi -p kore-lua -p kore-host --check
 	$(ZIG) fmt --check build.zig build.zig.zon crates/ffi/tests/consumer.zig extern/zig/src/root.zig extern/zig/src/allocator.zig
 
 docs:
@@ -30,7 +30,9 @@ owners:
 	python3 tools/check-owners.py < target/owners.json
 
 # Actual Kore user targets, including its hardware-float x86 ABI. A stock
-# x86_64-unknown-none check alone cannot certify this interface.  `kore-lua`
+# x86_64-unknown-none check alone cannot certify this interface. `kore-c` is
+# linked rather than checked (`tools/check-program.py`): `libkore.so`'s
+# exported ABI, soname and TLS model are properties of the linked image.  `kore-lua`
 # is here because its engine exists only on these targets — its host build
 # carries the logic and none of the C — so a Kore-only regression in the
 # amalgamation would otherwise reach a keytest before it reached a
@@ -46,6 +48,7 @@ cross:
 	    -Z build-std-features=compiler-builtins-mem; \
 	done
 	python3 tools/check-alloc-symbols.py
+	python3 tools/check-program.py
 	python3 tools/check-entry.py
 
 # kore-host drives real image files under POSIX record locks, which Miri does

README.md

@@ -14,12 +14,13 @@ machine's volume through the same exported owners a booted Kore runs.
 | --- | --- |
 | `kore-std` | Rust facade: filesystem, prelude, time, random, collections, process and optional driver APIs |
 | `kore-entry` | Executable-only adapter for a returning Rust `fn main()` on Kore |
-| `kore-ffi` | C headers and Zig module over a Rust-founded host, including filesystem, time, random, allocation and worker APIs; no standalone C/Zig CRT |
+| `kore-ffi` | C headers and Zig module over a Rust-founded host, including filesystem, time, random, allocation and worker APIs |
+| `kore-c` | The runtime of `libkore.so`: `kore.h` as one shared object, and the host of an independent C program (`main` on a worker, its filesystem session, its end) |
 | `kore-lua` | Embeddable Lua 5.5 engine and bridge; interactive and opt-in restricted worker policies |
 | `kore-wasi` | WASI 0.2 component host composed by an embedder with its Wasmtime engine and native owners |
 | `kore-host` | Host-side (Linux/macOS) tooling: a Kore machine's DagFS volume, offline, through the filesystem row's own engine |
 
-All six package manifests set `publish = false`; consume a reviewed Git
+All seven package manifests set `publish = false`; consume a reviewed Git
 revision or a deliberately composed local checkout, not a registry version.
 The WASI host supports the `wasi:cli/command` world and native-backed I/O,
 filesystem, clocks and random imports; unsupported imports such as sockets

crates/c/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "kore-c"
+version = "0.1.0-alpha.1"
+edition = "2024"
+publish = false
+description = "The runtime of libkore.so: the C ABI and the host of an independent C program on Kore"
+# No native library is linked: the key carries the headers this runtime
+# implements to dependents' build scripts as `DEP_KORE_INCLUDE` (`build.rs`).
+links = "kore"
+build = "build.rs"
+
+# The runtime `libkore.so` is built from: a distribution's one-line `cdylib`
+# crate names this one and links it under its own `[lib] name = "kore"`, so
+# the image is `libkore.so` (Kore's is `user/runtime/libkore`). Link it into
+# that shared object alone: it installs the process heap and the panic handler
+# a C program's runtime needs, which a Rust executable brings itself.
+[lib]
+name = "kore_c"
+path = "src/lib.rs"
+
+[dependencies]
+kore-std = { package = "kore-std", path = "../..", features = ["heap", "fs"] }
+# The C ABI itself, with the standard C allocation and thread names a C
+# program calls (`malloc`, `pthread_create`, ...) exported as real symbols.
+kore-ffi = { path = "../ffi", features = ["c-stdlib"] }
+# Kore's C library: the `printf` family and the standard streams, `<string.h>`
+# and `<stdlib.h>`'s parsers, `errno`. Its process half without its own
+# `malloc` and `abort`: kore-ffi's allocator is this image's `malloc`, and the
+# host ends a whole program.
+kore-c-shim = { path = "../../native/crates/c-shim", default-features = false, features = ["runtime"] }
+# The link window's placer: one cursor every `mmap` of the process takes its
+# address from, as a Wasmtime engine's guest mappings do.
+kore-ld = { path = "../../native/crates/ld", default-features = false }

crates/c/build.rs

@@ -0,0 +1,29 @@
+//! Publish the C headers `libkore.so` implements to whoever links this crate
+//! (`links = "kore"`): a dependent's build script reads `DEP_KORE_INCLUDE`, the
+//! directory holding `kore.h` and `kore/`, from this exact source revision, so
+//! the headers a distribution ships cannot drift from the image it builds.
+use std::path::PathBuf;
+
+fn main() {
+    let manifest =
+        PathBuf::from(std::env::var_os("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR"));
+    let include = manifest.join("../../extern/c/include");
+    let include = include
+        .canonicalize()
+        .unwrap_or_else(|error| panic!("{}: {error}", include.display()));
+    for header in [
+        "kore.h",
+        "kore/stdlib.h",
+        "kore/pthread.h",
+        "kore/program.h",
+    ] {
+        let path = include.join(header);
+        assert!(
+            path.is_file(),
+            "missing generated header {}",
+            path.display()
+        );
+        println!("cargo:rerun-if-changed={}", path.display());
+    }
+    println!("cargo:include={}", include.display());
+}

crates/c/cbindgen.toml

@@ -0,0 +1,23 @@
+language = "C"
+include_guard = "KORE_PROGRAM_H"
+pragma_once = true
+cpp_compat = true
+usize_is_size_t = true
+style = "both"
+no_includes = true
+includes = ["../kore.h"]
+autogen_warning = "/* Generated by cbindgen 0.29.4 from kore-c. Do not edit. */"
+header = "/* libkore.so: what an independent C program on Kore adds to kore.h. Link with -lkore. */"
+[parse]
+parse_deps = false
+[export]
+# The C library's half of the program lifecycle (its start and exit call
+# these), not an application API: the C library declares them itself, as
+# its <stdlib.h> declares `abort`. `KoreFsStep` is kore.h's typedef, which
+# this header includes.
+# `open`, `close`, `mmap` and `munmap` are POSIX's, declared by <fcntl.h>,
+# <unistd.h> and <sys/mman.h>.
+exclude = ["__kore_program_start", "__kore_program_exit", "__kore_program_arguments", "abort", "open", "close", "mmap", "munmap", "KoreFsStep"]
+[enum]
+prefix_with_name = true
+rename_variants = "ScreamingSnakeCase"