lab/sx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

comptime compiler-API: Phase 1 foundation + Phase 2.1 weld plan

Browse Source 
Introduce the welded comptime `compiler` library (`#library "compiler"` +
`abi(.zig) extern compiler`), per design/comptime-compiler-api.md, and unify
`callconv(...)` into the new `abi(...)` annotation.

abi(...) replaces callconv(...):
- New ABI enum { default, c, zig, pure }; `abi(.c|.zig|.pure)` parses in the
  postfix slot before extern/export (and standalone). `kw_callconv` -> `kw_abi`.
- Migrated 52 sx files, the call-convention-mismatch diagnostic, and docs
  (readme/specs) from `callconv(.c)` to `abi(.c)`.

Phase 1 — welded compiler library (parse -> registry -> validation -> bridge):
- `abi(.zig) extern compiler` parses on fn decls (carries abi/extern_lib) and
  struct decls (StructDecl.abi/extern_lib).
- `#library "compiler"` is the comptime-only internal surface — never dlopen'd.
- src/ir/compiler_lib.zig: the binding registry (the safety boundary). `Field`
  welded to StructInfo.Field with layout baked from the real Zig type
  (@offsetOf/@sizeOf); `findType`/`findFn`. Welded structs are layout-validated
  at registration (field set + total size) as a header checked against the impl.
- Host-call bridge: a `fn abi(.zig) extern compiler` dispatches under the
  comptime interp to its registered Zig handler (intern/text_of round-trip),
  never dlsym. IR Function.compiler_welded; validated in declareFunction.
- Comptime-only enforcement: a runtime call to a welded fn is a clean
  build-gating error (emitCall), not an undefined-symbol link failure.

Phase 2.1 — byte-layout weld foundation:
- Decision: full byte-layout weld (sx struct laid out byte-identically to the
  bound Zig type). Registered StructInfo (first non-natural / Zig-reordered
  layout). `computeWeldPlan` — pure offset-ordered element plan + padding +
  sx-field->LLVM-element remap; unit-tested. Emit/interp wiring is the next
  sub-step (2.2+, see current/CHECKPOINT-COMPILER-API.md).

Examples: 0625/0626 (welded struct + fn round-trip), 1183/1184/1185
(layout-mismatch, unexported-fn, runtime-call diagnostics).
This commit is contained in:
agra
2026-06-17 13:31:11 +03:00
parent 3a9b508502
commit cd5b958d19
100 changed files with 1490 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/ir/lower/closure.zig
View File

