Skip to content

feat(tools): add managed native dependencies#598

Open
Guikingone wants to merge 1 commit into
illegalstudio:mainfrom
Guikingone:feat/native-dependencies
Open

feat(tools): add managed native dependencies#598
Guikingone wants to merge 1 commit into
illegalstudio:mainfrom
Guikingone:feat/native-dependencies

Conversation

@Guikingone

@Guikingone Guikingone commented Jul 22, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR introduces Elephc's first curated native-dependency workflow through
elephc native, with PCRE2 10.47 as the initial package.

Projects can now declare, lock, install, update, remove, inspect, and diagnose
native packages without conflating them with Composer packages, Rust bridge
crates, or the user-provided compiler/SDK toolchain.

The complete frozen design is recorded in
.plans/native-dependencies-v1.md.

User-facing workflow

elephc native add pcre2
elephc native install --locked
elephc native install --locked --offline
elephc native update [pcre2[@10.47]]
elephc native remove pcre2
elephc native list
elephc native doctor
  • elephc.toml holds exact project declarations while preserving unrelated
    TOML comments and formatting.
  • elephc.lock records the exact catalog recipe, source checksum, outputs, and
    supported targets deterministically.
  • Artifacts are built from verified source into a content-addressed cache keyed
    by package, target, ABI, recipe, source, and toolchain fingerprint.
  • --locked refuses missing or stale lock state; --offline guarantees that
    no download is attempted.
  • Ordinary compilation is read-only: it never downloads, builds, repairs, or
    rewrites native dependency state.

Implementation

  • Adds the complete elephc native add/install/update/remove/list/doctor CLI
    family, project discovery, manifest and lock handling, catalog resolution,
    toolchain selection, verified downloads, transactional extraction/builds,
    cache receipts, and diagnostics.
  • Adds a typed, ordered link plan shared by managed archives, Elephc bridge
    archives, user link inputs, frameworks, and platform defaults.
  • Splits the linker into focused archive, bridge, command, and SDK modules while
    preserving the existing bridge table and target-aware behavior.
  • Makes regex support require the managed pcre2 package only on final-link
    paths. There is intentionally no production fallback to a system PCRE2.
  • Introduces a versioned Elephc-owned PCRE2 shim. Generated assembly only sees
    opaque handles and fixed-width capture offsets; no PCRE2-owned C layout
    crosses the runtime ABI boundary.
  • Preserves pay-for-use linking: programs that do not use regex do not resolve
    or link PCRE2.
  • Covers macos-aarch64, linux-aarch64, and linux-x86_64 in the same change.
  • Adds a reproducible date-json-regex example with committed manifest and lock
    state, plus managed-PCRE2 CI smoke coverage.

Compatibility note

Regex-enabled final links now require project-managed PCRE2 state:

elephc native add pcre2

Existing Homebrew, distribution, --link-path, or raw -lpcre2-* discovery is
not used as an implicit fallback. Front-end-only --check, --emit-ir, and
--emit-asm flows remain independent from installed native artifacts.

Documentation

  • Adds the native-dependency guide and complete CLI/environment reference.
  • Updates installation, linking, pipeline, architecture, runtime, regex, SPL,
    strings, and system/I/O documentation.
  • Regenerates the builtin documentation through the official generator; the
    generated content is idempotent.
  • Audits 1,011 Markdown files for frontmatter, H1 policy, and relative links.
  • Validates all 953 generated builtin pages and all 457 catalog entries.

Validation

  • cargo fmt --all -- --check
  • CARGO_INCREMENTAL=0 cargo check --bin elephc --tests --locked
  • git diff --check
  • CI workflow YAML parse
  • Native manager focused suite: 40/40
  • Linker and link-planning focused suite: 26/26
  • CLI focused suite: 22/22
  • Runtime-feature requirement suite: 19/19
  • PCRE2 shim ABI suite: 1/1
  • Rebased eval() bridge requirement regression: 1/1
  • Regex codegen suite on macOS ARM64: 45/45
  • Managed PCRE2 source-build CI smoke configured for macOS ARM64, Linux ARM64,
    and Linux x86_64, including locked offline reinstall and compiled output

Reviewer guide

The highest-value review areas are:

  1. manifest/lock reconciliation and exact comment-preserving edits;
  2. cache identity, receipt verification, and transactional installation;
  3. target toolchain discovery and offline/locked guarantees;
  4. deterministic archive ordering and deduplication in the typed link plan;
  5. the opaque PCRE2 shim boundary and capture-slot semantics.

@github-actions github-actions Bot added area:codegen Touches target-aware assembly or backend lowering. area:platform Touches targets, object formats, linking, or platform support. area:runtime Touches runtime helpers, GC, ownership, or bridge runtimes. scope:multi-area Touches more compiler areas than the automatic area-label cap. size:xl Very large pull request that needs deliberate review planning. type:feature Introduces new user-visible behavior or capabilities. labels Jul 22, 2026
@Guikingone Guikingone changed the title feat: add managed native dependencies feat(tools): add managed native dependencies Jul 22, 2026
@Guikingone
Guikingone force-pushed the feat/native-dependencies branch from a320e3a to a69cd5c Compare July 22, 2026 20:48
@Guikingone Guikingone self-assigned this Jul 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:codegen Touches target-aware assembly or backend lowering. area:platform Touches targets, object formats, linking, or platform support. area:runtime Touches runtime helpers, GC, ownership, or bridge runtimes. scope:multi-area Touches more compiler areas than the automatic area-label cap. size:xl Very large pull request that needs deliberate review planning. type:feature Introduces new user-visible behavior or capabilities.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant