| 1 |
debian-cd easy-build |
| 2 |
==================== |
| 3 |
|
| 4 |
INTRODUCTION |
| 5 |
============ |
| 6 |
easy-build.sh is a "wrapper" script around the more basic build.sh build |
| 7 |
script. It is designed to make building a specific image or set or images |
| 8 |
as easy as possible, while still offering all the flexibility of debian-cd. |
| 9 |
|
| 10 |
easy-build.sh supports the following variations: |
| 11 |
- businesscard, netinst and full CD images, and DVD images |
| 12 |
- single-architecture and multi-architecture images |
| 13 |
- optionally include source packages |
| 14 |
- select to install GNOME (default), KDE, LXDE or Xfce desktops as desktop |
| 15 |
task |
| 16 |
- create a combined LXDE/Xfce "light desktop" CD |
| 17 |
- create a businesscard or netinst CD, or DVD set supporting all four |
| 18 |
desktop environments |
| 19 |
- creates ISO files by default; creating jigdo files is possible |
| 20 |
- specify which Debian release to use |
| 21 |
- include custom versions of packages (debs) |
| 22 |
- specify which Debian Installer (D-I) version and source to use, including |
| 23 |
custom images |
| 24 |
- include custom versions of Debian Installer components (udebs) |
| 25 |
|
| 26 |
Using easy-build.sh is somewhat simpler than calling make directly or even |
| 27 |
than using build.sh as it splits the complex configuration of debian-cd |
| 28 |
into three levels: |
| 29 |
1) CONF.sh: basic configuration such as paths |
| 30 |
2) easy-build.sh: characteristicts of the CD/DVD set, for example: |
| 31 |
- Debian release |
| 32 |
- D-I version and source of D-I images |
| 33 |
- number of CDs or DVDs to generate |
| 34 |
3) command line parameters: |
| 35 |
- type of image (businesscard, netinst, full CD or DVD |
| 36 |
- which architecture(s) |
| 37 |
- which desktop to install |
| 38 |
|
| 39 |
easy-build.sh also ensures that "task files" are automatically updated as |
| 40 |
needed. If custom packages are included it can automatically generate a |
| 41 |
Packages file for the local repository: just copy the packages to the |
| 42 |
correct location and let easy-build.sh do the rest. |
| 43 |
|
| 44 |
Types of images & task definitions |
| 45 |
---------------------------------- |
| 46 |
easy-build.sh can be used to create four types of images: |
| 47 |
- businesscard CD: only contains Debian Installer; any packages neede for |
| 48 |
the installed system are retrieved from a mirror during the installation |
| 49 |
- netinst CD: contains Debian Installer and all packages needed to install a |
| 50 |
Debian "base system" (packages with priority important or higher) |
| 51 |
- full CD: same as netinst CD, but filled to capacity with additional |
| 52 |
packages based on "task" definitions; image size is 680MB |
| 53 |
- DVD: same as full CD, but with an image size of 4.7GB |
| 54 |
|
| 55 |
The businesscard and netinst CD are always a single image. The size of these |
| 56 |
images depends on the architecture. For i386 they are around 40MB and 150MB |
| 57 |
respectively. |
| 58 |
|
| 59 |
The full CD and DVD are sets of images, but the set can be limited to any |
| 60 |
number. The first image of the set always includes Debian Installer and |
| 61 |
packages needed for the base system. After that the first and following |
| 62 |
images are filled up to capacity with packages in the following order: |
| 63 |
- "essential" packages from tasksel tasks |
| 64 |
- "optional" packages from tasksel tasks |
| 65 |
- other packages sorted by popularity (popcon score) |
| 66 |
|
| 67 |
The basic order in which packages are included on full CDs and DVDs is |
| 68 |
defined in 'tasks/<CODENAME>/Debian'. The order in which tasksel tasks are |
| 69 |
included is defined in 'tasks/<CODENAME>/task.list*'. |
| 70 |
|
| 71 |
Current GNOME and KDE desktop environments are so large that only the |
| 72 |
packages needed to install one of them can be included on the first full CD. |
| 73 |
Therefore debian-cd supports creating a CD or DVD set targeted at a specific |
| 74 |
desktop environment: either GNOME, or KDE, or Xfce. |
| 75 |
The default 'task.list' is targeted at the GNOME desktop environment. |
| 76 |
|
| 77 |
It is possible to customize the debian-cd task definitions and even to |
| 78 |
customize tasksel, but that falls outside the scope of this document. |
| 79 |
|
| 80 |
CREATING A MIRROR OF THE ARCHIVE |
| 81 |
================================ |
| 82 |
debian-cd requires you to have a local mirror of the Debian archive, |
| 83 |
normally on the same machine where you run debian-cd. There are lots of |
| 84 |
methods to create a (partial) local archive. |
| 85 |
|
| 86 |
Make sure the following are included in your local archive: |
| 87 |
- ./dists/<codename>/main/debian-installer/binary-<arch>/ |
| 88 |
contains Debian Installer components (udebs) |
| 89 |
- ./doc/ |
| 90 |
- ./tools/ |
| 91 |
and optionally: |
| 92 |
- ./dists/<codename>/main/installer-<arch>/ |
| 93 |
contains Debian Installer images (official releases) |
| 94 |
|
| 95 |
One method is to use debmirror. An example script for creating a full or |
| 96 |
partial local mirror using debmirror suitable for use with debian-cd can be |
| 97 |
found at: http://alioth.debian.org/~fjp/debmirror/. |
| 98 |
|
| 99 |
BASIC CONFIGURATION |
| 100 |
=================== |
| 101 |
Most of the variables in CONF.sh can be left at their default values. Some |
| 102 |
just because their default value should be OK for most purposes, some |
| 103 |
because their value is set by easy-build.sh itself. |
| 104 |
|
| 105 |
The following variables that define paths *must* be set in CONF.sh: |
| 106 |
- MIRROR |
| 107 |
- TDIR |
| 108 |
- OUT |
| 109 |
- APTTMP |
| 110 |
|
| 111 |
You may also want to change the following variables: |
| 112 |
- CONTRIB: comment out if you only want to include packages from main |
| 113 |
- IMAGESUMS: comment out to skip creating checksums for images |
| 114 |
- OMIT_MANUAL |
| 115 |
- OMIT_RELEASE_NOTES / RELEASE_NOTES_LOCATION |
| 116 |
|
| 117 |
Note that if you want to vary the value of a variable for differbent builds |
| 118 |
you can also "add" it in easy-build.sh and set it there. |
| 119 |
|
| 120 |
BUILDING IMAGES |
| 121 |
=============== |
| 122 |
After the basic configuration has been done, there are still a few variables |
| 123 |
that need to be checked in easy-build.sh itself: |
| 124 |
- CODENAME: set to the codename (e.g. etch, lenny, sid) of the Debian release |
| 125 |
for which you want to build CD/DVD images |
| 126 |
- DI_CODENAME: set to the codename of Debian release from which D-I |
| 127 |
*components* (udebs) should be taken; normally same value as CODENAME |
| 128 |
- DI_DIST/DI_WWW_HOME/DI_DIR: location from where D-I *images* should be |
| 129 |
taken; value must "match" the specified DI_CODENAME |
| 130 |
- MAX_CDS, MAX_DVDS: only used when building full CD or DVD images |
| 131 |
|
| 132 |
D-I images and components |
| 133 |
------------------------- |
| 134 |
It is essential that D-I images and components used to build the CD match. |
| 135 |
For example, the kernel version included in the D-I image must be the same |
| 136 |
as the kernel version of the kernel module udebs copied to the CD. |
| 137 |
|
| 138 |
The easy-build.sh script offers four mutually exclusive options to specify |
| 139 |
the source of D-I images. In theory more are possible, but the included |
| 140 |
options should cover most use cases. |
| 141 |
Make sure you have only one of the four options uncommented! And don't let |
| 142 |
yourself be confused by the fact that the four options use different |
| 143 |
variables. |
| 144 |
|
| 145 |
If you keep to the following basic rules you should be OK. |
| 146 |
1) If DI_CODENAME is a real Debian release (e.g. etch or lenny, but not sid) |
| 147 |
you should normally use the 1st or 2nd option. Use the 1st option if your |
| 148 |
local mirror includes D-I images, else use the the 2nd option. |
| 149 |
2) If you use daily built D-I images (3rd option), DI_CODENAME should be set |
| 150 |
to "sid". |
| 151 |
3) If you use custom images (4th option), DI_CODENAME should match the branch |
| 152 |
of the your D-I SVN checkout and build environment; further explanation of |
| 153 |
this is outside the scope of this document. |
| 154 |
|
| 155 |
Examples |
| 156 |
-------- |
| 157 |
Below are some basic examples how to run easy-build.sh. Examples for some |
| 158 |
more advanced usages will be given in later sections. |
| 159 |
|
| 160 |
1) Build a lenny netinst CD image for i386 |
| 161 |
- set CODENAME and DI_CODENAME to "lenny" |
| 162 |
- select appropriate source for D-I images (1st or 2nd option) |
| 163 |
- run './easy-build.sh NETINST' |
| 164 |
|
| 165 |
2) Build the first three CD images for amd64 with KDE as desktop environment |
| 166 |
- set MAX_CDS to "3" |
| 167 |
- run './easy-build.sh -d kde CD amd64' |
| 168 |
|
| 169 |
3) Build the full set of DVD images for sparc |
| 170 |
- comment out MAX_DVDS |
| 171 |
- run './easy-build.sh DVD sparc' |
| 172 |
|
| 173 |
4) Build an i386 netinst to install testing using daily built D-I images |
| 174 |
- set CODENAME to the codename for the current testing release |
| 175 |
- set DI_CODENAME to "sid" |
| 176 |
- select the 3rd option as source for D-I images |
| 177 |
- run './easy-build.sh NETINST' |
| 178 |
|
| 179 |
BUILDING MULTI-ARCH IMAGES |
| 180 |
========================== |
| 181 |
Multi-arch images are CDs or DVDs that can be used to install more than one |
| 182 |
architecture. However, architectures cannot be randomly combined. The main |
| 183 |
limitations for combining architectures are: |
| 184 |
- boot loader files and configuration cannot conflict |
| 185 |
- image size |
| 186 |
|
| 187 |
The following architectures can safely be combined on a single image: |
| 188 |
- i386, amd64 and powerpc |
| 189 |
- alpha, hppa and ia64 |
| 190 |
|
| 191 |
When you combine two or three architectures on a single 680MB CD there |
| 192 |
remains very little space after Debian Installer and base system packages |
| 193 |
have been included. For that reason multi-arch CDs are normally created as |
| 194 |
a netinst image. For example: |
| 195 |
$ ./easy-build.sh NETINST i386 amd64 powerpc |
| 196 |
|
| 197 |
A DVD has a lot more space and can easily include packages needed to install |
| 198 |
a desktop environment. For example: |
| 199 |
$ ./easy-build.sh DVD -d kde i386 amd64 |
| 200 |
|
| 201 |
It is even possible to include source packages on a DVD, which makes it |
| 202 |
suitable to hand out at trade shows. For example: |
| 203 |
$ ./easy-build.sh DVD i386 amd64 source |
| 204 |
|
| 205 |
INCLUDING CUSTOM PACKAGES, D-I COMPONENTS and D-I IMAGES |
| 206 |
======================================================== |
| 207 |
easy-build.sh makes it relatively simple to include custom packages, both |
| 208 |
regular packages (debs) and debian-installer components (udebs), in CD |
| 209 |
images. The main rule to keep in mind is that if the package also exists |
| 210 |
in the official archive, the version number of your custom package must |
| 211 |
be higher than the one of the official package. |
| 212 |
|
| 213 |
Besides custom debian-installer components (udebs), you can also use custom |
| 214 |
or locally built debian-installer images (kernel, initrd and related files). |
| 215 |
|
| 216 |
You should always ensure that udebs included on a CD match the udebs used |
| 217 |
when building the debian-installer image you include. For example kernel |
| 218 |
versions need to match, but also versioned dependensies between udebs |
| 219 |
(and note that not all dependencies between udebs are declared explicitly). |
| 220 |
And two udebs from the same source package should in principle have the |
| 221 |
same version even if one is included in the initrd and the other is loaded |
| 222 |
from the CD during the installation. |
| 223 |
|
| 224 |
Whether custom debs and udebs are used is determined by the environment |
| 225 |
variable LOCAL. Whether custom D-I images are used is determined by |
| 226 |
selecting the correct source from them, in most cases that will be by |
| 227 |
setting DI_DIR (see comments in easy-build.sh). Both variables can be set |
| 228 |
in easy-build.sh. |
| 229 |
|
| 230 |
Using custom packages |
| 231 |
--------------------- |
| 232 |
The repository for the custom packages has the same basic structure as an |
| 233 |
official mirror. The main difference is the category: instead of "main" |
| 234 |
(or "contrib" or "non-free") this has to be "local". You should also make |
| 235 |
sure to use the release codename and not the suite. |
| 236 |
|
| 237 |
So you get for example: |
| 238 |
.../dists/lenny/local/binary-amd64/ |
| 239 |
.../dists/lenny/local/binary-i386/ |
| 240 |
.../dists/lenny/local/debian-installer/binary-amd64/ |
| 241 |
.../dists/lenny/local/debian-installer/binary-i386/ |
| 242 |
.../dists/sid/local/binary-amd64/ |
| 243 |
.../dists/sid/local/binary-i386/ |
| 244 |
.../dists/sid/local/debian-installer/binary-amd64/ |
| 245 |
.../dists/sid/local/debian-installer/binary-i386/ |
| 246 |
|
| 247 |
Note that debs will be taken from 'dists/$CODENAME/...' while udebs will be |
| 248 |
taken from 'dists/$DI_CODENAME/...'. So if CODENAME and DI_CODENAME have |
| 249 |
different values (e.g. when taking debs from testing but using D-I based on |
| 250 |
unstable), you will need to place your custom debs and udebs under different |
| 251 |
codenames. |
| 252 |
|
| 253 |
The local category does not need to have a Release file, but each |
| 254 |
'binary-<arch>' directory must have a Packages file. |
| 255 |
|
| 256 |
It is possible to have the packages themselves in a pool directory, but it |
| 257 |
is probably easier to just place them under the 'binary-<arch>' directories. |
| 258 |
You can group packages in subdirectories. |
| 259 |
|
| 260 |
By default debian-cd will look for the "local" category in the same place |
| 261 |
as the official mirror (as defined by the envvar MIRROR), but in most cases |
| 262 |
it will be simpler to specify an alternative location by setting the |
| 263 |
environment variable LOCALDEBS in your CONF.sh. In that case you can also |
| 264 |
let easy-build.sh take care of generating an updated Packages.gz file for |
| 265 |
each source that is used in a build by setting the envvar UPDATE_LOCAL in |
| 266 |
easy-build.sh (see tools/Packages-gen). |
| 267 |
|
| 268 |
Example, assuming we are building for and i386 CD for lenny: |
| 269 |
1) in CONF.sh, set for example: |
| 270 |
export MIRROR=/srv/mirror/debian |
| 271 |
export LOCALDEBS=/srv/mirror/custom |
| 272 |
2) create the following directories: |
| 273 |
/srv/mirror/custom/dists/lenny/local/binary-i386 |
| 274 |
/srv/mirror/custom/dists/lenny/local/debian-installer/binary-i386 |
| 275 |
3) copy your custom debs to the first directory |
| 276 |
4) copy your custom udebs to the second directory |
| 277 |
5) in easy-build.sh, set: |
| 278 |
export LOCAL=1 |
| 279 |
UPDATE_LOCAL=1 |
| 280 |
|
| 281 |
Note that debian-cd will fail if you set LOCAL but the "local" directory for |
| 282 |
a codename/arch/section that is referenced in a build does not exist. |
| 283 |
You will need to create the 'dists/<codename>/local' directories, but if |
| 284 |
UPDATE_LOCAL is set, easy-build.sh will automatically create any missing |
| 285 |
'binary-<codename>' subdirectories and (empty) Packages.gz files. |
| 286 |
|
| 287 |
Using custom debian-installer images |
| 288 |
------------------------------------ |
| 289 |
Note that the build target used and the way images are organized under the |
| 290 |
build/dest directory by the debian-installer build system varies per |
| 291 |
architecture. The example below should work for i386 and amd64, but may need |
| 292 |
to be adjusted for other architectures. |
| 293 |
|
| 294 |
Example: |
| 295 |
1) create a directory, for example: |
| 296 |
/srv/mirror/custom/images/i386/ |
| 297 |
2) build the d-i images (in the installer/build directory) using: |
| 298 |
$ make reallyclean; fakeroot make build_cdrom_isolinux |
| 299 |
3) copy the images using: |
| 300 |
$ cp -r dest/cdrom /srv/mirror/custom/images/i386/ |
| 301 |
4) in easy-build.sh, set: |
| 302 |
export DI_DIR="/srv/mirror/custom/images/%ARCH%" |
| 303 |
|
| 304 |
'%ARCH%' will be automatically expanded to the correct architecture whe |
| 305 |
debian-cd is run. |