[SCM] live-manual branch, master, updated. debian/20100301-1-22-gd57c1ff
Eric Dantan Rzewnicki
eric at zhevny.com
Sun Apr 11 18:50:44 UTC 2010
The following commit has been merged in the master branch:
commit d57c1ffd77f0e3587ab034ab0f0bb4c1177e5e69
Author: Eric Dantan Rzewnicki <eric at zhevny.com>
Date: Sun Apr 11 14:45:27 2010 -0400
Reformat and rewrap.
diff --git a/xml/chapters/customization/packages.xml b/xml/chapters/customization/packages.xml
index 027f5a8..35ecb21 100644
--- a/xml/chapters/customization/packages.xml
+++ b/xml/chapters/customization/packages.xml
@@ -1,33 +1,49 @@
<?xml version="1.0" encoding="utf-8"?>
+
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
- <!ENTITY % commondata SYSTEM "../../entities/common.ent" > %commondata;
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+ <!ENTITY % commondata SYSTEM "../../entities/common.ent" > %commondata;
]>
+
<sect1 id="packages">
<title>Customising package installation</title>
<para>
- This chapter discusses the customisation of package installation. This involves:
+ This chapter discusses the customisation of package installation. This
+ involves:
</para>
<orderedlist>
-<listitem><para>Selecting additional packages to be installed</para></listitem>
-<listitem><para>Installing modified packages</para></listitem>
+
+<listitem>
+<para>
+ Selecting additional packages to be installed
+</para>
+</listitem>
+
+<listitem>
+<para>
+ Installing modified packages
+</para>
+</listitem>
+
</orderedlist>
<sect2 id="package-sources">
<title>Package sources</title>
+
<para>
- FIXME
+ FIXME
</para>
-<para>
+
<variablelist>
-<varlistentry><term>Debian repositories</term>
-<listitem>
+<varlistentry>
+<term>Debian repositories</term>
+<listitem>
<para>
-To set a local mirror (used to ''build'' the live-cd)
+ To set a local mirror (used to ''build'' the live-cd)
</para>
<screen>
@@ -35,7 +51,7 @@ $ lh config --mirror-bootstrap "http://local.intra.net/debian/" --mirror-chroot
</screen>
<para>
-The generic mirror is added to the live-system's /etc/apt/sources.list.
+ The generic mirror is added to the live-system's /etc/apt/sources.list.
</para>
<screen>
@@ -43,11 +59,12 @@ $ lh config --mirror-binary "http://ftp.debian.org/debian/"
</screen>
<para>
-Note: It is ''not'' used for building the live-cd but to install new software while using the live-cd.
+ Note: It is ''not'' used for building the live-cd but to install new
+ software while using the live-cd.
</para>
<para>
-It can be disabled by setting binary indices parameter to disabled
+ It can be disabled by setting binary indices parameter to disabled
</para>
<screen>
@@ -55,26 +72,32 @@ $ lh config --binary-indices disabled
</screen>
<para>
-Note: the same applies for mirror chroot security and mirror binary security
+ Note: the same applies for mirror chroot security and mirror binary security
</para>
<screen>
$ lh config --mirror-chroot-security {URL}
$ lh config --mirror-binary-security {URL}
</screen>
+
</listitem>
</varlistentry>
-<varlistentry><term>Own repository</term>
-<listitem>
+<varlistentry>
+<term>Own repository</term>
+<listitem>
<para>
-To add more repositories (e.g. backports, experimental packages, etc...),
-create <filename>config/chroot_sources/your-cdd-repo.{chroot,binary}</filename> file.
+ To add more repositories (e.g. backports, experimental packages,
+ etc...), create
+ <filename>config/chroot_sources/your-cdd-repo.{chroot,binary}</filename>
+ file.
</para>
<para>
-e.g. <filename>config/chroot_sources/live.chroot</filename> allows you to install packages from the debian live snapshot repository at live-cd build time (you have to add the packages in your package list):
+ e.g. <filename>config/chroot_sources/live.chroot</filename> allows you
+ to install packages from the debian live snapshot repository at live-cd
+ build time (you have to add the packages in your package list):
</para>
<screen>
@@ -82,54 +105,71 @@ deb http://live.debian.net/ sid-snapshots main contrib non-free
</screen>
<para>
-If you add the line to <filename>config/chroot_sources/live.binary</filename> the repository will be added to your live-system's <filename>/etc/apt/sources.list</filename>.
+ If you add the line to
+ <filename>config/chroot_sources/live.binary</filename> the repository
+ will be added to your live-system's
+ <filename>/etc/apt/sources.list</filename>.
</para>
<para>
-If such files exist, they will be picked up automatically.
+ If such files exist, they will be picked up automatically.
</para>
<para>
-You can also put the gpg-key used to sign the repository into config/chroot_sources/foo.{binary,chroot}.gpg
+ You can also put the gpg-key used to sign the repository into
+ config/chroot_sources/foo.{binary,chroot}.gpg
</para>
</listitem>
</varlistentry>
</variablelist>
-</para>
</sect2>
<sect2 id="package-installation">
<title>Package installation</title>
+
<para>
- You can elect to use either <command>apt</command> or <command>aptitude</command> when installing packages. Which utility is used is governed by the <command>LH_APT</command> variable in <filename>config/chroot</filename> or by the <command>--apt</command> argument to <filename>lh config</filename>:
+ You can elect to use either <command>apt</command> or
+ <command>aptitude</command> when installing packages. Which utility is
+ used is governed by the <command>LH_APT</command> variable in
+ <filename>config/chroot</filename> or by the <command>--apt</command>
+ argument to <filename>lh config</filename>:
</para>
<variablelist>
-<varlistentry><term><command>apt</command></term>
+<varlistentry>
+<term><command>apt</command></term>
+
<listitem>
<para>
- Specifying a missing package causes package installation to fail, which may not be the desired behaviour.
+ Specifying a missing package causes package installation to fail, which
+ may not be the desired behaviour.
</para>
+
<para>
- This is the default setting for building images for Lenny or later.
+ This is the default setting for building images for Lenny or later.
</para>
</listitem>
</varlistentry>
-<varlistentry><term><command>aptitude</command></term>
+<varlistentry>
+<term><command>aptitude</command></term>
+
<listitem>
<para>
- Specifying a missing package causes package installation to succeed, which may not be the desired behaviour.
+ Specifying a missing package causes package installation to succeed,
+ which may not be the desired behaviour.
</para>
+
<para>
- This is the default setting for building images for Etch.
+ This is the default setting for building images for Etch.
</para>
</listitem>
</varlistentry>
+
</variablelist>
</sect2>
@@ -138,7 +178,8 @@ You can also put the gpg-key used to sign the repository into config/chroot_sour
<title>Installing additional packages</title>
<para>
- &live-helper; has a number of mechanisms for indicating that additional packages should be installed, including:
+ &live-helper; has a number of mechanisms for indicating that additional
+ packages should be installed, including:
</para>
<orderedlist>
@@ -150,8 +191,11 @@ You can also put the gpg-key used to sign the repository into config/chroot_sour
<sect3 id="lh-packages">
<title>The <command>LH_PACKAGES</command> variable</title>
+
<para>
- To install additional packages, simply add them to the <command>LH_PACKAGES</command> variable in <filename>config/chroot</filename>. For example:
+ To install additional packages, simply add them to the
+ <command>LH_PACKAGES</command> variable in
+ <filename>config/chroot</filename>. For example:
</para>
<screen>
@@ -159,54 +203,85 @@ LH_PACKAGES="package1 package2 package3 ... "
</screen>
<para>
- You can also specify initial values on the command line:
+ You can also specify initial values on the command line:
</para>
<screen>
$ lh config --packages "package1 package2 package3"
</screen>
-<para>The behaviour of &live-helper; when specifying a package that does not exist is determined by your choice of APT utility. See <xref linkend="package-installation"/> for more details.</para>
+<para>
+ The behaviour of &live-helper; when specifying a package that does not
+ exist is determined by your choice of APT utility. See <xref
+ linkend="package-installation"/> for more details.
+</para>
<para>
- If you need to specify a large number of packages to be installed or you need flexibility regarding which packages to install, you should probably be using package lists. See <xref linkend="package-lists"/> for more information.
+ If you need to specify a large number of packages to be installed or
+ you need flexibility regarding which packages to install, you should
+ probably be using package lists. See <xref linkend="package-lists"/>
+ for more information.
</para>
+
</sect3>
<sect3 id="package-lists">
<title>Package lists</title>
+
<para>
- Package lists are a powerful way of expressing which packages should be installed. &live-helper; ships with a number of predefined package lists which provide sensible default package selections for the GNOME and KDE desktop environments, as well as standard systems.
+ Package lists are a powerful way of expressing which packages should be
+ installed. &live-helper; ships with a number of predefined package
+ lists which provide sensible default package selections for the GNOME
+ and KDE desktop environments, as well as standard systems.
</para>
-<para>To specify a package list, add the name of the list to the <command>LH_PACKAGES_LISTS</command> variable in <filename>config/chroot</filename>. For example:</para>
+<para>
+ To specify a package list, add the name of the list to the
+ <command>LH_PACKAGES_LISTS</command> variable in
+ <filename>config/chroot</filename>. For example:
+</para>
<screen>
LH_PACKAGES_LISTS="gnome"
</screen>
-<para>Packages lists that are distributed with &live-helper; reside in view in the <command>/usr/share/live-helper/lists</command> directory.</para>
+<para>
+ Packages lists that are distributed with &live-helper; reside in view
+ in the <command>/usr/share/live-helper/lists</command> directory.
+</para>
<sect4>
<title>Local packages lists</title>
+
<para>
- You may supplement the supplied lists using local package lists stored in <command>config/chroot_local-packageslists</command>.
+ You may supplement the supplied lists using local package lists stored
+ in <command>config/chroot_local-packageslists</command>.
</para>
+
<para>
- Package lists that exist in this directory always override package lists distributed with &live-helper;. This can cause undesired effects when..
+ Package lists that exist in this directory always override package
+ lists distributed with &live-helper;. This can cause undesired effects
+ when..
</para>
<note>
<title>&live-helper; 2.x change</title>
- <para>
- Any file with <command>.list</command> suffix in <command>config/chroot_local-packageslists</command> is automatically enabled, the variable LH_PACKAES_LISTS should only be used referencing packages lists included in live-helper (at <command>/usr/share/live-helper/lists/</command>.
- </para>
+
+<para>
+ Any file with <command>.list</command> suffix in
+ <command>config/chroot_local-packageslists</command> is automatically
+ enabled, the variable LH_PACKAES_LISTS should only be used referencing
+ packages lists included in live-helper (at
+ <command>/usr/share/live-helper/lists/</command>.
+</para>
+
</note>
</sect4>
<sect4>
<title>Extending a provided package list using includes</title>
+
<para>FIXME.</para>
<screen>
@@ -215,12 +290,16 @@ iceweasel
</screen>
<para>
- The package lists that are included with &live-helper; make extensive use of includes. They are available to view in the <command>/usr/share/live-helper/lists</command> directory.
+ The package lists that are included with &live-helper; make extensive
+ use of includes. They are available to view in the
+ <command>/usr/share/live-helper/lists</command> directory.
</para>
+
</sect4>
<sect4>
<title>Using conditionals inside packages lists</title>
+
<para>FIXME</para>
<screen>
@@ -229,7 +308,10 @@ ia32-libs
#endif
</screen>
-<para>or if <command>LH_ARCHITECTURE</command> is set to <command>i386</command> or <command>amd64</command>:</para>
+<para>
+ or if <command>LH_ARCHITECTURE</command> is set to
+ <command>i386</command> or <command>amd64</command>:
+</para>
<screen>
#if ARCHITECTURE i386 amd64
@@ -237,7 +319,10 @@ memtest86+
#endif
</screen>
-<para>or if <command>LH_SECTIONS</command> contains either <command>contrib</command> or <command>non-free</command>:</para>
+<para>
+ or if <command>LH_SECTIONS</command> contains either
+ <command>contrib</command> or <command>non-free</command>:
+</para>
<screen>
#if SECTIONS contrib non-free
@@ -245,7 +330,9 @@ vrms
#endif
</screen>
-<para>A conditional may surround an <command>#include</command> directive:</para>
+<para>
+ A conditional may surround an <command>#include</command> directive:
+</para>
<screen>
#if ARCHITECTURE amd64
@@ -254,10 +341,12 @@ vrms
</screen>
<para>
- Any &live-helper; configuration variable that begins with <command>LH_</command> can be tested in this way.
+ Any &live-helper; configuration variable that begins with
+ <command>LH_</command> can be tested in this way.
</para>
+
<para>
- The nesting of conditionals is not supported.
+ The nesting of conditionals is not supported.
</para>
</sect4>
@@ -266,7 +355,9 @@ vrms
<sect3 id="tasks">
<title>Tasks</title>
+
<para>FIXME</para>
+
</sect3>
</sect2>
@@ -274,25 +365,63 @@ vrms
<sect2 id="custom-packages">
<title>Installing modified or third-party packages</title>
-<para>Whilst it is against the philosophy of Debian Live, it may sometimes be necessary to build a Live system with modified versions of packages that are in the Debian repository. This may be to modify or support additional features, languages and branding, or even to remove elements of existing packages that are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietary functionality.</para>
+<para>
+ Whilst it is against the philosophy of Debian Live, it may sometimes be
+ necessary to build a Live system with modified versions of packages
+ that are in the Debian repository. This may be to modify or support
+ additional features, languages and branding, or even to remove elements
+ of existing packages that are undesirable. Similarly, "third-party"
+ packages may be used to add bespoke and/or proprietary functionality.
+</para>
-<para>This section does not cover advice regarding building or maintaining modified packages. Joachim Breitner's <ulink url="http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html">'How to fork privately'</ulink> may be of interest, however. The creation of bespoke packages is covered in the <ulink url="http://www.debian.org/doc/maint-guide/">Debian New Maintainers' Guide</ulink> and elsewhere.</para>
+<para>
+ This section does not cover advice regarding building or maintaining
+ modified packages. Joachim Breitner's <ulink
+ url="http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html">'How
+ to fork privately'</ulink> may be of interest, however. The creation of
+ bespoke packages is covered in the <ulink
+ url="http://www.debian.org/doc/maint-guide/">Debian New Maintainers'
+ Guide</ulink> and elsewhere.
+</para>
+
+<para>
+ There are two ways of installing modified custom packages:
+</para>
-<para>There are two ways of installing modified custom packages:</para>
<orderedlist>
<listitem><para><filename>chroot_local-packages</filename></para></listitem>
<listitem><para>Using a custom APT repository</para></listitem>
</orderedlist>
-<para>The <filename>chroot_local-packages</filename> is simpler to achieve and useful for "one-off" customisations but has a number of drawbacks, whilst using a custom APT repository is more time-consuming to set up.</para>
+<para>
+ The <filename>chroot_local-packages</filename> is simpler to achieve
+ and useful for "one-off" customisations but has a number of drawbacks,
+ whilst using a custom APT repository is more time-consuming to set up.
+</para>
<sect3 id="local-packages">
-<title>Using <filename>chroot_local-packages</filename> to install custom packages</title>
-<para>To install a custom package, simply copy it to the <command>config/chroot_local-packages</command> directory. Packages that are inside this directory will be automatically installed into the live system during build - you do not need to specify them elsewhere.</para>
+<title>
+ Using <filename>chroot_local-packages</filename> to install custom
+ packages
+</title>
-<para>Packages <emphasis>must</emphasis> be named in the prescribed way. One simple way to is to use <command>dpkg-name</command>. FIXME</para>
+<para>
+ To install a custom package, simply copy it to the
+ <command>config/chroot_local-packages</command> directory. Packages
+ that are inside this directory will be automatically installed into the
+ live system during build - you do not need to specify them elsewhere.
+</para>
+
+<para>
+ Packages <emphasis>must</emphasis> be named in the prescribed way. One
+ simple way to is to use <command>dpkg-name</command>. FIXME
+</para>
+
+<para>
+ Using <filename>chroot_local-packages</filename> for installation of
+ custom packages has disadvantages:
+</para>
-<para>Using <filename>chroot_local-packages</filename> for installation of custom packages has disadvantages:</para>
<orderedlist>
<listitem><para>It is not possible to use secure APT</para></listitem>
<listitem><para>You must install all appropriate packages in the <command>config/chroot_local-packages</command> directory</para></listitem>
@@ -302,36 +431,56 @@ vrms
<sect3 id="custom-apt-repo">
<title>Using an APT repository to install custom packages</title>
+
<para>
FIXME
</para>
+
<para>
- Unlike You must ensure that you specify the package elsewhere, see (FIXME)
+ Unlike You must ensure that you specify the package elsewhere, see
+ (FIXME)
</para>
+
<para>
- Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.
+ Whilst it may seem unnecessary effort to create an APT repository to
+ install custom packages, the infrastructure can be easily re-used at a
+ later date to offer updates of the modified package.
</para>
</sect3>
<sect3 id="custom-packages-apt">
<title>Custom packages and APT</title>
+
<para>
- &live-helper; uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package is available in two different repositories, APT will elect to install the package with a higher version number over one with the lower.
+ &live-helper; uses APT to install all packages into the live system so
+ will therefore inherit behaviours from this program. One relevant
+ example is that (assuming a default configuration) given a package is
+ available in two different repositories, APT will elect to install the
+ package with a higher version number over one with the lower.
</para>
<para>
- Because of this. you may wish to increment the version number in your custom packages' <command>debian/changelog</command> files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see <xref linkend="apt-preferences"/> for more information.
+ Because of this. you may wish to increment the version number in your
+ custom packages' <command>debian/changelog</command> files to ensure
+ that your modified version is installed over one in the official Debian
+ repositories. This may also be achieved by altering the live system's
+ APT pinning preferences - see <xref linkend="apt-preferences"/> for
+ more information.
</para>
</sect3>
<sect3 id="apt-preferences">
<title>Altering APT preferences during Live system</title>
+
<para>
FIXME
</para>
+
<para>
- Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.
+ Whilst it may seem unnecessary effort to create an APT repository to
+ install custom packages, the infrastructure can be easily re-used at a
+ later date to offer updates of the modified package.
</para>
</sect3>
--
live-manual
More information about the debian-live-changes
mailing list