developers.html

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Developers - UraniumOS</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<header><div class="in"><nav class="l"><a href="index.html">Home</a><a href="download.html">Download</a><a href="docs.html">Documentation</a><a href="rod.html">Packages</a><a href="news.html">News</a><a href="about.html">About</a></nav><nav class="r"><a href="features.html">Features</a><a href="media.html">Install</a><a href="security.html">Security</a><a href="hardware.html">Hardware</a></nav></div></header>
<main class="in docs">
<aside><div class="sbhead"><a class="sbh" href="index.html">&#8962; UraniumOS</a><svg aria-hidden="true" viewBox="-50 -50 100 100"><circle r="48" fill="#f2d21b"/><circle r="6.5" fill="#1b1b19"/><path fill="#1b1b19" d="M6.50 -11.26 A13 13 0 0 0 -6.50 -11.26 L-20.00 -34.64 A40 40 0 0 1 20.00 -34.64 Z M-13.00 -0.00 A13 13 0 0 0 -6.50 11.26 L-20.00 34.64 A40 40 0 0 1 -40.00 -0.00 Z M6.50 11.26 A13 13 0 0 0 13.00 0.00 L40.00 0.00 A40 40 0 0 1 20.00 34.64 Z"/></svg><span class="ver">0.1.1</span><input type="search" placeholder="Search docs" aria-label="Search docs"></div><h4>Read first</h4><ul><li><a href="differences.html">Differences and known failures</a></li></ul><h4>1 Installation</h4><ul><li><a href="download.html">1.1 Download</a></li><li><a href="media.html">1.2 Live medium</a></li><li><a href="partitioning.html">1.3 Partitioning notes</a></li><li><a href="manual-install.html">1.4 Manual install</a></li><li><a href="first-steps.html">1.5 First steps</a></li></ul><h4>2 Configuration</h4><ul><li><a href="users.html">2.1 Users and groups</a></li><li><a href="keyboard.html">2.2 Keyboard</a></li><li><a href="time.html">2.3 Date and time</a></li><li><a href="services.html">2.4 Services</a></li><li><a href="cron.html">2.5 Cron</a></li><li><a href="network.html">2.6 Network</a></li><li><a href="ssh.html">2.7 SSH</a></li><li><a href="blastdoor.html">2.8 Firewall</a></li><li><a href="desktop.html">2.9 Desktop</a></li><li><a href="firmware.html">2.10 Firmware</a></li><li><a href="boot.html">2.11 Boot</a></li><li><a href="kernel.html">2.12 Kernel</a></li><li><a href="storage.html">2.13 Storage</a></li><li><a href="security.html">2.14 Security</a></li><li><a href="geiger.html">2.15 Health report</a></li></ul><h4>3 Packages</h4><ul><li><a href="rod.html">3.1 rod</a></li><li><a href="cheatsheet.html">3.2 rod cheat sheet</a></li><li><a href="not-in-rod.html">3.3 Package not in rod</a></li><li><a href="recipes.html">3.4 Recipes</a></li><li><a href="silo.html">3.5 Containers</a></li><li><a href="hazmat.html">3.6 Sandboxes</a></li></ul><h4>4 Snapshots</h4><ul><li><a href="scram.html">4.1 scram</a></li><li><a href="backups.html">4.2 Backups</a></li></ul><h4>5 Reference</h4><ul><li><a href="system.html">5.1 System and files</a></li><li><a href="troubleshooting.html">5.2 Troubleshooting</a></li><li><a href="hardware.html">5.3 Hardware status</a></li><li><a href="faq.html">5.4 FAQ</a></li></ul><h4>6 Project</h4><ul><li><a href="developers.html" aria-current="page">6.1 Developers</a></li><li><a href="contributing.html">6.2 Contributing</a></li><li><a href="about.html">6.3 About</a></li><li><a href="features.html">6.4 Features</a></li><li><a href="news.html">6.5 News</a></li></ul></aside><article><div class="band"><h1>Developers</h1></div>
<p>Clone the repositories side by side into one directory. The image builders find the others by relative path.</p>
<h2>Repositories</h2>
<table class="wide">
<tr><td><b>Repository</b></td><td><b>Contents</b></td></tr>
<tr><td><a href="https://github.com/uranium-os/uranium-tools"><code>uranium-tools</code></a></td><td>rod, scram, silo, hazmat, blastdoor, geiger and setup, in Rust with no dependencies. The manual pages are in the same repository.</td></tr>
<tr><td><a href="https://github.com/uranium-os/uranium-install"><code>uranium-install</code></a></td><td>The installer, the desktop setup, the session starter, the bootstrap rod and a few small scripts. Plain shell.</td></tr>
<tr><td><a href="https://github.com/uranium-os/uranium-recipes"><code>uranium-recipes</code></a></td><td>Nix expressions for what is not in the package index: the kernel and its configuration, the initramfs, the init script, doas, avtty, fetch, zen and the time zone data.</td></tr>
<tr><td><a href="https://github.com/uranium-os/uranium-mklive"><code>uranium-mklive</code></a></td><td>The scripts that build the stage tarball, the disk image and the live ISO, the system files that go into them.</td></tr>
<tr><td><a href="https://github.com/uranium-os/uranium-os.github.io"><code>uranium-os.github.io</code></a></td><td>This handbook and the front page.</td></tr>
</table>
<h2>Layout</h2>
<pre><code>uranium/
  uranium-tools/
  uranium-install/
  uranium-recipes/
  uranium-mklive/
  uranium-os.github.io/</code></pre>
<p>The build scripts look for <code>uranium-install</code>, <code>uranium-tools</code> and <code>uranium-recipes</code> next to <code>uranium-mklive</code>. The variables <code>INSTALL</code>, <code>TOOLS</code> and <code>RECIPES</code> point them somewhere else.</p>
<h2>What the host needs</h2>
<ul>
<li>Linux with unprivileged user namespaces. The builds run in chroots inside <code>unshare --map-auto --map-root-user --mount</code> and need no root.</li>
<li>Nix, to build the first closure into a chroot, a POSIX shell, curl, tar, xz and util-linux.</li>
<li>A copy of the package index at <code>$B/nixexprs.tar.xz</code>. The builds read it from there, so every image is built from the same index. <code>B</code> is the build directory and defaults to <code>~/uranium-build</code>.</li>
</ul>
<h2>Building</h2>
<p>The scripts are in <code>uranium-mklive/stage</code>. Run them in this order.</p>
<dl>
<dt><code>build-stage.sh</code></dt><dd>Installs the base packages into a root in <code>$B/root</code> with the bootstrap rod, lays out the system, copies in the skeleton, and writes <code>uranium-stage-VERSION.tar.xz</code> and it's checksum to <code>$OUT</code>.</dd>
<dt><code>build-image.sh</code></dt><dd>Copies the stage, installs the kernel, the initramfs and uranium-tools, takes the first frame, writes the boot menu and writes the btrfs disk image <code>$B/uranium.img</code>.</dd>
<dt><code>build-iso.sh</code></dt><dd>Copies the image root into a live root, packs it as squashfs and writes <code>uranium-VERSION.iso</code> with an EFI boot image.</dd>
<dt><code>release.sh</code></dt><dd>Runs the three scripts, packs the tools tarball, signs the checksums with <code>signify</code> and copies the files and the public key to the site.</dd>
</dl>
<p>The variables the scripts read are <code>B</code>, <code>OUT</code>, <code>VER</code>, <code>INSTALL</code>, <code>TOOLS</code>, <code>RECIPES</code>, and for incremental builds <code>KEEP</code>, <code>QUICK</code> and <code>KEEPIMG</code>. <code>release.sh</code> reads the signing key from <code>KEY</code>.</p>
<h2>Source of the tools</h2>
<p><code>uranium-tools/src/lib.rs</code> holds the helpers the tools share. Each tool is one file in <code>src/bin</code>. <code>rod</code> runs <code>nix-env</code> on the profile <code>/rod/profile</code> and keeps its own state in <code>/rod</code>. <code>scram</code> works on btrfs subvolumes through <code>btrfs</code> and writes boot menu entries for limine. The tools call the programs they need by name and link to nothing outside the standard library.</p>
<p>The release profile builds with <code>panic = "abort"</code> and <code>overflow-checks = true</code>. To build and run the tools on a host:</p>
<pre><code>$ cd uranium-tools
$ cargo build --release
$ ./target/release/rod</code></pre>
<h2>Adding things</h2>
<dl>
<dt>A package recipe</dt><dd>Add <code>NAME.nix</code> to <code>uranium-recipes</code>. rod installs a file in <code>/rod/recipes</code> under its name before it looks in the index. A recipe that fetches a source needs its hash. Run <code>rod +i NAME</code> with a wrong hash and rod prints the right one and offers to write it into the file.</dd>
<dt>A package set</dt><dd>Add a file to <code>uranium-mklive/stage/skel/etc/rod/sets</code>, one package attribute per line. <code>rod +i @NAME</code> installs it, and <code>-i</code> leaves members out. See <a href="rod.html">rod</a>.</dd>
<dt>A desktop</dt><dd>Add its set to the same directory, add it to the menu in <code>uranium-install</code> and to the case in <code>uranium-desktop</code> and <code>uranium-session</code>.</dd>
<dt>A manual page</dt><dd>Add the file to <code>uranium-tools/man</code>. The build scripts copy the sections 1 pages into the system.</dd>
<dt>A page of this handbook</dt><dd>Copy a page with a sidebar, replace the article, add the link to the sidebar of every page.</dd>
</dl>
<h2>Releases</h2>
<p><code>release.sh</code> writes the ISO, the stage tarball and the tools tarball, a <code>SHA256</code> file that lists them, and <code>SHA256.sig</code>, a <code>signify</code> signature of that file. The public key is <code>uranium-0.1.pub</code>. See <a href="download.html">download</a>.</p>
<p>See <a href="contributing.html">contributing</a> for how to send changes.</p>
<div class="pager"><span></span><a href="contributing.html">Contributing &rarr;</a></div></article>
</main>
<footer><div class="in"><p>Public domain, CC0 1.0</p><p><a href="https://github.com/uranium-os">GitHub</a> &nbsp; <a href="https://texivi.github.io">Blog</a></p></div></footer>
<script>document.querySelectorAll("pre:not(.term):not(.portrait)").forEach(function(p){var b=document.createElement("button");b.textContent="\u29c9";b.title="Copy";b.onclick=function(){navigator.clipboard.writeText(p.innerText.replace(/\u29c9$/,"").trim());b.textContent="\u2713";setTimeout(function(){b.textContent="\u29c9"},900)};p.appendChild(b)});</script>
<script src="docs.js"></script>
<script src="fun.js"></script>
</body>
</html>