debian-cd-clone/docs/README.variants

Introduction
------------

Variants enable debian-cd to include extra functionality in a built
image which is somewhat orthogonal to the usual DISKTYPE and ARCH
configurations.

Variants are enabled by setting the VARIANTS environment variable to a
space separated list of the variants to enable or by passing the -V
option (multiple times if desired) to the easy-build.sh script.

Available Variants
------------------

* `xen' [i386, amd64 only]

  This variant includes a kernel and installer initrd which is
  compatible with the Xen hypervisor in `install.<arch>/xen' and
  includes matching kernel module .udebs as well as a suitable kernel
  .deb for installation into the final system.

Implementation
--------------

Variants impact several aspects of the debian-cd infrastructure:

  environment variable
  --------------------

  The $VARIANTS environment variable is available to any scripts etc
  which are run as part of the build process and is a space separated
  list of the variants which are enabled.

  In particular this maybe used by the per-archtecture
  tools/boot/<distro>/boot-* scripts which make an image bootable on a
  particular architecure. To facilitate this
  tools/boot/<distro>/common.sh defines a function `variant_enabled'
  which takes a variant name as an argument and returns true if that
  variant is enabled.

  deb package lists
  -----------------

  A variant may wish to include extra .deb packages in the image. The
  package lists are preprocessed using `cpp' as part of the build
  process and a C-preprocessor variable `VARIANT_<x>' will be defined
  to 1 for each variant which is enabled.

  udeb package lists
  ------------------

  Similarly a variant may which to include extra .udeb packages in the
  image. The list of udebs to include in an image is generated using
  tools/generate_di_list which reads one or more udeb exclude files
  from data/<distribution>/*. The syntax of these exclude files allows
  a udeb to be excluded or included based on which variants are
  enabled.

  Each line in an exclude file specifies a glob pattern, a udeb whose
  name matches the glob will _not_ be included in the image. After the
  udeb glob each line can optionally contain on or more space
  separated conditions. At least one of these conditions must be met
  in order to exclude the udeb. A condition may either be:
     - a positive `variant' condition, in which case the udeb is
       excluded when that variant is enabled
     - a negative `!variant' condition, in which case the udeb is
       excluded when that variant is not enabled.