| 1 |
debian-cd
|
| 2 |
=========
|
| 3 |
|
| 4 |
Copyright 1999-2001 Raphaël Hertzog <hertzog@debian.org> and others,
|
| 5 |
2004-2010 Steve McIntyre <steve@einval.com>
|
| 6 |
This set of tools is licensed under the General Public License version
|
| 7 |
2 or any later version. You can find it in
|
| 8 |
/usr/share/common-licenses/GPL on a Debian GNU system.
|
| 9 |
|
| 10 |
Some of the ideas here (a loooong time ago) came from Steve McIntyre's
|
| 11 |
slink_cd script.
|
| 12 |
|
| 13 |
Thanks also to all the contributors on the debian-cd mailing list.
|
| 14 |
|
| 15 |
What is needed?
|
| 16 |
===============
|
| 17 |
Software:
|
| 18 |
- the apt-get (>= 0.3.11.1) tool
|
| 19 |
- perl (>= 5.004)
|
| 20 |
- bash (or another POSIX shell)
|
| 21 |
- make
|
| 22 |
- cpp
|
| 23 |
- mkisofs/genisoimage
|
| 24 |
- the perl Digest::MD5 module
|
| 25 |
- the perl Compress::Zlib module
|
| 26 |
- lynx (for text version of README.html) and todos from sysutils
|
| 27 |
to convert docs to DOS format (although you can rip that out, too)
|
| 28 |
- if you want to generate jigdo files: jigdo-file (see below)
|
| 29 |
Other:
|
| 30 |
- apt-utils (for apt-ftparchive)
|
| 31 |
- lots of free space on your disks
|
| 32 |
- a Debian mirror, on a partition where you can write.
|
| 33 |
If you can't write on it then you may try to use a symlink farm,
|
| 34 |
but it's not the recommended way to build Debian CDs.
|
| 35 |
|
| 36 |
|
| 37 |
-------------------------------
|
| 38 |
- GENERATING DEBIAN CD IMAGES -
|
| 39 |
-------------------------------
|
| 40 |
|
| 41 |
|
| 42 |
For the people that don't have time, here's the quick explanation
|
| 43 |
=================================================================
|
| 44 |
|
| 45 |
Edit the CONF.sh and change the PATHs for the mirror and so on.
|
| 46 |
$ sensible-editor CONF.sh
|
| 47 |
$ . CONF.sh
|
| 48 |
$ make distclean
|
| 49 |
$ make status
|
| 50 |
$ make official_images
|
| 51 |
|
| 52 |
However, you really should consider reading further for more information.
|
| 53 |
You can also take a look at build.sh and build_all.sh for an automated
|
| 54 |
way of building CD images.
|
| 55 |
|
| 56 |
The script easy-build.sh offers the easiest way to build a specific image
|
| 57 |
or set of images, but is still very flexible and powerful. It is the
|
| 58 |
recommended tool for building test images and for people new to debian-cd.
|
| 59 |
See the file README.easy-build for further info.
|
| 60 |
|
| 61 |
How to build a CD set - step by step
|
| 62 |
====================================
|
| 63 |
|
| 64 |
If you haven't already, change to the /usr/share/debian-cd/ directory
|
| 65 |
(or, alternatively, set the variable BASEDIR in CONF.sh to point
|
| 66 |
there).
|
| 67 |
|
| 68 |
The process of building a CD is composed of the following steps:
|
| 69 |
|
| 70 |
- first configure what is needed in CONF.sh and source it in your shell:
|
| 71 |
|
| 72 |
$ . CONF.sh
|
| 73 |
|
| 74 |
The exported environment variables will be used by all the
|
| 75 |
tools involved here (Makefiles, perl scripts, shell scripts).
|
| 76 |
|
| 77 |
If you want to build CD images for more than one arch, you will
|
| 78 |
have to build them one after the other (you may use a shell
|
| 79 |
script for this).
|
| 80 |
|
| 81 |
Note that the temporary dir must be on the same device as the
|
| 82 |
mirror because debian-cd uses hardlinks for generating an image
|
| 83 |
tree. If you can't do this, you'll have to use a symlink farm.
|
| 84 |
The symlink farm is explained at the end of this README.
|
| 85 |
|
| 86 |
Keep in mind that the environment variables will stay in the
|
| 87 |
environment after your debian-cd run, and may interfere with
|
| 88 |
other program using the same variables (e.g. kernel-package).
|
| 89 |
So if you want to be 100% safe, run debian-cd in a
|
| 90 |
separate shell that you can leave after you're done.
|
| 91 |
|
| 92 |
- then we clean everything that may still be there from previous runs:
|
| 93 |
|
| 94 |
$ make distclean
|
| 95 |
|
| 96 |
- then we initialize the temporary directory used for the build:
|
| 97 |
|
| 98 |
$ make status
|
| 99 |
|
| 100 |
If this has failed then this will be automatically launched:
|
| 101 |
|
| 102 |
$ make correctstatus
|
| 103 |
|
| 104 |
Note however that "make status" should never fail if it is
|
| 105 |
used for building a CD set for the stable release...
|
| 106 |
|
| 107 |
- now you can decide what you want on your CDs
|
| 108 |
|
| 109 |
Note that task files are always taken from the subdirectory in ./tasks/
|
| 110 |
that matches the CODENAME environment variable. At the beginning of a
|
| 111 |
build these "static" task files are copied to the working directory.
|
| 112 |
During the build some additional task files - that are referenced from
|
| 113 |
the static task files - are generated automatically using scripts from
|
| 114 |
the ./tools directory.
|
| 115 |
|
| 116 |
Examples:
|
| 117 |
|
| 118 |
$ make packagelists TASK=Debian-generic COMPLETE=1
|
| 119 |
|
| 120 |
or
|
| 121 |
|
| 122 |
$ make packagelists TASK=Debian-kde COMPLETE=0
|
| 123 |
|
| 124 |
or
|
| 125 |
|
| 126 |
$ export NONFREE=1; make packagelists TASK=your-task-here COMPLETE=1
|
| 127 |
|
| 128 |
or for something like an official image for the USA (without non-free):
|
| 129 |
|
| 130 |
$ make packagelists COMPLETE=1
|
| 131 |
|
| 132 |
.... take a look at the file tasks/* to see the options you can have :)
|
| 133 |
|
| 134 |
You can change the behaviour of this command with the following
|
| 135 |
variables:
|
| 136 |
- if NONFREE is set, then packages from non-free will be allowed
|
| 137 |
(NONFREE must be exported to all sub-shells)
|
| 138 |
- if EXTRANONFREE is set, then non-free packages will be included
|
| 139 |
on an extra CD (the last CD in fact). Don't use NONFREE and
|
| 140 |
EXTRANONFREE at the same time!
|
| 141 |
(EXTRANONFREE must be exported to all sub-shells)
|
| 142 |
- if COMPLETE is set, all packages that are not listed in the
|
| 143 |
selected task file will be included at the end
|
| 144 |
- setting INSTALLER_CD will use an appropriate task file for
|
| 145 |
building small CDs (businesscard and netinst)
|
| 146 |
|
| 147 |
- now, we'll start making temporary trees:
|
| 148 |
|
| 149 |
$ make image-trees
|
| 150 |
|
| 151 |
This will first work sort the list of packages for each architecture
|
| 152 |
into order so that standard, required, important and base packages
|
| 153 |
are placed first, then other packages will be added in the order
|
| 154 |
given modulo dependency ordering. Once the sorted list is created,
|
| 155 |
the different architecture lists will be merged (if more than one
|
| 156 |
architecture is selected).
|
| 157 |
|
| 158 |
Then the code will start laying out temporary directory trees for
|
| 159 |
the CDs. In order, this includes the following steps:
|
| 160 |
|
| 161 |
- Creating an empty directory layout
|
| 162 |
- Generating an image label and volume ID and other metadata such as
|
| 163 |
debian-installer information files
|
| 164 |
- Add documentation and installation/upgrade tools
|
| 165 |
- Add Release files and other archive metadata
|
| 166 |
- Make the image bootable for the selected architecture(s)
|
| 167 |
- Start generating the md5sum.txt file
|
| 168 |
|
| 169 |
If you want to use boot-floppies built by yourself you can add
|
| 170 |
a parameter BOOTDISKS=<dir> which specifies the directory where
|
| 171 |
they are. Note that $BOOTDISKS/current must be a symlink to the
|
| 172 |
real directory and it must follow the same setup as the FTP
|
| 173 |
mirror. Your boot-floppies must also be on the same partition as
|
| 174 |
your mirror and temporary dir (hardlinks are used here too).
|
| 175 |
|
| 176 |
Once the disc tree has all of this start data, we start filling the
|
| 177 |
directory trees with packages from the sorted list. The size of the
|
| 178 |
image to be created is set using DISKTYPE in CONF.sh; if the
|
| 179 |
standard sizes do not match what you're after, use DISKTYPE=CUSTOM
|
| 180 |
and specify your own size using CUSTOMSIZE. The algorithm is simple
|
| 181 |
for adding packages:
|
| 182 |
|
| 183 |
- link the package into the temporary disc tree
|
| 184 |
- append the metadata to the appropriate Packages or Sources file
|
| 185 |
- add md5sum information for the added file(s) to the md5sum.txt file
|
| 186 |
|
| 187 |
This continues until the temporary tree grows one package *too
|
| 188 |
large* for the selected image size. At that point, we roll back the
|
| 189 |
last set of changes associated with that package. Then:
|
| 190 |
|
| 191 |
- check if the disc contains all the packages needed to install a base system
|
| 192 |
- finish off the Release file, using the checksums of the
|
| 193 |
Packages/Sources files we generated
|
| 194 |
- finish off the md5sum.txt file
|
| 195 |
|
| 196 |
Next, we continue to the next disc tree, using the same process:
|
| 197 |
start it, copy packages in until they overflow, roll back and
|
| 198 |
finish. And repeat. Each time a package is found to be too large to
|
| 199 |
fit inside an image, it will be kept back and will (obviously) be
|
| 200 |
the first package placed into the next disc tree.
|
| 201 |
|
| 202 |
- now we can create the images:
|
| 203 |
|
| 204 |
$ make images
|
| 205 |
|
| 206 |
If you don't have enough space for all images, you can generate
|
| 207 |
only one image (of the second CD for example) with:
|
| 208 |
|
| 209 |
$ make image CD=2
|
| 210 |
|
| 211 |
Note: here we use "make images", but you could as well use
|
| 212 |
"make official_images" since the latter is the same as the former
|
| 213 |
with some dependencies on targets that you already launched
|
| 214 |
(make bootable packages sources).
|
| 215 |
|
| 216 |
- if you want to generate a MD5SUMS file with the md5sums of the
|
| 217 |
images you can do it with:
|
| 218 |
|
| 219 |
$ make imagesums
|
| 220 |
|
| 221 |
Official images
|
| 222 |
===============
|
| 223 |
|
| 224 |
If you use make official_images you're building CD images that have
|
| 225 |
the same properties than official CD images but they still doesn't
|
| 226 |
have the name of "Official Images". The name of the images is given
|
| 227 |
by setting the OFFICIAL and DEBVERSION environment variable (check
|
| 228 |
CONF.sh).
|
| 229 |
|
| 230 |
Please never ever use the "Official" name for a CD image that you
|
| 231 |
built yourself. The only images that can be called "Official" are the
|
| 232 |
ones built by Debian itself and which are provided on Debian's
|
| 233 |
servers.
|
| 234 |
|
| 235 |
The default configuration shipped with this package will automatically
|
| 236 |
name the images "Unofficial". CD will work exactly in the same way
|
| 237 |
with all Debian tools, only the label is different. That means you
|
| 238 |
can use build.sh and build_all.sh to build your "Unofficial" images
|
| 239 |
without modifying anything.
|
| 240 |
|
| 241 |
|
| 242 |
Local packages
|
| 243 |
==============
|
| 244 |
|
| 245 |
If you provide some custom made packages and you want to put them on
|
| 246 |
Debian CD set you can do it. Simply put your packages in
|
| 247 |
$MIRROR/dists/$CODENAME/local/binary-$ARCH/<section>.
|
| 248 |
The organization of this sub-tree is the same than what you can find
|
| 249 |
in the main, contrib or non-free part. You may use different section
|
| 250 |
names if you want. Be sure to create Packages files (and Sources.gz if you
|
| 251 |
include sources).
|
| 252 |
|
| 253 |
You can also put your local packages under $MIRROR/pool/local (just a new
|
| 254 |
facility for people who don't want packages under dists/). To include local
|
| 255 |
packages, the LOCAL environment variable must be set to "1" while building
|
| 256 |
the CDs.
|
| 257 |
|
| 258 |
You can also set the LOCALDEBS environment variable, and it will be used
|
| 259 |
instead of MIRROR when looking for local packages.
|
| 260 |
|
| 261 |
|
| 262 |
Additional targets
|
| 263 |
==================
|
| 264 |
|
| 265 |
Jigdo
|
| 266 |
-----
|
| 267 |
You may also want to make the CD images available in jigdo format.
|
| 268 |
Jigsaw Download, the successor to the Pseudo-Image Kit.
|
| 269 |
See http://www.debian.org/CD/jigdo-cd/ for more information on jigdo.
|
| 270 |
|
| 271 |
Set the DOJIGDO and related variables in CONF.sh. This is no separate target
|
| 272 |
for jigdo, merely a modification of the "images" targets. You can choose
|
| 273 |
only .iso generation (default), only .jigdo generation (for highly reduced
|
| 274 |
disk usage), or both .iso and .jigdo generation.
|
| 275 |
|
| 276 |
To generate the jigdo files and templates, you need an
|
| 277 |
appropriately-patched version of mkisofs/genisoimage, as shipped in
|
| 278 |
Debian Etch.
|
| 279 |
|
| 280 |
The MD5SUMS file generated by the "imagesums" target will contain the MD5
|
| 281 |
checksums of all generated images, regardless of the DOJIGDO setting. If
|
| 282 |
no full iso image is available, the MD5sum will be extracted from the
|
| 283 |
.template file. A note in the Makefile shows how the original file size
|
| 284 |
can be extracted from the .template in a similar way.
|
| 285 |
|
| 286 |
About jigdo "fallback servers":
|
| 287 |
|
| 288 |
jigdo works by downloading individual packages and other files from a
|
| 289 |
normal Debian mirror, and using them to regenerate a CD/DVD image.
|
| 290 |
However, the content of Debian mirrors changes over time, files are
|
| 291 |
added and removed. But jigdo must have access to all files needed for
|
| 292 |
the image it has to regenerate, even those that have been removed from
|
| 293 |
the normal Debian mirrors.
|
| 294 |
|
| 295 |
A fallback server contains a backup of the Debian FTP space for the
|
| 296 |
moment the .jigdo files were generated. This backup is made available
|
| 297 |
under a certain URL which is written to the .jigdo files. jigdo will
|
| 298 |
*only* revert to the fallback server after an unsuccessful attempt to
|
| 299 |
retrieve a file from the normal user-selected Debian mirror, so the
|
| 300 |
bandwidth requirements are modest.
|
| 301 |
|
| 302 |
A fallback is even necessary for .jigdo files of the stable release,
|
| 303 |
because some files (typically documentation or boot floppies) can
|
| 304 |
change at any time.
|
| 305 |
|
| 306 |
debian-cd allows you to automatically create a directory on disc which
|
| 307 |
is suitable for use as a fallback mirror. It is populated with hard
|
| 308 |
links to the archive contents. In CONF.sh, simply supply as
|
| 309 |
JIGDOFALLBACKPATH the name of the directory, and as JIGDOFALLBACKURLS
|
| 310 |
the URLs under which it will be made available.
|
| 311 |
|
| 312 |
About the hook system
|
| 313 |
=====================
|
| 314 |
|
| 315 |
A hook script can be executed at different times during the CD build
|
| 316 |
process to customise your CDs. You can specify the script by setting
|
| 317 |
the various HOOK variables in CONF.sh; look there for more information
|
| 318 |
about what hook points are available.
|
| 319 |
|
| 320 |
About the symlink farm
|
| 321 |
======================
|
| 322 |
|
| 323 |
If you don't have write access on the disk where you have the mirror
|
| 324 |
or if for another reason hardlink cannot be used, you can try to
|
| 325 |
use a symlink farm. Instead of having real files, your temporary tree
|
| 326 |
will be filled with symlinks that mkhybrid will change into files when
|
| 327 |
it will build the image. You'll need to use a special options. You
|
| 328 |
have 2 lines of options in CONF.sh as examples.
|
| 329 |
|
| 330 |
I've never tested the symlink farm ... it may well generate unusable
|
| 331 |
images. Don't use it for ISO images that will used by many users.
|
| 332 |
|
| 333 |
Note that you will also need a patched mkhybrid that does support the
|
| 334 |
-F option. Have a look here about it :
|
| 335 |
http://www.chiark.greenend.org.uk/~stevem/DebianCD/
|
Parent Directory
| 
Revision Log