Dev guide

2026-04-03 05:43:13 -04:00
parent 2d26a0b8d1
commit 6259c25d4c
25 changed files with 1207 additions and 25 deletions
@@ -0,0 +1,49 @@
+# Bare OS — developer guide
+
+Welcome. This guide is the **how-to companion** for writing software **on** and **for** Bare OS: scripts that run inside the replicated system image, utilities under `/bin`, the session kernel, and—when you need full JavaScript modules—the **host** Pear packages that implement the booter and seeder.
+
+The [handbook](../handbook/README.md) explains *why* the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The [DOCUMENTATION.md](../DOCUMENTATION.md) inventory lists *where* every file lives. **This guide** focuses on *what you actually type*: entrypoint signatures, the `ctx` object, why `import` does not work in drive-resident scripts, and how the coreutils build turns sources into `/bin` commands.
+
+This project is **experimental research software**. APIs described here follow the current code in `packages/bare-os-booter` and `packages/bare-os-coreutils`; when in doubt, read the cited paths.
+
+---
+
+## Who this is for
+
+- You want to drop a **`hello.js`** on your personal drive and run it from the shell without misunderstanding the execution model.
+- You plan to add or change a **`/bin`** utility and need the no-`import` contract and build steps.
+- You are modifying the **booter** or **seeder** Pear apps and need to separate “host ESM” from “in-image `AsyncFunction`.”
+- You are debugging **`async function run(ctx, argv)`** or **`start(ctx)`** and need a map of `ctx`.
+
+---
+
+## Reading order
+
+| Chapter | Topic |
+| ------- | ----- |
+| [01 — Two runtimes: host vs in-image](01-two-runtimes-host-vs-image.md) | Pear/Node packages vs Hyperdrive JS evaluated with `AsyncFunction`; trust boundaries |
+| [02 — The context object (`ctx`)](02-the-context-object.md) | `vfs`, `drive`, `console`, identity hooks, `execLine`, `runBinCommand`, … |
+| [03 — Kernel: `/boot/init.js`](03-kernel-boot-init.md) | `async function start(ctx)`; readline loop; calling the shell |
+| [04 — User scripts and PATH resolution](04-user-scripts-and-path.md) | `run(ctx, argv)`, shebangs, `*.js` in cwd, `./` paths, `/bin` |
+| [05 — Modules and `import`](05-modules-and-imports.md) | Why ESM does not apply to in-image scripts; bundling and alternatives |
+| [06 — Extending `/bin` (coreutils)](06-extending-bin-coreutils.md) | `commands.mjs`, `build.mjs`, preamble, man pages |
+| [07 — Apps beyond the shell](07-apps-beyond-the-shell.md) | What an “app” means here; initd, cron, git, custom kernels (overview) |
+| [08 — Testing and debugging](08-testing-and-debugging.md) | `npm test`, Brittle, Pear dev, common failure modes |
+| [09 — Security and trust](09-security-and-trust.md) | System vs personal drive; eval boundaries |
+| [10 — Glossary and FAQ](10-glossary-and-faq.md) | Quick definitions; frequent questions |
+
+---
+
+## Related docs
+
+- [Handbook home](../handbook/README.md)
+- [Chapter 4 — Booter runtime](../handbook/04-the-booter-runtime.md)
+- [Chapter 6 — Kernel and binaries](../handbook/06-kernel-and-binaries.md)
+- [Chapter 7 — Operations and development](../handbook/07-operations-and-development.md)
+- [Chapter 9 — POSIX utilities and shell](../handbook/09-posix-utilities-shell-and-vfs.md)
+- [bare-os-coreutils README](../packages/bare-os-coreutils/README.md)
+- [bare-os-booter README](../packages/bare-os-booter/README.md)
+
+---
+
+_License: Apache-2.0 — see [LICENSE](../LICENSE)._