Skip to content

Latest commit

 

History

History

ferric

README.md

ferric

A wrapper around Cargo making it easier to produce prebuilt binaries targeting iOS and Android matching the prebuilt binary specification as well as napi.rs to generate bindings from annotated Rust code.

Feature check

Before building, ferric build asks Cargo for the crate's resolved features for each target and fails if napi-sys has either of these enabled:

  • dyn-symbols, which makes napi-rs look up Node-API functions in the host process at runtime instead of linking them against weak-node-api. That doesn't work in React Native (#331).
  • A napiN feature above Node-API version 10, the highest version the host supports.

napi enables dyn-symbols through its default features, so disable those and pick the Node-API version explicitly:

[dependencies.napi]
version = "3"
default-features = false
features = ["napi10"]

From napi4 onward, napi-rs's runtime uses threadsafe functions. If your addon doesn't need them (or anything else above Node-API 3), napi3 gives a slightly smaller binary (about 5 KB for a minimal addon).

Pass --skip-feature-check to bypass the check.

ferric init [path]

Scaffold a package building a Rust Node-API module, or bring an existing package up to what ferric build expects of it:

npx ferric init packages/my-addon

The command creates whatever is missing — package.json, Cargo.toml, build.rs, src/lib.rs and .gitignore — and adds the package to the pnpm-workspace.yaml or "workspaces" of the mono-repo it is initialized into.

Running it against a package which already exists updates rather than overwrites:

  • package.json gains the scripts, dependencies and prebuilt artifacts it lacks, and outdated dependencies are bumped.
  • An existing Cargo.toml keeps its comments and formatting. Outdated napi, napi-derive and napi-build versions are bumped in place, and the command points out anything else ferric build needs.
  • A main, types, src/lib.rs or build.rs that differs is skipped, printing a diff to merge by hand. Pass --force to overwrite them instead.

A newly created Cargo.toml can be configured with:

  • --node-api-version <version>: the napiN feature to enable, defaulting to 10.
  • --napi-crate-version, --napi-derive-crate-version and --napi-build-crate-version: the crate versions, defaulting to those tested with ferric-example. These also set what an existing Cargo.toml is bumped to.
  • --release-profile <speed|size|none>: speed (the default) enables lto and a single codegen unit, size also optimizes for size and strips symbols, and none leaves [profile.release] out.

The name of the crate defaults to the package name without its npm scope (@my-org/my-addon becomes my-addon) and can be set with --name. Cargo normalizes it to my_addon for the artifacts it produces, which is the basename ferric build writes its outputs and entrypoint with.

Every file it updates is printed as a diff, and --dry-run prints the whole plan without writing anything:

npx ferric init packages/my-addon --dry-run

The ferric-example package is generated by this command: run pnpm run init-ferric-example from the root of the repository after changing the templates, which CI asserts leaves no diff.