| 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 MD5/SHA5 sums 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.
|
Parent Directory
| 
Revision Log