emsandbox [[-a] | [--arch ] ARCHITECTURE] [[--create] | [create]] [[--script] FILENAME] [[--machine-path]PATH] [[--machine] NAME [[--variant] NAME]]
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 native chroot
is intended to support testing of a rootfs and package installability.
The tarball created by emsandbox should be copied onto the target device and unpacked using:
$ cd /path/to/target/dir
$ sudo tar -xzpf emdebian-arm.tgz
Once unpacked, the packages need only to be configured.
$ sudo ./emsecondstage
emsecondstage should always be run from the directory into which it was installed.
emsandbox creates a chroot for the target architecture, not the architecture of the system running emsandbox. This has some important results:
The chroot is an Emdebian system running an Emdebian rootfs e.g. using busybox. Perl and debconf are not available inside the chroot (cdebconf replaces debconf).
Initially, emsandbox only supports creating
the chroot, other options like login and
update would require some form of emulator. The expectation
at this time is that the user will copy or install the created rootfs
onto a device that can execute the installed binaries. Once installed,
the binaries do not need to be executed from emsandbox.
emsandbox is a work-in-progress.
--create|createRuns 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|--helpprint the usage message and exit.
--version
print the usage message and exit.
-a|--arch ARCHITECTUREOverride the dpkg-cross default architecture for this operation on the chroot.
-s|--script FILENAMEOverride 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).
-m|--machine MACHINELoad 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 VARIANTLoad 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.
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/lib/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://buildd.emdebian.org/emdebian/
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
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.
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)
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.
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.
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.
emsandbox was written
by Neil Williams <codehelp@debian.org>.
This manual page was written by Neil Williams
<codehelp@debian.org>