--- name: "emsandbox" section: "1" platform: "linux" package: "emdebian-rootfs" version: "1.4.3" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/emsandbox" --- # emsandbox(1) native chroot tool for Emdebian testing ## 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 \. This manual page was written by Neil Williams \ ## SEE ALSO See also *apt-cross* (1), *em\_make* (1), *dpkg-cross* (1), *emdebian-tools* (1). ## AUTHOR **Emdebian** **Neil Williams** - Author. ## COPYRIGHT