NAME
emsandbox - create Emdebian root filesystems
SYNOPSIS
emsandbox [[-a] | [--arch] ARCHITECTURE] [[--create] | [create]] [[[-s]
| [--script]] FILENAME] [[-S] | [--suite] NAME]
[[--machine-path]PATH] [[-m] | [--machine] NAME [[-v] |
[--variant] NAME]]
SHELL INTERPRETERS
emsandbox is bash code and uses embootstrap which is bash code and also
sources pbuilder code which is also bash code. debootstrap 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.
This problem can show up as a failure within debootstrap
I: Retrieving zlib1g
I: Validating zlib1g
The next line should be:
I: Extracting base-passwd...
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 embootstrap could migrate
to cdebootstrap currently.
The only current solution is to change your default shell to /bin/bash
inside the environment running emsandbox.
DESCRIPTION
emsandbox supports customised generation of basic root filesystems from
cross-built Emdebian packages, ready for unpacking and configuring on
an embedded device.
Note that emsandbox does not support all the options available to
debootstrap. Some of the debootstrap options that are supported are
implemented as machine specific configuration files in your Emdebian
work directory. (See --machine and --variant.)
emsandbox 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.
The Emdebian rootfs, as generated by emsandbox 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 must be run on the actual device
before the first boot, using the emsecondstage script which requires a
working chroot environment. Typically, emsecondstage 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.
The tarball created by emsandbox should be copied onto the target
device and unpacked using:
# cd /mnt/target/dir
# tar -xzpf emdebian-arm.tgz
Immediately after unpacking, start the package configuration by running
./emsecondstage 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.)
emsecondstage should always be run from the directory into which it was
installed.
# ./emsecondstage
COMMANDS
--create|create
Runs debootstrap --foreign with a modified suite rule set to create
a basic Emdebian rootfs.
Checks for an existing chroot and exits if one is found.
-h|--help
print the usage message and exit.
--version
print the usage message and exit.
OPTIONS
-a|--arch ARCHITECTURE
Override the dpkg-cross default architecture for this operation on
the chroot.
-s|--script FILENAME
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).
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.
Customised scripts packages with emdebian-tools include scripts for
a root filesystem including libgtk2.0-0 and a complete GPE root
filesystem.
--machine-path PATH
Override the default path to machine and variant configuration. By
default, emsandbox uses ${WORK}/machine where $WORK is the working
directory specified to emdebian-tools in the debconf configuration.
The specified path must already exist and contain the relevant
packages.conf configuration as well as the setup.sh and config.sh
shell scripts (which may be empty).
Examples of packages.conf, setup.sh and config.sh are in
/usr/share/doc/emdebian-rootfs/examples/
-m|--machine MACHINE
Load machine specific configuration data from your Emdebian working
directory. If no variant is specified, config is read from
$WORK/machine/$MACHINE/default/ where $WORK is the work directory
specified in debconf for emdebian-tools.
-v|--variant VARIANT
Load variant specific configuration data from your Emdebian working
directory. Requires --machine. Configuration data is read from
$WORK/machine/$MACHINE/$VARIANT/ where $WORK is the work directory
specified in debconf for emdebian-tools.
-S|--suite NAME
Override the default suite [unstable] and specify another supported
suite. Note that if the Emdebian repository is used, the suite
chosen must 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.
The selected suite is set in the root filesystem as the default
suite for apt to use when looking for updates.
MACHINE VARIANTS
emsandbox 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 machine subdirectory of your Emdebian work directory. Using the
-m option to emsandbox loads packages.conf from the
$WORK/machine/$MACHINE/default subdirectory prior to starting
debootstrap. Once the first stage install is complete, emsandbox calls
setup.sh 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, config.sh is copied into the
/machine/$MACHINE/default/ directory of the rootfs, ready to be called
when emsecondstage has completed the second stage of the debootstrap
process.
Skeleton versions of packages.conf, setup.sh and config.sh are
available in /usr/share/emdebian-tools/machine/.
packages.conf is intended to be the principal place for adjusting the
emsandbox tarball to suit the needs of specific machine variants.
setup.sh and config.sh 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 packages.conf will
collate those into a single configuration parameter available to all.
packages.conf supports:
INCLUDE
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 PROXY and specify a usable mirror for the device in MIRROR.
DEFAULT: empty
SCRIPT
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.
DEFAULT: /usr/share/emdebian-tools/emdebian.crossd
MIRROR
Overrides the default emsandbox mirror. This repository will be set
in /etc/apt/sources.list and will also be used by debootstrap to
obtain all packages for the tarball unless PROXY is also set.
DEFAULT: http://www.emdebian.org/crush/
PROXY
Specifies a separate repository to pass to debootstrap that may be
local or otherwise not intended for use once the tarball is
installed. Use MIRROR to set the same value in debootstrap and
/etc/apt/sources.list. If PROXY is specified without MIRROR, the
default emsandbox MIRROR (http://buildd.emdebian.org/emdebian/)
will be written into /etc/apt/sources.list.
DEFAULT: empty
TARBALL_NAME
Overrides the default name (emdebian-$ARCH) of the tarball. Do not
specify a path here, just a filename with the .tgz suffix.
DEFAULT: emdebian-$ARCH.tgz where $ARCH is specified to emsandbox
or as the dpkg-cross default architecture.
SUITE
Override the default suite [unstable] and specify another supported
suite. Note that if the Emdebian repository is used, the suite
chosen must 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.
The selected suite is set in the root filesystem as the default
suite for apt to use when looking for updates.
Not recommended to be changed.
DEFAULT: unstable
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.
AUTOMATING ROOTFS BUILDS
Providing you are trying to build a root filesystem for an architecture
supported within Debian, emdebian-tools can help you automate the
package builds. See em_autobuild (1)
SHELL VARIABLES
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 /etc/passwd is bash which is not
present in the Emdebian rootfs so chroot needs the /bin/sh option.
FILES
Most emdebian-tools use configuration data from apt-cross and
dpkg-cross. emsource and emsandbox also support configuration using
debconf 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
~/.apt-cross/emsource or ~/.apt-cross/emsandbox respectively.
/etc/emsandbox.conf
System-wide configuration file handled by debconf controlling unpacking
source archives to a default working directory. Can also include a
subversion username setting, intended for single-user installations.
/etc/emsandbox.conf settings can be overridden on a per-user basis by
copying the current file to ~/.apt-cross/emsandbox and editing the
values.
Two variables can be set (see also /etc/emsandbox.conf):
· workingdir: A simple default location for emsandbox 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.
· targetsuite: 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.
~/.apt-cross/emsandbox
User-specific version of /etc/emsandbox.conf, supporting the same
variables to provide user-specific overrides.
AUTHOR
emsandbox was written by Neil Williams codehelp@debian.org.
This manual page was written by Neil Williams codehelp@debian.org
SEE ALSO
See also apt-cross (1), em_make (1), dpkg-cross (1), emdebian-tools
(1).