From 6e3256941564a97dc1cb563bb2667caef7e7a0ce Mon Sep 17 00:00:00 2001
From: Ben Pirt <ben@pirt.co.uk>
Date: Fri, 15 Dec 2017 11:31:40 +0000
Subject: [PATCH] Update README with some information on how the build works
 (#136)

---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 65 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3008140..7a73c77 100755
--- a/README.md
+++ b/README.md
@@ -3,13 +3,13 @@
 _Tool used to create the raspberrypi.org Raspbian images_
 
 
-### TODO
-1. Documentation
-
-
 ## Dependencies
 
-On Debian-based systems:
+pi-gen runs on Debian based operating systems. Currently it is only supported on
+either Debian Stretch or Ubuntu Xenial and is known to have issues building on
+earlier releases of these systems.
+
+To install the required dependencies for pi-gen you should run:
 
 ```bash
 apt-get install quilt parted realpath qemu-user-static debootstrap zerofree pxz zip \
@@ -80,6 +80,48 @@ IMG_NAME='Raspbian'
 ```
 
 
+## How the build process works
+
+The following process is followed to build images:
+
+ * Loop through all of the stage directories in alphanumeric order
+
+ * Move on to the next directory if this stage directory contains a file called
+   "SKIP"
+
+ * Run the script ```prerun.sh``` which is generally just used to copy the build
+   directory between stages.
+
+ * In each stage directory loop through each subdirectory and then run each of the
+   install scripts it contains, again in alphanumeric order. These need to be named
+   with a two digit padded number at the beginning.
+   There are a number of different files and directories which can be used to
+   control different parts of the build process:
+
+     - **00-run.sh** - A unix shell script. Needs to be made executable for it to run
+
+     - **00-run-chroot.sh** - A unix shell script which will be run in the chroot
+       of the image build directory. Needs to be made executable for it to run.
+
+     - **00-debconf** - Contents of this file are passed to debconf-set-selections
+       to configure things like locale, etc.
+
+     - **00-packages** - A list of packages to install. Can have more than one, space
+       separated, per line.
+
+     - **00-packages-nr** - As 00-packages, except these will be installed using
+       the ```--no-install-recommends -y``` parameters to apt-get
+
+     - **00-patches** - A directory containing patch files to be applied
+
+  * If the stage directory contains files called "EXPORT_NOOBS" or "EXPORT_IMAGE" then
+    add this stage to a list of images to generate
+
+  * Generate the images for any stages that have specified them
+
+It is recommended to examine build.sh for finer details.
+
+
 ## Docker Build
 
 ```bash
@@ -179,3 +221,21 @@ sudo ./build.sh  # or ./build-docker.sh
 If you wish to build further configurations upon (for example) the lite
 system, you can also delete the contents of `./stage3` and `./stage4` and
 replace with your own contents in the same format.
+
+
+## Skipping stages to speed up development
+
+If you're working on a specific stage the recommended development process is as
+follows:
+
+ * Remove the EXPORT_IMAGE and EXPORT_NOOBS files until you're ready to actually
+   generate an image
+ * Add SKIP files to the stages you don't want to build. For example, if you're
+   basing your image on the lite image you would add these to stages 3, 4 and 5.
+ * Run build.sh to build all stages
+ * Add SKIP files to the earlier successfully built stages
+ * Modify the last stage
+ * Rebuild just the last stage using ```sudo CLEAN=1 ./build.sh```
+ * Once you're happy with the image you can add the EXPORT files back in and
+   export your image to test
+