Further Updates to MD
This commit is contained in:
Raven Scott
@@ -67,7 +67,7 @@ cd packages/bare-os-booter && node index.js
|
||||
|
||||
Default store paths are under **`~/.bare-os/corestore/`** for seeder and booter unless you set **`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, or the shared base **`BARE_OS_HOST_DATA`**. See each package’s **`lib/paths.js`** for how overrides compose.
|
||||
|
||||
On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before staging: from the repo root run `**npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs**` (or `**npm run pretest**`, which also verifies kernel/seeder parity). Root `**npm run os:seeder**` runs those builds automatically before `**pear run --dev`**.
|
||||
On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before staging: from the repo root run **`npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs`** (or **`npm run pretest`**, which also verifies kernel/seeder parity). Root **`npm run os:seeder`** runs those builds automatically before **`pear run --dev`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@ On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before
|
||||
<details>
|
||||
<summary><strong>When to expand this block</strong></summary>
|
||||
|
||||
**Pear** exercises **`pear run --dev**`, hoisted **`node_modules`**, and **`BARE_OS_PEAR_*`** behavior. Install the [Pear CLI](https://docs.pears.com/) first; confirm with `**pear --version`**.
|
||||
**Pear** exercises **`pear run --dev`**, hoisted **`node_modules`**, and **`BARE_OS_PEAR_*`** behavior. Install the [Pear CLI](https://docs.pears.com/) first; confirm with **`pear --version`**.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -92,7 +92,7 @@ In another terminal:
|
||||
npm run os:booter
|
||||
```
|
||||
|
||||
These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way `**npm ci**` does at the repo root. Without that step, `**pear run**` from inside a package directory can miss modules that live at the root **`node_modules`**.
|
||||
These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way **`npm ci`** does at the repo root. Without that step, **`pear run`** from inside a package directory can miss modules that live at the root **`node_modules`**.
|
||||
|
||||
> **Important**
|
||||
> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
|
||||
@@ -101,9 +101,9 @@ These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees
|
||||
|
||||
## Pear channels and released keys
|
||||
|
||||
When you change **`packages/bare-os-booter/lib/bare-module-manifest.json`** or run `**npm run sync:bare-manifest**`, **`bare-module-manifest.data.mjs`** is regenerated for Pear (sync script and `**npm run build -w bare-os-bare-libs**` **`prebuild`**). From the repo root, run `**npm run verify:manifest-data**` before `**pear stage**` so the JSON and **`.data.mjs`** stay aligned.
|
||||
When you change **`packages/bare-os-booter/lib/bare-module-manifest.json`** or run **`npm run sync:bare-manifest`**, **`bare-module-manifest.data.mjs`** is regenerated for Pear (sync script and **`npm run build -w bare-os-bare-libs`** **`prebuild`**). From the repo root, run **`npm run verify:manifest-data`** before **`pear stage`** so the JSON and **`.data.mjs`** stay aligned.
|
||||
|
||||
After **`pear stage**` and `**pear release**`, you receive `**pear://…**` links that point at released artifacts. Consumers normally run those keys rather than a raw git checkout, unless they use dev mode (`**pear run --dev .`**).
|
||||
After **`pear stage`** and **`pear release`**, you receive **`pear://…`** links that point at released artifacts. Consumers normally run those keys rather than a raw git checkout, unless they use dev mode (**`pear run --dev .`**).
|
||||
|
||||
Concrete channel names, keys, versioned links, and host-side environment variables (**`BARE_OS_PEAR_*`**, HTTP allow lists, TLS pin forwarding, **`ctx.bare`** toggles) are documented in **[PEAR-RUN.md](../docs/PEAR-RUN.md)**. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.
|
||||
|
||||
@@ -112,9 +112,9 @@ Concrete channel names, keys, versioned links, and host-side environment variabl
|
||||
## Common mistakes
|
||||
|
||||
- **Booter times out** — No peer is serving the **`bare-os-v1`** topic, or the network cannot reach bootstrap nodes. Confirm the seeder is running and check **`HYPERSWARM_BOOTSTRAP`** if you use custom bootstraps ([Handbook — Chapter 7, troubleshooting](../handbook/07-operations-and-development.md#troubleshooting)).
|
||||
- **Missing `/bin` utilities under Pear** — Run **`npm run build -w bare-os-coreutils**` (and seed again) so the image contains a fresh **`/bin`** build.
|
||||
- **Missing `/bin` utilities under Pear** — Run **`npm run build -w bare-os-coreutils`** (and seed again) so the image contains a fresh **`/bin`** build.
|
||||
- **Wrong working directory for the seeder** — Start the seeder from **`packages/bare-os-seeder`** (or use the npm script from root) so kernel paths resolve.
|
||||
- **Expecting full POSIX job control** — The shell supports **`jobs`**, **`fg`**, **`bg`**, **`wait`**, background `**&**`, and logical stop/resume, but not monitor mode, real host process groups, or kernel **`SIGTSTP`** (see [Handbook ch.9 — Shell](../handbook/09-posix-utilities-shell-and-vfs.md)).
|
||||
- **Expecting full POSIX job control** — The shell supports **`jobs`**, **`fg`**, **`bg`**, **`wait`**, background **`&`**, and logical stop/resume, but not monitor mode, real host process groups, or kernel **`SIGTSTP`** (see [Handbook ch.9 — Shell](../handbook/09-posix-utilities-shell-and-vfs.md)).
|
||||
|
||||
---
|
||||
|
||||
@@ -128,7 +128,7 @@ Canonical **booter boot steps** (**`vfs`** → **`ctx`** → **`repl`** → **`i
|
||||
|
||||
## Choosing Node versus Pear
|
||||
|
||||
**Node** (`node index.js` in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. **Pear** tracks production embedding more closely: module layout, **`pear run --dev**`, and host **`BARE_OS_PEAR_*`** toggles matter. If a bug appears **only** under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. [PEAR-RUN.md](../docs/PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||||
**Node** (`node index.js` in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. **Pear** tracks production embedding more closely: module layout, **`pear run --dev`**, and host **`BARE_OS_PEAR_*`** toggles matter. If a bug appears **only** under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. [PEAR-RUN.md](../docs/PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user