@@ -78,7 +78,7 @@ pub fn lowerLambda(self: *Lowering, lam: *const ast.Lambda) Ref {
// Without implicit_ctx, env is slot 0 and user params follow.
var params = std.ArrayList(Function.Param).empty;
const env_ptr_ty = self.module.types.ptrTo(.void);
const lambda_wants_ctx = self.implicit_ctx_enabled and lam.call_conv != .c;
const lambda_wants_ctx = self.implicit_ctx_enabled and lam.abi != .c;
if (lambda_wants_ctx) {
params.append(self.alloc, .{
.name = self.module.types.internString("__sx_ctx"),
@@ -168,7 +168,7 @@ pub fn lowerLambda(self: *Lowering, lam: *const ast.Lambda) Ref {
};
const name_id = self.module.types.internString(name);
const func_id = self.builder.beginFunction(name_id, params.items, ret_ty);
if (lam.call_conv == .c) {
if (lam.abi == .c) {
self.module.getFunctionMut(func_id).call_conv = .c;
}
self.builder.currentFunc().has_implicit_ctx = lambda_wants_ctx;

37
src/ir/lower/decl.zig
View File

@@ -10,6 +10,7 @@ const unescape = @import("../../unescape.zig");
const errors = @import("../../errors.zig");
const program_index_mod = @import("../program_index.zig");
const resolver_mod = @import("../resolver.zig");
const compiler_lib = @import("../compiler_lib.zig");
const ProgramIndex = program_index_mod.ProgramIndex;
const GlobalInfo = program_index_mod.GlobalInfo;
const ModuleConstInfo = program_index_mod.ModuleConstInfo;
@@ -497,7 +498,7 @@ pub fn detectContextDecl(decls: []const *const Node) bool {
/// `__sx_<name>_impl` with the ctx param) lands in Step 4 proper.
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;
if (fd.abi == .c) return false;
// `extern` imports and `export` defines are external C symbols —
// C ABI, no sx context (Phase 2, gap iv).
if (fd.extern_export != .none) return false;
@@ -2256,11 +2257,11 @@ pub fn declareFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8)
}
// `extern` declarations are external C symbols by definition — promote
// them to callconv(.c) when the user didn't write it explicitly. This keeps
// them to abi(.c) when the user didn't write it explicitly. This keeps
// fn-ptr coercion type-safe: anything typed by name as `(args) -> ret` of an
// `extern` decl can be assigned to / passed as a `callconv(.c)` fn-pointer
// `extern` decl can be assigned to / passed as a `abi(.c)` fn-pointer
// without a call-convention mismatch.
const cc: Function.CallingConvention = if (fd.call_conv == .c or is_extern_decl or fd.extern_export == .export_) .c else .default;
const cc: Function.CallingConvention = if (fd.abi == .c or is_extern_decl or fd.extern_export == .export_) .c else .default;
// Symbol-name override: `extern … "csym"` / `export … "csym"` (fd.extern_name).
// Declare under the C name and map the sx name → C name so call sites resolve
@@ -2296,9 +2297,29 @@ pub fn declareFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8)
func.source_file = self.current_source_file;
func.is_variadic = is_variadic;
func.has_implicit_ctx = wants_ctx;
if (weldedCompilerFn(self, fd, name)) func.compiler_welded = true;
self.fn_decl_fids.put(fd, fid) catch {};
}
/// A `fn abi(.zig) extern <lib>` binds the comptime `compiler` library. Validate
/// it (the bound lib must be `compiler`; the name must be on the function-export
/// list) and return whether it is a welded compiler function — the interpreter
/// dispatches such a call to its registered Zig handler instead of dlsym. Any
/// failure is a build-gating `.err` (never a silent fall-through to dlsym).
fn weldedCompilerFn(self: *Lowering, fd: *const ast.FnDecl, name: []const u8) bool {
if (fd.abi != .zig) return false;
const diags = self.diagnostics;
if (fd.extern_lib == null or !std.mem.eql(u8, fd.extern_lib.?, compiler_lib.lib_name)) {
if (diags) |d| d.addFmt(.err, fd.name_span, "abi(.zig) function '{s}' must bind the compiler library — write `extern {s}`", .{ name, compiler_lib.lib_name });
return false;
}
if (compiler_lib.findFn(name) == null) {
if (diags) |d| d.addFmt(.err, fd.name_span, "'{s}' is not a function exported by the '{s}' library", .{ name, compiler_lib.lib_name });
return false;
}
return true;
}
/// Register a namespaced import's OWN functions under their module-qualified
/// name (`ns.fn`), giving each a UNIQUE FuncId in the function table. Two
/// modules each exporting a top-level `parse` otherwise collide in the
@@ -2553,7 +2574,7 @@ pub fn lowerFunctionBodyInto(self: *Lowering, fd: *const ast.FnDecl, fid: FuncId
func.is_extern = false; // promote from extern stub to real function
// `export` defines force external linkage + C ABI (Phase 2, gaps i+ii).
func.linkage = if (isExportedEntryName(name) or fd.extern_export == .export_) .external else .internal;
if (fd.call_conv == .c or fd.extern_export == .export_) func.call_conv = .c;
if (fd.abi == .c or fd.extern_export == .export_) func.call_conv = .c;
// Set inst_counter to param count (params occupy refs 0..N-1). IR params
// = AST params + 1 if the function carries `__sx_ctx` at slot 0.
const ctx_slots: usize = if (func.has_implicit_ctx) 1 else 0;
@@ -2589,7 +2610,7 @@ pub fn lowerFunctionBodyInto(self: *Lowering, fd: *const ast.FnDecl, fid: FuncId
scope.put(p.name, .{ .ref = slot, .ty = pty, .is_alloca = true });
}
// Inbound entry points + callconv(.c) sx functions: bind current_ctx_ref
// Inbound entry points + abi(.c) sx functions: bind current_ctx_ref
// to the static default before any user code runs.
if (!wants_ctx and self.implicit_ctx_enabled) {
if (self.program_index.global_names.get("__sx_default_context")) |dctx_gi| {
@@ -2695,7 +2716,7 @@ pub fn lowerFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8, i
}
// Set calling convention. `export` defines promote to C ABI (gap ii).
if (fd.call_conv == .c or fd.extern_export == .export_) {
if (fd.abi == .c or fd.extern_export == .export_) {
self.builder.currentFunc().call_conv = .c;
}
@@ -2729,7 +2750,7 @@ pub fn lowerFunction(self: *Lowering, fd: *const ast.FnDecl, name: []const u8, i
scope.put(p.name, .{ .ref = slot, .ty = pty, .is_alloca = true });
}
// Inbound entry points + callconv(.c) sx functions: bind
// Inbound entry points + abi(.c) sx functions: bind
// current_ctx_ref to &__sx_default_context. See companion comment
// in `lowerFunction` for the same case.
if (!wants_ctx_lf and self.implicit_ctx_enabled) {

6
src/ir/lower/expr.zig
View File

@@ -1894,7 +1894,7 @@ pub fn lowerExpr(self: *Lowering, node: *const Node) Ref {
// Coercing a bare fn name to a fn-pointer
// type — the call_conv must match. A
// default-conv sx fn assigned to a
// callconv(.c) slot (e.g. passed to
// abi(.c) slot (e.g. passed to
// pthread_create) would otherwise crash at
// runtime when the C caller doesn't supply
// the implicit __sx_ctx arg.
@@ -1902,8 +1902,8 @@ pub fn lowerExpr(self: *Lowering, node: *const Node) Ref {
const func_cc = self.module.functions.items[@intFromEnum(fid)].call_conv;
if (func_cc != tt_info.function.call_conv) {
if (self.diagnostics) |d| {
const want_cc = if (tt_info.function.call_conv == .c) "callconv(.c)" else "default sx convention";
const have_cc = if (func_cc == .c) "callconv(.c)" else "default sx convention";
const want_cc = if (tt_info.function.call_conv == .c) "abi(.c)" else "default sx convention";
const have_cc = if (func_cc == .c) "abi(.c)" else "default sx convention";
d.addFmt(.err, node.span, "call-convention mismatch: '{s}' is declared with {s} but the target type expects {s}", .{ eff_fn_name, have_cc, want_cc });
}
break :blk self.emitPlaceholder(eff_fn_name);

2
src/ir/lower/ffi.zig
View File

@@ -1133,7 +1133,7 @@ pub fn synthesizeJniMainStub(self: *Lowering, fcd: *const ast.RuntimeClassDecl,
// JNI native methods are C-callable entry points — install the
// static default Context so `context.X` reads in the method body
// resolve through `current_ctx_ref`. Mirror the same binding
// `lowerFunction` does for callconv(.c) / isExportedEntryName.
// `lowerFunction` does for abi(.c) / isExportedEntryName.
const saved_ctx_ref_jni = self.current_ctx_ref;
defer self.current_ctx_ref = saved_ctx_ref_jni;
if (self.implicit_ctx_enabled) {

54
src/ir/lower/nominal.zig
View File

@@ -6,6 +6,7 @@ const mod_mod = @import("../module.zig");
const type_bridge = @import("../type_bridge.zig");
const program_index_mod = @import("../program_index.zig");
const resolver_mod = @import("../resolver.zig");
const compiler_lib = @import("../compiler_lib.zig");
const StructTemplate = program_index_mod.StructTemplate;
const TemplateParam = program_index_mod.TemplateParam;
@@ -673,7 +674,13 @@ pub fn registerStructDecl(self: *Lowering, sd: *const ast.StructDecl, source_fil
// any forward-reference stub. Same-name structs in DIFFERENT sources get
// distinct TypeIds instead of last-wins clobbering the first.
const info: types.TypeInfo = .{ .@"struct" = .{ .name = name_id, .fields = fields.items } };
_ = self.internNamedTypeDecl(decl_key, name_id, info, nominal_id);
const struct_tid = self.internNamedTypeDecl(decl_key, name_id, info, nominal_id);
// Welded `struct abi(.zig) extern compiler { … }`: the sx declaration is a
// header checked against the compiler's real Zig type — validate the layout
// matches the binding registry (a mismatch is a build error). See
// design/comptime-compiler-api.md.
if (sd.abi == .zig) validateWeldedStruct(self, sd, struct_tid, fields.items);
// Store field defaults for struct literal lowering
if (sd.field_defaults.len > 0) {
@@ -709,6 +716,51 @@ pub fn registerStructDecl(self: *Lowering, sd: *const ast.StructDecl, source_fil
}
}
/// Validate a welded `struct abi(.zig) extern <lib> { … }` against the `compiler`
/// library's binding registry: the bound library must be `compiler`, the name
/// must be on the export list, and the sx-declared layout must match the real Zig
/// type's (the sx side is a *header* checked against the implementation). Any
/// failure is a build-gating `.err` diagnostic — never a silent reinterpretation.
fn validateWeldedStruct(self: *Lowering, sd: *const ast.StructDecl, tid: TypeId, fields: []const types.TypeInfo.StructInfo.Field) void {
const diags = self.diagnostics orelse return;
const table = &self.module.types;
// A span that points into the struct (its first field, else zero) — the decl
// has no name span of its own.
const span: ast.Span = if (sd.field_types.len > 0) sd.field_types[0].span else .{ .start = 0, .end = 0 };
// The bound library must be the sole welded source.
if (sd.extern_lib == null or !std.mem.eql(u8, sd.extern_lib.?, compiler_lib.lib_name)) {
diags.addFmt(.err, span, "abi(.zig) struct '{s}' must bind the compiler library — write `extern {s}`", .{ sd.name, compiler_lib.lib_name });
return;
}
// The name must be on the curated export list (the safety boundary).
const bt = compiler_lib.findType(sd.name) orelse {
diags.addFmt(.err, span, "'{s}' is not a type exported by the '{s}' library", .{ sd.name, compiler_lib.lib_name });
return;
};
// Build the observed sx layout (field name + computed size) and total size.
var sx_fields = std.ArrayList(compiler_lib.SxField).empty;
defer sx_fields.deinit(self.alloc);
for (fields) |f| {
sx_fields.append(self.alloc, .{
.name = table.getString(f.name),
.size = table.typeSizeBytes(f.ty),
}) catch return;
}
const total = table.typeSizeBytes(tid);
const mismatch = compiler_lib.validateStructLayout(bt, sx_fields.items, total) orelse return;
switch (mismatch) {
.field_count => |m| diags.addFmt(.err, span, "welded type '{s}' has {d} field(s) in the compiler library but the declaration has {d}", .{ sd.name, m.expected, m.got }),
.field_name => |m| diags.addFmt(.err, span, "welded type '{s}' field {d} is named '{s}' in the compiler library, not '{s}'", .{ sd.name, m.index, m.expected, m.got }),
.field_size => |m| diags.addFmt(.err, span, "welded type '{s}' field '{s}' is {d} byte(s) in the compiler library but {d} as declared", .{ sd.name, m.name, m.expected, m.got }),
.total_size => |m| diags.addFmt(.err, span, "welded type '{s}' is {d} byte(s) in the compiler library but {d} as declared (padding/alignment mismatch)", .{ sd.name, m.expected, m.got }),
}
}
/// Register a top-level ENUM decl under a per-decl nominal identity (E6a) —
/// the enum twin of `registerStructDecl`. A GENUINE same-name shadow already
/// reserved its DISTINCT slot up-front in `scanDecls` (the first at id 0, the

4
src/ir/lower/objc_class.zig
View File

@@ -255,7 +255,7 @@ pub fn lowerObjcPropertySetter(self: *Lowering, obj_expr: *const ast.Node, field
} }, .void);
}
/// Get a FuncId for an external C-callconv function. If a function
/// Get a FuncId for an external C-ABI function. If a function
/// with this exported name already exists in the module (e.g.
/// declared by stdlib `extern` decl), return it; otherwise
/// declare it fresh with the given signature.
@@ -290,7 +290,7 @@ pub fn ensureCRuntimeDecl(self: *Lowering, name: []const u8, param_tys: []const
/// 2. Calls `object_getIvar(obj, ivar)` to get the `*<Cls>State`
/// state pointer.
/// 3. Calls the sx body `@<Cls>.<method>(__sx_default_context,
/// state, ...user_args)` (default sx-callconv).
/// state, ...user_args)` (default sx convention).
/// 4. Returns the result (or `ret void`).
///
/// IMP name: `__<ClassName>_<methodName>_imp`. emit_llvm's