emsandbox emsandbox 1 EMDEBIAN-TOOLS EMDEBIAN-TOOLS 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 installed. # ./emsecondstage --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. -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. -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. 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://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 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. 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. User-specific version of /etc/emsandbox.conf, supporting the same variables to provide user-specific overrides. emsandbox was written by Neil Williams codehelp@debian.org. This manual page was written by Neil Williams codehelp@debian.org See also apt-cross (1), em_make (1), dpkg-cross (1), emdebian-tools (1).