Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

FFI and extern

Platform spec feature

FFI and extern

Back to Interop Open in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

v0.3 scope

v0.3 FFI finalizes normative platform contracts for user interop and layout at foreign boundaries. This pass is spec-first: reference compiler and CLI behavior may land in v0.3.x point releases after the text is stable.

In scope for v0.3 Standard

  • Extern on contract declarations (import from C-compatible libraries).
  • Interop view types (v0.3.0) for buffers and string-like data at the boundary.
  • Link-time library binding as the conformance path for Standard tier-1 hosts.
  • Export and callbacks for embedding and plugin models.
  • Project link metadata and foreign library import tooling.

Out of scope or deferred

  • Changes to BESKID_RUNTIME_ABI_VERSION and the frozen runtime builtin export table — runtime embedding stays on the Rust ABI profile.
  • repr(C) record types on arbitrary Beskid types — v0.3.1 (see C layout types).
  • WinAPI / stdcall as a stdlib concern — tier-1 Standard conformance does not require Windows user-extern linking in corelib; platform packages may document Proposed mappings separately.
  • Runtime dlopen resolution — demoted to dynamic resolution profile (non-Standard appendix).

Profile boundary map 

flowchart TB
  subgraph author [Author Beskid code]
    contract[contract + Extern attribute]
    views[interop view types]
  end
  subgraph lang [language-meta]
    ic[Interop.Contracts]
    cabi[C ABI profile]
    export[Export and callbacks]
    rustabi[Rust ABI profile]
  end
  subgraph tool [tooling]
    link[Project.proj link metadata]
    fli[foreign library import]
  end
  subgraph exec [execution]
    dispatch[Extern dispatch and policy]
    builtins[Runtime builtins table]
  end
  contract --> ic
  contract --> cabi
  views --> ic
  link --> fli --> dispatch
  cabi --> dispatch
  export --> rustabi --> builtins
  dispatch -.->|must not mutate| builtins

Tier-1 rule: user Extern libraries use C ABI profile + link-time binding. Runtime embedding and compiler builtins stay on Rust ABI profile / frozen BESKID_RUNTIME_ABI_VERSION — never mixed in the same symbol namespace.

Link-time resolution (reference compiler): AOT builds resolve ExternImport symbols through the project link block and AotBuildRequest::external_libraries (compiler/crates/beskid_aot/src/api.rs, compiler/crates/beskid_aot/src/linker.rs). See C ABI profile — Link-time linking for normative rules; normative text is not duplicated here.

What this feature specifies

This feature is the canonical language-level chapter for foreign import in Beskid: Extern metadata, contract import syntax, optional per-method symbol overrides, and how declarations connect to Interop.Contracts and the C ABI profile.

Lowering tables, linker drivers, and syscall policy remain under /execution/ and Extern dispatch and policy; this hub owns author-facing rules only.

Placement of Extern

The Extern attribute is a contract-level interop marker only. The reference compiler must reject Extern on non-contract declarations (diagnostic E1510).

Extern on mod is not part of v0.3 Standard; bulk C-header-style surfaces should use contract blocks with method signatures ending in ;.

Extern supplies ABI and library metadata consumed when building ExternImport records during codegen (compiler/crates/beskid_codegen/src/lowering/lowerable.rs).

Formal attribute shape

The platform reserves a built-in attribute declaration equivalent to:

pub attribute Extern(ContractDeclaration) {
    Abi: string = "C",
    Library: string,
}

Contract methods may carry additional method-level attributes documented in extern attribute schema (for example Symbol overrides).

Safety and pointers

Unmanaged data crossing the boundary must use interop view types or primitives permitted by the active profile. Obligations for borrow, transfer, and opaque handles are normative under ownership at the boundary.

Compiler mods do not gain ambient FFI unless the manifest grants extern_ffi — see mod host bridge FAQ.

Implementation anchors

  • Grammar: compiler/crates/beskid_analysis/src/beskid.pest (contract, ContractMethodSignature)
  • AST: compiler/crates/beskid_analysis/src/syntax/items/contract_definition.rs
  • Semantic validation: compiler/crates/beskid_analysis/src/types/context/context.rs
  • Diagnostics: compiler/crates/beskid_tests/src/analysis/diagnostics.rs (E1510, extern type band)
  • Codegen extern collection: compiler/crates/beskid_codegen/src/lowering/lowerable.rs, compiler/crates/beskid_codegen/src/lowering/context.rs

Decisions

Section titled “Decisions”

No open decisions. Closed choices are normative ADRs under adr/ (D-LMETA-FFI-0001 … D-LMETA-FFI-0005); use the reader ADRs tab for detail.

Articles