commit 9c0516c2991fc409b2db17a99fda4a76c857b217
parent ad5fdfd09243c2d1bcbb95f3b1c5d99c1b7e5b3c
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Thu, 18 Jun 2026 16:51:45 -0700
Align release public docs surface
Diffstat:
11 files changed, 61 insertions(+), 29 deletions(-)
diff --git a/doc/BUILD_COORDINATOR.md b/doc/BUILD_COORDINATOR.md
@@ -758,14 +758,16 @@ Build execution:
```
kit build [--store DIR] [--root DIR] [--def FILE]
- [--config K=V]... [--verify] [--stats] TARGET [-- ARG...]
+ [--config K=V|env.NAME]... [--env NAME[=V]]...
+ [--verify] [--stats] TARGET [-- ARG...]
```
Test execution:
```
kit build test [--store DIR] [--root DIR] [--def FILE]
- [--config K=V]... [--verify] [--stats] TARGET [-- ARG...]
+ [--config K=V|env.NAME]... [--env NAME[=V]]...
+ [--verify] [--stats] TARGET [-- ARG...]
```
`kit build` prints `<output-tree-hex> <path>` and exits 0 on success. `kit build
@@ -775,8 +777,9 @@ errors also exit nonzero and print diagnostics on stderr. `--stats` prints
cumulative coordinator counters, including `test_runs`, `test_cache_hits`, and
`test_failures`, to stderr.
-Recipe-side shell helper commands are available only inside a running recipe
-(`$KIT_BUILD_SOCK` set), or explicitly as `kit build --client ...`:
+Recipe-side shell helper commands are available as `kit build <verb> ...` inside
+a running recipe (`$KIT_BUILD_SOCK` set), or explicitly outside a recipe as
+`kit build --client <verb> ...`:
```
kit build config-get [--default VALUE] KEY
diff --git a/doc/DESIGN.md b/doc/DESIGN.md
@@ -10,7 +10,10 @@ the docs indexed at the end.
## What kit is
A single multi-call binary (`kit`) that bundles a complete C toolchain plus the
-machinery to JIT, debug, and emulate what it produces. Capabilities:
+machinery to JIT and debug what it produces. The v1 public surface is controlled
+by [plan/RELEASE.md](plan/RELEASE.md); subsystems marked internal there, such as
+the Toy frontend and `emu`, may remain documented for maintainers without being
+release claims. Capabilities:
- C11 preprocessor, single-pass parser/type checker, and code generator.
- A JIT compiler, an in-process runner, and an interactive debugger.
@@ -23,7 +26,6 @@ machinery to JIT, debug, and emulate what it produces. Capabilities:
portable C-source backend.
- Object read/write for ELF, Mach-O, and PE/COFF; a Wasm object form.
- DWARF debug-info production and consumption; a disassembler.
-- A user-mode guest-ELF emulator (per-basic-block JIT translation).
- A bytecode interpreter over the optimizer IR (`run --no-jit`).
- Signed, content-addressed code distribution (`.kpkg`).
- A parser/lexer generator (`gram`): EBNF in, C parser / lexer / token-machine
@@ -79,15 +81,16 @@ driver/ CLI policy + host I/O. Includes ONLY <kit/*.h>.
```
- **`driver/`** implements the multi-call binary. `driver/main.c` holds the
- central tool table; each tool (`cc`, `as`, `ld`, `ar`, `run`, `dbg`, `emu`,
+ central tool table; each public tool (`cc`, `as`, `ld`, `ar`, `run`, `dbg`,
`cas`, `pkg`, …) translates command-line flags into public API calls and
supplies the host vtables. The content-addressed store and `.kpkg` packaging
(tar/deflate/lz4, BLAKE2b, ed25519/minisign) are a libkit subsystem
(`src/dist/`, behind `<kit/cas.h>` / `<kit/package.h>`); `cas`/`pkg` are
thin CLIs over it.
- **`lang/`** holds the frontends. `lang/c` preprocesses (`lang/cpp`), parses,
- type-checks, manages C declarations, and drives the public CG API; `lang/toy`
- and `lang/wasm` are smaller frontends exercising the same boundary. Each
+ type-checks, manages C declarations, and drives the public CG API; `lang/wasm`
+ is the Wasm/WAT frontend and `lang/toy` is an internal test frontend exercising
+ the same boundary. Each
registers a `KitFrontendVTable` per compiler and emits through `KitCg`; no
frontend owns object formats or linker policy.
- **`include/kit/`** is the public boundary — the only headers `driver/` and
@@ -215,7 +218,7 @@ unless an API states otherwise.
| [LINK.md](LINK.md) | Linking: symbol resolution, layout, relocation, linker scripts, and incremental linking. |
| [KERNEL.md](KERNEL.md) | The freestanding kernel build + image pipeline: `build-obj`/`build-exe`, the linker-script subset, `kit image` / `objcopy -O binary`, flat-kernel `Image` headers, and `kit cpio` initramfs archives. |
| [JIT.md](JIT.md) | The JIT image model, executable-memory and TLS host hooks, and publish/append/replace. |
-| [EMU.md](EMU.md) | The user-mode guest-ELF emulator and its per-block JIT translation. |
+| [EMU.md](EMU.md) | Internal user-mode guest-ELF emulator design and per-block JIT translation. |
| [DWARF.md](DWARF.md) | DWARF debug-info production and the consumer used by the debugger and dumpers. |
| [DBG.md](DBG.md) | The debugger: breakpoints, single-step, displaced execution, register/memory access. |
| [CBACKEND.md](CBACKEND.md) | The portable C-source backend (`src/arch/c_target/`). |
diff --git a/doc/DISTRIBUTE.md b/doc/DISTRIBUTE.md
@@ -12,6 +12,10 @@ through two public headers — `<kit/cas.h>` (the content store) and
command line: `kit cas` and `kit pkg`. See [DRIVER.md](DRIVER.md) for how
these slot into the multitool.
+Release artifacts use the same package format. See [RELEASE.md](RELEASE.md) for
+the `kit update` flow, install-root layout, default tool links, and release
+channel index built on top of `kit pkg`.
+
## Why this shape
Three design decisions drive the whole subsystem:
diff --git a/doc/EMU.md b/doc/EMU.md
@@ -1,5 +1,10 @@
# Emulator
+The emulator is an internal/development subsystem for v1. `kit emu` and the
+`kit_emu_*` API may be built and tested, but they are not part of the v1 public
+release surface unless [plan/RELEASE.md](plan/RELEASE.md) is updated to promote
+them.
+
`kit emu` is a user-mode emulator for guest ELF executables. It loads a
guest program image into a host-managed address space, then runs it by
JIT-translating one guest basic block at a time into host machine code
diff --git a/doc/FRONTENDS.md b/doc/FRONTENDS.md
@@ -9,8 +9,10 @@ language-agnostic. This document covers the frontend model, the C frontend
pipeline, and the smaller toy and wasm frontends. For testing, see
[TESTING.md](TESTING.md).
-kit ships four frontends: C (the real one), asm (lives inside the codegen
-substrate), toy (a CG-API exercise vehicle), and wasm (WAT/wasm lowering).
+kit ships four frontends in-tree: C (the public C frontend), asm (lives inside
+the codegen substrate), wasm (the public WAT/wasm lowering frontend), and toy
+(an internal CG-API exercise vehicle). Toy may remain in developer tests, but it
+is not part of the v1 public release surface.
## The frontend contract
diff --git a/doc/KERNEL.md b/doc/KERNEL.md
@@ -36,11 +36,10 @@ the strict validation described below.
There is no separate `kit kernel` command. The compile/link front doors are the
ordinary build verbs (see [DRIVER.md](DRIVER.md)):
-- **`build-obj`** compiles a polyglot source set (C / asm / toy / wasm) to one
+- **`build-obj`** compiles a source set (C / asm / wasm) to one
object; multiple sources combine into a single relocatable object via `ld -r`.
- **`build-exe`** compiles a source set in memory and links it — together with
- any `.o` / `.a` / `.so` inputs — into an executable, with no intermediate
- files.
+ any `.o` / `.a` inputs — into an executable, with no intermediate files.
Both accept the freestanding and link flags a kernel needs, and `build-exe`
accepts the common direct linker flags (not only the `-Wl,` escape hatch). A
diff --git a/doc/RELEASE.md b/doc/RELEASE.md
@@ -160,6 +160,14 @@ and refreshes the `bin/` links — the live binary is reached through `current`,
so the swap never mutates the running image. All versions are retained, so any
prior one is an instant **offline** flip.
+`kit install DIR [TOOL...]` is the standalone link-layout tool for an existing
+binary. With no explicit tools it installs the default drop-in compiler/binutils
+and standard byte-utility names. `kit install --all` installs every public tool
+compiled into the binary, while internal v1 tools such as `emu` are excluded.
+`kit update` uses the same link writer after installing or flipping a version, so
+`$KIT_HOME/bin` and an explicit `kit install` directory expose the same public
+tool names for the selected mode.
+
```
kit update # latest on the tracked channel (network)
kit update <file.kpkg> # offline: verify + install a local package
diff --git a/doc/TESTING.md b/doc/TESTING.md
@@ -127,10 +127,10 @@ fallback (see the gotcha below).
stdout, and an optional `<name>.expected` oracle). This is the end-to-end "it
runs the same" signal, tolerant of benign encoding differences L1 would flag.
Crucially, **no qemu is needed for the host arch**: execution goes through the
-in-process JIT (`kit run` / the `jit-runner`), and cross-arch execution is
-available via the emulator (`kit emu`) — see [JIT.md](JIT.md) and
-[EMU.md](EMU.md). L2 runs only when the target arch matches the host
-(native JIT); otherwise it self-skips.
+in-process JIT (`kit run` / the `jit-runner`). Developer lanes may also use the
+internal emulator (`kit emu`, not v1 public surface; see [EMU.md](EMU.md)), but
+L2 runs only when the target arch matches the host (native JIT); otherwise it
+self-skips.
Opt levels matter: `-O0` and `-O1` emit different encodings, so each lane runs
at every level in `KIT_TEST_OPTS`.
diff --git a/doc/plan/RELEASE.md b/doc/plan/RELEASE.md
@@ -75,16 +75,16 @@ changes, update those sources and this checklist together.
All command output for signoff should be captured under a release-check log
directory, then inspected from the saved logs.
-- [ ] `make test-tier1` passes with no unexpected skip/fail.
-- [ ] `make test-cross DEPTH=coarse` passes for the full official target set.
-- [ ] `make test-cross DEPTH=smoke RUN=1` passes for every target with an
+- [x] `make test-tier1` passes with no unexpected skip/fail.
+- [x] `make test-cross DEPTH=coarse` passes for the full official target set.
+- [x] `make test-cross DEPTH=smoke RUN=1` passes for every target with an
execution runner. Android and iOS are excluded from runtime assertions.
- [ ] Deferred portability lanes are listed with owner/status:
`make test-cross DEPTH=full`, `make test-selfhost DEPTH=smoke`, and
`make test-selfhost DEPTH=full`.
- [x] Release-gate configuration has `emu` and user-facing Toy hidden/disabled,
while internal Toy tests remain available if still useful.
-- [ ] No public v1 doc or help text claims a feature outside this checklist.
+- [x] No public v1 doc or help text claims a feature outside this checklist.
## Blocking correctness issues
@@ -115,7 +115,7 @@ converted into a non-public unsupported feature.
### Documentation and help
-- [ ] README, `kit --help`, per-tool help, and install output match the V1 public
+- [x] README, `kit --help`, per-tool help, and install output match the V1 public
surface exactly.
- [x] [../DRIVER.md](../DRIVER.md) documents `-O2` as a temporary `-O1` alias,
ELF-only shared-library creation, and hidden `emu`/Toy policy.
@@ -123,10 +123,10 @@ converted into a non-public unsupported feature.
creation from executable links against DSOs on all object formats.
- [x] [../WASM.md](../WASM.md) states the `wasm32`, WAT/Wasm input, runtime,
partial-WASI, and same-invocation multi-source boundary.
-- [ ] [../BUILD_COORDINATOR.md](../BUILD_COORDINATOR.md),
+- [x] [../BUILD_COORDINATOR.md](../BUILD_COORDINATOR.md),
[../DISTRIBUTE.md](../DISTRIBUTE.md), and release packaging docs cover
`build`, `cas`, `pkg`, `install`, and `update`.
-- [ ] [../KERNEL.md](../KERNEL.md) matches the shipped `image` and `cpio` tool
+- [x] [../KERNEL.md](../KERNEL.md) matches the shipped `image` and `cpio` tool
surface.
- [x] [../DBG.md](../DBG.md) contains only debugger platforms that are
hard-green.
diff --git a/driver/main.c b/driver/main.c
@@ -28,7 +28,7 @@ typedef struct DriverToolDesc {
static const DriverToolDesc driver_tools[] = {
#if KIT_TOOL_CC_ENABLED
{"cc", driver_cc, NULL, driver_help_cc,
- "Compile (and link) C sources, with cpp / dep-emit / -shared modes",
+ "Compile (and link) C sources, with cpp / dep-emit / ELF -shared modes",
DRIVER_GROUP_TOOLCHAIN},
#endif
#if KIT_TOOL_CHECK_ENABLED
@@ -42,7 +42,7 @@ static const DriverToolDesc driver_tools[] = {
#endif
#if KIT_TOOL_BUILD_LIB_ENABLED
{"build-lib", driver_build_lib, driver_build_lib_ex, driver_help_build_lib,
- "Compile sources into a static .a or shared library (in memory)",
+ "Compile sources into a static .a or ELF shared library (in memory)",
DRIVER_GROUP_TOOLCHAIN},
#endif
#if KIT_TOOL_BUILD_OBJ_ENABLED
@@ -72,7 +72,7 @@ static const DriverToolDesc driver_tools[] = {
#endif
#if KIT_TOOL_LD_ENABLED
{"ld", driver_ld, NULL, driver_help_ld,
- "Link objects/archives into an executable or shared library",
+ "Link objects/archives into an executable or ELF shared library",
DRIVER_GROUP_TOOLCHAIN},
#endif
#if KIT_TOOL_AR_ENABLED
diff --git a/test/driver/run.sh b/test/driver/run.sh
@@ -1385,6 +1385,14 @@ else
not_ok "kit-help-hides-emu" "$work/kit-help.out"
fi
+if grep -q "ELF -shared modes" "$work/kit-help.out" &&
+ grep -q "static .a or ELF shared library" "$work/kit-help.out" &&
+ grep -q "executable or ELF shared library" "$work/kit-help.out"; then
+ ok "kit-help-elf-shared-scope"
+else
+ not_ok "kit-help-elf-shared-scope" "$work/kit-help.out"
+fi
+
if "$KIT" dbg --help > "$work/dbg-help.out" 2> "$work/dbg-help.err" &&
! grep -q "toy" "$work/dbg-help.out"; then
ok "dbg-help-hides-toy"
