ExternalLibrary provider trait

Platform spec article

ExternalLibrary provider trait

Back to Foreign library import ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-link-time-ffi-v03 Link-time FFI Accepted

   Link-time FFI

   Context

   Dynamic load deferred.

   Decision

   v0.3 maps Extern libraries to link-time providers.

   Consequences

   C ABI profile.

   Verification anchors

   Foreign-library import tests.

   Open full ADR page

2. 0002-closed-provider-registry Closed providers Accepted

   Closed providers

   Context

   Plugin security.

   Decision

   v0.3 closed provider registry; plugins deferred.

   Consequences

   Tier-1 hosts only.

   Verification anchors

   CLI provider list.

   Open full ADR page

Articles

• beskid import lib command CLI workflow for mapping foreign libraries into Project.proj link metadata (v0.3). article Standard Reviewed Wed May 20
• ExternalLibrary provider trait Rust tooling trait for resolving Extern Library strings to linker flags (v0.3). 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

OKarea · 5 SpecSection(s) · 0 H2 heading(s)

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

Related spec docs

• Feature
  Foreign library import

  Parent feature hub

Purpose

Extern contracts carry a logical Library name (for example "libc", "pthread"). Linkers need concrete flags (-lc, -lpthread, framework paths). The ExternalLibrary trait abstracts that mapping so the CLI can support multiple providers over time.

Trait contract (normative Rust shape)

/// Resolves a logical library name from Beskid `Extern` metadata to linker inputs.
pub trait ExternalLibrary: Send + Sync {
    /// Stable provider id (for example `"c-posix"`, `"msvc"` Proposed).
    fn id(&self) -> &'static str;

    /// Target triple or host key this provider supports.
    fn host_key(&self) -> &str;

    /// Map logical name to linker arguments (for example `["-lc"]`).
    fn resolve_link_args(&self, logical: &str) -> Result<Vec<String>, LibraryResolveError>;

    /// Optional: search paths to pass the linker when the logical name is a path.
    fn resolve_search_paths(&self, logical: &str) -> Vec<std::path::PathBuf>;
}

Provider registry (v0.3)

The reference CLI must ship at least one provider:

Provider id	Host	Logical names
c-posix	Linux / macOS tier-1	libc, libpthread, libm, paths to .so / .dylib

msvc / WinAPI providers are Proposed and out of scope for stdlib Standard (platform tier matrix).

Extension

Future providers (Rust rlib, Swift, etc.) must implement ExternalLibrary without changing Beskid source syntax—only manifest/link metadata and CLI selection.

Errors

LibraryResolveError must surface as CLI diagnostics with the logical name, provider id, and host key so authors can fix Project.proj link entries.

Verification anchors

• Trait + closed registry implementation: compiler/crates/beskid_analysis/src/external_library/ (trait_def.rs, providers.rs, registry.rs).
• Closed provider list: compiler/crates/beskid_analysis/src/external_library/registry.rs::default_registry ships c-posix (+ posix alias) only; per ADR D-TOOL-FLI-0002.
• C / POSIX mapping table: compiler/crates/beskid_analysis/src/external_library/providers.rs::C_POSIX_LOGICAL_NAMES (e.g. c -> -lc, m -> -lm, pthread -> -lpthread); canonicalization strips lib prefix and .so/.dylib/.a suffixes.
• Tests: external_library::providers::tests and external_library::registry::tests (in-tree unit tests). End-to-end coverage in compiler/crates/beskid_tests/src/cli/import_lib.rs.