Rust ABI profile — Shims and compatibility strategy

Platform spec article

Rust ABI profile — Shims and compatibility strategy

Back to Rust ABI profile ◎ Open feature in platform map

Spec standingProposed

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

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

   Runtime embedding exports defer to this hub.

   Context

   Rust runtime exports were documented beside user C extern rules.

   Decision

   This feature hub must own normative MUST/SHOULD for Rust-hosted runtime interop distinct from user C ABI profile libraries.

   Consequences

   Builtin table and ABI version policy stay here; user Extern stays on C profile.

   Verification anchors

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

   Open full ADR page

2. 0002-runtime-c-exports-rust-internal Runtime exposes C-compatible entrypoints Accepted

   Rust-specific choices stay inside the runtime crate boundary.

   Context

   JIT/AOT loaders need stable C symbol names while implementation remains Rust.

   Decision

   The Beskid runtime must expose stable C-compatible entrypoints to loaders. Rust-specific implementation choices must remain inside the runtime crate boundary.

   Consequences

   beskid_abi symbols and unwind bridges document the outward face only.

   Verification anchors

   compiler/crates/beskid_abi; compiler/crates/beskid_runtime.

   Open full ADR page

3. 0003-user-extern-not-rust-crates User Extern not arbitrary Rust crates Accepted

   User foreign code uses C ABI profile until a future spec promotes Rust-native interop.

   Context

   Linking arbitrary rlib targets as user Extern would imply unstable Rust ABI across toolchains.

   Decision

   This profile is not a promise that arbitrary Rust crates can be user Extern targets without shims. User-authored foreign code on the supported path must remain C ABI profile until a future specification promotes additional Rust-native interop.

   Consequences

   Embedding docs steer authors to C contracts + shims for Rust libraries.

   Verification anchors

   /platform-spec/language-meta/interop/rust-abi-profile/ and FFI and extern.

   Open full ADR page

Articles

• Rust ABI profile — Boundary and stability What is stable at the Rust runtime ↔ generated code boundary versus implementation-private Rust types. article Standard Reviewed Fri May 01
• Rust ABI profile — Shims and compatibility strategy How future Rust-native interop would layer on top of C ABI exports without breaking the stable runtime contract. article Proposed 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 · 2 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
  Rust ABI profile

  Parent feature hub

• Feature
  C ABI profile

  Current user extern path

Status: Proposed — forward-looking strategy; not required for current toolchain conformance.

Shim pattern

Any future Rust-native user interop would introduce thin shim symbols with stable C names that delegate to Rust extern "Rust" or crate-specific metadata. Interop.Contracts normalization would run before shim emission so that profiles remain composable.

Compatibility bands

The platform can evolve:

1. Band A — only C-profile user Extern and stable runtime exports (today’s supported story).
2. Band B — optional Rust-profile extensions gated by language version, manifest flags, or engine features, each documented with its own conformance tests.

Upgrades must preserve Band A artifacts unless accompanied by a major ABI version policy change documented under conformance and versioning.