68 lines
3.9 KiB
Markdown
68 lines
3.9 KiB
Markdown
# /lib/bare (system image)
|
|
|
|
Self-contained **`ctx.bare` support** on the **system** Hyperdrive: Holepunch **Bare** packages bundled as IIFE scripts the booter can execute without a traditional Node module graph on the drive.
|
|
|
|
**Documentation:** [Developer guide ch.12](../../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [bare-os-bare-libs package README](../../../packages/bare-os-bare-libs/README.md).
|
|
|
|
---
|
|
|
|
## On this page
|
|
|
|
- [What gets staged](#what-gets-staged)
|
|
- [Boot order: drive bundles vs host imports](#boot-order-drive-bundles-vs-host-imports)
|
|
- [Environment toggles](#environment-toggles)
|
|
- [Trust model](#trust-model)
|
|
- [Regenerating bundles](#regenerating-bundles)
|
|
- [When builds fail (stubs)](#when-builds-fail-stubs)
|
|
|
|
---
|
|
|
|
## What gets staged
|
|
|
|
- **`bare-module-manifest.json`** — Copy of the booter manifest (same keys and packages as host resolution). Tells the runtime which logical module names exist.
|
|
- **`manifest.json`** — Drive loader index: **`bundles`** lists IIFE paths that assign into **`globalThis.__bare_os_stdlib__`**; **`bundleStats`** summarizes esbuild success versus stub-only placeholders (per-entry success/failure counts and paths).
|
|
- **`bundles/*.js`** — One file per manifest row. Successful builds are full IIFE bundles; failures are no-op stubs (see the file header comment). Regenerate with **`npm run build -w bare-os-bare-libs`**.
|
|
|
|
At boot the booter runs **drive bundles first**, then (unless **`BARE_OS_BARE_HOST_IMPORTS=0`**) fills any missing keys via host **`import()`** so development iterations can patch a single package without re-seeding the entire drive.
|
|
|
|
---
|
|
|
|
## Boot order: drive bundles vs host imports
|
|
|
|
1. **Seeded bundles** win for keys they actually populate — they are part of the trusted image, same class as **`/bin`**.
|
|
2. **Host imports** run only for keys still missing after bundle evaluation, keeping local checkout workflows fast.
|
|
3. Disabling host imports (**`BARE_OS_BARE_HOST_IMPORTS=0`**) approximates production Pear behavior where only the drive contents exist.
|
|
|
|
---
|
|
|
|
## Environment toggles
|
|
|
|
The authoritative list is in the [environment appendix](../../../docs/reference/environment-and-posix-appendix.md). Names that operators mention most often alongside **`/lib/bare`**:
|
|
|
|
- **`BARE_OS_BARE_HOST_IMPORTS`** — Set to **`0`** / **`false`** to forbid host **`import()`** fallback (drive-only resolution).
|
|
- Related Pear **`ctx.bare`** toggles and HTTP allow lists are documented in **[PEAR-RUN.md](../../../PEAR-RUN.md)** and the booter package reference.
|
|
|
|
---
|
|
|
|
## Trust model
|
|
|
|
**Trusted image only:** executing these bundles is equivalent to running seeded **`/bin`** utilities. Do not copy arbitrary third-party IIFEs into **`kernel/lib/bare/bundles/`** without reviewing them the same way you would review a new setuid binary on a Unix system.
|
|
|
|
---
|
|
|
|
## Regenerating bundles
|
|
|
|
1. Edit **`packages/bare-os-booter/lib/bare-module-manifest.json`** or bundle sources under **`packages/bare-os-bare-libs/`** as needed.
|
|
2. Run **`npm run build -w bare-os-bare-libs`** — output lands in **`kernel/lib/bare/`** (and CI expects **`packages/bare-os-seeder/kernel/`** to match **`kernel/`** byte-for-byte afterward).
|
|
3. Re-run the seeder so peers replicate the updated system drive.
|
|
|
|
---
|
|
|
|
## When builds fail (stubs)
|
|
|
|
If **`bundleStats`** shows failures, open the corresponding **`bundles/*.js`** stub: the header usually names the missing dependency or unsupported pattern. Fix the catalog entry, adjust esbuild options in **`packages/bare-os-bare-libs/build.mjs`**, or mark the module optional in the manifest until the ecosystem catches up. **`npm run smoke:bare-manifest`** guards required imports listed in the manifest smoke list.
|
|
|
|
---
|
|
|
|
_Note:_ This file is copied to **`kernel/lib/bare/README.md`** (and the vendored seeder tree) by **`bare-os-bare-libs`** build. Links are written for the **`kernel/lib/bare/`** path; **`verify-doc-links`** skips this template path because its on-disk location differs.
|