migrate website from KeruOS web to its own repo

2026-09-01 12:06:36 +02:00
commit 4a32fab414
56 changed files with 4120 additions and 0 deletions
@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Mirrors and cache — Keru OS</title>
+<meta name="description" content="How Keru and Kama download source tarballs: an optional mirror you run, upstream as fallback, and the download/source/stage cache layout.">
+<link rel="stylesheet" href="assets/css/style.css">
+<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>ける</text></svg>">
+</head>
+<body>
+
+<nav class="top" data-nav></nav>
+
+<header class="pagehead">
+    <p class="crumbs"><a href="index.html">home</a> / <a href="docs.html">docs</a> / mirrors &amp; cache</p>
+    <h1>Mirrors and cache</h1>
+    <p>Where source comes from, and where it waits.</p>
+</header>
+
+<section>
+    <div class="wrap">
+        <div class="prose">
+            <p>Every Keru build is a network operation. Package recipes always come from the GitHub-hosted <a href="kama-repos.html">kama-packages</a> repo; this page is about the other half — the <em>source tarballs</em> each recipe downloads, and the cache they pass through.</p>
+
+            <h3>Download order</h3>
+            <ul class="features">
+                <li><strong>1. <code>SOURCE_MIRROR</code></strong> — tried first when set; run a mirror of source tarballs and point it here.</li>
+                <li><strong>2. Upstream</strong> — the canonical source URL from the recipe. Used when no mirror is set or the mirror lacks a file.</li>
+                <li><strong>Verification at every step.</strong> A file that doesn't match its checksum is dropped, and the next source in line is tried. Tampered files never reach a build.</li>
+            </ul>
+
+            <h3>The cache layout</h3>
+            <div class="code-block">/var/cache/kama/        # CACHEDIR (set CACHEDIR=/path to relocate)
+├── dl/                  # downloaded tarballs, one per package
+├── src/                 # extracted source (per package dir)
+└── stage/               # staged installs before they commit to $ROOT</div>
+
+            <table>
+                <tr><th>Dir</th><th>Everything</th><th>Purpose</th></tr>
+                <tr><td><code>dl</code></td><td>Downloads</td><td>Already-downloaded archives are reused, never re-fetched.</td></tr>
+                <tr><td><code>src</code></td><td>Extracted</td><td>Extraction is skipped when the checked-out source is present.</td></tr>
+                <tr><td><code>stage</code></td><td>Staged builds</td><td>Progress survives a failed build; re-running continues.</td></tr>
+            </table>
+
+            <h3>Working offline, or your own mirror</h3>
+            <div class="code-block"># warm the cache once, then build with the network down
+SOURCE_MIRROR=https://mirror.example.org kama fetch busybox
+...
+CACHEDIR=/var/cache/kama kama make busybox   # no network needed</div>
+            <p>Run a mirror yourself and point <code>SOURCE_MIRROR</code> at it. The layout mirrors <code>dl/</code>; the fetch layer treats it as a read-mostly source of truth.</p>
+
+            <h3>Cleanup</h3>
+            <ul class="features">
+                <li><code>rm -rf /var/cache/kama/src/*</code> — free extracted source (re-extracts on next build).</li>
+                <li><code>rm -rf /var/cache/kama/dl/*</code> — dump downloads (re-fetches next time).</li>
+                <li><code>rm -rf /var/cache/kama/stage/*</code> — discard staged builds.</li>
+            </ul>
+
+            <div class="callout">A corrupt cache is the #1 source of confusing fetch errors. When in doubt, clear the relevant dir — downloads verify anyway, so you lose nothing but time.</div>
+
+            <p><a href="kama-usage.html">← kama usage</a> · <a href="troubleshooting.html">Troubleshooting</a></p>
+        </div>
+    </div>
+</section>
+
+<footer data-footer></footer>
+
+<noscript><div style="text-align:center;padding:16px">See the <a href="sitemap.html">sitemap</a> for all pages.</div></noscript>
+
+<script src="assets/js/include.js" data-base="."></script>
+</body>
+</html>