|
| 1 | +## Project structure |
| 2 | + |
| 3 | +- `goldboot/src/builder/os/` — one module per supported OS |
| 4 | +- `goldboot/src/builder/options/` — shared config types (`Locale`, `Timezone`, |
| 5 | + `Ntp`, `Packages`, `UnixUsers`, etc.) |
| 6 | +- `goldboot-image/` — image format library |
| 7 | +- `goldboot-macros/` — proc macros (`#[Os(...)]`, `#[derive(Prompt)]`) |
| 8 | + |
| 9 | +## Adding a new OS |
| 10 | + |
| 11 | +1. Create `goldboot/src/builder/os/<name>/mod.rs`. |
| 12 | +2. Annotate the struct with `#[goldboot_macros::Os(architectures(...))]` and |
| 13 | + derive |
| 14 | + `Clone, Serialize, Deserialize, Validate, Debug, SmartDefault, goldboot_macros::Prompt`. |
| 15 | +3. Use shared option types from `builder::options` where applicable (hostname, |
| 16 | + locale, timezone, ntp, packages, unix_users, root_password, iso, size, arch). |
| 17 | +4. Implement `BuildImage` with a `build()` method. We need to manipulate the VM |
| 18 | + until we get to a shell so we can finish the install via SSH. Use |
| 19 | + `wait_text!` to wait for the given text to be displayed on the screen. |
| 20 | +5. Register the module in `goldboot/src/builder/os/mod.rs`. |
| 21 | + |
| 22 | +## Updating for a new upstream OS release |
| 23 | + |
| 24 | +1. **Add the new release variant** to the release enum (e.g. `V3_24`, |
| 25 | + `Bookworm`) at the top of the enum so it sorts newest-first. |
| 26 | +2. **Keep EOL releases** |
| 27 | +3. **Update the default variant** to the newest stable release. |
| 28 | +4. **Update the default ISO** — find the new ISO filename, URL, and sha256 |
| 29 | + checksum from the upstream mirror and update the `#[default(Iso { ... })]` on |
| 30 | + the `iso` field. |
| 31 | +5. Run `cargo check` to confirm everything compiles. |
| 32 | + |
| 33 | +### Pop!\_OS (`goldboot/src/builder/os/pop_os/mod.rs`) |
| 34 | + |
| 35 | +Release page: https://pop.system76.com ISO index: |
| 36 | +`https://iso.pop-os.org/<YY.MM>/amd64/<generic|nvidia>/<revision>/` API: |
| 37 | +`https://api.pop-os.org/builds/<YY.MM>/stable?arch=amd64` |
| 38 | + |
| 39 | +**Release enum** — `PopOsRelease` lists LTS releases only, newest-first. |
| 40 | +Pop!\_OS follows Ubuntu's LTS cadence. |
| 41 | + |
| 42 | +Pop!\_OS uses a **custom graphical installer** (not Ubuntu autoinstall). |
| 43 | +Installation is driven by VNC automation in `build()`. Because of this, the |
| 44 | +primary user account must be configured via `user: PopOsUser` — the installer |
| 45 | +requires it. Post-install config (extra users, packages, hostname, timezone) is |
| 46 | +applied over SSH. |
| 47 | + |
| 48 | +### Ubuntu (`goldboot/src/builder/os/ubuntu/mod.rs`) |
| 49 | + |
| 50 | +Release page: https://ubuntu.com/about/release-cycle ISO index: |
| 51 | +https://releases.ubuntu.com/<codename>/SHA256SUMS |
| 52 | + |
| 53 | +**Release enum** — `UbuntuRelease` lists only currently-supported releases. LTS |
| 54 | +releases are preferred; interim releases are included but not the default. |
| 55 | + |
| 56 | +Ubuntu uses **autoinstall** (cloud-init YAML) for unattended installation — |
| 57 | +generated at build time in `Ubuntu::generate_autoinstall()`. There is no static |
| 58 | +config file. |
| 59 | + |
| 60 | +### Debian (`goldboot/src/builder/os/debian/mod.rs`) |
| 61 | + |
| 62 | +Release page: https://www.debian.org/releases/ ISO index: |
| 63 | +https://cdimage.debian.org/cdimage/release/current/amd64/iso-cd/ |
| 64 | + |
| 65 | +**Release enum** — `DebianEdition` lists releases stable-first (Trixie, |
| 66 | +Bookworm, Bullseye, Forky, Sid). Stable and oldstable always have real ISOs; |
| 67 | +testing/unstable are opt-in. |
| 68 | + |
| 69 | +The preseed is generated at build time in `Debian::generate_preseed()` — no |
| 70 | +static file to update. |
| 71 | + |
| 72 | +### Alpine Linux (`goldboot/src/builder/os/alpine_linux/mod.rs`) |
| 73 | + |
| 74 | +Release page: https://alpinelinux.org/releases/ CDN root: |
| 75 | +https://dl-cdn.alpinelinux.org/alpine/ |
| 76 | + |
| 77 | +**Release enum** — `AlpineRelease` lists supported branches newest-first, with |
| 78 | +`Edge` last. Only include branches that appear on the releases page as actively |
| 79 | +supported. |
| 80 | + |
| 81 | +## TODO list |
| 82 | + |
| 83 | +- Finish registry implementation |
| 84 | +- Create nixpkgs branch for configuring server |
| 85 | +- Figure out how to package goldboot.efi |
| 86 | +- Finish remaining builders |
| 87 | +- Finish multiboot builds |
0 commit comments