Extern attribute schema

Platform spec article

Extern attribute schema

Back to FFI and extern ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   Author-facing extern import rules live on this hub.

   Context

   v0.3 interop split author syntax from execution lowering; articles must not fork MUST tables.

   Decision

   This feature hub must own normative MUST/SHOULD contract text for foreign import. Sibling articles must not redefine hub requirements.

   Consequences

   Execution and tooling specs link here for Extern placement and attribute shape.

   Verification anchors

   /platform-spec/language-meta/interop/ffi-and-extern/; compiler/crates/beskid_analysis contract validation.

   Open full ADR page

2. 0002-extern-contract-level-only Extern on contract declarations only Accepted

   Extern on non-contract declarations is E1510.

   Context

   Bulk C-style surfaces need stable contract blocks; module-level extern was exploratory.

   Decision

   Extern must apply only to contract declarations in v0.3 Standard. The reference compiler must reject Extern on non-contract declarations (E1510).

   Consequences

   Codegen collects ExternImport from contract metadata; mod-level extern remains non-Standard.

   Verification anchors

   compiler/crates/beskid_analysis/src/types/context/context.rs; extern attribute schema.

   Open full ADR page

3. 0003-mod-level-extern-deferred Mod-level Extern not Standard v0.3 Accepted

   Bulk import uses contract blocks with method signatures.

   Context

   Header-style Extern on mod was considered for v0.3 but increases parser and ABI ambiguity.

   Decision

   Extern on mod is not part of v0.3 Standard. Authors must use contract blocks with method signatures ending in ;.

   Consequences

   Future promotion requires a dedicated ADR and profile conformance tests.

   Verification anchors

   /platform-spec/language-meta/interop/ffi-and-extern/ v0.3 scope section.

   Open full ADR page

4. 0004-user-cabi-vs-runtime-rustabi User C ABI separate from runtime Rust exports Accepted

   Tier-1 user libraries use C profile; runtime builtins stay on Rust ABI.

   Context

   Mixing user Extern symbols with BESKID_RUNTIME_ABI_VERSION exports caused namespace and stability risk.

   Decision

   Plane	Rule
   User libraries	C ABI profile + link-time binding
   Runtime embedding	Rust ABI profile / frozen builtin table
   Separation	User Extern must not mutate runtime builtin symbol namespace

   Consequences

   JIT registration and engine policy keep tables disjoint; see profile boundary map on hub.

   Verification anchors

   compiler/crates/beskid_abi; Rust ABI profile; C ABI profile.

   Open full ADR page

5. 0005-repr-c-deferred-v031 repr C records deferred to v0.3.1 Accepted

   CLayout primitive structs are Proposed not v0.3.0 Standard.

   Context

   Arbitrary Beskid record repr(C) needs layout rules beyond interop views.

   Decision

   repr(C) on arbitrary Beskid types is out of scope for v0.3.0 Standard; CLayout primitive structs land in v0.3.1 (Proposed) per C layout types.

   Consequences

   v0.3.0 Standard ships interop view types and link-time import first.

   Verification anchors

   C ABI profile.

   Open full ADR page

Articles

• Contract import syntax How extern contracts declare foreign imports and map to symbols and call shapes. article Standard Reviewed Wed May 20
• Extern attribute schema Normative Extern and per-method interop attributes for contract imports (v0.3). article Standard Reviewed Wed May 20
• FFI and extern — Verification and traceability Conformance strategy for v0.3 FFI spec (fixtures, diagnostics, ignored runtime tests). article Standard Reviewed Wed May 20

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 7 SpecSection(s) · 1 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  FFI and extern

  Parent feature hub

• Feature
  C ABI profile

  Linking and type lowering

Contract-level Extern

Applied only to contract declarations.

Field	Required	Meaning
Abi	yes	In v0.3 Standard, must be "C" (case-insensitive). Other values are reserved.
Library	yes	Logical library identity for link-time resolution (see link-time linking and foreign library import). Must be non-empty.

Example:

[Extern(Abi:"C", Library:"libc")]
pub contract Libc {
    i64 getpid();
}

Per-method overrides (v0.3.0)

Contract methods may carry method-level attributes:

Attribute	Required	Meaning
Symbol	no	Linker / foreign symbol name when it differs from the Beskid method name (for example Symbol:"pthread_create"). When omitted, the method identifier is the logical symbol.
Library	no	Overrides contract-level Library for this method only.

Example:

[Extern(Abi:"C", Library:"libc.so.6")]
pub contract Libc {
    [Symbol("write")]
    i64 write(i32 fd, CBuffer buf, i64 count);
}

Parameter modifiers (v0.3.0)

Modifier	Meaning
(none)	Borrow — caller retains ownership; foreign code must not retain pointers beyond the call unless documented otherwise.
Transfer	Transfer — ownership of the view’s storage obligation moves per profile rules (see ownership at the boundary).
GcPin	Proposed — GC-managed handle pinned for the call duration via runtime root handle; not required for Standard conformance in v0.3.0.

ref u8 remains valid as a byte slice start without length; authors should prefer CBuffer / CStringView interop views instead.

Diagnostics

Code	Condition
E1510	Extern applied to a disallowed declaration target
E1520	Invalid Abi (not "C") — transition: T0901
E1521	Missing Library — transition: T0902
E1522	Disallowed extern parameter type — transition: T0903
E1523	Disallowed extern return type — transition: T0904
E1524–E1539	Export, interop views, link manifest — see registry

Full band: Diagnostic code registry / design model. Fixtures: compiler/crates/beskid_tests/src/analysis/ffi_v03_spec.rs.