Contents of /branches/EFI_support/README

YACS - Yet Another CD Script :-)
================================
(better known as debian-cd)

Copyright 1999 Raphaël Hertzog <hertzog@debian.org>
This set of tools is licensed under the General Public License
version 2 or any later version. You can find it in 
/usr/share/common-licenses/GPL on a Debian GNU system.

Thanks to Steve McIntyre <stevem@chiark.greenend.org.uk> for his
work on slink_cd/debian_cd. Some ideas come from his script.

Thanks to all the contributors on the debian-cd mailing list.

What is needed ?
================
Software :
- the apt-get (>= 0.3.11.1) tool
- perl (>= 5.004)
- bash (or another POSIX shell)
- make
- mkisofs/mkhybrid (mkisofs also provides the isoinfo binary used by the
  Pseudo Image Kit)
- dpkg-multicd package (for dpkg-scanpackages with -m option)
- the perl MD5 module
- dpkg-dev (>= 1.4.1.6) (for dpkg-scansources)
Other :
- lots of free space on your disks
- a Debian mirror (on a partition where you can write, if you can't write
  on it then you may try to use a symlink farm but it's not the
  recommended way to build Debian CDs)

                -------------------------------
                - GENERATING DEBIAN CD IMAGES -
                -------------------------------


For people that do not have time, here's the quick explanation :
================================================================

Edit the CONF.sh and change the PATHs for the mirror and so on.
$ vim CONF.sh
$ . CONF.sh
$ make status
$ make list COMPLETE=1 SIZELIMIT1=576716800
$ make official_images
[ or if you want only binary images :
  $ make bin-official_images ]

But you really should consider reading further for more information.


How to build a CD set - step by step
====================================

If not yet done, cd to the /usr/share/debian-cd/ directory.

The process of building a CD is decomposed as follow :

- first configure what is needed in CONF.sh and source it
  in your shell
  $ . CONF.sh
  The exported environment variables will be used by all the
  tools involved here (Makefiles, perl scripts, shell scripts).

  If you want to build CD images for more than one arch, you will
  have to build them one after the other (you may use a shell
  script for this).

  Note that the temporary dir must be on the same device than the
  mirror because debian-cd uses hardlinks for generating an image 
  tree. If you can't do this, you'll have to use the symlink farm.
  The symlink farm is explained at the end of this README.

- now we'll check if your mirror is ok (with good Packages files) :
  $ make mirrorcheck

- then you will have to launch this for initializing the
  temporary directory used for the build :
  $ make status
  If this has failed then this will be automatically launched :
  $ make correctstatus
  However note that make status should never fail if it is
  used for building a CD set for the stable release ...

