snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Updates

Browse Source
This commit is contained in:
Raven Scott
2026-04-03 19:39:13 -04:00
parent 02904e7523
commit 54ea903bd4
19 changed files with 435 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-guide/02-the-context-object.md
+3 -2
View File
@@ -23,7 +23,8 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
| Field | Role |
| ----- | ---- |
| **`bareOsCtxApiVersion`** | String semver for the documented **`ctx`** contract (e.g. **`1.1.0`**). Bump in [`bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) when you make breaking changes to stable fields. |
| **`bareOsCtxApiVersion`** | String semver for the documented **`ctx`** contract (e.g. **`1.2.0`**). Bump in [`bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) when you make breaking changes to stable fields. |
| **`bareOsRuntimeCaps`** | **Frozen** snapshot from [`bare-os-runtime-caps.js`](../packages/bare-os-booter/lib/bare-os-runtime-caps.js): **`ctxApiVersion`**, resolved simulated **pipeline** limits (from **`env`** / defaults), documented pseudo **`/`** paths (**`pseudoFsPaths`**), and **`features`** flags. Reflects session env at **`executeKernel`** start (including host **`BARE_OS_PIPELINE_*`** when set). |
| **`bareOsBootStartedMs`** | Epoch milliseconds when the booter started building the session (used for synthetic **`/proc/uptime`**). |
| **`bareOsSkipRepl`** | **`true`** when **`BARE_OS_SKIP_REPL=1`** (non-interactive stdin); kernels may shorten banners. |
| **`disk`** | Disk bundle used during boot (includes drives and helpers); advanced use |
@@ -44,7 +45,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
| **`runBinCommand(argv)`** | Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar) |
| **`registerKernelShutdownHook(fn)`** | Register an async or sync function to run when the REPL session ends, **before** initd disposers (`clearInterval`, …). See [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) |
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`), not on `ctx`—extend the image or hooks like `registerKernelShutdownHook` rather than adding boot fields to the context object.
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`, optional **`/etc/bare-os/profile`** / **`rc.profile.*`**, **`/etc/bare-os/onboot`**), not on `ctx`—extend the image or hooks like `registerKernelShutdownHook` rather than adding boot fields to the context object. The booter seeds **`ctx.env`** from the host for **`BARE_OS_PIPELINE_MAX_STAGES`**, **`BARE_OS_PIPELINE_MAX_BYTES`**, **`BARE_OS_PIPELINE_MAX_LINES`**, **`BARE_OS_BOOT_PROFILE`**, and **`BARE_OS_ONBOOT`** when those variables are set (automation / tuning).
After [`createKernelReplSession`](../packages/bare-os-booter/lib/repl-session.js) returns:
developer-guide/03-kernel-boot-init.md
+9 -4
View File
@@ -16,15 +16,20 @@ There is **no `argv`** at the kernel layer—the session’s command line is wha
The repository’s default kernel ([`kernel/init.js`](../kernel/init.js)) is intentionally small:
1. Read **`/etc/os-release`** from the system drive and print it (banner).
2. Print a one-line hint (guest session, builtins, **`help`**, **`ls /bin`**).
3. Loop forever:
1. Print **`/etc/os-release`** and optional **`/etc/motd`** (errors logged, not fatal).
2. Optional **profile** snippet **`/etc/bare-os/rc.profile.<name>`** when **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`** names a safe profile string.
3. Run **`/etc/bare-os/rc`**, then sorted digit-prefixed **`/etc/bare-os/rc.d/*`** (see [Handbook ch.6](../handbook/06-kernel-and-binaries.md)).
4. Print session banner (from **`/etc/bare-os/banner`**, **`/etc/issue`**, or a built-in hint).
5. If **`ctx.bareOsSkipRepl`**: run a single **onboot** line from **`BARE_OS_ONBOOT`** or **`/etc/bare-os/onboot`** (first non-`#` line), then fall through to the loop (where **`readLine`** returns **`null`** immediately).
6. Loop forever:
- `line = await ctx.readLine('')`
- If `line == null`, break (session end / EOF).
- Skip empty lines.
- `status = await ctx.execLine(line)` inside try/catch (`console.error` on failure).
- If `status === 'exit'`, break.
Set **`BARE_OS_BOOT_TRACE=1`** in the environment to log boot phase timings on stderr. Inspect **`ctx.bareOsRuntimeCaps`** for pipeline limits and documented pseudo paths.
So the “OS personality” is mostly the **shell** (`execShellLine` behind `execLine`) plus **`/bin`**.
---
@@ -49,7 +54,7 @@ Use **`execLine`** when you want users to type natural shell commands from your
## Session termination
- The **`exit`** builtin (or **`/bin/exit`**) ultimately calls **`ctx.requestBooterExit(code)`**, which forces **`readLine`** to return `null` on subsequent calls and ends the loop.
- **`BARE_OS_SKIP_REPL=1`** makes **`readLine`** return `null` immediately—useful for non-interactive smoke tests.
- **`BARE_OS_SKIP_REPL=1`** makes **`readLine`** return `null` immediately—useful for non-interactive smoke tests. Pair with **`BARE_OS_ONBOOT='echo ok'`** or **`/etc/bare-os/onboot`** so the stock kernel runs one trusted **`execLine`** before idle exit.
---