88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# Chapter 2 — Install and repository layout
|
||
|
||
**Prerequisites:** [Chapter 1 — What this is](01-what-this-is.md). **Time to read:** about six minutes.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [What you need on the host](#what-you-need-on-the-host)
|
||
- [Clone and install](#clone-and-install)
|
||
- [Monorepo layout at a glance](#monorepo-layout-at-a-glance)
|
||
- [Where to go next](#where-to-go-next)
|
||
- [Root npm scripts (operators)](#root-npm-scripts-operators)
|
||
- [Disk, caches, and Corestore](#disk-caches-and-corestore)
|
||
|
||
---
|
||
|
||
## What you need on the host
|
||
|
||
- **Node.js 20 or newer** (see root `package.json` `engines`).
|
||
- **Git** to clone the repository.
|
||
- For Pear workflows: **Pear CLI** installed and configured on your machine. The repo’s **`npm run os:seeder`** and **`npm run os:booter`** scripts assume Pear when you use those entry points.
|
||
|
||
Continuous integration also installs **Bare** globally for tests that touch identity crypto; if you run the full **`npm test`** suite locally, match that setup. Details live in [Handbook — Chapter 7](../handbook/07-operations-and-development.md#continuous-integration-github-actions).
|
||
|
||
---
|
||
|
||
## Clone and install
|
||
|
||
From a terminal:
|
||
|
||
```bash
|
||
git clone https://git.ssh.surf/snxraven/bare-operating-system.git
|
||
cd bare-operating-system
|
||
npm ci
|
||
```
|
||
|
||
Run **`npm test`** when you want to confirm the tree is healthy before you change code. **`pretest`** builds coreutils and bare-libs, verifies kernel and seeder parity, and runs several contract and documentation checks. If **`pretest`** fails, the handbook’s operations chapter explains the common causes.
|
||
|
||
---
|
||
|
||
## Monorepo layout at a glance
|
||
|
||
The repository is an **npm workspace** monorepo. These paths matter most when you are running or debugging Bare OS:
|
||
|
||
- **`kernel/`** — Sources that are staged onto the **system** Hyperdrive by the seeder. A copy is kept under **`packages/bare-os-seeder/kernel/`** for Pear packaging; CI enforces that they stay in sync.
|
||
- **`packages/bare-os-protocol`** — Shared protocol constants: swarm topic, MBR layout, Protomux identifiers, kernel feature bits.
|
||
- **`packages/bare-os-seeder`** — Publishes the OS drive and joins the swarm so booters can replicate.
|
||
- **`packages/bare-os-booter`** — Joins the swarm, opens system and personal drives, constructs the guest runtime, and runs **`/boot/init.js`**.
|
||
- **`packages/bare-os-coreutils`** — Sources and build for **`/bin`** utilities and the merged **`man.json`** database.
|
||
- **`packages/bare-os-bare-libs`** — Optional **`/lib/bare`** bundles merged into **`ctx.bare`** when enabled.
|
||
- **`scripts/`** — Automation: Pear `node_modules` helpers, parity verifiers, catalog generation, release checklist.
|
||
|
||
Each workspace package has its own **README** with package-specific commands. For a file-by-file inventory, use [docs/reference — Repository layout](../docs/reference/repo-layout-and-root.md).
|
||
|
||
Default **Corestore** directories for seeder and booter usually live under **`~/.bare-os/`** unless you override them with environment variables documented in the [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||
|
||
---
|
||
|
||
## Root npm scripts (operators)
|
||
|
||
From the **repository root**, the scripts you touch most often are:
|
||
|
||
- **`npm run os:seeder`** — Builds **coreutils** and **bare-libs**, ensures Pear sees hoisted **`node_modules`**, then **`pear run --dev .`** inside **`packages/bare-os-seeder`**. Use when you want Pear-accurate seeding during app development.
|
||
- **`npm run os:booter`** — Same Pear **`node_modules`** preparation for the booter package, then **`pear run --dev .`** in **`packages/bare-os-booter`**.
|
||
- **`npm run pretest`** — Required gate before **`npm test`**: builds artifacts, runs parity and documentation verifiers (see [Chapter 7](07-troubleshooting-and-operations.md)).
|
||
- **`npm test`** — Runs **`pretest`**, then **`npm run test --workspaces --if-present`** so every workspace package can contribute its own suite.
|
||
|
||
Maintainers also use **`npm run gen:bare-catalog`**, **`npm run sync:bare-manifest`**, and **`npm run release-checklist`**; see [Handbook — Chapter 7](../handbook/07-operations-and-development.md) for workflow context.
|
||
|
||
---
|
||
|
||
## Disk, caches, and Corestore
|
||
|
||
Seeder and booter persist Hypercore storage on disk. Default layouts are described in package READMEs and the [environment appendix](../docs/reference/environment-and-posix-appendix.md) (**`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, **`BARE_OS_HOST_DATA`**). If you switch between **Node** and **Pear** runs, you usually keep the **same** store paths so the personal drive and replication state stay consistent. Deleting **`~/.bare-os/`** is a blunt “factory reset” for local development: you lose replicated drives unless you have keys or snapshots elsewhere.
|
||
|
||
---
|
||
|
||
## Where to go next
|
||
|
||
- **Run the system:** [Chapter 3 — Running seeder and booter](03-running-seeder-and-booter.md).
|
||
- **Deeper operations and CI:** [Handbook — Chapter 7](../handbook/07-operations-and-development.md).
|
||
- **Exact env var names:** [Environment variables and POSIX appendix](../docs/reference/environment-and-posix-appendix.md).
|
||
|
||
---
|
||
|
||
_Previous: [Chapter 1](01-what-this-is.md)_ · _Next: [Chapter 3 — Running seeder and booter](03-running-seeder-and-booter.md)_
|