From 18c43984e1796d03fca34753ee71f8738b244eec Mon Sep 17 00:00:00 2001 From: agra Date: Sun, 14 Jun 2026 13:17:00 +0300 Subject: [PATCH] feat(ffi-linkage): lower extern fns as C imports (Phase 1.1) Route a bare 'extern' fn declare-only, exactly like a lib-less #foreign import. Six edits in decl.zig, each mirroring an existing foreign_expr guard so the empty-block placeholder body is never lowered: 1. funcWantsImplicitCtx: suppress the implicit __sx_ctx for .extern_ 2. declareFunction: add is_extern_decl 3. ...and include it in the C-ABI calling-convention promotion 4. lazyLowerFunction: .extern_ -> declareFunction (declare-only) 5. lowerFunction: .extern_ in the declare-only guard 6. lowerFunctionBodyInto: never promote/lower an extern stub examples/1223 now green: 'extern' abs lowers to 'declare i32 @abs(i32)' (external linkage, C ABI, no ctx param) and the call resolves against the default-linked libc -> abs(-7)=7, abs(42)=42. The 1.0b hand-authored snapshot matched byte-exact (no regen). Suite green (634 corpus / 443 unit). green commit (makes the 1.0b xfail pass; adds no new test). --- current/CHECKPOINT-EXTERN-EXPORT.md | 63 +++++++++++++++++------------ src/ir/lower/decl.zig | 23 +++++++++-- 2 files changed, 57 insertions(+), 29 deletions(-) diff --git a/current/CHECKPOINT-EXTERN-EXPORT.md b/current/CHECKPOINT-EXTERN-EXPORT.md index b6a033c..09b8044 100644 --- a/current/CHECKPOINT-EXTERN-EXPORT.md +++ b/current/CHECKPOINT-EXTERN-EXPORT.md @@ -5,38 +5,47 @@ Companion to `current/PLAN-EXTERN-EXPORT.md` — one merged plan: **Part A** add every commit, one step at a time per the cadence rule. ## Last completed step -**Phase 1.0b** (xfail — example half of 1.0) — added `examples/1223-ffi-extern-fn.sx` -(extern-binds libc `abs` via bare `extern`; sx name = C symbol, no rename) + -hand-authored `expected/` capturing the SUCCESS output (`abs(-7) = 7` / `abs(42) = -42`, exit 0). **RED**: 1223 is the only corpus failure (634 ran, 1 failed) — it parses -then errors at sema (`body produces no value`) because lowering doesn't route extern -yet. Phase 1.1 turns it green. (Prior: 1.0a (lock, green) wired fn-path extern -parsing — `parseFnDecl` → `parseOptionalExternExport()` → `FnDecl.extern_export`, -`;` body = empty-block placeholder; both lookahead predicates accept -`kw_extern`/`kw_export`; per user feedback added `FnDecl.extern_lib`/`extern_name` + -`VarDecl.extern_lib`, decision 4 REVISED.) +**Phase 1.1** (green) — wired extern fn lowering in `decl.zig`; example **1223 now +green**, full suite green (634 corpus / 443 unit, 0 fail). A bare `extern` fn lowers +exactly like a lib-less `#foreign` import: `declare i32 @abs(i32) #0` — external +linkage, C ABI, NO `__sx_ctx` param; calls emit `call i32 @abs(i32 -7)` and resolve +against the default-linked libc. Six edits, all routing `extern` declare-only +(mirroring the `foreign_expr` guards): (1) `funcWantsImplicitCtx` suppresses ctx for +`.extern_`; (2) `declareFunction` adds `is_extern_decl` and (3) includes it in the +C-ABI promotion; (4) `lazyLowerFunction` routes `.extern_`→declare-only; (5) +`lowerFunction` declare-only guard; (6) `lowerFunctionBodyInto` never promotes/lowers +an extern stub. Hand-authored 1.0b snapshot matched byte-exact — no regen needed. No +`.ir` snapshot added (the trivial `declare i32 @abs(i32)` doesn't warrant a 1000-line +full-prelude dump; behavioral `.stdout` already catches ctx/linkage regressions). ## Current state Syntax: bare `extern`/`export`, postfix after `callconv(.c)`, `extern ⇒ callconv(.c)`. **Decision 4 revised** (user 2026-06-14): `extern` carries an optional `LIB`+`"csym"` axis (`extern_lib`/`extern_name`) like `#foreign`; the `#library` decl + build-flag -linking stays separate. Touch-points: token `token.zig:45,282`; parser -`1950,3669,316,425,1305`; lowering `decl.zig:1123,387,2110,2382,2514`; IR/emit already -capable (no codegen change). Part B `foreign` footprint to purge: 643 lines / ~57 -identifiers in `src/` + 28 doc lines. End-state invariant: **zero `foreign`** (Phase -9.4 gate). **Done**: tokens (0.0) + AST/parser plumbing (0.1) + fn-path extern parsing -+ lib/name fields (1.0a), all unconsumed. Lowering not yet wired. +linking stays separate. **`extern` FUNCTIONS WORK** (import; bare form, no rename) — +parse + lower complete, behavior-equivalent to a lib-less `#foreign` fn. Still TODO in +Phase 1: the `extern LIB "csym"` lib/rename axis (fields exist, unconsumed) and the +extern-global form. `export` not started (Phase 2). Part B `foreign` footprint to +purge: 643 lines / ~57 identifiers in `src/` + 28 doc lines. End-state invariant: +**zero `foreign`** (Phase 9.4 gate). **Done**: 0.0 tokens, 0.1 AST/parser plumbing, +1.0a fn-path parsing + lib/name fields, 1.0b xfail example, 1.1 fn lowering (green). ## Next step -**Phase 1.1** (green, turns 1223 green) — in `decl.zig`, when -`fn_decl.extern_export == .extern_`, route the fn through `declareExtern` (`is_extern`, -`.external` linkage, `callconv(.c)`, no implicit ctx — anchors `decl.zig:1123,387, -2110,2113`) instead of lowering the empty-block placeholder body. Treat the bare -`extern` (no `extern_lib`/`extern_name` yet) like a lib-less `#foreign` import — the -sx name IS the C symbol, resolves against the default-linked libc. Run, then -`-Dupdate-goldens` to finalize 1223's snapshot byte-exact; review diff. Then **1.2** -(green): consume `extern LIB "csym"` rename (`extern_lib`/`extern_name`) + extern-global -`g : T extern;` (`parser.zig:425`). Stop at end of Phase 1. +**Phase 1.2** (green) — two parts, each its own xfail→green or behavior-lock: +1. **`extern LIB "csym"` rename for fns** — extend `parseOptionalExternExport()` (or + `parseFnDecl`) to parse the optional `LIB` ident + `"csym"` string after the + keyword into `FnDecl.extern_lib`/`extern_name`; consume them in `declareFunction` + (mirror the `#foreign` c_name block at `decl.zig:~2119`: declare under the C name, + map sx→C in `foreign_name_map`/dedupe). New example renaming a libc symbol (e.g. + `c_abs :: (n: i32) -> i32 extern "abs";`). +2. **extern-global `g : T extern [LIB] ["csym"];`** — parse path at `parser.zig:425` + (the var-decl with type annotation): accept postfix `extern` → set + `VarDecl.is_extern`/`extern_lib`/`extern_name`; lower like the `#foreign` global + (`decl.zig:~1115-1137`, `.is_extern = vd.is_foreign`). New example mirroring + `examples/1205-ffi-foreign-global` with `extern`. + +Stop at end of Phase 1 (do NOT start Phase 2 `export` or Part B migration). Then the +A→B gate: a unit test that `#foreign` and `extern` lower to identical IR. ## Open decisions Part A ratified (bare / postfix / `⇒ callconv(.c)` / lib-separate). Part B (confirm @@ -58,6 +67,10 @@ historical carve-out — keep `issues/*.md` provenance, gate the live tree only. Suite green (443/633). `lock` commit. - (1.0b) Added `examples/1223-ffi-extern-fn.sx` + hand-authored success snapshots. RED (634 ran, 1 failed — sema `body produces no value`). `xfail` commit; 1.1 greens it. +- (1.1) Wired extern fn lowering (6 edits in `decl.zig`, all declare-only routing + mirroring `foreign_expr`): `funcWantsImplicitCtx` + `declareFunction` cc + + `lazyLowerFunction`/`lowerFunction`/`lowerFunctionBodyInto` guards. 1223 green; + `declare i32 @abs(i32)` (C ABI, no ctx). Suite green (634/443). `green` commit. ## Known issues None yet. diff --git a/src/ir/lower/decl.zig b/src/ir/lower/decl.zig index d7d61ad..a13b56d 100644 --- a/src/ir/lower/decl.zig +++ b/src/ir/lower/decl.zig @@ -387,6 +387,9 @@ pub fn detectContextDecl(decls: []const *const Node) bool { pub fn funcWantsImplicitCtx(self: *const Lowering, fd: *const ast.FnDecl) bool { if (!self.implicit_ctx_enabled) return false; if (fd.call_conv == .c) return false; + // `extern` imports are external C symbols — C ABI, no sx context. + // (`export` defines get the same treatment in Phase 2, gap iv.) + if (fd.extern_export == .extern_) return false; return switch (fd.body.data) { .foreign_expr, .builtin_expr, .compiler_expr => false, else => !isExportedEntryName(fd.name), @@ -2078,6 +2081,12 @@ pub fn declareFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8) // calling convention's `...` tail. Drop the variadic param from the // IR signature (it has no C-level slot) and set is_variadic. const is_foreign = fd.body.data == .foreign_expr; + // Bare `extern` import: an external C symbol declared via the new linkage + // surface (empty-block placeholder body, no `foreign_expr`). It shares + // `#foreign`'s C-ABI promotion + declareExtern routing below; the optional + // `extern LIB "csym"` lib/rename axis (extern_lib/extern_name) is consumed + // in Phase 1.2. (`export` defines take the beginFunction path, not here.) + const is_extern_decl = fd.extern_export == .extern_; var is_variadic = false; var effective_params = fd.params; if (is_foreign and fd.params.len > 0 and fd.params[fd.params.len - 1].is_variadic) { @@ -2107,7 +2116,7 @@ pub fn declareFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8) // typed by name as `(args) -> ret` of a `#foreign` decl can be // assigned to / passed as a `callconv(.c)` fn-pointer without a // call-convention mismatch. - const cc: Function.CallingConvention = if (fd.call_conv == .c or is_foreign) .c else .default; + const cc: Function.CallingConvention = if (fd.call_conv == .c or is_foreign or is_extern_decl) .c else .default; // For #foreign with C name override, declare under C name and map sx name → C name if (is_foreign) { @@ -2284,7 +2293,7 @@ pub fn lazyLowerFunction(self: *Lowering, name: []const u8) void { // a fresh ct_module via `evalComptimeString`) emits `.call` against a // FuncId that doesn't exist locally; the interp can't find the // foreign target and silently no-ops instead of dispatching to libc. - if (fd.body.data == .foreign_expr) { + if (fd.body.data == .foreign_expr or fd.extern_export == .extern_) { if (self.resolveFuncByName(name) == null) { self.declareFunction(fd, name); self.lowered_functions.put(name, {}) catch {}; @@ -2372,6 +2381,11 @@ pub fn lowerFunctionBodyInto(self: *Lowering, fd: *const ast.FnDecl, fid: FuncId const func = &self.module.functions.items[@intFromEnum(fid)]; self.setCurrentSourceFile(func.source_file); + // `extern` imports are pure declarations — never promote the stub to a real + // function or lower the (empty placeholder) body. Mirrors the declare-only + // handling in lowerFunction / lazyLowerFunction. + if (fd.extern_export == .extern_) return; + const ret_ty = self.resolveReturnType(fd); if (!func.is_extern) { @@ -2477,8 +2491,9 @@ pub fn lowerFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8, i }) catch unreachable; } - // Check if the function body is a builtin or foreign declaration (no body needed) - if (fd.body.data == .builtin_expr or fd.body.data == .foreign_expr or fd.body.data == .compiler_expr) { + // Check if the function body is a builtin or foreign declaration (no body + // needed). `extern` imports are declare-only too (empty placeholder body). + if (fd.body.data == .builtin_expr or fd.body.data == .foreign_expr or fd.body.data == .compiler_expr or fd.extern_export == .extern_) { // Already declared by scanDecls/declareFunction (which handles #foreign renames) return; }