README.md: Describe more config variables, cleanup

Added some documentation of environment variables to README.md,
specifically WORK_DIR and DEPLOY_DIR.  Explicitly did not include
SCRIPT_DIR at this time because that appears to require some small work
before it can be changed.

Took the chance for some other syntax cleanups while I was at it, mostly
breaking long lines and inserting whitespace where some Markdown parsers
require it.
This commit is contained in:
T. Joseph Carter 2017-05-06 16:16:00 -07:00 committed by XECDesign
parent 0ee2578bc6
commit d729fc2dbb

View file

@ -1,12 +1,24 @@
# pi-gen
_Tool used to create the raspberrypi.org Raspbian images_
### TODO
1. Documentation
## Dependencies
`quilt parted realpath qemu-user-static debootstrap zerofree pxz zip dosfstools bsdtar libcap2-bin grep rsync`
On Debian-based systems:
```bash
apt-get install quilt parted realpath qemu-user-static debootstrap zerofree pxz zip \
dosfstools bsdtar libcap2-bin grep rsync
```
The file `depends` contains a list of tools needed. The format of this
package is `<tool>[:<debian-package>]`.
## Config
@ -29,29 +41,57 @@ The following environment variables are supported:
will not be included in the image, making it safe to use an `apt-cacher` or
similar package for development.
* `BASE_DIR` (Default: location of `build.sh`)
**CAUTION**: Currently, changing this value will probably break build.sh
Top-level directory for `pi-gen`. Contains stage directories, build
scripts, and by default both work and deployment directories.
* `WORK_DIR` (Default: `"$BASE_DIR/work"`)
Directory in which `pi-gen` builds the target system. This value can be
changed if you have a suitably large, fast storage location for stages to
be built and cached. Note, `WORK_DIR` stores a complete copy of the target
system for each build stage, amounting to tens of gigabytes in the case of
Raspbian.
* `DEPLOY_DIR` (Default: `"$BASE_DIR/deploy"`)
Output directory for target system images and NOOBS bundles.
A simple example for building Raspbian:
```bash
IMG_NAME='Raspbian'
```
## Docker Build
```bash
vi config # Edit your config file. See above.
./build-docker.sh
```
If everything goes well, your finished image will be in the `deploy/` folder.
You can then remove the build container with `docker rm pigen_work`
If something breaks along the line, you can edit the corresponding scripts, and
continue:
```
```bash
CONTINUE=1 ./build-docker.sh
```
There is a possibility that even when running from a docker container, the installation of `qemu-user-static` will silently fail when building the image because `binfmt-support` _must be enabled on the underlying kernel_. An easy fix is to ensure `binfmt-support` is installed on the host machine before starting the `./build-docker.sh` script (or using your own docker build solution).
There is a possibility that even when running from a docker container, the
installation of `qemu-user-static` will silently fail when building the image
because `binfmt-support` _must be enabled on the underlying kernel_. An easy
fix is to ensure `binfmt-support` is installed on the host machine before
starting the `./build-docker.sh` script (or using your own docker build
solution).
## Stage Anatomy
@ -104,14 +144,22 @@ maintenance and allows for more easy customization.
the stage that installs all of the things that make Raspbian friendly to
new users.
### Stage specification
If you wish to build up to a specified stage (such as building up to stage 2 for a lite system), place an empty file named `SKIP` in each of the `./stage` directories you wish not to include.
Then remove the `EXPORT*` files from `./stage4` (if building up to stage 2) or from `./stage2` (if building a minimal system).
If you wish to build up to a specified stage (such as building up to stage 2
for a lite system), place an empty file named `SKIP` in each of the `./stage`
directories you wish not to include.
```
Then remove the `EXPORT*` files from `./stage4` (if building up to stage 2) or
from `./stage2` (if building a minimal system).
```bash
# Example for building a lite system
$ touch ./stage3/SKIP ./stage4/SKIP
$ rm stage4/EXPORT*
touch ./stage3/SKIP ./stage4/SKIP
rm stage4/EXPORT*
```
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.
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.