[SCM] live-manual branch, debian-next, updated. debian/3.0_a14-1-28-g654e492

Mon Aug 6 15:33:01 UTC 2012

The following commit has been merged in the debian-next branch:
commit 654e492fe3ed1394deeff8c5a76ab51bc9bda937
Author: Ben Armstrong <synrg at debian.org>
Date:   Mon Aug 6 12:33:57 2012 -0300

    Rewriting 'Managing a configuration' for greater clarity and introducing --config option.

diff --git a/manual/en/user_managing_a_configuration.ssi b/manual/en/user_managing_a_configuration.ssi
index 3a92e1d..4de9985 100644
--- a/manual/en/user_managing_a_configuration.ssi
+++ b/manual/en/user_managing_a_configuration.ssi
@@ -6,70 +6,73 @@ This chapter explains how to manage a live configuration from initial creation,
 
 2~ Use auto to manage configuration changes
 
-Live configurations rarely are perfect on the first try. You'll likely need to make a series of revisions until you are satisfied. However, inconsistencies can creep into your configuration from one revision to the next if you aren't careful. The main problem is, once a variable is given a default value, that value will not be recomputed from other variables that may change in later revisions.
+Live configurations rarely are perfect on the first try. It may be fine to pass #{lb config}# options from the command-line to perform a single build, but it is more typical to revise those options and build again until you are satisfied. To support these changes, you will need auto scripts which ensure your configuration is kept in a consistent state.
 
-For example, when the distribution is first set, many 'dependent' variables are given default values that suit that distribution. However, if you later decide to change the distribution, those dependent variables continue to retain old values that are no longer appropriate.
+3~ Why you need auto
 
-A second, related problem is that if you run #{lb config}# and then upgrade to a new version of live-build that has changed one of the variable names, you will discover this only by manual review of the variables in your #{config/*}# files, which you will then need to use to set the appropriate option again.
+The #{lb config}# command stores the options you pass to it in #{config/*}# files along with many other options set to default values. If you run #{lb config}# again, it will not reset any option that was defaulted based on your initial options. So, for example, if you run #{lb config}# again with a new value for #{--distribution}#, any dependent options that were defaulted for the old distribution may no longer work with the new. Nor are these files intended to be read or edited. They store values for over a hundred options, so nobody, let alone yourself, will be able to see in these which options you actually specified. And finally, if you run #{lb config}#, then upgrade live-build and it happens to rename an option, #{config/*}# would still contain variables named after the old option that are no longer valid.
 
-All of this would be a terrible nuisance if it weren't for auto/* scripts, simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# commands that are designed to help you manage your configuration. Simply create an auto/config script containing #{lb config}# command with all desired options, and an auto/clean that removes the files containing configuration variable values, and each time you run #{lb config}# and #{lb clean}#, these files will be executed. This will ensure that your configuration is kept internally consistent from one revision to the next and from one live-build release to the next (Although you will still have to take care and read the documentation when you upgrade live-build and make adjustments as needed).
+For all these reasons, #{auto/*}# scripts will make your life easier. They are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# commands that are designed to help you manage your configuration. The #{auto/config}# script stores your #{lb config}# command with all desired options, the #{auto/clean}# script removes the files containing configuration variable values, and the #{auto/build}# script keeps a #{build.log}# of each build. Each of these scripts is run automatically every time you run the corresponding #{lb}# command. By using these scripts, your configuration is easier to read and is kept internally consistent from one revision to the next. Also, it will be much easier for you identify and fix options which need to change when you upgrade live-build after reading the updated documentation.
 
-2~ Example auto scripts
+3~ Use example auto scripts
 
-Use auto script examples such as the following as the starting point for your new live-build configuration. Take note that when you call the #{lb}# command that the auto script wraps, you must specify #{noauto}# as its parameter to ensure that the auto script isn't called again, recursively. Also, don't forget to ensure the scripts are executable (e.g. #{chmod 755 auto/*}#).
+For your convenience, live-build comes with example auto shell scripts to copy and edit. Start a new, default configuration, then copy the examples into it:
 
-#{auto/config}#
+code{
+
+ $ mkdir mylive && cd mylive && lb config
+ $ cp /usr/share/doc/live-build/examples/auto/* auto/
+
+}code
+
+Edit #{auto/config}#, adding any options as you see fit. For instance:
 
 code{
 
  #!/bin/sh
  lb config noauto \
+     --architectures i386 \
+     --linux-flavours 686-pae \
+     --binary-images hdd \
+     --mirror-bootstrap http://ftp.es.debian.org/debian/ \
+     --mirror-binary http://ftp.es.debian.org/debian/ \
      "${@}"
 
 }code
 
-#{auto/clean}#
+Now, each time you use #{lb config}#, #{auto/config}# will reset the configuration based on these options. When you want to make changes to them, edit the options in this file instead of passing them to #{lb config}#. When you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files along with any other build products. And finally, when you use #{lb build}#, a log of the build will be written by #{auto/build}# in #{build.log}#.
 
-code{
+Note: A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next.
 
- #!/bin/sh
- lb clean noauto "${@}"
- rm -f config/binary config/bootstrap \
-     config/chroot config/common config/source
- rm -f build.log
+2~ Clone a configuration published via Git
 
-}code
+Use the #{lb config --config}# option to clone a Git repository that contains a Debian Live configuration. If you would like to base your configuration on one maintained by the Debian Live project, look at http://live.debian.net/gitweb for the repositories prefixed with #{config-}#.
 
-#{auto/build}#
+For example, to build a rescue image, use the #{config-rescue}# repository as follows:
 
 code{
 
- #!/bin/sh
- lb build noauto "${@}" 2>&1 | tee build.log
+ $ mkdir live-rescue && cd live-rescue
+ $ lb config git://live.debian.net/git/config-rescue.git
 
 }code
 
-We now ship example auto scripts with live-build based on the examples above. You may copy those as your starting point.
+Edit #{auto/config}# and any other things you need in the #{config}# tree to suit your needs.
+
+You may optionally define a shortcut in your Git configuration by adding the following to your #{${HOME}/.gitconfig}#:
 
 code{
 
- $ cp /usr/share/doc/live-build/examples/auto/* auto/
+ [url "git://live.debian.net/git/"]
+     insteadOf = ldn:
 
 }code
 
-Edit #{auto/config}#, adding any options as you see fit. For instance:
+This enables you to use #{ldn:}# anywhere you need to specify the address of a #{live.debian.net}# git repository. If you also drop the optional #{.git}# suffix, starting a new image using this configuration is as easy as:
 
 code{
 
- #!/bin/sh
- lb config noauto \
-	--architectures i386 \
-	--linux-flavours 686-pae \
-	--binary-images hdd \
-	--mirror-bootstrap http://ftp.es.debian.org/debian/  \
-	--mirror-binary http://ftp.es.debian.org/debian/ \
-	"${@}"
+ $ lb config ldn:config-rescue
 
 }code
 
-And any other additional options in continuation lines that follow.

-- 
live-manual