- now you can decide what you want on your CDs
  $ make list TASK=tasks/debian-2.2 COMPLETE=1
  or
  $ make list TASK=tasks/gnome COMPLETE=0 SIZELIMIT=576716800
  or
  $ export NONFREE=1; make list TASK=tasks/kde COMPLETE=1
  or for something like an official image for the USA (without non-US &
  non-free) :
  $ make COMPLETE=1 SIZELIMIT1=576716800
  .... take a look at the file tasks/* to see the options you can have :)
  
  You can change the behaviour of this command with the following
  variables :
  - if NONUS is set, then packages from non-US will be allowed (remember
    that the value of NONUS must be the path to the non-US mirror
    if you have one)
  - if NONFREE is set, then packages from non-free will be allowed
    (NONFREE must be exported to all sub-shells)
  - if COMPLETE is set, all packages that are not listed in the
    selected task file will be included at the end
  - if SIZELIMIT is set, it will be used as the maximum size that
    we can put into each CD
  - if SIZELIMIT<X> (with <X> beeing a integer) is set, it will be used 
    as the maximum size of the X'th binary CD. SIZELIMIT<X> overrides
    SIZELIMIT ...
  - if SRCSIZELIMIT is set, it's used as the maximum size for source CD
  - if SRCSIZELIMIT<X> (with <X> beeing an integer) is set, it will be
    used as the maximum size of the X'th source CD

  This target calls the targets "bin-list" and "src-list" that can be used to
  build only binary CDs or only source CDs.

- it may be time to add the disks-arch stuff and to make the CDs bootable
  $ make bootable
  This does affect only the binary CDs.

  If you want to use boot-floppies built by yourself you can give
  a parameter BOOTDISKS=<dir> giving the directory where
  they are (note that $BOOTDISKS/current must be a symlink to the
  real directory, it must follow the same setup than in the FTP
  mirror). Your boot-floppies must also be on the same partiton than
  your mirror & temporary dir (hardlinks are used here too).

- now, we'll add the binary packages to the temporary tree :
  $ make packages

- and we'll add the sources to the temporary tree :
  $ make sources

- if you want to install additional files :
  make bin-extras CD=1 ROOTSRC=/home/ftp/ DIR=goodies/wordperfect
  make src-extras CD=3 ROOTSRC=/home/ftp/ DIR=goodies/kernel-2.3

  The first will copy /home/ftp/goodies/wordperfect/ on the first binary
  CD. It will be in <root of the cd>/goodies/wordperfect ... you can call
  make extras multiple times if you need more. Please note that
  the files to be copied should be on the same partition than
  your mirror (unless you use a symlink farm).

  If you want to do customize your CD even more, you can use the hook
  system. Read below about them.

- We can add an md5sum.txt file on each CD to enable users to check their
  files :
  $ make md5list
  This does call the targets 'bin-md5list' and 'src-md5list'. You can
  choose to call only bin-md5list if you're building only binary images.

- now we can create the images
  $ make images
  If you don't have enough space for all images, you can generate 
  only one image (of the second binary CD for example) with :
  $ make bin-image CD=2
  Of course if you want to build all binary images you'll use :
  $ make bin-images
  And "make src-images" will generate the sources images.

- if you want to generate a MD5SUMS file with the md5sums of the
  images you can do it with :
  $ make imagesums


Local packages
==============

If you provide some custom made packages and you want to put them on
Debian CD set you can do it. Simply put your packages in
$MIRROR/dists/$CODENAME/local/binary-$ARCH/<section>.
The organization of this sub-tree is the same than what you can find
in the main, contrib or non-free part. You may use different section
names if you want. Be sure to create Packages files (and Sources.gz if you
include sources). 

To include local packages, the LOCAL environment variable must be set
to "1" while building the CDs.


Additionnal targets
===================

Pseudo Image Kit
----------------
Those of you, who will make images available to people for download may
consider using the Pseudo Image Kit (cf http://cdimage.debian.org for more
information). That's why you can launch "make pi-makelist" that will generate
the *.list files for the images you've just generated.

The tools/pi-makelist script needs the isoinfo binary. You can get the
sources from http://www.fokus.gmd.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html

Alternatively (and certainly simpler for people using Debian system), the
isoinfo binary is in the mkisofs package (since Debian potato at least).


About the hook system
=====================

A hook script can be executed at different times. You can specify the
script by setting the HOOK variable to the script filename. It will
get 2 arguments, the first is the CD number. The second depends on
where/when the hook script is called. It can be 'before-scanpackages'
or 'before-mkisofs' (their values are explicit ...). When the script
is called, the current directory will be the temporary directory used for
the build (aka $TDIR/$CODENAME-$ARCH).

There are hooks only for binary CDs at the present time. If HOOK is not
set, it will look for a script $BASEDIR/tools/$CODENAME.hook.


About the symlink farm
======================

If you don't have write access on the disk where you have the mirror
or if for another reason hardlink cannot be used, you can try to
use a symlink farm. Instead of having real files, your temporary tree
will be filled with symlinks that mkhybrid will change into files when
it will build the image. You'll need to use a special options. You
have 2 lines of options in CONF.sh as examples.

I've never tested the symlink farm ... it may well generate unusable
images. Don't use it for ISO images that will used by many users.

Note that you will also need a patched mkhybrid that does support the
-F option. Have a look here about it :
http://www.chiark.greenend.org.uk/~stevem/DebianCD/

The mkhybrid package in Debian does support this -F option since 
potato (Debian 2.2).
1	aph	43	YACS - Yet Another CD Script :-)
2			================================
3	hertzog	59	(better known as debian-cd)
4	aph	43
5			Copyright 1999 Raphaël Hertzog <hertzog@debian.org>
6			This set of tools is licensed under the General Public License
7			version 2 or any later version. You can find it in
8			/usr/share/common-licenses/GPL on a Debian GNU system.
9
10			Thanks to Steve McIntyre <stevem@chiark.greenend.org.uk> for his
11			work on slink_cd/debian_cd. Some ideas come from his script.
12
13	hertzog	59	Thanks to all the contributors on the debian-cd mailing list.
14
15	aph	43	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	hertzog	60	- mkisofs/mkhybrid (mkisofs also provides the isoinfo binary used by the
23			Pseudo Image Kit)
24	aph	43	- dpkg-multicd package (for dpkg-scanpackages with -m option)
25			- the perl MD5 module
26			- dpkg-dev (>= 1.4.1.6) (for dpkg-scansources)
27			Other :
28			- lots of free space on your disks
29			- a Debian mirror (on a partition where you can write, if you can't write
30			on it then you may try to use a symlink farm but it's not the
31			recommended way to build Debian CDs)
32
33			-------------------------------
34			- GENERATING DEBIAN CD IMAGES -
35			-------------------------------
36	hertzog	60
37
38	aph	43	For people that do not have time, here's the quick explanation :
39			================================================================
40
41			Edit the CONF.sh and change the PATHs for the mirror and so on.
42			$ vim CONF.sh
43			$ . CONF.sh
44	hertzog	47	$ make status
45	aph	43	$ make list COMPLETE=1 SIZELIMIT1=576716800
46			$ make official_images
47			[ or if you want only binary images :
48			$ make bin-official_images ]
49
50			But you really should consider reading further for more information.
51
52	hertzog	60
53	aph	43	How to build a CD set - step by step
54			====================================
55
56	hertzog	47	If not yet done, cd to the /usr/share/debian-cd/ directory.
57	aph	43
58			The process of building a CD is decomposed as follow :
59
60			- first configure what is needed in CONF.sh and source it
61			in your shell
62			$ . CONF.sh
63			The exported environment variables will be used by all the
64			tools involved here (Makefiles, perl scripts, shell scripts).
65
66			If you want to build CD images for more than one arch, you will
67			have to build them one after the other (you may use a shell
68			script for this).
69
70	hertzog	61	Note that the temporary dir must be on the same device than the
71			mirror because debian-cd uses hardlinks for generating an image
72			tree. If you can't do this, you'll have to use the symlink farm.
73			The symlink farm is explained at the end of this README.
74
75	aph	43	- now we'll check if your mirror is ok (with good Packages files) :
76			$ make mirrorcheck
77
78			- then you will have to launch this for initializing the
79			temporary directory used for the build :
80			$ make status
81	hertzog	47	If this has failed then this will be automatically launched :
82	aph	43	$ make correctstatus
83			However note that make status should never fail if it is
84			used for building a CD set for the stable release ...
85
86			- now you can decide what you want on your CDs
87			$ make list TASK=tasks/debian-2.2 COMPLETE=1
88			or
89			$ make list TASK=tasks/gnome COMPLETE=0 SIZELIMIT=576716800
90			or
91			$ export NONFREE=1; make list TASK=tasks/kde COMPLETE=1
92	hertzog	52	or for something like an official image for the USA (without non-US &
93			non-free) :
94			$ make COMPLETE=1 SIZELIMIT1=576716800
95	aph	43	.... take a look at the file tasks/* to see the options you can have :)
96
97			You can change the behaviour of this command with the following
98			variables :
99			- if NONUS is set, then packages from non-US will be allowed (remember
100			that the value of NONUS must be the path to the non-US mirror
101			if you have one)
102			- if NONFREE is set, then packages from non-free will be allowed
103			(NONFREE must be exported to all sub-shells)
104			- if COMPLETE is set, all packages that are not listed in the
105			selected task file will be included at the end
106			- if SIZELIMIT is set, it will be used as the maximum size that
107			we can put into each CD
108			- if SIZELIMIT<X> (with <X> beeing a integer) is set, it will be used
109			as the maximum size of the X'th binary CD. SIZELIMIT<X> overrides
110			SIZELIMIT ...
111			- if SRCSIZELIMIT is set, it's used as the maximum size for source CD
112			- if SRCSIZELIMIT<X> (with <X> beeing an integer) is set, it will be
113			used as the maximum size of the X'th source CD
114
115			This target calls the targets "bin-list" and "src-list" that can be used to
116			build only binary CDs or only source CDs.
117
118			- it may be time to add the disks-arch stuff and to make the CDs bootable
119			$ make bootable
120			This does affect only the binary CDs.
121
122	hertzog	47	If you want to use boot-floppies built by yourself you can give
123			a parameter BOOTDISKS=<dir> giving the directory where
124			they are (note that $BOOTDISKS/current must be a symlink to the
125			real directory, it must follow the same setup than in the FTP
126			mirror). Your boot-floppies must also be on the same partiton than
127			your mirror & temporary dir (hardlinks are used here too).
128
129	aph	43	- now, we'll add the binary packages to the temporary tree :
130			$ make packages
131
132			- and we'll add the sources to the temporary tree :
133			$ make sources
134
135			- if you want to install additional files :
136			make bin-extras CD=1 ROOTSRC=/home/ftp/ DIR=goodies/wordperfect
137			make src-extras CD=3 ROOTSRC=/home/ftp/ DIR=goodies/kernel-2.3
138
139			The first will copy /home/ftp/goodies/wordperfect/ on the first binary
140			CD. It will be in <root of the cd>/goodies/wordperfect ... you can call
141			make extras multiple times if you need more. Please note that
142			the files to be copied should be on the same partition than
143			your mirror (unless you use a symlink farm).
144
145			If you want to do customize your CD even more, you can use the hook
146			system. Read below about them.
147
148			- We can add an md5sum.txt file on each CD to enable users to check their
149			files :
150			$ make md5list
151			This does call the targets 'bin-md5list' and 'src-md5list'. You can
152			choose to call only bin-md5list if you're building only binary images.
153
154			- now we can create the images
155			$ make images
156			If you don't have enough space for all images, you can generate
157			only one image (of the second binary CD for example) with :
158			$ make bin-image CD=2
159			Of course if you want to build all binary images you'll use :
160			$ make bin-images
161			And "make src-images" will generate the sources images.
162
163	hertzog	59	- if you want to generate a MD5SUMS file with the md5sums of the
164			images you can do it with :
165			$ make imagesums
166
167	hertzog	60
168	hertzog	61	Local packages
169			==============
170
171			If you provide some custom made packages and you want to put them on
172			Debian CD set you can do it. Simply put your packages in
173			$MIRROR/dists/$CODENAME/local/binary-$ARCH/<section>.
174			The organization of this sub-tree is the same than what you can find
175			in the main, contrib or non-free part. You may use different section
176			names if you want. Be sure to create Packages files (and Sources.gz if you
177			include sources).
178
179			To include local packages, the LOCAL environment variable must be set
180			to "1" while building the CDs.
181
182
183	hertzog	60	Additionnal targets
184			===================
185
186			Pseudo Image Kit
187			----------------
188			Those of you, who will make images available to people for download may
189			consider using the Pseudo Image Kit (cf http://cdimage.debian.org for more
190			information). That's why you can launch "make pi-makelist" that will generate
191			the *.list files for the images you've just generated.
192
193			The tools/pi-makelist script needs the isoinfo binary. You can get the
194			sources from http://www.fokus.gmd.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html
195
196			Alternatively (and certainly simpler for people using Debian system), the
197			isoinfo binary is in the mkisofs package (since Debian potato at least).
198
199
200	aph	43	About the hook system
201			=====================
202
203			A hook script can be executed at different times. You can specify the
204			script by setting the HOOK variable to the script filename. It will
205			get 2 arguments, the first is the CD number. The second depends on
206			where/when the hook script is called. It can be 'before-scanpackages'
207			or 'before-mkisofs' (their values are explicit ...). When the script
208			is called, the current directory will be the temporary directory used for
209			the build (aka $TDIR/$CODENAME-$ARCH).
210
211			There are hooks only for binary CDs at the present time. If HOOK is not
212			set, it will look for a script $BASEDIR/tools/$CODENAME.hook.
213
214
215			About the symlink farm
216			======================
217
218			If you don't have write access on the disk where you have the mirror
219			or if for another reason hardlink cannot be used, you can try to
220			use a symlink farm. Instead of having real files, your temporary tree
221			will be filled with symlinks that mkhybrid will change into files when
222			it will build the image. You'll need to use a special options. You
223			have 2 lines of options in CONF.sh as examples.
224
225			I've never tested the symlink farm ... it may well generate unusable
226			images. Don't use it for ISO images that will used by many users.
227
228			Note that you will also need a patched mkhybrid that does support the
229			-F option. Have a look here about it :
230			http://www.chiark.greenend.org.uk/~stevem/DebianCD/
231
232	hertzog	48	The mkhybrid package in Debian does support this -F option since
233			potato (Debian 2.2).
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision