Developers

Clone the repositories side by side into one directory. The image builders find the others by relative path.

Repositories

Repository	Contents
`uranium-tools`	rod, scram, silo, hazmat, blastdoor, geiger and setup, in Rust with no dependencies. The manual pages are in the same repository.
`uranium-install`	The installer, the desktop setup, the session starter, the bootstrap rod and a few small scripts. Plain shell.
`uranium-recipes`	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.
`uranium-mklive`	The scripts that build the stage tarball, the disk image and the live ISO, the system files that go into them.
`uranium-os.github.io`	This handbook and the front page.

Layout

uranium/
  uranium-tools/
  uranium-install/
  uranium-recipes/
  uranium-mklive/
  uranium-os.github.io/

The build scripts look for uranium-install, uranium-tools and uranium-recipes next to uranium-mklive. The variables INSTALL, TOOLS and RECIPES point them somewhere else.

What the host needs

Linux with unprivileged user namespaces. The builds run in chroots inside unshare --map-auto --map-root-user --mount and need no root.
Nix, to build the first closure into a chroot, a POSIX shell, curl, tar, xz and util-linux.
A copy of the package index at $B/nixexprs.tar.xz. The builds read it from there, so every image is built from the same index. B is the build directory and defaults to ~/uranium-build.

Building

The scripts are in uranium-mklive/stage. Run them in this order.

build-stage.sh: Installs the base packages into a root in $B/root with the bootstrap rod, lays out the system, copies in the skeleton, and writes uranium-stage-VERSION.tar.xz and it's checksum to $OUT.
build-image.sh: 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 $B/uranium.img.
build-iso.sh: Copies the image root into a live root, packs it as squashfs and writes uranium-VERSION.iso with an EFI boot image.
release.sh: Runs the three scripts, packs the tools tarball, signs the checksums with signify and copies the files and the public key to the site.

The variables the scripts read are B, OUT, VER, INSTALL, TOOLS, RECIPES, and for incremental builds KEEP, QUICK and KEEPIMG. release.sh reads the signing key from KEY.

Source of the tools

uranium-tools/src/lib.rs holds the helpers the tools share. Each tool is one file in src/bin. rod runs nix-env on the profile /rod/profile and keeps its own state in /rod. scram works on btrfs subvolumes through btrfs and writes boot menu entries for limine. The tools call the programs they need by name and link to nothing outside the standard library.

The release profile builds with panic = "abort" and overflow-checks = true. To build and run the tools on a host:

$ cd uranium-tools
$ cargo build --release
$ ./target/release/rod

Adding things

A package recipe: Add NAME.nix to uranium-recipes. rod installs a file in /rod/recipes under its name before it looks in the index. A recipe that fetches a source needs its hash. Run rod +i NAME with a wrong hash and rod prints the right one and offers to write it into the file.
A package set: Add a file to uranium-mklive/stage/skel/etc/rod/sets, one package attribute per line. rod +i @NAME installs it, and -i leaves members out. See rod.
A desktop: Add its set to the same directory, add it to the menu in uranium-install and to the case in uranium-desktop and uranium-session.
A manual page: Add the file to uranium-tools/man. The build scripts copy the sections 1 pages into the system.
A page of this handbook: Copy a page with a sidebar, replace the article, add the link to the sidebar of every page.

Releases

release.sh writes the ISO, the stage tarball and the tools tarball, a SHA256 file that lists them, and SHA256.sig, a signify signature of that file. The public key is uranium-0.1.pub. See download.

See contributing for how to send changes.