From b9b8df3d113288765e893e181e6c3ea54cab5f43 Mon Sep 17 00:00:00 2001 From: Joseph Carter Date: Sun, 4 Sep 2016 21:02:39 -0700 Subject: [PATCH] README.md: Working toward basic documentation (#10) * README.md: document config file Still pretty sparse, but as this bit is necessary to actually use pi-gen, here it is. * README.md: Overview of Raspbian's stages * README.md: Stages -> Raspbian Stages + heading Decided that the Stages heading probably made more sense as being retitled to refer specifically to Raspbian since it has no direct bearing on pi-gen itself which could produce any Debianish system for the pi, and also that there ought to be a Stage Anatomy section first talking about the nuts and bolts of what goes into these stages. Stage Anatomy is just a heading for now. * README.md: Make Config section less conversational Left the stage overview as it was since it's intended more as a plain language explanation than a technically complete look. I believe that kind of information is useful to have, but perhaps as README.md becomes longer it may be advisable to move it to another location. --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/README.md b/README.md index b8ac6e5..9ff754f 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,70 @@ #Dependencies `quilt kpartx realpath qemu-user-static debootstrap zerofree pxz` + +#Config + +Upon execution, `build.sh` will source the file `config` in the current +working directory. This bash shell fragment is intended to set needed +environment variables. + +The following environment variables are supported: + + * `IMG_NAME`, the name of the distribution to build (required) + * `APT_PROXY`, proxy/cache URL to be included in the build + +A simple example for building Raspbian: + +```bash +IMG_NAME='Raspbian' +``` + +#Stage Anatomy + + + +#Raspbian Stage Overview + +The build of Raspbian is divided up into several stages for logical clarity +and modularity. This causes some initial complexity, but it simplifies +maintenance and allows for more easy customization. + + - Stage 0, bootstrap. The primary purpose of this stage is to create a + usable filesystem. This is accomplished largely through the use of + `debootstrap`, which creates a minimal filesystem suitable for use as a + base.tgz on Debian systems. This stage also configures apt settings and + installs `raspberrypi-bootloader` which is missed by debootstrap. The + minimal core is installed but not configured, and the system will not quite + boot yet. + + - Stage 1, truly minimal system. This stage makes the system bootable by + installing system files like `/etc/fstab`, configures the bootloader, makes + the network operable, and installs packages like raspi-config. At this + stage the system should boot to a local console from which you have the + means to perform basic tasks needed to configure and install the system. + This is as minimal as a system can possibly get, and its arguably not + really usable yet in a traditional sense yet. Still, if you want minimal, + this is minimal and the rest you could reasonably do yourself as sysadmin. + + - State 2, lite system. This stage produces the Raspbian-Lite image. It + installs some optimized memory functions, sets timezone and charmap + defaults, installs fake-hwclock and ntp, wifi and bluetooth support, + dphys-swapfile, and other basics for managing the hardware. It also + creates necessary groups and gives the pi user access to sudo and the + standard console hardware permission groups. + + There are a few tools that may not make a whole lot of sense here for + development purposes on a minimal system such as basic python and lua + packages as well as the `build-essential` package. They are lumped right + in with more essential packages presently, though they need not be with + pi-gen. These are understandable for Raspbian's target audience, but if + you were looking for something between truly minimal and Raspbian-lite, + here's where you start trimming. + + - Stage 3, desktop system. Here's where you get the full desktop system + with X11 and LXDE, web browsers, git for development, Raspbian custom UI + enhancements, etc. This is a base desktop system, with some development + tools installed. + + - Stage 4, complete Raspbian system. More development tools, large packages + like LibreOffice, email, sonic-pi, wolfram-engine, etc. All the things.