C ABI profile — Extern contracts and linking

Platform spec article

C ABI profile — Extern contracts and linking

Back to C ABI profile ◎ 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

   C/System V binding rules defer to this hub.

   Context

   Interop.Contracts primitives need a single C profile authority for tier-1 hosts.

   Decision

   This feature hub must own normative MUST/SHOULD for C-compatible foreign libraries. Sibling articles add detail without redefining hub MUST tables.

   Consequences

   Cranelift lowering and foreign library import tooling align to this profile.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/

   Open full ADR page

2. 0002-link-time-standard-tier1 Link-time binding Standard tier-1 Accepted

   dlopen is not Standard conformance for tier-1.

   Context

   Dynamic resolution complicates reproducible builds and CI conformance.

   Decision

   v0.3 Standard tier-1 conformance must use link-time library binding (link-time linking).

   Consequences

   Engine may retain Proposed extern_dlopen paths separately from Standard claims.

   Verification anchors

   compiler/crates/beskid_codegen; Foreign library import.

   Open full ADR page

3. 0003-dynamic-resolution-proposed Runtime dlopen Proposed appendix Accepted

   Dynamic resolution profile is non-Standard.

   Context

   Some hosts want late binding; tier-1 reference path standardizes link-time.

   Decision

   Runtime dlopen / dlsym resolution is demoted to the dynamic resolution profile (Proposed appendix, not Standard).

   Consequences

   Documentation and conformance matrices must not require dlopen for Standard tier-1.

   Verification anchors

   compiler/crates/beskid_engine/src/engine.rs (extern_dlopen, Proposed).

   Open full ADR page

4. 0004-winapi-out-of-stdlib-standard WinAPI outside stdlib Standard Accepted

   Windows user-extern linking not tier-1 Standard in corelib.

   Context

   WinAPI/stdcall surfaces belong in platform packages with distinct conformance tiers.

   Decision

   WinAPI / stdcall as a stdlib concern is out of scope for tier-1 Standard conformance; platform packages may document Proposed mappings separately.

   Consequences

   Platform tier matrix records host-specific tiers.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/

   Open full ADR page

5. 0005-v03-delivery-bands v0.3.0 views v0.3.1 CLayout bands Accepted

   Delivery bands separate Standard views from Proposed layout structs.

   Context

   Implementers need a spec-first schedule when codegen trails text.

   Decision

   Band	Content	Status
   v0.3.0	Interop views, link-time import, symbol overrides	Standard (spec; impl may trail)
   v0.3.1	CLayout primitive structs	Proposed
   Later	Nested FFI structs, enum ABI, foreign-thread entry	Planned

   Consequences

   Articles tag Proposed vs Standard explicitly; CI strict mode can gate premature Standard claims.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/ and child articles.

   Open full ADR page

Articles

• C ABI profile — C layout types (v0.3.1) repr(C) records for FFI after interop views ship; nested complex types deferred. article Proposed Reviewed Wed May 20
• C ABI profile — Dynamic resolution profile Non-Standard appendix for runtime dlopen/dlsym extern resolution (legacy v0.1 path). article Proposed Reviewed Wed May 20
• C ABI profile — Extern contracts and linking Library and symbol metadata, JIT dlopen resolution, and policy gates for user extern contracts. article Standard Reviewed Fri May 01
• C ABI profile — Interop view types (v0.3.0) CStringView, CBuffer, and CArrayView layouts for user Extern boundaries. article Standard Reviewed Wed May 20
• C ABI profile — Link-time linking Normative link-time binding for user Extern libraries (v0.3 Standard). article Standard Reviewed Sat May 23
• C ABI profile — Platform tier matrix Tier-1 Standard hosts vs Proposed platforms; WinAPI out of stdlib scope. article Standard Reviewed Wed May 20
• C ABI profile — Types and call conventions Permitted C ABI representations for Beskid extern contract parameters and returns in the reference compiler. article Standard Reviewed Fri May 01

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

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

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

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

Related spec docs

• Feature
  C ABI profile

  Parent feature hub

• Feature
  FFI and extern

  Syntax and semantic placement of Extern

Extern metadata

User foreign entrypoints are declared on contract types using the Extern attribute (see FFI and extern). The C ABI profile interprets attribute fields as:

• Abi — in current toolchains, "C" is the supported user-facing choice for this profile; other strings are reserved.
• Library — shared object or loadable module path semantics as implemented by the engine when dynamic resolution is enabled.

Implementation references: ExternImport in compiler/crates/beskid_codegen/src/lowering/context.rs and collection in compiler/crates/beskid_codegen/src/lowering/lowerable.rs.

Link-time resolution (v0.3 Standard)

User Extern symbols must be satisfied at link time via project link metadata and driver inputs. See link-time linking and foreign library import.

Artifacts with unresolved imports must fail before run with diagnostics listing (library, symbol) pairs.

Dynamic resolution (non-Standard)

Runtime dlopen / dlsym is documented under dynamic resolution profile (Proposed). It must not be described as the default path in v0.3 platform-spec.

AOT and JIT parity

Object emission paths must surface the same import set for a given artifact; unresolved symbols must fail at link time with parity between JIT link drivers and AOT link steps.