multistrap/doc/xml/emsandbox.1.xml
2009-06-11 18:56:40 +00:00

448 lines
20 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="emsandbox">
<refentryinfo>
<productname>emsandbox</productname>
<productnumber/>
</refentryinfo>
<refmeta>
<refentrytitle>emsandbox</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
<refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
</refmeta>
<refnamediv id="name">
<refname>emsandbox</refname>
<refpurpose>create Emdebian root filesystems</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>emsandbox</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--create</arg>
<arg>create</arg>
</group>
<group>
<group>
<arg>-s</arg>
<arg>--script</arg>
</group>
<replaceable> FILENAME</replaceable>
</group>
<group>
<arg>-S</arg>
<arg>--suite</arg>
<replaceable> NAME</replaceable>
</group>
<group>
<arg>--machine-path</arg>
<replaceable>PATH</replaceable>
</group>
<group>
<arg>-m</arg>
<arg>--machine</arg>
<replaceable> NAME</replaceable>
<group>
<arg>-v</arg>
<arg>--variant</arg>
<replaceable> NAME</replaceable>
</group>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="shell">
<title>SHELL INTERPRETERS</title>
<para><command>emsandbox</command> is bash code and uses
<command>embootstrap</command> which is bash code and also sources
pbuilder code which is also bash code. <command>debootstrap</command>
re-executes itself with the default shell and then tries to source the
suite script which fails because the re-executed copy of debootstrap is
now running under the default shell, not bash.
</para>
<para>This problem can show up as a failure within <command>debootstrap</command>
</para>
<programlisting>
I: Retrieving zlib1g
I: Validating zlib1g
</programlisting>
<para>The next line should be:</para>
<programlisting>
I: Extracting base-passwd...
</programlisting>
<para>Unfortunately, this is a result of the default shell
interpreter in Debian being changed after the scripts were written
and it is a non-trivial problem. It is not possible for
<command>embootstrap</command> could migrate to cdebootstrap currently.
</para>
<para>The only current solution is to change your default shell to
/bin/bash inside the environment running <command>emsandbox</command>.
</para>
</refsect1>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para><command>emsandbox</command> supports customised generation of
basic root filesystems from cross-built Emdebian packages, ready for
unpacking and configuring on an embedded device.
</para>
<para>Note that <filename>emsandbox</filename> does not support all the
options available to <filename>debootstrap</filename>. Some of the
debootstrap options that are supported are implemented as machine
specific configuration files in your Emdebian work directory.
(See <option>--machine</option> and <option>--variant</option>.)
</para>
<para><filename>emsandbox</filename> is a wrapper for debootstrap to prepare
an Emdebian root filesystem, using Emdebian packages and a native chroot
via 'debootstrap --foreign' and code from pbuilder.
</para>
<para>The Emdebian rootfs, as generated by <command>emsandbox</command>
is not fully configured - packages are unpacked and certain support
files are created but none of the packages are configured (not even
the pre-install scripts). This last stage is the only process that
<emphasis>must</emphasis> be run on the actual device
<emphasis>before the first boot</emphasis>, using the <command>emsecondstage</command>
script which requires a working <command>chroot</command> environment.
Typically, <command>emsecondstage</command> is run from some kind of
minimal bootloader environment that has sufficient support for mounting
subsystems like proc and filesystems like the root filesystem partition
and can chroot into the root filesystem. This method means that the
majority of the work of creating the root filesystem can be done on
the build machine.
</para>
<para>The tarball created by <command>emsandbox</command> should be
copied onto the target device and unpacked using:
</para>
<programlisting>
# cd /mnt/target/dir
# tar -xzpf emdebian-arm.tgz
</programlisting>
<para>Immediately after unpacking, start the package configuration
by running <command>./emsecondstage</command> on the target device.
(Configuration involves running the cross-built binaries and is the
only part of the process that must be run on the target device.)
</para>
<para><command>emsecondstage</command> should <emphasis>always</emphasis>
be run from the directory into which it was installed.
</para>
<programlisting>
# ./emsecondstage
</programlisting>
</refsect1>
<refsect1 id="commands">
<title>COMMANDS</title>
<variablelist remap="TP">
<varlistentry>
<term><option>--create</option>|<option>create</option></term>
<listitem>
<para>Runs <command>debootstrap</command> <option>--foreign</option>
with a modified suite rule set to create a basic Emdebian rootfs.
</para>
<para>Checks for an existing chroot and exits if one is found.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>|<option>--help</option></term>
<listitem>
<para>print the usage message and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--version</option>
</term>
<listitem>
<para>print the usage message and exit.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<variablelist remap="TP">
<varlistentry>
<term><option>-a</option>|<option>--arch</option><replaceable> ARCHITECTURE</replaceable></term>
<listitem>
<para>Override the <command>dpkg-cross</command> default architecture
for this operation on the chroot.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>|<option>--script</option><replaceable> FILENAME</replaceable></term>
<listitem>
<para>Override the default package selection and installation
script with a customised debootstrap suite script (written in shell
and compatible with whichever shell interpreter is to be installed
on the target).
</para>
<para>Some customised scripts are provided with emdebian-tools. The
default uses the standard Emdebian 'busybox' package with 'dpkg' and
'apt'. Replacement scripts need to be full debootstrap suite shell
scripts that specify how to complete the first and second stage
installations.
</para>
<para>Customised scripts packages with <emphasis>emdebian-tools</emphasis>
include scripts for a root filesystem including libgtk2.0-0 and a complete
GPE root filesystem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--machine-path</option>
<replaceable> PATH</replaceable>
</term>
<listitem>
<para>Override the default path to machine and variant configuration. By
default, emsandbox uses <filename>${WORK}/machine</filename> where
<userinput>$WORK</userinput> is the working directory specified
to <emphasis>emdebian-tools</emphasis> in the debconf configuration.
The specified path must already exist and contain the relevant
<filename>packages.conf</filename> configuration as well as the
<filename>setup.sh</filename> and <filename>config.sh</filename> shell
scripts (which may be empty).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option>|<option>--machine</option><replaceable> MACHINE</replaceable></term>
<listitem>
<para>Load machine specific configuration data from your Emdebian
working directory. If no variant is specified, config is read from
<filename>$WORK/machine/$MACHINE/default/</filename> where $WORK
is the work directory specified in debconf for emdebian-tools.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>|<option>--variant</option><replaceable> VARIANT</replaceable></term>
<listitem>
<para>Load variant specific configuration data from your Emdebian
working directory. Requires <option>--machine</option>. Configuration
data is read from <filename>$WORK/machine/$MACHINE/$VARIANT/</filename> where $WORK
is the work directory specified in debconf for emdebian-tools.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option>|<option>--suite</option><replaceable> NAME</replaceable></term>
<listitem>
<para>Override the default suite [unstable] and specify another
supported suite. Note that if the Emdebian repository is used,
the suite chosen <emphasis>must</emphasis> be a normal
Emdebian/Debian suite name from 'unstable, testing or sid', or
a Debian release codename for a release including or later
than lenny. No other suite name is supported in Emdebian.
</para>
<para>The selected suite is set in the root filesystem as the
default suite for apt to use when looking for updates.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="machinevariants">
<title>Machine variants</title>
<para><command>emsandbox</command> supports a set of customisation routines
for each combination of machine and variant, allowing the rootfs to be customised
to specific variants of a specific machine. Configuration data is stored in the
<filename>machine</filename> subdirectory of your Emdebian work directory.
Using the <option>-m</option> option to <command>emsandbox</command> loads
<filename>packages.conf</filename> from the <filename>$WORK/machine/$MACHINE/default</filename>
subdirectory prior to starting debootstrap. Once the first stage install is complete,
<command>emsandbox</command> calls <filename>setup.sh</filename> from the same
directory, passing the location and architecture of the tarball, so that other
fine tuning can take place prior to creating the tarball. At this stage, any
operations inside the rootfs must not try to execute any binaries within the
rootfs. Immediately before creating the tarball, <filename>config.sh</filename>
is copied into the <filename>/machine/$MACHINE/default/</filename> directory
of the rootfs, ready to be called when <command>emsecondstage</command> has
completed the second stage of the debootstrap process.
</para>
<para>Skeleton versions of <filename>packages.conf</filename>,
<filename>setup.sh</filename> and <filename>config.sh</filename> are available
in <filename>/usr/share/emdebian-tools/machine/</filename>.
</para>
<para><filename>packages.conf</filename> is intended to be the principal place
for adjusting the emsandbox tarball to suit the needs of specific machine variants.
<filename>setup.sh</filename> and <filename>config.sh</filename> can fine tune
the results but in order to avoid reinventing the wheel, if more than a few
machines need similar adjustments to the same files, future versions of
<filename>packages.conf</filename> will collate those into a single
configuration parameter available to all.
</para>
<para><filename>packages.conf</filename> supports:</para>
<variablelist>
<varlistentry>
<term>
<option>INCLUDE</option>
</term>
<listitem>
<para>Add a comma separated list of package names to the list of packages
added to the tarball and installed in the second stage. Currently, debootstrap
has problems with multiple repositories so either upload this package to the
same repository as your other packages or create an apt-proxy that can serve
as a local repository, set it in <option>PROXY</option> and specify a usable
mirror for the device in <option>MIRROR</option>.</para>
<para>DEFAULT: empty</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>SCRIPT</option>
</term>
<listitem>
<para>Overrides the default emsandbox suite-script that debootstrap uses to
determine the base and required packages and the all important sequence in which
the packages can be installed. SCRIPT can be overridden on the emsandbox command line.
</para>
<para>DEFAULT: <filename>/usr/share/emdebian-tools/emdebian.crossd</filename></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>MIRROR</option>
</term>
<listitem>
<para>Overrides the default emsandbox mirror. This repository will be set in
<filename>/etc/apt/sources.list</filename> and will also be used by debootstrap to obtain
all packages for the tarball unless <option>PROXY</option> is also set.
</para>
<para>DEFAULT: http://www.emdebian.org/crush/</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>PROXY</option>
</term>
<listitem>
<para>Specifies a separate repository to pass to debootstrap that may be local or
otherwise not intended for use once the tarball is installed. Use <option>MIRROR</option>
to set the same value in debootstrap and <filename>/etc/apt/sources.list</filename>.
If <option>PROXY</option> is specified without <option>MIRROR</option>, the default
emsandbox MIRROR (http://buildd.emdebian.org/emdebian/) will be written into
<filename>/etc/apt/sources.list</filename>.</para>
<para>DEFAULT: empty</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>TARBALL_NAME</option>
</term>
<listitem>
<para>Overrides the default name (emdebian-$ARCH) of the tarball. Do not specify a path here,
just a filename with the .tgz suffix.</para>
<para>DEFAULT: emdebian-$ARCH.tgz where $ARCH is specified to emsandbox or as the dpkg-cross
default architecture.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>SUITE</option>
</term>
<listitem>
<para>Override the default suite [unstable] and specify another
supported suite. Note that if the Emdebian repository is used,
the suite chosen <emphasis>must</emphasis> be a normal
Emdebian/Debian suite name from 'unstable, testing or sid', or
a Debian release codename for a release including or later
than lenny. No other suite name is supported in Emdebian.
</para>
<para>The selected suite is set in the root filesystem as the
default suite for apt to use when looking for updates.
</para>
<para>Not recommended to be changed.
</para>
<para>DEFAULT: unstable
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Due to limitations in the current debootstrap support, the only way
of adding packages to the first stage is by providing a customised suite
script. Even if emsandbox migrates to using a tool from Stag to overcome
shortcomings in debootstrap, support for packages.conf, setup.sh and config.sh
will remain.</para>
</refsect1>
<refsect1 id="automation">
<title>Automating rootfs builds</title>
<para>Providing you are trying to build a root filesystem for an
architecture supported within Debian, <emphasis>emdebian-tools</emphasis>
can help you automate the package builds.
See <filename>em_autobuild</filename> (1)</para>
</refsect1>
<refsect1 id="shell">
<title>SHELL variables</title>
<para>Note that the Debian chroot program from coreutils expects you
to want the same shell outside the chroot as you want to use inside
the chroot. The typical Debian default shell in <filename>/etc/passwd</filename>
is bash which is not present in the Emdebian rootfs so <command>chroot</command>
needs the <option>/bin/sh</option> option.</para>
</refsect1>
<refsect1 id="files">
<title>FILES</title>
<para>Most <emphasis>emdebian-tools</emphasis> use configuration data from
<filename>apt-cross</filename> and <filename>dpkg-cross</filename>.
<command>emsource</command> and <command>emsandbox </command> also support
configuration using <filename>debconf</filename> to set a subversion username
and default working directory (which must be writable) for unpacking source
downloads. Default debconf values can be overridden with user-specific
values using <filename>~/.apt-cross/emsource</filename> or
<filename>~/.apt-cross/emsandbox</filename> respectively.
</para>
<refsect2>
<title>/etc/emsandbox.conf</title>
<para>System-wide configuration file handled by <command>debconf</command>
controlling unpacking source archives to a default working
directory. Can also include a subversion username setting, intended for
single-user installations. <filename>/etc/emsandbox.conf</filename>
settings can be overridden on a per-user basis by copying the current
file to <filename>~/.apt-cross/emsandbox</filename> and editing the
values.</para>
<para>Two variables can be set (see also <filename>/etc/emsandbox.conf</filename>):
</para>
<itemizedlist>
<listitem>
<para><emphasis>workingdir</emphasis>: A simple default
location for <command>emsandbox</command> to create a source tree to
download and unpack prebuilt binary packages. If left blank, a
new top level directory tree is used but this is intended for chroot
support only.
</para>
</listitem>
<listitem>
<para><emphasis>targetsuite</emphasis>: Emdebian follows Debian by
defaulting to building against unstable. This setting determines the
versions of libraries and packages linked against the cross-built emdebian
packages.
</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2>
<title>~/.apt-cross/emsandbox</title>
<para>User-specific version of <filename>/etc/emsandbox.conf</filename>,
supporting the same variables to provide user-specific overrides.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Author</title>
<para><command>emsandbox</command> was written
by Neil Williams <email>codehelp@debian.org</email>.
</para>
<para>This manual page was written by Neil Williams
<email>codehelp@debian.org</email>
</para>
</refsect1>
<refsect1 id="seealso">
<title>SEE ALSO</title>
<para>See also <filename>apt-cross</filename> (1), <filename>em_make</filename> (1),
<filename>dpkg-cross</filename> (1), <emphasis>emdebian-tools</emphasis> (1).
</para>
</refsect1>
</refentry>