Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,40 @@ nothing else: it does not look in the source tree, and a missing addon is an
error that says how to build it. `npm --prefix api run gen:types` regenerates
`node/src/index.d.ts` after a change to the call table.

### Package and install

Each artifact is for the OS, CPU and C library it was built on (a Linux build
needs at least the glibc of its build host). None is published; install the
files you build, here into `$OUT`:

```bash
npm --prefix api run build:native # node/layerfs.node
(cd api/node && npm pack --pack-destination "$OUT") # layerfs-2.0.0.tgz
npm install "$OUT/layerfs-2.0.0.tgz" # in an empty project

(cd api/python && maturin build --release --locked -o "$OUT") # layerfs-2.0.0-*.whl
pip install "$OUT"/layerfs-2.0.0-*.whl # in a virtualenv

cargo +1.85.1 build --release --locked -p layerfs-cli # target/release/layerfs, one file
```

`npm pack` fails when `node/layerfs.node` is missing, so a tarball never lacks
its addon. The default addon, wheel and command have no PostgreSQL and no TLS:
a call that needs them is refused `Unsupported` ("this LayerFS build has no
PostgreSQL engine"). Both are opt-in at build time and need the OpenSSL
development files (`libssl-dev`) on the build host:

```bash
npm --prefix api run build:native -- --features postgresql # or tls, or postgresql,tls
(cd api/python && maturin build --release --locked --features postgresql -o "$OUT")
cargo +1.85.1 build --release --locked -p layerfs-cli --features postgresql
```

For such a wheel `maturin` copies `libssl`, `libcrypto` and `libzstd` into it
and needs `patchelf`; the addon and the command load them from the system.
The runs behind these steps are in
[artifact-qualification-2.0.0.md](../docs/general/artifact-qualification-2.0.0.md).

Disposable/WAL/synchronous=OFF only. Durable execution is NOT_RUN — disabled by
owner until explicit reauthorization. One attempted operation; no retry or replay.

Expand Down
1 change: 1 addition & 0 deletions api/node/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
"node": ">=22"
},
"scripts": {
"prepack": "node -e \"require('node:fs').existsSync('layerfs.node') || (console.error('layerfs.node is missing: run npm --prefix api run build:native before packing'), process.exit(1))\"",
"test": "node --test test/*.mjs"
},
"license": "MIT",
Expand Down
7 changes: 7 additions & 0 deletions api/python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,13 @@ python api/python/tools/gen_stubs.py # --check fails on drift
cd api/python && maturin build --locked
```

That is a debug build. The wheel to install is `maturin build --release
--locked`; add `--features postgresql` (or `tls`) for PostgreSQL Stores,
which needs the OpenSSL development files and `patchelf`. The wheel's
platform tag follows the build host's glibc (`manylinux_2_39` on Ubuntu 26.04).
The steps to install it into an empty virtualenv are in
[api/README.md](../README.md#package-and-install).

For the tests, either install the module in a virtualenv (`maturin develop
--locked --offline` puts `_native.abi3.so` beside the package) or build it
with Cargo and put it there:
Expand Down
7 changes: 6 additions & 1 deletion api/scripts/build-native.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,12 @@ import { fileURLToPath } from "node:url";
const root = fileURLToPath(new URL("../../", import.meta.url));
const suffix = { darwin: "dylib", linux: "so" }[process.platform];
if (!suffix) throw new Error(`native addon builds require macOS or Linux, got ${process.platform}`);
const usage = "usage: build-native.mjs [--debug] [--features postgresql,tls]";
const flags = process.argv.slice(2);
if (flags.some((flag) => flag !== "--debug")) throw new Error("usage: build-native.mjs [--debug]");
const featuresAt = flags.indexOf("--features");
const features = featuresAt < 0 ? [] : (flags[featuresAt + 1] ?? "").split(",");
if (featuresAt >= 0) flags.splice(featuresAt, 2);
if (flags.some((flag) => flag !== "--debug") || features.some((name) => !["postgresql", "tls"].includes(name))) throw new Error(usage);
const profile = flags.includes("--debug") ? "debug" : "release";
const configured = process.env.CARGO_TARGET_DIR;
const target = configured ? resolve(root, configured) : join(root, "target");
Expand All @@ -19,6 +23,7 @@ if (process.env.CARGO_BUILD_TARGET) throw new Error("build on the actual macOS/L
const result = spawnSync("cargo", [
"+1.85.1", "build", "--manifest-path", "Cargo.toml", "--offline", "--locked",
...(profile === "release" ? ["--release"] : []), "-p", "layerfs-node",
...(features.length ? ["--features", features.join(",")] : []),
], { cwd: root, stdio: "inherit", env: { ...process.env, CARGO_TARGET_DIR: target } });
if (result.error) throw result.error;
if (result.status !== 0) process.exit(result.status ?? 1);
Expand Down
4 changes: 3 additions & 1 deletion docs/architecture/api/front-ends/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,9 @@ Give each a wall limit of at most 120 s.
`{"ok":true,"findings":[]}` and does not create it; a Store record that
is not JSON gives `1 error(s), 0 warning(s)` and its fix with `--text`;
`doctor --all` is exit 2. Command:
`cargo +1.85.1 test --locked -p layerfs-cli --test doctor`. Needs Unix.
`cargo +1.85.1 test --locked -p layerfs-cli --test doctor`, built first
with `--no-run` (the cold build takes over a minute and would hit the
100 s limit). Needs Unix.
- **Node tests**: `calls.mjs`, `shell.mjs`, `events.mjs`, `close.mjs`,
`doctor.mjs`; see [Node](node.md#native-addon-build). Command:
`perl -e 'alarm 100; exec @ARGV' npm --prefix api/node test`
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/api/front-ends/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ api/crates/layerfs-node (cdylib, napi 2.16, napi4)

| Step | What happens | Source |
| --- | --- | --- |
| Build | `npm --prefix api run build:native` runs `cargo +1.85.1 build --manifest-path Cargo.toml --offline --locked [--release] -p layerfs-node`; `-- --debug` builds a dev profile | [`build-native.mjs`](../../../../api/scripts/build-native.mjs) |
| Build | `npm --prefix api run build:native` runs `cargo +1.85.1 build --manifest-path Cargo.toml --offline --locked [--release] -p layerfs-node`; `-- --debug` builds a dev profile; `-- --features postgresql,tls` (either name or both, nothing else) passes the opt-in features on, default none | [`build-native.mjs`](../../../../api/scripts/build-native.mjs) |
| Host | `darwin` (`.dylib`) or `linux` (`.so`); any other platform, a set `CARGO_BUILD_TARGET`, or a `CARGO_TARGET_DIR` outside the worktree is refused | `build-native.mjs` |
| Output | copied to `api/node/layerfs.node` (git-ignored; the package's own addon), or to `LAYERFS_NATIVE_OUTPUT`, through a staged file and a rename | `build-native.mjs` |
| Loading | the file `LAYERFS_NATIVE` names, else `layerfs.node` beside the package's `src`; nothing else is looked at. A missing file, or one that does not load, throws one error naming the path, `platform/arch`, the Node version and how to build | [`native.js`](../../../../api/node/src/native.js) |
Expand Down
Loading