Man Linux: Main Page and Category List


       emsandbox - create Emdebian root filesystems


       emsandbox [[-a] | [--arch] ARCHITECTURE] [[--create] | [create]] [[[-s]
                 | [--script]] FILENAME] [[-S] | [--suite] NAME]
                 [[--machine-path]PATH] [[-m] | [--machine] NAME [[-v] |
                 [--variant] NAME]]


       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.


       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

           # ./emsecondstage


           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.

           print the usage message and exit.

           print the usage message and exit.


       -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

       --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 and
           shell scripts (which may be empty).

           Examples of packages.conf, and are in

       -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

           The selected suite is set in the root filesystem as the default
           suite for apt to use when looking for updates.


       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 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, 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

       Skeleton versions of packages.conf, and 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. and 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:

           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

           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

           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.


           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 (
           will be written into /etc/apt/sources.list.

           DEFAULT: empty

           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.

           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

           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, and 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

       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.

       User-specific version of /etc/emsandbox.conf, supporting the same
       variables to provide user-specific overrides.


       emsandbox was written by Neil Williams

       This manual page was written by Neil Williams


       See also apt-cross (1), em_make (1), dpkg-cross (1), emdebian-tools