debian-cd-clone/README.easy-build

			debian-cd easy-build
			====================

INTRODUCTION
============
easy-build.sh is a "wrapper" script around the more basic build.sh build
script. It is designed to make building a specific image or set or images
as easy as possible, while still offering all the flexibility of debian-cd.

easy-build.sh supports the following variations:
- businesscard, netinst and full CD images, and DVD images
- single-architecture and multi-architecture images
- optionally include source packages
- select to install GNOME (default), KDE or Xfce desktops as desktop task
- creates ISO files by default; creating jigdo files is possible
- specify which Debian release to use
- include custom versions of packages (debs)
- specify which Debian Installer (D-I) version and source to use, including
  custom images
- include custom versions of Debian Installer components (udebs)

Using easy-build.sh is somewhat simpler than calling make directly or even
than using build.sh as it splits the complex configuration of debian-cd
into three levels:
1) CONF.sh: basic configuration such as paths
2) easy-build.sh: characteristicts of the CD/DVD set, for example:
   - Debian release
   - D-I version and source of D-I images
   - number of CDs or DVDs to generate
3) command line parameters:
   - type of image (businesscard, netinst, full CD or DVD
   - which architecture(s)
   - which desktop to install

easy-build.sh also ensures that "task files" are automatically updated as
needed. If custom packages are included it can automatically generate a
Packages file for the local repository: just copy the packages to the
correct location and let easy-build.sh do the rest.

Types of images & task definitions
----------------------------------
easy-build.sh can be used to create four types of images:
- businesscard CD: only contains Debian Installer; any packages neede for
  the installed system are retrieved from a mirror during the installation
- netinst CD: contains Debian Installer and all packages needed to install a
  Debian "base system" (packages with priority important or higher)
- full CD: same as netinst CD, but filled to capacity with additional
  packages based on "task" definitions; image size is 680MB
- DVD: same as full CD, but with an image size of 4.7GB

The businesscard and netinst CD are always a single image. The size of these
images depends on the architecture. For i386 they are around 40MB and 150MB
respectively.

The full CD and DVD are sets of images, but the set can be limited to any
number. The first image of the set always includes Debian Installer and
packages needed for the base system. After that the first and following
images are filled up to capacity with packages in the following order:
- "essential" packages from tasksel tasks
- "optional" packages from tasksel tasks
- other packages sorted by popularity (popcon score)

The basic order in which packages are included on full CDs and DVDs is
defined in 'tasks/<CODENAME>/Debian'. The order in which tasksel tasks are
included is defined in 'tasks/<CODENAME>/task.list*'.

Current GNOME and KDE desktop environments are so large that only the
packages needed to install one of them can be included on the first full CD.
Therefore debian-cd supports creating a CD or DVD set targeted at a specific
desktop environment: either GNOME, or KDE, or Xfce.
The default 'task.list' is targeted at the GNOME desktop environment.

It is possible to customize the debian-cd task definitions and even to
customize tasksel, but that falls outside the scope of this document.

CREATING A MIRROR OF THE ARCHIVE
================================
debian-cd requires you to have a local mirror of the Debian archive,
normally on the same machine where you run debian-cd. There are lots of
methods to create a (partial) local archive.

Make sure the following are included in your local archive:
- ./dists/<codename>/main/debian-installer/binary-<arch>/
  contains Debian Installer components (udebs)
- ./doc/
- ./indices/
- ./tools/
and optionally:
- ./dists/<codename>/main/installer-<arch>/
  contains Debian Installer images (official releases)

One method is to use debmirror. An example script for creating a full or
partial local mirror using debmirror suitable for use with debian-cd can be
found at: http://alioth.debian.org/~fjp/debmirror/.

BASIC CONFIGURATION
===================
Most of the variables in CONF.sh can be left at their default values. Some
just because their default value should be OK for most purposes, some
because their value is set by easy-build.sh itself.

The following variables that define paths *must* be set in CONF.sh:
- MIRROR
- TDIR
- OUT
- APTTMP

You may also want to change the following variables:
- CONTRIB: comment out if you only want to include packages from main
- IMAGESUMS: comment out to skip creating MD5/SHA5 sums for images
- OMIT_MANUAL
- OMIT_RELEASE_NOTES / RELEASE_NOTES_LOCATION

Note that if you want to vary the value of a variable for differbent builds
you can also "add" it in easy-build.sh and set it there.

BUILDING IMAGES
===============
After the basic configuration has been done, there are still a few variables
that need to be checked in easy-build.sh itself:
- CODENAME: set to the codename (e.g. etch, lenny, sid) of the Debian release
  for which you want to build CD/DVD images
- DI_CODENAME: set to the codename of Debian release from which D-I
  *components* (udebs) should be taken; normally same value as CODENAME
- DI_DIST/DI_WWW_HOME/DI_DIR: location from where D-I *images* should be
  taken; value must "match" the specified DI_CODENAME
- MAX_CDS, MAX_DVDS: only used when building full CD or DVD images

D-I images and components
-------------------------
It is essential that D-I images and components used to build the CD match.
For example, the kernel version included in the D-I image must be the same
as the kernel version of the kernel module udebs copied to the CD.

The easy-build.sh script offers four mutually exclusive options to specify
the source of D-I images. In theory more are possible, but the included
options should cover most use cases.
Make sure you have only one of the four options uncommented! And don't let
yourself be confused by the fact that the four options use different
variables.

If you keep to the following basic rules you should be OK.
1) If DI_CODENAME is a real Debian release (e.g. etch or lenny, but not sid)
   you should normally use the 1st or 2nd option. Use the 1st option if your
   local mirror includes D-I images, else use the the 2nd option.
