bare-operating-system/packages/bare-os-seeder/kernel

kernel — system image sources

Files in this directory are read from disk by the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear) and written into the system Hyperdrive with no temporary directory on the host.

This README.md file only documents the tree layout in the repository; the seeder does not install it as /README.md on the image (so the guest root directory stays free of repo docs).

Documentation: Concepts — Boot · User manual · Handbook · Kernel image reference · Developer guide.

Staging map (seeder)

• init.js — /boot/init.js
• bin/<name> — /bin/<name>
• etc/... — /etc/...
• share/man/... — /share/man/...
• lib/bare/... — /lib/bare/... (optional ctx.bare bundles; see bare-os-bare-libs)
• Any other file — /<relative path>
• **README.md (this file)** — (skipped — not copied to /README.md)

Contents

• init.js — Kernel entry: must define async function start(ctx). Boot order: /etc/os-release → /etc/motd → optional /etc/bare-os/rc.profile.<profile> (profile from BARE_OS_BOOT_PROFILE or first line of /etc/bare-os/profile; the booter mirrors the resolved name in ctx.env.BARE_OS_BOOT_PROFILE_RESOLVED and /run/bare-os/boot_profile) → /etc/bare-os/rc → **/etc/bare-os/rc.d/*** (sorted; digit-prefixed names only; skip dotfiles, *~, README*, *.md; optional BARE_OS_RC_D_SKIP comma list and prefix* patterns) → optional /etc/bare-os/rc.local → /etc/bare-os/kernel.d/* (same rules as rc.d) → banner → when BARE_OS_SKIP_REPL, optional onboot lines from BARE_OS_ONBOOT or /etc/bare-os/onboot → **readLine / execLine** loop. Boot execLine errors in trusted snippets are logged; with BARE_OS_BOOT_STRICT=1 or true, the first throw calls requestBooterExit(1) and stops later boot phases. Custom kernels may call ctx.registerKernelShutdownHook(fn) before initd disposers; use ctx.bareOsRuntimeCaps for limits, pseudo paths, and features ([developer-guide/02-the-context-object.md](../developer-guide/02-the-context-object.md)).
• bin/ — Tier-1 utilities built by bare-os-coreutils plus sshd / bare-sshd from bare-os-openssh (179 commands in COREUTILS_COMMANDS; sshd is listed for man/help but its concatenated script is emitted by the openssh package build, not coreutils src/). Each file is runtime.js + optional preamble (lib/md5.js for md5sum, lib/sha224.js for sha224sum, lib/*-engine.js for sed/awk, jq-engine.js, lib/man-render.js, lib/edit-*.js for edit/nano, lscolors for ls/dircolors, …) + **async function run(ctx, argv)** (no ESM import in src/). /bin/nano duplicates /bin/edit for familiarity; the shell’s default **nano → edit** alias uses the edit command name after expansion. dir/vdir invoke ls via ctx.runBinCommand.
• lib/bare/ — Optional IIFE bundles + manifest.json for ctx.bare drive merge, built by bare-os-bare-libs. Same trust model as bin/ (trusted seeded image).
• share/man/man.json — Merged manual database for /bin/man (built by bare-os-coreutils; see handbook ch.10).
• etc/os-release — Static OS metadata (NAME, VERSION, …).
• etc/motd — Optional message printed after os-release (distributors can customize).
• etc/bare-os/banner or /etc/issue — If present on the system drive, the default kernel prints one of these instead of the built-in session hint (unless BARE_OS_SKIP_REPL shortens the banner). Set BARE_OS_BOOT_TRACE=1 or true for [boot] phase: Nms lines on stderr, json for {"phase":"…","ms":n} per phase, or ndjson for machine-readable lines with sessionId. Recovery: BARE_OS_BOOT_MINIMAL, granular BARE_OS_BOOT_SKIP, optional BARE_OS_KERNEL_SELFTEST (TAP via BARE_OS_SELFTEST_FORMAT=tap; includes /proc/bare_os_resources / /proc/bare_os_features checks), readiness via ctx.bareOsPublishBootReady → /run/bare-os/ready and /run/bare-os/boot.json (phases from the stock kernel plus booterPhases from the booter — see developer guide ch.2).
• etc/bare-os/rc — Optional boot snippet: one execLine per non-comment line (trusted).
• etc/bare-os/rc.d/ — Optional extra snippets (basename must start with a digit), same line rules, run after rc in filename order. Human-oriented notes live in .README (a dotfile so legacy init.js never executes it).

Editing workflow

Do not edit kernel/init.js by hand. It is generated from kernel/lib/boot/*.js (sorted), kernel/lib/init/fragments/*.js (sorted), and kernel/lib/init/init-main.js via npm run bundle:kernel (scripts/bundle-kernel-init.mjs). CI and npm run verify:init-bundle fail when the file drifts. Edit the fragments under lib/boot/, lib/init/fragments/, and lib/init/ only, then bundle and rsync to packages/bare-os-seeder/kernel/ for Pear parity. See lib/init/STRUCTURE.md.

1. Change sources under kernel/ or packages/bare-os-coreutils/src/.
2. Run npm run build -w bare-os-coreutils to refresh kernel/bin/*.
3. Run npm run build -w bare-os-bare-libs when packages/bare-os-booter/lib/bare-module-manifest.json or bundle entries change.
4. Run seeder again to re-stage the drive (or use a fresh Corestore for a clean image).

Host boot perf: when BARE_OS_BOOT_PERF_DETAIL=1, the stock booter logs bare_stdlib_merge_ns after maybeMergeBareFromDrive (monotonic hrtime delta in nanoseconds) alongside guest boot-perf.json stages.

Pear bundles use the vendored tree under packages/bare-os-seeder/kernel/; keep it in sync by running the same builds before pear stage. Use npm run maintainer:kernel-image from the repo root for coreutils + bare-libs + init bundle + extensions index + parity verify (then rsync -a --delete kernel/ packages/bare-os-seeder/kernel/ if the verifier reports drift). npm test runs scripts/verify-kernel-seeder-parity.mjs, scripts/verify-ctx-api-feature-bits.mjs, and scripts/validate-example-schemas.mjs (after bare-os-coreutils and bare-os-bare-libs builds) so the two trees match byte-for-byte, ctx semver / feature words stay wired, example JSON matches docs/schemas/, and every kernel/bin/* file contains the BARE_OS_BIN_API pragma (coreutils runtime.js and hand-written stubs such as systemctl / journalctl).

Optional system image examples: etc/bare-os/boot.allow.example (copy to boot.allow when using host BARE_OS_BOOT_ALLOWLIST=1), etc/bare-os/boot.policy.example.json (install as boot.policy.json when using BARE_OS_BOOT_POLICY=1; v2 fields maxExecLineDepth, denyEnvKeys, requireProcNodes; v3 requireKernelCapabilitiesExtendedSeedingPlatform, requireKernelCapabilitiesRlimitsDelegatesShell, allowedPearIpcChannels, denyVfsPrefixes, maxInitdRestartsPerUnit; v4 requireKernelCapabilitiesOfflineNetExtensions, denyExecLineBuiltins, allowedCtxMethods; v9 requireKernelCapabilitiesBareModuleCryptoStaging, requirePearRuntimeRange, denyBareModuleSpecifierPatterns, requireBareCryptoMin, denyKernelSyscalls, requirePearIpcMin, extensionSignerPinsV2, offlineLkgManifestMaxAgeSec, bootPhasesRequireProcIndexMinSchema; v10 requireKernelCapabilitiesPearInspectLoggerTls, requireBareBootMin, bootPhasesRequireLifecycleMinSchema, extensionSignerPinsV3, …; JSON Schema: [docs/schemas/boot.policy.schema.json](../docs/schemas/boot.policy.schema.json)), etc/bare-os/kernel.extensions.registry.example.json (shape for /proc/bare_os/extensions.json schema 7), etc/bare-os/boot-trace-line.example.json and etc/bare-os/telemetry-ndjson.example.json (shape checks for CI), etc/bare-os/rc.profile.full (sample full profile referenced from profile), etc/bare-os/crontab.example (system-wide cron lines merged ahead of user ~/.crontab), etc/bare-os/timers/*.timer.example (copy to ~/.config/bare-os/timers/*.timer for OnCalendar=, EveryMs=, or OnInactiveSec= jobs). kernel.ext.d scripts register into /proc/bare_os/extensions.json when the booter provides ctx.bareOsRegisterKernelExtensionRecord.

See also

• Handbook — Kernel and userspace
• Handbook — POSIX utilities, shell, VFS
• Kernel image reference §9