# Ownerboot Architecture

## Nixpkgs

Nixpkgs is organized as a mutually-recursive package collection; the machinery for this involves `lib.makeScope` and `callPackage`.

## Ownerboot

Ownerboot creates a second mutually-recursive package set containing all of the build products which go into the final flash image; this package set is what you see in `src/default.nix`:

* `coreboot` -- a Nix package for coreboot, since it is not in nixpkgs
* `kernel` -- the Linux kernel, using a custom (non-nixpkgs) expression
* `userspace` -- the userspace for the linux initramfs
* `initramfs` -- merges `userspace` with the boot-critical modules from `kernel` and wraps it in a properly-formatted `cpio` archive
* `arm-trusted-firmware` -- the ARM EL3 privileged routines
* `fit` -- generates a FIT payload
* `iasl` -- the Intel ACPI compiler

Many of these packages are simply customizations of the corresponding packages in nixpkgs.  In spite of this, the ownerboot package set is *not* a scope-extension of any nixpkgs package set, in order to avoid future package name collisions as nixpkgs adds more packages (and present name collisions due to mistakes!).

## Cross Compilation

Ownerboot is designed for cross-compilation as a first-class citizen.  My arm64 laptop is fanless and lightweight but slow; I don't want to use it to build its own bootloader.

### Terminology

Recall the GCC cross-compilation terminology:

* `build`: the platfrom doing the compiling
* `host`: the platform which runs the result of the compilation
* `target`: if running the result of the compilation emits code, the platform on which *that* code runs

### Package Sets

When cross-compiling nixpkgs there will be (at least) two of these mutually-recursive package sets.  Ownerboot instantiates them as:

* `nixpkgsOnBuildForBuild`: a copy of nixpkgs which executes on the build machine and emits code for the build machine
* `nixpkgsOnBuildForHost`: a copy of nixpkgs which executes on the build machine and emits code for the host machine

The ownerboot package set is host-independent; it contains only the code which is common across all hosts.  Several essential inputs (for example, choice of coreboot version) are host-specific.  The host-independent package set has `throw "you must provide..."` placeholders for these.  If you attempt to build the host-independent package set, you will encounter these thrown exceptions.

Each host platform supported by ownerboot applies an overlay (i.e. `overrideScope'`) to the host-independent package set.  These overlays must replace all of the `throw` placeholders in order to produce a useful build artifact.  There is one entry for each supported host platform near the bottom of `src/default.nix`.