4.1. live-helper

live-helper is a collection of scripts to build Debian Live systems. These scripts are also referred to as "helpers".

The idea behind live-helper is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image.

Many concepts are similar with the debhelper Debian package tools written by Joey Hess:

  1. The scripts have a central location for configuring their operation.

    In debhelper, this is the debian subdirectory of a package tree. For example, dh_install will look for file called debian/<packagename>.install to determine which files should exist in a particular binary package. In much the same way, live-helper stores its configuration entirely under a config/ subdirectory.

  2. The scripts are independent - that is to say, it is always safe to run each command.

Unlike debhelper, live-helper contains a tool to generate a skeleton configuration directory, lh_config. This could be considered to be similar to tools such as dh-make. For more information about lh_config, please see Section 4.1.1, “The lh_config helper”.

Besides the common config/common, which is used by all live-helper helper commands, some additional files can be used to configure the behavior of specific helper commands. These files are typically named config/foo or config/stage (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper).

For example, the lh_bootstrap_debootstrap helper command uses files named config/bootstrap and config/bootstrap_debootstrap to read the options it will use. Generally, these files contain variables with values assigned, one variable per line. Some programs in live-helper use pairs of values or slightly more complicated variable assignments.

live-helper respects environment variables which are present in the context of the shell it is running. If variables can be read from config files, then they override environment variables, and if command line options are used, they override values from config files. If no value for a given variable can be found (and is thus unset), live-helper will automatically set it to a default value.

All config files are shell scripts which are sourced by a live-helper program. That means they have to follow the normal shell syntax. You can also put comments in these files; lines beginning with "#" are ignored.

In some rare cases, you may want to have different versions of these files for different architectures or distributions. If files named config/stage.arch or config/stage_helper.arch, and config/stage.dist or config/stage_helper.dist exist (where "arch" is the same as the output of dpkg --print-architecture and "dist" is the same as the codename of the target distribution), then they will be used in preference to the other, more general files.

Please see Chapter 2, Installation for information on how to install live-helper.

The remainder of this section discusses the three most important helpers:

lh_config

Responsible for initialising a Live system configuration directory. See Section 4.1.1, “The lh_config helper” for more information.

lh_build

Responsible for starting a Live system build. See Section 4.1.2, “The lh_build helper” for more information.

lh_clean

Responsible for removing parts of a Live system build. Section 4.1.3, “The lh_clean helper” for more information.

4.1.1. The lh_config helper

As discussed in Section 4.1, “live-helper”, the scripts that make up live-helper source their configuration from a single directory named config/. As constructing this directory by hand would be time-consuming and error-prone, the lh_config helper can be used to create skeleton configuration folders.

Issuing lh_config without any arguments creates a config subdirectory which it populates with some default settings:

$ lh_config
$ ls -l
total 4.1k
drwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config
$ ls -l config/
total 91k
-rw-r--r-- 1 user group 4.0k 2008-05-09 21:37 binary
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_debian-installer
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_grub
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-debs
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-hooks
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-includes
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-packageslists
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-udebs
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_rootfs
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_syslinux
-rw-r--r-- 1 user group 1.7k 2008-05-09 21:37 bootstrap
-rw-r--r-- 1 user group 1.5k 2008-05-09 21:37 chroot
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_apt
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-hooks
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-includes
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packages
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packageslists
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_sources
-rw-r--r-- 1 user group 2.9k 2008-05-09 21:37 common
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 includes
-rw-r--r-- 1 user group  212 2008-05-09 21:37 source
drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 templates

Using lh_config without any arguments would be suitable for users who are either happy editing the generated files, or are simply happy with the defaults it creates.

You can ask lh_config to generate config/ directory "preseeded" with various options. This might be suitable if you do not require the default settings but do not need to change a large number of options. For example:

$ lh_config -p gnome

will build a config/ directory configured to include the 'gnome' package list. It is possible to specify many options:

$ lh_config --apt aptitude --binary-images net --hostname live-machine --username live-user ...

A full list of options is available FIXME. Most options have a parallel with an "LH_" prefixed variable.

4.1.2. The lh_build helper

FIXME

4.1.3. The lh_clean helper

It is the job of the lh_clean helper to remove various parts of a Live helper build.