452 lines
20 KiB
XML
452 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>
|
|
<para>Examples of <filename>packages.conf</filename>,
|
|
<filename>setup.sh</filename> and <filename>config.sh</filename> are
|
|
in <filename>/usr/share/doc/emdebian-rootfs/examples/</filename>
|
|
</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>
|