From d729fc2dbbfc4bae691b6cc3be51b446fccbf8f1 Mon Sep 17 00:00:00 2001 From: "T. Joseph Carter" Date: Sat, 6 May 2017 16:16:00 -0700 Subject: [PATCH] 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. --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0603869..8ee6506 100755 --- a/README.md +++ b/README.md @@ -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 `[:]`. + ## 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.