2) If you use daily built D-I images (3rd option), DI_CODENAME should be set
   to "sid".
3) If you use custom images (4th option), DI_CODENAME should match the branch
   of the your D-I SVN checkout and build environment; further explanation of
   this is outside the scope of this document.

Examples
--------
Below are some basic examples how to run easy-build.sh. Examples for some
more advanced usages will be given in later sections.

1) Build a lenny netinst CD image for i386
- set CODENAME and DI_CODENAME to "lenny"
- select appropriate source for D-I images (1st or 2nd option)
- run './easy-build.sh NETINST'

2) Build the first three CD images for amd64 with KDE as desktop environment
- set MAX_CDS to "3"
- run './easy-build.sh -d kde CD amd64'

3) Build the full set of DVD images for sparc
- comment out MAX_DVDS
- run './easy-build.sh DVD sparc'

4) Build an i386 netinst to install testing using daily built D-I images
- set CODENAME to the codename for the current testing release
- set DI_CODENAME to "sid"
- select the 3rd option as source for D-I images
- run './easy-build.sh NETINST'

BUILDING MULTI-ARCH IMAGES
==========================
Multi-arch images are CDs or DVDs that can be used to install more than one
architecture. However, architectures cannot be randomly combined. The main
limitations for combining architectures are:
- boot loader files and configuration cannot conflict
- image size

The following architectures can safely be combined on a single image:
- i386, amd64 and powerpc
- alpha, hppa and ia64

When you combine two or three architectures on a single 680MB CD there
remains very little space after Debian Installer and base system packages
have been included. For that reason multi-arch CDs are normally created as
a netinst image. For example:
$ ./easy-build.sh NETINST i386 amd64 powerpc

A DVD has a lot more space and can easily include packages needed to install
a desktop environment. For example:
$ ./easy-build.sh DVD -d kde i386 amd64

It is even possible to include source packages on a DVD, which makes it
suitable to hand out at trade shows. For example:
$ ./easy-build.sh DVD i386 amd64 source

INCLUDING CUSTOM PACKAGES AND D-I COMPONENTS
============================================
# FIXME