Initial scaffold

docs/DESIGN.md

@@ -0,0 +1,19 @@
+# design/index
+
+This directory holds the working design for Keru OS. The code is scaffolding
+and not yet functional end-to-end.
+
+## What exists
+
+- `recipe-format.md` — the Kama recipe format (easy/advanced tiers)
+- `README.md` (repo root) — project identity + layout
+
+## Open design questions
+
+- **Bootstrapping toolchain**: chicken-and-egg — the first compiler must be
+  obtained somehow. Options: a documented one-time bootstrap from a binary
+  seed, or a multi-stage rebuild (host -> minimal -> full). Not yet decided.
+- **No dependency resolver**: how upgrades/rebuilds are handled for a system
+  that's "built once at install." Currently framed as install-time-only.
+- **Cache artifacts vs. rebuilds**: whether the build cache stores binaries
+  for fast re-install or always recompiles.

docs/recipe-format.md

@@ -0,0 +1,121 @@
+# Kama recipe format
+#
+# A package is a plain POSIX shell script that describes how to compile and
+# install one piece of software. The syntax is split into two tiers:
+#
+#   EASY      - declare three variables, fill in build + install, done.
+#               The common case for 90% of packages (autotools/cmake/meson).
+#
+#   ADVANCED  - full control when you need it: custom fetch/extract, staging
+#               layout, packaging hooks, multi-arch, verification, etc.
+#               Everything the easy tier does is just sugar over this.
+#
+# In both tiers, Kama sources the recipe and runs the functions you define.
+#
+#
+# =========================================================================
+# EASY TIER — most packages only need this
+# =========================================================================
+#
+#   name=busybox
+#   version=1.36.1
+#   url=https://busybox.net/downloads/busybox-1.36.1.tar.bz2
+#   deps=()        # build-time deps, purged after (AUR-style)
+#
+#   build() {      # configure + compile
+#       make defconfig
+#       make
+#   }
+#
+#   install() {    # install into $pkgdir (staging), not $ROOT
+#       make install CONFIG_PREFIX="$pkgdir"
+#   }
+#
+# That's it. Kama supplies the conventional pkg_fetch (download + extract --
+# auto-detects tar.xz/.gz/.bz2/.zip, strips the top dir) and pkg_clean.
+#
+#
+# =========================================================================
+# ADVANCED TIER — override any step, add packaging control
+# =========================================================================
+#
+#   name=busybox
+#   version=1.36.1
+#   url=https://busybox.net/downloads/busybox-1.36.1.tar.bz2
+#   deps=(gcc musl-headers)          # temp build deps (AUR-style)
+#   runtime_deps=(musl)              # stays installed
+#   license=(GPL-2.0)
+#   provides=(sh)                    # capability this package provides
+#   conflicts=(dash)                 # mutual exclusion
+#   arch=(x86_64)                    # if non-empty, restrict to archs
+#   noextract=()                     # URLs to download but NOT auto-extract
+#
+#   # override auto extract (e.g. patching before configure)
+#   pkg_fetch() {
+#       default_fetch               # run the easy-tier default
+#       cd "$src"
+#       patch -p1 < ../my.patch
+#   }
+#
+#   build()   { ./configure --prefix=/usr "$@" && make; }
+#   install() { make install DESTDIR="$pkgdir"; }
+#
+#   # split headers/binary into separate sub-package stage (advanced)
+#   pkg_split() { ... }
+#
+#   # run after install, before purge (e.g. generate ldconfig cache)
+#   pkg_post() { msg "post-install hook"; }
+#
+#
+# =========================================================================
+# FULL FUNCTION REFERENCE
+# =========================================================================
+#
+# Variables (easy tier):
+#   name, version, url, deps
+#
+# Variables (advanced, all optional):
+#   runtime_deps, license, provides, conflicts, arch, noextract
+#
+# Functions:
+#   build()       - configure + compile into $src (also callable `pkg_build`)
+#   install()     - install into $pkgdir  (also callable `pkg_install`)
+#   pkg_fetch     - override download/extract (call `default_fetch` for the
+#                   easy-tier default)
+#   pkg_clean     - override cleanup
+#   pkg_post      - run after install, before temp deps are purged
+#   pkg_split     - split staging into multiple sub-packages (advanced)
+#
+# Easy-tier aliases: `build` and `install` are sugar; if you define them,
+# Kama maps them to pkg_build / pkg_install automatically. Defining the
+# pkg_* forms directly also works (that IS the advanced way).
+#
+# Provided by Kama (do not redefine):
+#   $src         - build dir (cannot be changed)
+#   $pkg     - pkg dir alt alias for $pkgdir
+#   $pkgdir      - staging dir; Kama moves $pkgdir/* into $ROOT after success
+#   $CACHEDIR, $ROOT, $CFLAGS, ... from make.conf
+#   msg() warn() die()
+#   default_fetch - the easy-tier fetch/extract implementation
+
+# ---- easy-tier defaults (override as needed) ----------------------------
+name=
+version=
+url=
+deps=()
+
+# ---- advanced overrides (all optional) ----------------------------------
+runtime_deps=()
+license=()
+provides=()
+conflicts=()
+arch=()
+noextract=()
+
+# ---- functions -----------------------------------------------------------
+build()     { :; }   # or pkg_build
+install()   { :; }   # or pkg_install
+pkg_fetch() { :; }
+pkg_clean() { :; }
+pkg_post()  { :; }
+pkg_split() { :; }