From 38b3cf2ad6761ea207abbbc090c2f102c0cfa765 Mon Sep 17 00:00:00 2001
From: "Dustin C. Hatch" <dustin@hatch.name>
Date: Sat, 21 Dec 2024 17:37:47 -0600
Subject: [PATCH] Add README

---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4fcfd5c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# Aimee OS Build Container Images
+
+This repository contains the build scripts for the container images that
+provide the build environment for Aimee OS projects.  Most projects will use
+the _build/build-{target}_ image, which contains a cross-compiler toolchain for
+the _{target}_ system (e.g. _aarch64-unknown-linux-gnu_) with Rust support, as
+well as several other tools for compiling software and creating bootable OS
+images.
+
+
+## Container Images
+
+There are several images in the collection:
+
+```
+gentoo/stage3 †
+build/base
+└── build/cross-aarch64-unknown-linux-gnu
+    └── build/build-aarch64-unknown-linux-gnu ‡
+```
+
+† The _gentoo/stage3_ image contains an unmodified Gentoo stage3 system.  It is
+used to bootstrap the _build/base_ image.
+
+‡ Although the _build/build-{target}_ image is initially populated from the
+corresponding _build/cross-{target}_ image, the final image is "squashed" into
+a single layer to minimize download size.
+
+
+## Git Branches
+
+To enable building images in Jenkins without building all of the preceding
+images, each image has its own Jenkins job.  Since Jenkins does not support
+(auto discovering) multiple jobs in a single Git repository branch, the build
+scripts for the images are tracked in separate branches.  Each branch is named
+like _{image}/{sub-branch}_, where _{image}_ is the short name of the image
+(e.g. `base`, `cross`, etc) and _{sub-branch}_ is an arbitrary name (e.g.
+_main_).
+
+* _base/main_: This branch is responsible for building _gentoo/stage3_ and
+  _build/base_.
+* _cross/main_: This branch contains the build script for
+  _build/cross-{target}_.
+* _build/main_: This branch builds _build/build-{target}_.
+
+In addition to the per-image branches, there is also _lib/{sub-branch}_.
+Code shared by multiple image build scripts is tracked here.  Build scripts
+expect the shared code to be available in the `lib` directory, which is
+generally populated using a Git worktree, e.g.:
+
+```sh
+git worktree add lib lib/main
+```
+
+The _main_ branch itself is empty except for this README.