Initial scaffold

2026-09-01 08:00:05 +02:00
commit ffe32f6dda
4 changed files with 291 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Kama (窯)
+
+**Kama** — the kiln — is the package manager for [Keru OS](https://github.com/AstralZX/KeruOS).
+
+It's a single shell script (plus a small library) that builds packages from
+source by executing their recipes. It is deliberately minimal: there is no
+dependency resolver, no package database, and no binary format. Kama reads a
+`make.conf`, and it runs whatever each recipe tells it to.
+
+## Why shell?
+
+Kama is the whole point of Keru stated plainly: the package manager shouldn't
+be more complex than the packages it builds. It's not a program that manages
+packages as much as a *runner* for recipe scripts — the clever part lives in
+the recipes, not the mangement machinery.
+
+## Usage
+
+```
+kama fetch   <pkg>   download + extract source into the cache
+kama build   <pkg>   stage-build one package
+kama install <pkg>   build + install into $ROOT
+kama make    <pkg>   fetch deps, build, install, purge temp deps (AUR-style)
+kama purge            remove temp build-time deps
+kama info    <pkg>   show recipe metadata
+```
+
+## Configuration
+
+Kama reads a `make.conf` (default `/etc/kama/make.conf`) for global build
+flags and profile choices. Key variables:
+
+- `ROOT` — target rootfs the packages install into
+- `CACHEDIR` — persistent source + build cache
+- `CFLAGS` / `MAKEFLAGS` — passed to every build
+- `PKGDIR` — where the recipe repository lives (default: sibling `kama-packages`)
+
+## Recipes
+
+Packages are plain POSIX shell scripts. The syntax splits into two tiers:
+
+- **Easy tier** — declare `name`, `version`, `url`, then a `build()` and
+  `install()`. Kama handles fetch + extract automatically.
+- **Advanced tier** — override `pkg_fetch`, add `pkg_post`, `pkg_split`,
+  `provides`, `conflicts`, `arch`, etc.
+
+See [the recipe format](KeruOS/blob/main/docs/recipe-format.md) in the KeruOS
+repo for the full spec.
+
+## Dependencies
+
+Dependencies are handled AUR-style: build-time deps are fetched, compiled, and
+stripped away once the real package is built, leaving only what the system
+needs. This is the foundation of Keru's "nothing you didn't ask for" ethos.
+
+## License
+
+AGPL-3.0