emsandbox(1)
NAME
emsandbox - native chroot tool for Emdebian testing
SYNOPSIS
emsandbox [[-a] | [--arch] ARCHITECTURE] [[--create] | [create]] [[--script] FILENAME] [[--machine-path]PATH] [[--machine] NAME [[--variant] NAME]]
DESCRIPTION
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 is a native chroot
emsandbox creates a chroot for the target architecture, not the architecture of the system running emsandbox. This has some important results:
1. 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).- 2. 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.
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). - -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.
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/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.
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).
AUTHOR
Emdebian
- Neil Williams
- Author.