diff --git a/README b/README index 9830067c..7ac2241c 100644 --- a/README +++ b/README @@ -39,8 +39,8 @@ Other: ------------------------------- -For the people that don't have time, here's the quick explanation: -================================================================== +For the people that don't have time, here's the quick explanation +================================================================= Edit the CONF.sh and change the PATHs for the mirror and so on. $ sensible-editor CONF.sh @@ -53,6 +53,11 @@ However, you really should consider reading further for more information. You can also take a look at build.sh and build_all.sh for an automatized way of building CD images. +The script easy-build.sh offers the easiest way to build a specific image +or set of images, but is still very flexible and powerful. It is the +recommended tool for building test images and for people new to debian-cd. +See the file README.easy-build for further info. + How to build a CD set - step by step ==================================== diff --git a/README.easy-build b/README.easy-build new file mode 100644 index 00000000..95ffbed7 --- /dev/null +++ b/README.easy-build @@ -0,0 +1,204 @@ + 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/Debian-'. The order in which tasksel tasks are +included is defined in 'tasks/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//main/debian-installer/binary-/ + contains Debian Installer components (udebs) +- ./doc/ +- ./indices/ +- ./tools/ +and optionally: +- ./dists//main/installer-/ + 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 diff --git a/debian/rules b/debian/rules index afbd004d..fb4065ab 100755 --- a/debian/rules +++ b/debian/rules @@ -24,7 +24,7 @@ install-stamp: build-stamp # Add here commands to install the package into debian/tmp. cp -r tools tasks data Makefile README README.devel build.sh \ - build_all.sh update-cd easy-build.sh \ + build_all.sh update-cd easy-build.sh README.easy-build \ debian/debian-cd/usr/share/debian-cd/ cp debian/CONF.sh debian/debian-cd/etc/debian-cd/conf.sh ln -sf /etc/debian-cd/conf.sh \