From 1726b902a24aa88c767f072b129e855fdd52a9a8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Tue, 13 Nov 2007 20:43:25 +0100 Subject: Rewritten live-helper manpage. --- manpages/live-helper.en.7 | 193 ++++++++++++++++++++++++---------------------- 1 file changed, 100 insertions(+), 93 deletions(-) diff --git a/manpages/live-helper.en.7 b/manpages/live-helper.en.7 index 113509c..67dcd32 100644 --- a/manpages/live-helper.en.7 +++ b/manpages/live-helper.en.7 @@ -1,161 +1,164 @@ .TH LIVE\-HELPER 7 "2007\-11\-19" "1.0~a37" "live\-helper" .SH NAME -live\-helper \- Debian Live helper programs +live\-helper \- the Debian Live tool suite .SH SYNOPSIS -.B lh_* [\fIlive\-helper\ options\fR\|] +\fBdh_\fR\fI*\fR [\fB\-h|\-\-help\fR] [\fB\-u|\-\-usage\fR] [\fB\-v|\-\-version\fR] .SH DESCRIPTION -Live\-helper is a collection of programs that can be used to build Debian Live system images. The philosophy behind live\-helper is to provide a collection of small, simple, and easily understood tools that can be used in your own program to automate building of a Live system. -.PP -A typical program that uses live\-helper will call several live\-helper commands in sequence. Live\-helper commands are all named with a "lh_" prefix. - -.\" .SH CONFIGURATION FILE -.\" live\-helper reads debian\-live/config/live\-helper if available. See ENVIRONMENT for the correct environment variables to use. - -.\" .SH ENVIRONMENT -.\" Every live\-helper command respects the following environment variables if available. -.\" .IP "\fI$LH_DEBUG\fR" 4 -.\" enables debug (Default: false) -.\" .IP "\fI$LH_QUIET\fR" 4 -.\" be quiet (Default: false) -.\" .IP "\fI$LH_VERBOSE\fR" 4 -.\" be verbose (Default: false) +live\-helper is used to help you build a Debian Live system. The philosophy +behind live\-helper is to provide a collection of small, simple, and easily +understood tools that are used on a config directory to automate all aspects of +building a Debian Live image. .SH LIVE\-HELPER COMMANDS -Here is the complete list of available live\-helper commands. See their man pages for additional documentation. +Here is the complete list of available live\-helper commands. See their man +pages for additional documentation. +.IP "\fIlh\fR(1)" 4 +generic live\-helper wrapper .IP "\fIlh_binary\fR(1)" 4 -meta\-helper for lh_binary_*. +meta\-helper for lh_binary_* .IP "\fIlh_binary_chroot\fR(1)" 4 -copies chroot into chroot. -.IP "\fIlh_binary_debian\-installer\fR(1)" 4 -copies debian-installer into the binary image. +.IP "\fIlh_binary_debian-installer\fR(1)" 4 +.IP "\fIlh_binary_disk\fR(1)" 4 .IP "\fIlh_binary_encryption\fR(1)" 4 -encrypts the root filesystem. .IP "\fIlh_binary_grub\fR(1)" 4 -copies grub into the binary image. -.IP "\fIlh_binary_tar\fR(1)" 4 -creates the harddisk binary tarball. .IP "\fIlh_binary_includes\fR(1)" 4 -copies files into the binary image. .IP "\fIlh_binary_iso\fR(1)" 4 -creates the CD/DVD binary image. .IP "\fIlh_binary_linux-image\fR(1)" 4 -copies linux\-image into the binary image. +.IP "\fIlh_binary_local-hooks\fR(1)" 4 .IP "\fIlh_binary_local-includes\fR(1)" 4 -copies local files into the binary image. +.IP "\fIlh_binary_local-packageslists\fR(1)" 4 .IP "\fIlh_binary_manifest\fR(1)" 4 -creates the package list of the root filesystem. .IP "\fIlh_binary_md5sum\fR(1)" 4 -creates md5sum.txt in the binary image. .IP "\fIlh_binary_memtest\fR(1)" 4 -copies a memtest into the binary image. .IP "\fIlh_binary_net\fR(1)" 4 -creates the netboot binary tarball. .IP "\fIlh_binary_rootfs\fR(1)" 4 -creates the root filesystem. .IP "\fIlh_binary_syslinux\fR(1)" 4 -copies syslinux into the binary image. +.IP "\fIlh_binary_tar\fR(1)" 4 .IP "\fIlh_binary_usb-hdd\fR(1)" 4 -creates the USB-hdd binary image. .IP "\fIlh_binary_yaboot\fR(1)" 4 -copies yaboot into the binary image. .IP "\fIlh_bootstrap\fR(1)" 4 -meta\-helper for lh_bootstrap_*. +meta\-helper for lh_bootstrap_* +.IP "\fIlh_bootstrap_cache\fR(1)" 4 .IP "\fIlh_bootstrap_cdebootstrap\fR(1)" 4 -bootstraps system with cdebootstrap. +.IP "\fIlh_bootstrap_copy\fR(1)" 4 .IP "\fIlh_bootstrap_debootstrap\fR(1)" 4 -bootstraps system with debootstrap. .IP "\fIlh_build\fR(1)" 4 -meta\-helper for lh_bootstrap, lh_chroot, lh_binary and lh_source. +meta\-helper for lh_bootstrap, lh_chroot, lh_binary, and lh_source .IP "\fIlh_chroot\fR(1)" 4 -meta\-helper for lh_chroot_*. +meta\-helper for lh_chroot_* .IP "\fIlh_chroot_apt\fR(1)" 4 -configures /etc/apt/apt.conf in chroot. +.IP "\fIlh_chroot_cache\fR(1)" 4 .IP "\fIlh_chroot_debianchroot\fR(1)" 4 -configures /etc/debian_chroot in chroot. +.IP "\fIlh_chroot_devpts\fR(1)" 4 +.IP "\fIlh_chroot_dpkg\fR(1)" 4 .IP "\fIlh_chroot_hacks\fR(1)" 4 -does evil (temporary) hacks in the chroot. .IP "\fIlh_chroot_hooks\fR(1)" 4 -executes additional commands in the chroot. +.IP "\fIlh_chroot_hostname\fR(1)" 4 .IP "\fIlh_chroot_hosts\fR(1)" 4 -configures /etc/hosts in the chroot. .IP "\fIlh_chroot_interactive\fR(1)" 4 -makes build interactive. .IP "\fIlh_chroot_linux-image\fR(1)" 4 -configures /etc/kernel\-img.conf in the chroot. .IP "\fIlh_chroot_local-hooks\fR(1)" 4 -executes additional local commands in the chroot. .IP "\fIlh_chroot_local-includes\fR(1)" 4 -copies local files into the binary image. -.IP "\fIlh_chroot_localization\fR(1)" 4 -installs localization packages in the chroot. .IP "\fIlh_chroot_local-packages\fR(1)" 4 -installs local packages in the chroot. .IP "\fIlh_chroot_local-packageslists\fR(1)" 4 -installs local packages lists in the chroot. +.IP "\fIlh_chroot_local-preseed\fR(1)" 4 +.IP "\fIlh_chroot_localization\fR(1)" 4 .IP "\fIlh_chroot_packages\fR(1)" 4 -installs packages in the chroot. .IP "\fIlh_chroot_packageslists\fR(1)" 4 -installs packages lists in the chroot. +.IP "\fIlh_chroot_preseed\fR(1)" 4 .IP "\fIlh_chroot_proc\fR(1)" 4 -mounts /proc in the chroot. .IP "\fIlh_chroot_resolv\fR(1)" 4 -configures /etc/resolv.conf in the chroot. .IP "\fIlh_chroot_sources\fR(1)" 4 -configures /etc/apt/sources.list in the chroot. .IP "\fIlh_chroot_symlinks\fR(1)" 4 -converts symlinks in the chroot. .IP "\fIlh_chroot_sysfs\fR(1)" 4 -mounts /sys in the chroot. +.IP "\fIlh_chroot_sysv-rc\fR(1)" 4 .IP "\fIlh_chroot_sysvinit\fR(1)" 4 -minimizes daemon startup in the chroot. -.IP "\fIlh_chroot_sysvrc\fR(1)" 4 -installs policy\-id hack in the chroot. .IP "\fIlh_chroot_tasks\fR(1)" 4 -installs packages tasks in the chroot. .IP "\fIlh_clean\fR(1)" 4 -cleans up build directory. +clean up build directories .IP "\fIlh_config\fR(1)" 4 -creates sample configuration. +create configuration directory .IP "\fIlh_losetup\fR(1)" 4 -manages loop device handling +wrapper for losetup .IP "\fIlh_source\fR(1)" 4 -meta\-helper for lh_source_*. -.IP "\fIlh_source_debian-live\fR(1)" 4 -copies config into source directory. +meta\-helper for lh_source_* .IP "\fIlh_source_debian\fR(1)" 4 -downloads source packages. +.IP "\fIlh_source_debian-live\fR(1)" 4 +.IP "\fIlh_source_disk\fR(1)" 4 .IP "\fIlh_source_iso\fR(1)" 4 -creates CD/DVD source image. +.IP "\fIlh_source_md5sum\fR(1)" 4 .IP "\fIlh_source_net\fR(1)" 4 -creates netboot source tarball. +.IP "\fIlh_source_tar\fR(1)" 4 .IP "\fIlh_source_usb-hdd\fR(1)" 4 -creates USB-hdd source image. .IP "\fIlh_testroot\fR(1)" 4 -checks for root privileges. +ensure that a system is built as root +.PP +If a program's name starts with "lh_", and the program is not on the above list, +then it is not part of the live\-helper package, but it should still work like +the other programs described on this page. + +.SH LIVE\-HELPER CONFIG FILES +Many live\-helper commands make use of files in the \fIconfig/\fR directory to +control what they do. Besides the common \fIconfig/common\fR, which is used by +all live\-helper commands, some additional files can be used to configure the +behavior of specific live\-helper commands. These files are typically named +config/stage or config/stage_helper (where "stage" of course, is replaced with +the name of the stage that they belong to, and "helper" with the name of the +helper). +.PP +For example, dh_bootstrap_debootstrap uses files named config/bootstrap and +config/bootstrap_debootstrap to read the options it will use. See the man pages +of individual commands for details about the names and formats of the files they +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 assignements. +.PP +Note that live\-helper will 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 thus is unset, live\-helper will automatically set it to the +default value. +.PP +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 +exists, 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 other, more general files. +.PP +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. -.SH LIVE\-HELPER OPTIONS +.SH SHARED LIVE\-HELPER OPTIONS The following command line options are supported by all live\-helper programs. +.IP "\fB-h, --help\fR" 4 +display help and exit. +.IP "\fB-u, --usage\fR" 4 +show usage and exit. +.IP "\fB-v, --version\fR" 4 +output version information and exit. + +.SH COMMON LIVE\-HELPER OPTIONS +The following command line options are supported by some live\-helper programs. +See the man page of each program for a complete explanation of what each option +does. .IP "\fB\-\-breakpoints\fR" 4 -run with breakpoints +run with breakpoints. .IP "\fB\-\-conffile\fR" 4 -use custom configuration file +use custom configuration file. .IP "\fB\-\-debug\fR" 4 -show debug information +show debug information. .IP "\fB\-\-force\fR" 4 force helper execution, even if stage file exists. -.IP "\fB\-h, \-\-help\fR" 4 -display help and exit .IP "\fB\-\-quiet\fR" 4 -be quiet -.IP "\fB\-u, \-\-usage\fR" 4 -show usage and exit +be quiet. .IP "\fB\-\-verbose\fR" 4 -be verbose -.IP "\fB\-v, \-\-version\fR" 4 -output version information and exit +be verbose. .SH SEE ALSO \fIlive\-initramfs\fR(7) @@ -165,10 +168,14 @@ output version information and exit \fIlive\-webhelper\fR(7) .SH BUGS -Report bugs against live\-helper <\fIhttp://packages.qa.debian.org/live\-helper\fR>. +Report bugs against live\-helper +<\fIhttp://packages.qa.debian.org/live\-helper\fR>. .SH HOMEPAGE -More information about the Debian Live project can be found at <\fIhttp://debian\-live.alioth.debian.org/\fR> and <\fIhttp://wiki.debian.org/DebianLive/\fR>. +More information about the Debian Live project can be found at +<\fIhttp://debian\-live.alioth.debian.org/\fR> and +<\fIhttp://wiki.debian.org/DebianLive/\fR>. .SH AUTHOR -live\-helper was written by Daniel Baumann <\fIdaniel@debian.org\fR> for the Debian project. +live\-helper was written by Daniel Baumann <\fIdaniel@debian.org\fR> for the +Debian project. -- cgit v1.0