Skip to content

fix: support older glibc and musl NAPI builds#460

Merged
ubugeeei merged 1 commit into
mainfrom
fix/napi-linux-glibc-musl
Jul 5, 2026
Merged

fix: support older glibc and musl NAPI builds#460
ubugeeei merged 1 commit into
mainfrom
fix/napi-linux-glibc-musl

Conversation

@ubugeeei

@ubugeeei ubugeeei commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Build Linux GNU NAPI artifacts with cargo-zigbuild using a GLIBC 2.17 target suffix.
  • Add linux x64/arm64 musl NAPI targets and publish them as optional binding packages.
  • Teach the Node loader to select gnu or musl bindings at runtime and extend package dry-run coverage.
  • Add release/nightly readelf checks so GNU artifacts fail if they require newer GLIBC symbols and musl artifacts fail if they reference GLIBC symbols.

Root Cause

The published Linux NAPI artifacts were built as GNU-only binaries on current Linux runners, so consumers on older glibc distributions could hit runtime loader failures from newer GLIBC symbol requirements. Alpine/musl environments also had no matching binding package.

Validation

  • node --check crates/ox_content_napi/index.js
  • node --check scripts/package-dry-run.mjs
  • cargo test -p ox_content_napi javascript_wrapper -- --nocapture
  • node scripts/package-dry-run.mjs
  • Generated NAPI sub-package directories in a temp dir and confirmed linux-*-musl packages include libc: musl.
  • Parsed .github/workflows/publish.yml and .github/workflows/nightly.yml as YAML.
  • Ran actionlint; it only reported the existing custom blacksmith-32vcpu-ubuntu-2404 runner label as unknown.

View with Codesmith Autofix with Codesmith
Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.

Summary by CodeRabbit

  • New Features

    • Added support for additional Linux musl prebuilt binaries, including x64 and arm64 variants.
    • Linux package loading now selects the correct binary for musl or glibc systems automatically.
  • Bug Fixes

    • Improved release and publish workflows to validate Linux builds more reliably.
    • Added checks to prevent incompatible Linux binaries from being published.
  • Tests

    • Updated dry-run validation to include the new Linux musl targets and packages.

@coderabbitai

coderabbitai Bot commented Jul 3, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 43a696cc-f283-4971-b7a6-2f77195e01bd

📥 Commits

Reviewing files that changed from the base of the PR and between d31b0c8 and df12b6c.

⛔ Files ignored due to path filters (2)
  • crates/ox_content_napi/src/tests/snapshots/ox_content_napi__tests__runtime_features__javascript_wrapper_index_js.snap is excluded by !**/*.snap
  • crates/ox_content_napi/src/tests/snapshots/ox_content_napi__tests__runtime_features__javascript_wrapper_native_load_errors.snap is excluded by !**/*.snap
📒 Files selected for processing (5)
  • .github/workflows/nightly.yml
  • .github/workflows/publish.yml
  • crates/ox_content_napi/index.js
  • crates/ox_content_napi/package.json
  • scripts/package-dry-run.mjs

📝 Walkthrough

Walkthrough

Adds musl-based Linux (x86_64, aarch64) NAPI build targets across nightly and publish GitHub Actions workflows, unifying Linux cross-compilation via zig/cargo-zigbuild with GLIBC version verification. Updates the native module's package.json targets, runtime musl detection/binary selection logic in index.js, and dry-run validation script accordingly.

Changes

CI musl build and publish support

Layer / File(s) Summary
Nightly workflow musl build flow
.github/workflows/nightly.yml
Adds LINUX_GLIBC_VERSION env var, extends matrix with musl/ARM64 targets, replaces ARM64-only zig steps with a generalized unknown-linux zig/cargo-zigbuild build plus GLIBC verification, and updates artifact target mapping and pkg-pr-new publish args for musl.
Publish workflow musl build flow
.github/workflows/publish.yml
Sets global LINUX_GLIBC_VERSION, adds musl platform identifiers to matrix, replaces ARM64-specific cross-compile with unified unknown-linux zig/cargo-zigbuild build and GLIBC verification, and extends publish-napi target_map with musl mappings.

Runtime musl detection and package resolution

Layer / File(s) Summary
musl detection and binary/package selection
crates/ox_content_napi/index.js
Adds execSync/readFileSync imports, implements isMusl() detection via ldd checks, computes Linux platform key as musl or gnu, and extends local .node and npm sub-package maps with musl entries.
Package manifest and dry-run validation for musl targets
crates/ox_content_napi/package.json, scripts/package-dry-run.mjs
Adds musl target triples to napi.targets and expands dry-run required target/binding package lists to include the new musl entries.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Workflow as build-napi (nightly/publish)
  participant Zig as zig / cargo-zigbuild
  participant Verify as Native dependency check
  participant Artifacts as binding-packages / publish

  Workflow->>Zig: build target (gnu or musl)
  Zig->>Workflow: produced .so shared library
  Workflow->>Verify: extract GLIBC version or symbols
  Verify->>Verify: fail if GLIBC exceeds LINUX_GLIBC_VERSION (gnu) or GLIBC symbols found (musl)
  Verify->>Artifacts: copy .node artifact into target_map path
  Artifacts->>Artifacts: publish binding-packages including *-musl directories
Loading
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/napi-linux-glibc-musl

Comment @coderabbitai help to get the list of available commands.

@pkg-pr-new

pkg-pr-new Bot commented Jul 3, 2026

Copy link
Copy Markdown

Open in StackBlitz

@ox-content/binding-darwin-arm64

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-darwin-arm64@460

@ox-content/binding-darwin-x64

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-darwin-x64@460

@ox-content/binding-linux-arm64-gnu

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-linux-arm64-gnu@460

@ox-content/binding-linux-arm64-musl

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-linux-arm64-musl@460

@ox-content/binding-linux-x64-gnu

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-linux-x64-gnu@460

@ox-content/binding-linux-x64-musl

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-linux-x64-musl@460

@ox-content/binding-win32-x64-msvc

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/binding-win32-x64-msvc@460

@ox-content/napi

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/napi@460

@ox-content/islands

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/islands@460

@ox-content/unplugin

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/unplugin@460

@ox-content/vite-plugin

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/vite-plugin@460

@ox-content/vite-plugin-react

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/vite-plugin-react@460

@ox-content/vite-plugin-svelte

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/vite-plugin-svelte@460

@ox-content/vite-plugin-vue

npm i https://pkg.pr.new/ubugeeei-prod/ox-content/@ox-content/vite-plugin-vue@460

commit: df12b6c

@ubugeeei ubugeeei marked this pull request as ready for review July 5, 2026 03:54
@ubugeeei ubugeeei merged commit 1668239 into main Jul 5, 2026
34 checks passed
@ubugeeei ubugeeei deleted the fix/napi-linux-glibc-musl branch July 5, 2026 03:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant