Emdebian customisation support.

Emdebian customisation has three components. Vendor changes apply equally across lots of (or all) packages, multistrap changes make customised root filesystems for any vendor or variant and baked support provides ways to create preconfigured systems.

The components can be used individually or together to create a flexible build system. DEB_VENDOR support can be used to adapt the package generation processes for Emdebian Grip.

1. DEB_VENDOR

   DEB_VENDOR provides support for macro changes to cross-built packages using emdebian-grip. Packages can be labelled for specific vendors and package changes can be set across all packages using emgrip. DEB_VENDOR also supports making consistent changes across a set of packages, mediated via emvendor to change the dependencies of cross-built packages and make other build-time changes in a consistent manner.

   The main emphasis of DEB_VENDOR is to allow vendors to select groups of customisation changes and apply the same changes across all affected packages.

   The first example is how Emdebian Crush and Emdebian Grip both use DEB_VENDOR to retrieve the build options when used with emgrip.

   A narrower example is changing the ./configure options to packages like 'avahi' to drop dependencies. Individual vendors can choose which options are switched off by placing a config file in /etc/emvendor.d/vendor-name. See emvendor (1) and Vendor configuration.

2. xcontrol

   The debian/xcontrol file provides support for adding customised binary packages to an existing Debian source package and can then be used with DEB_VENDOR or directly to replace standard Debian binary packages with custom packages with modified dependencies or build-time options, e.g. changing the commands passed to ./configure to --disable-foo where Debian would pass --enable-foo.

   xcontrol is package-reliant and each change to a package needs to be implemented within the xcontrol file for that package. Where such support is implemented in more than one package, DEB_VENDOR support could be used to apply (or de-apply) sets of changes in a single step.

   Where the debian/xcontrol file does not already include the necessary support, machine:variant support could be used to provide a modified xcontrol file.

   xcontrol is concerned with providing multiple options in a single package to support a variety of purposes.

   An example would be providing a new binary package for 'avahi' so that the libraries built with the modified ./configure options gain a new binary package name (which can Provide: and/or Conflict: with the standard Debian package).

3. machine:variant support

   Machine:variant operates in two modes - macro and micro.

   Support for each variant is based on two scripts:

   setup.sh
   config.sh
   

   Once multistrap has unpacked the downloaded packages, the setup.sh script can be called, passing the location and architecture of the root filesystem, so that other fine tuning can take place. At this stage, any operations inside the rootfs must not try to execute any binaries within the rootfs. As the final stage of the multistrap process, config.sh is copied into the root directory of the rootfs.

   One advantage of using machine:variant support is that the entire root filesystem can be managed by a single call to multistrap - this is useful when building root filesystems in userspace.

   To enable variant support, specify the path to the scripts to be called in the variant configuration file (General section):

    [General]
    include=/path/to/general.conf
    setup_script=/path/to/setup.sh
    config_script=/path/to/config.sh
   

   These two shell scripts can call, include or execute other files or scripts but if these scripts or files are intended for use within the rootfs, setup.sh must arrange for them to be included into the tarball.

   Skeleton versions of these files are available in the multistrap package.

   Machine variants

   Once the first stage install is complete, multistrap 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.

   Example

   $ cat /etc/dpkg/origins/my-vendor
   Vendor: my-vendor
   Vendor-Name: My Vendor
   Grip-Build-Option: usecrush
   Short-Desc-Suffix: flavoured
   $ export DEB_VENDOR my-vendor
   $ cat /etc/emvendor.d/my-vendor.conf
   [avahi]
   EXCONFARGS= --disable-mono --disable-gobject --with-distro debian
   
   [busybox]
   configfile=/foo/bar/myhome/vendor/busybox/config
   
   $ emsource -b busybox
   

   Once the Emdebian patches for busybox are updated to support DEB_VENDOR in this way, busybox would be built with the vendor specific config file and then gripped using the options specified in /etc/dpkg/origins/my-vendor.