commit f7fbbc9db78d92ef2796ccc4def521332e77e50e
parent a89695e3122b7a118a91d8828d350e2ffc18409c
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Thu, 4 Jun 2026 09:59:48 -0700
Add initial release punchlist
Diffstat:
2 files changed, 271 insertions(+), 0 deletions(-)
diff --git a/doc/plan/README.md b/doc/plan/README.md
@@ -8,6 +8,7 @@ shrinks to whatever remains open.
| Roadmap | Scope | Design doc |
|---------|-------|------------|
+| [RELEASE.md](RELEASE.md) | Cross-cutting initial-release punchlist: release scope, deferred features, and per-subsystem completion/validation items. | — |
| [OPTIMIZER.md](OPTIMIZER.md) | Completing the O2 SSA mid-end, expanded inlining, -O0/-O1 performance work, machine register-constraint improvements. | [../OPT.md](../OPT.md) |
| [LINKER.md](LINKER.md) | Incremental linking: the file-based object-link redesign and remaining non-ELF format coverage. | [../LINK.md](../LINK.md) |
| [JIT.md](JIT.md) | Function-level hot reload, Go-runtime-style codegen support, and remaining JIT host-portability work. | [../JIT.md](../JIT.md) |
diff --git a/doc/plan/RELEASE.md b/doc/plan/RELEASE.md
@@ -0,0 +1,270 @@
+# Initial release punchlist
+
+This is the release-control checklist for kit's first public release. It turns
+the current scope decisions into concrete work items. Design details remain in
+the subsystem docs and roadmaps linked from `doc/DESIGN.md` and
+`doc/plan/README.md`; this file is the cross-cutting release list.
+
+## Release scope
+
+### Ship
+
+- C11 toolchain: preprocessor, parser/checker, codegen, `cc`, `cpp`, `as`, `ld`,
+ archive/object tools, byte tools, hash/compress, `cas`/`pkg`, and `install`.
+- Curated real-world C library/application build gates, including hosted links
+ against system libraries and platform frameworks.
+- Optimization: `-O0` and `-O1` only. `-O2` is not a release feature.
+- LTO / whole-program optimization, enabled explicitly and able to run at `-O1`.
+- Content-addressed build coordinator (`kit build` / `<kit/build.h>`), layered on
+ CAS and package/trust infrastructure.
+- Runtime: target `libkit_rt.a`, freestanding headers/libc subset, compiler-rt
+ helpers, atomics, setjmp, and coroutines for the release support set.
+- JIT runtime (`kit run`) and IR interpreter (`kit run --no-jit`) for supported
+ host-compatible targets.
+- WebAssembly: single-TU `wasm32` output, Wasm/WAT input, and runtime execution
+ with partial WASI Preview1 compatibility.
+- Interactive debugger on x64, arm64, and rv64 for Linux, macOS, and FreeBSD.
+- Cross-compilation support set:
+ - arm64: macOS, Linux, Windows, FreeBSD, freestanding
+ - x64: Linux, Windows, FreeBSD, freestanding
+ - rv64: Linux, FreeBSD, freestanding
+ - rv32: freestanding
+
+### Do not ship
+
+- `-O2` as a distinct optimization level.
+- The Toy frontend as a user-facing language.
+- The user-mode ELF emulator.
+- File-based/AOT incremental linking.
+- Creating dynamic/shared libraries. Release builds may still create executables
+ that link against dynamic libraries.
+- Multi-TU Wasm output, Wasm static linking, wasm64, or complete WASI.
+- Interactive debugger support on Windows or rv32.
+
+## Global release cleanup
+
+- [ ] Freeze the public release surface in README/help/docs so it matches the
+ scope above.
+- [ ] Disable or hide the emulator (`KIT_EMU_ENABLED`, `KIT_TOOL_EMU_ENABLED`,
+ docs, help, default tests).
+- [ ] Hide Toy from user-facing docs and install/help output; keep it as internal
+ test coverage where useful.
+- [ ] Remove `-O2` release claims and make `-O2` behavior explicit: either reject
+ it for v1 or document it as an alias for `-O1` only if that is intentional.
+- [ ] Remove or reject dynamic-library creation entry points for release:
+ `cc -shared`, `ld -shared`, `build-lib -dynamic`, and any equivalent flag
+ spellings. Preserve executable links against DSOs.
+- [ ] Remove incremental-linking claims from docs and make any public reserved
+ entry points either unavailable or clearly unsupported.
+- [ ] Update `src/core/config_assert.c` so every release gate is asserted,
+ including RV32 and newer `KIT_TOOL_*` flags.
+- [ ] Build and test at least one "release gates" configuration with disabled
+ emulator, no user-facing Toy, and no dynamic-library creation path.
+
+## Target support matrix
+
+For each target in the release set:
+
+- [ ] `kit cc -c` produces a valid object with correct predefined macros and data
+ model.
+- [ ] `kit as` / inline asm support is either validated or explicitly diagnosed
+ when unsupported.
+- [ ] `kit ld` links static executables and relocatable objects where applicable.
+- [ ] Runtime archive auto-selection works for `cc` and `ld`.
+- [ ] Runtime helpers, atomics, setjmp, and coroutines pass targeted tests.
+- [ ] Debug info emission and object inspection round-trip.
+- [ ] Hosted targets validate sysroot/libc integration; freestanding targets
+ validate startup/runtime policy.
+
+Target-specific work:
+
+- [ ] Add/validate FreeBSD target parsing and serialization for arm64/x64/rv64.
+- [ ] Add/validate FreeBSD hosted profiles against a real FreeBSD rootfs for
+ arm64/x64/rv64.
+- [ ] Add/validate runtime variants for arm64 FreeBSD, x64 FreeBSD, rv64
+ FreeBSD, arm64 freestanding, and x64 freestanding.
+- [ ] Validate Windows arm64/x64 object/link/runtime support, including UCRT
+ import libraries and large-frame stack probing.
+- [ ] Validate Linux arm64/x64/rv64 hosted static and dynamic-executable links.
+- [ ] Validate freestanding arm64/x64/rv64/rv32 startup, runtime autolink, and
+ no-host assumptions.
+- [ ] Decide and document target names accepted for the support set
+ (`aarch64-*`, `arm64-*`, `x86_64-*`, `riscv64-*`, `riscv32-*`,
+ `*-none-elf`, `*-freestanding`, etc.).
+
+## Runtime
+
+- [ ] Fill the runtime variant table in `mk/rt.mk` and `driver/lib/runtime.c` for
+ every release target.
+- [ ] Validate compiler-rt integer/fp helpers for every release data model:
+ LP64, LLP64, and ILP32.
+- [ ] Validate atomic helper coverage, including non-lock-free widths.
+- [ ] Validate `<setjmp.h>` and `<kit/coro.h>` on arm64/x64/rv64/rv32 release
+ variants. Wasm32 has no coroutine support in v1; document that clearly.
+- [ ] Wire or reject Win64 large-frame probing cleanly.
+- [ ] Validate runtime header search/install layout for release packages and
+ `kit install`.
+- [ ] Add targeted runtime tests for every newly supported FreeBSD/freestanding
+ variant.
+
+## RV32
+
+- [ ] Finish or clearly reject `__int128` on rv32 with a front-end diagnostic.
+- [ ] Provide or reject 64-bit atomic libcalls (`__atomic_*_8`) for rv32.
+- [ ] Legalize 64-bit overflow intrinsics on rv32.
+- [ ] Fix rv32 i64 varargs.
+- [ ] Decide and document TLS behavior for freestanding rv32.
+- [ ] Fix the rv32 soft-float compare lowering bug.
+- [ ] Triage and fix the `123_spec_demo` hang.
+- [ ] Add rv32 assembler byte-golden lanes and CSR pseudo-op/name coverage, or
+ document the assembler limitation.
+- [ ] Move rv32 C corpus lanes from known-red/opt-in to release-green, and keep
+ any Toy rv32 lane internal-only rather than part of the release claim.
+- [ ] Run `test-smoke-rv32`, rv32 object/link/JIT host-gated tests, and the rv32
+ parse/codegen corpus under `qemu-system-riscv32`.
+
+## LTO and optimizer
+
+- [ ] Merge the LTO work to main without regressing the current build commands,
+ RV32 work, or test layout.
+- [ ] Keep release optimization levels to `-O0` and `-O1`; LTO must be available
+ at `-O1`.
+- [ ] Decide the release spelling (`-flto`, plus any rejected aliases) and make
+ diagnostics precise.
+- [ ] Finish link-picture preserved/export set computation for LTO:
+ entry symbol, dynamic imports used by executable links, opaque object/asm
+ references, `used`, init/fini, IFUNC, address-significant symbols, and
+ visibility.
+- [ ] Internalize non-preserved globals and re-run whole-module reachability.
+- [ ] Keep shared-library creation out of scope; make `-shared -flto` reject
+ cleanly as part of the general dynamic-library creation policy.
+- [ ] Validate cross-TU inlining and interposition safety on arm64/x64/rv64.
+- [ ] Add LTO tests for `cc`, `build-exe`, `build-lib`, and `build-obj`.
+- [ ] Refresh O0/O1 benchmark baselines and record LTO impact separately.
+
+## Build coordinator
+
+- [ ] Bring the build-coordinator branch up to current main before merging; avoid
+ losing current `build-exe`/`build-lib`/`build-obj`, RV32, and Wasm work.
+- [ ] Implement the public surface: `<kit/build.h>`, `KIT_BUILD_ENABLED`,
+ `KIT_TOOL_BUILD_ENABLED`, and `kit build`.
+- [ ] Implement the internal modules from the build design: config/argv,
+ definition parser, protocol, trace/deepset, store, remote, coordinator,
+ resolver, runner, bundle import/export, and API composition.
+- [ ] Keep all build state hanging off explicit coordinator/store/client
+ contexts; no global state.
+- [ ] Add hermetic tests for byte-stable config/argv/trace/deepset emission and
+ fail-safe parsing.
+- [ ] Add store crash-safety/fault-injection tests.
+- [ ] Add minimal-rebuild tests: no-op rebuild, source edit absorbed by a dep,
+ config changes, recipe edits, absent file creation, materialize miss, and
+ diamond deepset sharing.
+- [ ] Add concurrency tests for jobs limits, future dedup, cancellation, and
+ cycle detection.
+- [ ] Add `kit build` CLI smoke tests with real recipes and release packaging
+ integration.
+- [ ] Move shipped design details from `doc/plan/BUILD*.md` into durable design
+ docs once implemented; leave only remaining roadmap items in `doc/plan/`.
+
+## WebAssembly and WASI
+
+- [ ] Define the exact v1 Wasm target surface: single-TU `wasm32`, no wasm64, no
+ static Wasm linker, no multi-TU Wasm output.
+- [ ] Validate `wasm32-none` single-TU output for C sources and runtime helpers.
+- [ ] Enable and document partial `wasm32-wasi` compatibility if accepted for v1.
+- [ ] Define the supported WASI Preview1 import subset, expected failures, and
+ security policy. At minimum audit argv/env, stdio, `proc_exit`, random,
+ clock, preopened directories, read/write permissions, and unsupported fd/fs
+ calls.
+- [ ] Validate `kit run` Wasm host-import binding, resource policy flags, cwd,
+ env, and exit-code propagation.
+- [ ] Add Wasm/WASI smoke tests that do not depend on Toy.
+- [ ] Make unsupported Wasm proposals and unsupported WASI calls fail with
+ feature-naming diagnostics.
+- [ ] Update `doc/WASM.md`, `doc/plan/WASM.md`, driver help, and README to match
+ the v1 Wasm/WASI surface.
+
+## Interactive debugger
+
+- [ ] Define debugger v1 scope: x64, arm64, rv64 on Linux, macOS, and FreeBSD.
+ Windows and rv32 are explicitly out of scope.
+- [ ] Validate end-to-end sessions for every supported host/arch pair:
+ breakpoints, continue, step, next, finish, backtrace, registers, variables,
+ memory read/write, Ctrl-C/interrupt, and teardown.
+- [ ] Bring x64 and rv64 session integration to parity with arm64:
+ fault classification, trap PC normalization, register marshalling, and
+ displaced single-step.
+- [ ] Add or extend ucontext/register marshalling for FreeBSD x64/arm64/rv64.
+- [ ] Handle known declined displaced-step forms or diagnose them cleanly.
+- [ ] Add scripted transcript tests and low-level unit tests for breakpoint patch
+ round-trip, guarded copy, displaced stepping, and source stepping.
+- [ ] Remove degraded-mode messaging once the v1 session implementation is
+ complete.
+- [ ] Update `doc/DBG.md`, `doc/plan/DEBUG.md`, help text, and README with the
+ exact v1 platform scope.
+
+## Linker and dynamic linking
+
+- [ ] Preserve executable dynamic-link support: PT_INTERP/PT_DYNAMIC/DT_NEEDED,
+ import libraries, `.tbd`, and sysroot/library resolution as applicable.
+- [ ] Reject or hide creating shared libraries for v1 across `cc`, `ld`, and
+ build verbs.
+- [ ] Keep `ld -r` relocatable combining supported and tested.
+- [ ] Remove release claims for file-based incremental linking; keep any JIT
+ append/publish internals documented only where they are real and needed.
+- [ ] Validate executable links against dynamic libraries for Linux, FreeBSD,
+ macOS, and Windows targets in the support set.
+
+## C ecosystem gates
+
+- [ ] Add a small, curated `examples/` or `test/ecosystem/` suite that proves kit
+ can compile real C projects with ordinary headers, build scripts, archives,
+ and hosted system libraries.
+- [ ] Keep the suite deterministic: pinned upstream versions, checked hashes,
+ patch files kept minimal and documented, no network access in default test
+ runs.
+- [ ] Add a source-built library gate for SQLite: compile the amalgamation,
+ archive `libsqlite3.a`, build the shell or a focused smoke app, and validate
+ basic SQL execution.
+- [ ] Add a source-built compression/library gate such as zlib or libpng to cover
+ common configure-style C and archive linking.
+- [ ] Add a hosted SDL2 gate: compile a minimal C app and link it through the
+ platform mechanism (`pkg-config`/`sdl2-config`, framework, or import
+ library), with an offscreen/headless smoke mode where possible.
+- [ ] Add at least one terminal/system-library app gate, such as ncurses/curses or
+ readline/editline, to exercise hosted include/library discovery.
+- [ ] Add a macOS framework gate, preferably a pure-C CoreFoundation smoke, to
+ prove `-framework` and `.tbd` system-library resolution.
+- [ ] Add Linux/FreeBSD system-library link gates for `-lm`, `-ldl`, `-lpthread`,
+ and one package-discovered library.
+- [ ] Add Windows hosted link gates for system/import libraries used by the
+ release support set.
+- [ ] Run the ecosystem suite at `-O0` and `-O1`; add an LTO lane for at least
+ SQLite once LTO lands.
+- [ ] Decide which gates are required in default release CI and which are
+ opt-in because they require host packages or graphics/display access.
+- [ ] Document the examples as supported smoke builds, with exact commands users
+ can run after installing kit.
+
+## Release validation
+
+- [ ] Reconcile `doc/TESTING.md` with `mk/test.mk` so default and opt-in test
+ tiers match reality.
+- [ ] Define the release CI/test matrix, separating host-independent tests,
+ exec-dependent tests, cross-arch tests, and bootstrap.
+- [ ] Run targeted frontend tests: `test-asm`, `test-parse`, `test-pp`,
+ `test-toy` only if still used internally, and Wasm tests.
+- [ ] Run codegen/API/opt tests: `test-cg-api`, `test-opt`, `test-isa`,
+ `test-aa64-inline`, x64/rv64 inline tests, LTO tests.
+- [ ] Run link/object tests: `test-link`, `test-elf`, `test-macho`, `test-coff`,
+ `test-ar`, `test-driver-ar`, `test-driver-build`.
+- [ ] Run debug tests: `test-debug`, `test-dwarf`, `test-dbg`, arch-specific dbg
+ tests on supported hosts.
+- [ ] Run runtime/libc/smoke tests for every supported runtime target.
+- [ ] Run bootstrap in debug and release modes on the reference host; add other
+ host bootstraps if feasible.
+- [ ] Run sanitizer/LSan lanes on Linux for driver and library leaks.
+- [ ] Refresh O0/O1 benchmarks and `doc/CODE_SIZE.md`.
+- [ ] Update release packaging: version, licenses, support-dir layout, runtime
+ archives, headers, docs, and `kit install` default tool set.
+- [ ] Produce a final release-note feature list and a separate limitations list.
