refactor(ffi-linkage): Phase 9.3 — purge remaining 'foreign' from library/docs/example comments

Capital-Foreign + stale-identifier comment refs: library (Foreign Java types→Runtime,
foreign-class→runtime-class, foreign_class_map→runtime_class_map); docs/debugger
(foreign call→extern call); docs/fork-c ledger (foreign_class_map, protocol/foreign→
runtime-class); docs/inline-asm-design Deviation-6 obsolete #foreign-vs-extern design
RESOLVED to the landed extern/export reality; example comments (parseForeignClassDecl→
parseRuntimeClassDecl, checkForeignRefs→checkExternRefs, Foreign decls→Extern). Docs/
comments only — no build impact.
This commit is contained in:
agra
2026-06-15 11:03:29 +03:00
parent dfae690b31
commit 9719432e79
14 changed files with 32 additions and 34 deletions

View File

@@ -457,8 +457,7 @@ ATT,
**C-calling-convention**, raw-named, link-time-resolved declaration — the same
thing Zig's `extern fn` produces (also C-callconv). The reverse direction (asm
calling *back into* an sx function) is handled by `export`, the define-and-expose
dual of `extern`. (The legacy prefix `#foreign` spelling that originally provided
the import path has since been replaced by the postfix `extern`/`export` keywords.)
dual of `extern`.
Everything *semantic* — comptime-known template, register/memory constraints
verbatim to LLVM, clobber meaning, "no-output ⇒ must be volatile," AT&T default,
@@ -682,7 +681,7 @@ LLVM — `@19/include/llvm-c/Core.h:971`). No operands, no rewrite, no volatile;
multiple blocks concatenate in source order (as Zig does).
**Calling into an asm-defined symbol needs no new machinery** — declare it with a
lib-less `#foreign` (Deviation 6, §II.2): `my_func :: (sig) -> R #foreign;` emits
lib-less `extern` (Deviation 6, §II.2): `my_func :: (sig) -> R extern;` emits
an external-linkage, raw-named, C-ABI extern that the linker resolves against the
`.global` the asm block defines.
@@ -721,7 +720,7 @@ No change to `src/codegen.zig` is needed (the IR/LLVM path owns this).
indirect-memory (`"=*m"`) constraints, `%=` unique-id, output-to-const rejection.
* **Phase 3.** Global/module asm decl (`LLVMAppendModuleInlineAsm`) + the
comptime-call guard, plus Intel-dialect opt-in. Small: the extern-call path
already exists (lib-less `#foreign`).
already exists (lib-less `extern`).
* **Phase 4 (optional).** Upgrade `clobbers(.name)` from dot-name sugar to a
compile-time-checked per-architecture `Clobber` enum (typo-checking; same syntax).
* **Phase 5 (optional).** Naked functions (`callconv`-equivalent) for full
@@ -760,18 +759,17 @@ Largely settled through design review; what remains:
source-compat risk)* vs globally reserved *(simpler lexer)*.
3. **Brace separator:** comma *(recommended — trailing-comma-friendly,
literal-style)* vs `;` *(matches sx statement blocks)*.
4. **Asm-symbol extern spelling (Deviation 6):** reuse lib-less `#foreign` for v1
*(works, zero new surface — but it is a C-FFI **import** binding: import-only,
C-ABI, spelled "foreign")* vs a dedicated `#extern`/linkname *(cleaner spelling,
and the only path that could also **export** an sx symbol so asm can call back
in — which `#foreign` cannot)*. **Recommend `#foreign` for v1**; revisit
`#extern` if/when asm-calls-into-sx or non-C-ABI symbols are needed.
4. **Asm-symbol extern spelling (Deviation 6): RESOLVED** — use the lib-less `extern`
keyword to call *into* an asm symbol (import), and `export` for the reverse
direction (an sx function asm can call *back into*). The dedicated linkage
keywords landed (FFI-linkage stream), so no new surface is needed and both
directions are covered.
*Decided:* brace block `{ … }` (Dev 1) · `->`/`=` markers, `:` sections dropped,
`<-` rejected (Dev 2) · `clobbers(.…)` enum-literal list, dot-name sugar now →
checked enum later (Dev 3) · multiple value-outputs return a tuple (Dev 5). For
global asm (Dev 6) the call-*into*-asm direction reuses lib-less `#foreign`
(`specs.md:1209` updated); the extern *spelling* is open decision 4 above.
global asm (Dev 6) the call-*into*-asm direction reuses lib-less `extern` (Decision
4, resolved).
## II.11 Risks
@@ -816,8 +814,8 @@ void LLVMAppendModuleInlineAsm(LLVMModuleRef M, const char *Asm, size_t Len); /
(syntax) · `doc/langref.html.in:4217-4300` (spec).
**sx (target, `~/projects/sx`):** `src/token.zig` · `src/lexer.zig:402` (#string) ·
`src/ast.zig:13,85,721` · `src/parser.zig` (`parsePrimary`), `:319` (optional
`#foreign` library) · `src/ir/expr_typer.zig` · `src/ir/inst.zig:80,219,260` ·
`src/ast.zig:13` · `src/parser.zig` (`parsePrimary`), the optional `extern`
library tail · `src/ir/expr_typer.zig` · `src/ir/inst.zig:80,219,260` ·
`src/ir/lower/expr.zig` · `src/ir/module.zig:300` (`declareExtern`) ·
`src/ir/emit_llvm.zig:167` (msgSend cache), `:1244` (extern⇒C-ABI), `:1279`
(raw symbol name) · `src/ir/interp.zig` (`bailDetail`) · `src/llvm_api.zig:1-17` ·
@@ -995,5 +993,5 @@ asm {
retq
ATT,
};
my_add :: (a: i32, b: i32) -> i32 #foreign; // lib-less extern = Zig's `extern fn`
my_add :: (a: i32, b: i32) -> i32 extern; // lib-less extern = Zig's `extern fn`
```