1
<?xml version="1.0" encoding="utf-8"?>
3
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
4
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
5
<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
8
<chapter id="overview">
9
<title>Overview of tools</title>
12
This chapter contains an overview of the two main tools used in building
16
<section id="live-helper">
17
<title>&live-helper;</title>
20
&live-helper; is a collection of scripts to build Debian Live systems.
21
These scripts are also referred to as "helpers".
25
The idea behind &live-helper; is to be a framework that uses a
26
configuration directory to completely automate and customize all aspects
27
of building a Live image.
31
Many concepts are similar to those in the <command>debhelper</command>
32
Debian package tools written by Joey Hess:
39
The scripts have a central location for configuring their operation.
43
In <command>debhelper</command>, this is the <filename class="directory"
44
>debian</filename> subdirectory of a package tree. For example,
45
<command>dh_install</command> will look for a file called
46
<filename>debian/<packagename>.install</filename> to determine
47
which files should exist in a particular binary package. In much the
48
same way, &live-helper; stores its configuration entirely under a
49
<filename class="directory">config/</filename> subdirectory.
55
The scripts are independent - that is to say, it is always safe to run
63
Unlike <command>debhelper</command>, &live-helper; contains a tool to
64
generate a skeleton configuration directory,
65
<filename>lh config</filename>. This could be considered to be similar
66
to tools such as <command>dh-make</command>. For more information about
67
<filename>lh config</filename>, please see <xref linkend="lh-config" />.
71
Besides the common <filename>config/common</filename>, which is used by
72
all &live-helper; helper commands, some additional files can be used to
73
configure the behavior of specific helper commands. These files are
74
typically named <command>config/helper</command> or
75
<command>config/stage</command> (where "stage", of course, is replaced
76
with the name of the stage that they belong to, and "helper" with the
81
For example, the <command>lh bootstrap debootstrap</command> helper
82
command uses files named <filename>config/bootstrap</filename> and
83
<filename>config/bootstrap_debootstrap</filename> to read the options it
84
will use. Generally, these files contain variables with values assigned,
85
one variable per line. Some programs in &live-helper; use pairs of
86
values or slightly more complicated variable assignments.
90
&live-helper; respects environment variables which are present in the
91
context of the shell it is running. If variables can be read from config
92
files, then they override environment variables, and if command line
93
options are used, they override values from config files. If no value
94
for a given variable can be found (and is thus unset), &live-helper;
95
will automatically set it to a default value.
99
All config files are shell scripts which are sourced by a &live-helper;
100
program. That means they have to follow the normal shell syntax. You can
101
also put comments in these files; lines beginning with "#" are ignored.
105
In some rare cases you may want to have different versions of these
106
files for different architectures or distributions. If files named
107
<command>config/stage.arch</command> or
108
<command>config/stage_helper.arch</command>, and
109
<command>config/stage.dist</command> or
110
<command>config/stage_helper.dist</command> exist (where "arch" is the
111
same as the output of <command>dpkg --print-architecture</command> and
112
"dist" is the same as the codename of the target distribution), then
113
they will be used in preference to the other, more general files.
117
Please see <xref linkend="installation" /> for information on how to
118
install &live-helper;.
122
The remainder of this section discusses the three most important
129
<term><filename>lh config</filename></term>
133
Responsible for initialising a Live system configuration directory. See
134
<xref linkend="lh-config" /> for more information.
140
<term><filename>lh build</filename></term>
144
Responsible for starting a Live system build. See <xref
145
linkend="lh-build" /> for more information.
151
<term><filename>lh clean</filename></term>
155
Responsible for removing parts of a Live system build. See <xref
156
linkend="lh-clean" /> for more information.
163
<section id="lh-config">
164
<title>The <filename>lh config</filename> helper</title>
167
As discussed in <xref linkend="live-helper" />, the scripts that make up
168
&live-helper; source their configuration from a single directory named
169
<command>config/</command>. As constructing this directory by hand would
170
be time-consuming and error-prone, the <filename>lh config</filename>
171
helper can be used to create skeleton configuration folders.
175
Issuing <filename>lh config</filename> without any arguments creates a
176
<command>config</command> subdirectory which it populates with some
184
drwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config
187
-rw-r--r-- 1 user group 4175 2010-04-11 12:16 binary
188
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer
189
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer-includes
190
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_grub
191
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-debs
192
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-hooks
193
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-includes
194
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-packageslists
195
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-udebs
196
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_rootfs
197
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_syslinux
198
-rw-r--r-- 1 user group 2205 2010-04-11 12:16 bootstrap
199
-rw-r--r-- 1 user group 1599 2010-04-11 12:16 chroot
200
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_apt
201
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-hooks
202
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-includes
203
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packages
204
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packageslists
205
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-patches
206
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-preseed
207
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_sources
208
-rw-r--r-- 1 user group 2938 2010-04-11 12:16 common
209
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 includes
210
-rw-r--r-- 1 user group 206 2010-04-11 12:16 source
211
drwxr-xr-x 2 user group 4096 2010-04-11 12:16 templates
216
Using <filename>lh config</filename> without any arguments would be
217
suitable for users who are either happy editing the generated files, or
218
are simply happy with the defaults it creates.
222
You can ask <filename>lh config</filename> to generate a <filename
223
class="directory">config/</filename> directory "preseeded" with various
224
options. This might be suitable if you do not require the default
225
settings but do not need to change a large number of options. For
230
<screen>$ lh config -p gnome</screen>
234
will build a <filename class="directory">config/</filename> directory
235
configured to include the '<command>gnome</command>' package list. It is
236
possible to specify many options:
240
<screen>$ lh config --apt aptitude --binary-images net --hostname live-machine --username live-user ...</screen>
244
A full list of options is available in the <command>lh_config</command>
245
man page. Most options have a parallel with an "<command>LH_</command>"
251
<section id="lh-build">
252
<title>The <filename>lh build</filename> helper</title>
255
The <filename>lh build</filename> helper reads in your configuration
256
from the <filename class="directory">config/</filename> directory. It
257
then runs the lower lower level commands needed to build your Live
263
<section id="lh-clean">
264
<title>The <filename>lh clean</filename> helper</title>
267
It is the job of the <filename>lh clean</filename> helper to remove
268
various parts of a Live helper build so subsequent builds can start
276
<section id="live-initramfs">
277
<title>The &live-initramfs; package</title>
280
&live-initramfs; is a collection of scripts providing hooks for the
281
<command>initramfs-tools</command>, used to generate an initramfs
282
capable of booting live systems, such as those created by
283
<command>live-helper</command>. This includes the Debian Live isos,
284
netboot tarballs, and usb stick images.
288
At boot time it will look for read-only media containing a "/live"
289
directory where a root filesystem (often a compressed filesystem image
290
like squashfs) is stored. If found, it will create a writable
291
environment, using aufs or unionfs, for Debian like systems to boot
296
&live-initramfs; is a fork of
297
<ulink url="http://packages.ubuntu.com/casper">casper</ulink>.
301
More information on initial ramfs in Debian can be found in the
302
<ulink url="http://kernel-handbook.alioth.debian.org/">
303
Debian Linux Kernel Handbook</ulink>'s chapter on
304
<ulink url="http://kernel-handbook.alioth.debian.org/ch-initramfs.html">
added
removed
manual/en/overview.xml
