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 to those in the debhelper Debian package tools written by Joey Hess:
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 a 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.
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/helper 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. See Section 4.1.3, “The lh clean
helper” for more information.
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 104 -rw-r--r-- 1 user group 4175 2010-04-11 12:16 binary drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_grub drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-debs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-udebs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_rootfs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_syslinux -rw-r--r-- 1 user group 2205 2010-04-11 12:16 bootstrap -rw-r--r-- 1 user group 1599 2010-04-11 12:16 chroot drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_apt drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packages drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-patches drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-preseed drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_sources -rw-r--r-- 1 user group 2938 2010-04-11 12:16 common drwxr-xr-x 2 user group 4096 2010-04-11 12:16 includes -rw-r--r-- 1 user group 206 2010-04-11 12:16 source drwxr-xr-x 2 user group 4096 2010-04-11 12:16 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 a 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 in the lh_config man page. Most options have a parallel with an "LH_" prefixed variable.
The lh build
helper reads in your configuration from
the config/
directory. It then runs
the lower lower level commands needed to build your Live system.