source: soft/build_system/build_system/mkcd/tags/V3_3_6_1mdk/mkcd.old.xml @ 1

Last change on this file since 1 was 1, checked in by fasma, 12 years ago

Initial Import from Mandriva's soft revision 224062 and package revision 45733

File size: 18.7 KB
Line 
1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2"/usr/share/sgml/docbook/sgml-dtd-4.1/docbook.dtd">
3<article>
4  <title>mkcd-howto</title>
5
6  <sect1>
7    <title>What does mkcd ?</title>
8   
9    <para>
10      mkcd is a script written in Perl and designed to make the design of CD images of a linux-mandrake distribution easier.
11    </para>
12
13    <para>
14      mkcd uses as input a set of RPMs and SRPMs, and other files like the image of a boot disk and the
15      install program; it outputs iso 9660 images. Its action is parametrized by a configuration file which
16      basically tells what belongs to each CD. Some checks are performed, and finally the ISO images are
17      created.
18    </para>
19   
20    <para>
21      The checks mainly involve dependencies between RPM packages, using rpmtools (see rpmtools manpage).
22    </para>
23   
24    <para>
25      mkcd uses a working directory to perform its task, with some standard subdirectories:
26    </para>
27
28    <itemizedlist>     
29      <listitem>
30        <para>input : the configuration files, together with the files listing the packages on each CD. for example, for a
31          8.0 distrib, one 8.0.conf file, and files 8.0-1, 8.0-2, 8.0-3, 8.0-com1, 8.0-com2, 8.0-com3,
32          8.0-ViaVoice, which are files describing the packages of the corresponding CDs.
33        </para>
34      </listitem>
35      <listitem>
36        <para>build : where the file hierachy of each CD is written</para>     
37      </listitem>     
38      <listitem>
39        <para>iso : where the isos are to be (finally) written</para>   
40      </listitem>     
41      <listitem>
42        <para>config : some files produced by mkcd describing what it has actually found and will go in the CDs</para> 
43      </listitem>     
44      <listitem>
45        <para>tmp : temporary files, including the list of the dependencies between packages (depslist.ordered) and the
46          file containing all the headers of the rpms, manipulated by rpmtools and by the installation process</para>   
47      </listitem>
48    </itemizedlist>
49
50    <para>
51      Usually, a "log" subdirectory can also be found, and when there is the need to make a
52      local copy of the files which go in the distrib (rpms, srpms...), they are stored in a subdirectory named
53      "pieces".
54    </para>
55
56  </sect1>
57  <sect1>
58    <title>Checks performed by mkcd</title>
59   
60    <para>
61      In order to create the filesystem of each CD, mkcd first builds intermediate lists of packages, from the
62      lists the user provided. These lists may differ from the user-provided ones because of the checks
63      performed by mkcd against
64    </para>
65
66    <itemizedlist>     
67      <listitem>
68        <para>
69          dependency problems caused by missing packages
70        </para>
71      </listitem>
72      <listitem>
73        <para>
74          corrupted RPMs
75        </para>
76      </listitem>
77      <listitem>
78        <para>
79          mismatching SRPM and RPM version numbers
80        </para>
81      </listitem>
82      <listitem>
83        <para>
84          multiple copies of each package (different versions for example)
85        </para>
86      </listitem>
87    </itemizedlist>
88
89  </sect1>
90  <sect1 id=cmdline>
91    <title id=cmdline.title>mkcd command-line options, examples of use</title>
92
93    <para>
94      <table frame="all"><title>Options relative to lists</title>
95        <tgroup cols="2" align="left" colsep="1" rowsep="1">
96          <tbody>
97            <row>
98              <entry>-l, --lists-check</entry>
99              <entry>check the lists</entry>
100            </row>
101            <row>
102              <entry>-f, --fast</entry>
103              <entry>fast mode.</entry>
104            </row>
105            <row>
106              <entry>-d, --depslist-creation</entry>
107              <entry>rebuild the depslist.ordered file before checking the list.</entry>
108            </row>
109          </tbody>
110        </tgroup>
111      </table>
112    </para>
113
114    <para>
115      <table frame="all"><title>Other common options</title>
116        <tgroup cols="2" align="left" colsep="1" rowsep="1">
117          <tbody>
118            <row>
119              <entry>--distrib</entry>
120              <entry>specify the target distrib.</entry>
121            </row>
122            <row>
123              <entry>-a, --auto</entry>
124              <entry>Automated mode, add dependencies.</entry>
125            </row>
126            <row>
127              <entry>-m, --make  &lt;cds number> </entry>
128              <entry> Build the CDs.</entry>
129            </row>
130            <row>
131              <entry> -c, --catto  &lt;log file> </entry>
132              <entry> Log file.</entry>
133            </row>
134            <row>
135              <entry> -o, --outname  &lt;tag> </entry>
136              <entry>Tag added to the VERSION file.</entry>
137            </row>
138          </tbody>
139        </tgroup>
140      </table>
141    </para>
142   
143    <para>
144      To make a distrib, one usually proceeds in two steps: building the package lists (and checking dependencies)
145      and building the CDs.
146    </para>
147
148    <sect2>
149      <title>Building the lists of packages</title>
150      <para>
151        The first one consists in building the list of packages for each CD (in the config/ subdirectory) and the
152        dependencies list; this list enables to ensure that there are no required packages missing.
153      </para>
154
155      <para>
156        Assume we are in the working directory of mkcd (with its subdirectories "tmp", "input"...)
157      </para>
158     
159      <para>
160        <programlisting format="linespecific">
161        mkcd --distrib "80" -c log/freq.log -l input/8.0-freq.conf
162        </programlisting>
163      </para>
164     
165      <para>
166        builds in "config/" the lists of packages for each CD, following the rules of the configuration file
167        "input/8.0-freq.conf", using the logfile "log/freq.conf". For each CD, several files are created. Their names
168        begin with the name of the CD (for example, 8.0-freq-1 (CD 1 of the 8.0-freq distrib) or 8.0-ViaVoice (CD
169        ViaVoice of the 8.0 distro)). For a CD named NAME, you'll find in config after the -l stage:
170      </para>
171
172
173      <table frame="all"><title>Files created in config/</title>
174        <tgroup cols="2" align="left" colsep="1" rowsep="1">
175          <tbody>
176            <row>
177              <entry>NAME</entry>
178              <entry>raw names of the rpms on the CD, without version numbers and .rpm extension</entry>
179            </row>
180            <row>
181              <entry>NAME.rpm</entry>
182              <entry>complete names of the rpms of the CD</entry>
183            </row>
184            <row>
185              <entry>NAMEs</entry>
186              <entry>raw names of the srpms associated with the rpms of the CD</entry>
187            </row>
188            <row>
189              <entry>NAME.srpm</entry>
190              <entry>complete names of the srpms</entry>
191            </row>
192          </tbody>
193        </tgroup>
194      </table>
195     
196      <para>
197        Some other lists may be generated if the config file in input/ requires to split the srpm CDs. See the
198        <quote><link linkend=config endterm="config.title"></link></quote> section.
199      </para>
200     
201      <para>
202        <programlisting format="linespecific">
203          mkcd --distrib "80" -c log/freq.log -d input/8.0-freq.conf
204        </programlisting>
205      </para>
206
207      <para>
208        builds in "tmp/" the dependencies list depslist.ordered, and a file containing all the headers of the rpms of
209        the distrib, hdlist (in a gzipped form). Checks are performed against missing packages. "-c" option works as
210        before.
211      </para>
212
213      <para>
214        -d and -l options can be combined; thus one often writes
215      </para>
216
217      <para>
218        <programlisting format="linespecific">
219          mkcd --distrib "80" -c log/freq.log -dl input/8.0-freq.conf
220        </programlisting>
221      </para>
222
223      <para>
224        to perform the two operations in one single pass.
225      </para>
226
227      <para>
228        The name associated with the option --distrib is used to <!-- ???????????????????????? -->
229      </para>
230
231      <para>
232        After this step, you can take a look at the logfile to see a list of the problems mkcd has found. Here is an
233        example of the sections of this file for a distribution with 2 CDs (namely the freq whose lists were build
234        with the previous command)
235      </para>
236   
237      <para>
238        <programlisting format="linespecific">
239          DUPLICATE RPM (dir where the rpms are taken. see
240             configuration file)
241          (list of RPMs duplicate, i.e. for which there are at least
242             two different versions available in dir)
243         
244          DUPLICATE SRPM (dir)
245          (list of duplicate SRPMS)
246
247          FAILING DEPS
248          (list of required rpms which are missing)
249         
250          NOT IN REPOSITORIES CD 1
251          <!-- ?????????????? -->
252
253          SRPMS NOT IN REPOSITORY CD 1
254          <!-- ???????????? -->
255
256          BAD SRPMS VERSION CD 1
257          (list of corrupted rpms on CD 1. See configuration file for the
258             splitting of rpms between the different CDs.)
259         
260          DUPLICATE RPMS CD 1
261          (list of duplicate rpms on CD 1)
262
263          NOT IN REPOSITORIES CD 2
264         
265          SRPMS NOT IN REPOSITORY CD 2
266         
267          BAD SRPMS VERSION CD 2
268         
269          DUPLICATE RPMS CD 2
270
271          PACKAGES NOT IN LIST
272          <!-- ?????????????????????????? -->
273        </programlisting>
274      </para>
275
276      <para>
277        Example of falling dependencies section:
278      </para>
279
280    <para>
281      <programlisting format="linespecific">
282          FAILING DEPS
283          rute ghostscript-module-X
284          gv ghostscript-module-X
285        </programlisting>
286    </para>
287
288    <!-- ??????? signification : le premier package est celui qui a besoin du second qui est manquant, je suppose. -->
289
290    <para>
291      You can see that the names of the packages are displayed without the version numbers.
292    </para>
293
294    </sect2>
295    <sect2>
296      <title>Building the CD images</title>
297
298      <para>
299        This is performed as following:
300      </para>
301     
302      <para>
303        <programlisting format="linespecific">
304          mkcd --distrib "80" -c /log/freq_build.log -o Traktopel-Freq1-i586 -m 1,2 input/8.0-freq.conf
305        </programlisting>
306      </para>
307     
308      <para>
309        The options regarding the configuration file and the log file work as before; here we build CDs 1 and
310        2 (option "-m 1,2"). The name and the place where the isos are created depends on the argument of the
311        "-o" option and on the name of the distrib in the config file (see <quote><link linkend=config
312        endterm="config.title"></link></quote> section), in that
313        case "8.0-freq". The first iso will be called "1-8.0-freq-Traktopel-Freq1-i586.iso" and the second
314        "2-8.0-freq-Traktopel-Freq1-i586.iso" (these names are a bit redundant in the present case). They are
315        put in the "iso/8.0-freq" subdirectory of the working dir; the "iso" subdirectory must be created
316        before the command is issued.
317      </para>
318         
319    </sect2>
320  </sect1>
321  <sect1>
322    <title>Config files, packages lists (input/ subdirectory)</title>
323   
324    <para>
325      The files found in that subdir fall into two categories: config files and packages lists. The config
326      file gives to mkcd the global structure of the distribution, but does not include the list of the
327      packages on each CD. Those lists are stored in separate files corresponding to CDs.
328      For example, for a freq distrib, one finds the following files:
329    </para>
330   
331    <itemizedlist>     
332      <listitem>   
333        <para>
334          8.0-freq.conf: the main config file
335        </para>
336      </listitem>
337      <listitem>   
338        <para>
339          8.0-freq-1: list of packages for CD #1
340        </para>
341      </listitem>
342      <listitem>   
343        <para>
344          8.0-freq-2: list of packages for CD #2
345        </para>
346      </listitem>
347    </itemizedlist>     
348   
349    <para>
350      We'll see that the names of the package list files must match those given in the main config file.
351    </para>
352   
353
354    <sect2 id=config>
355      <title id=config.title>Configuration file</title>
356      <para>
357        A config file consists in a general section providing some global information regarding the distrib,
358        and in one more specific section for each CD.
359      </para>
360     
361      <sect3>
362        <title>General section</title>
363        <para>
364          The general section looks like this:
365        </para>
366       
367        <para>
368          <programlisting>
369            8.0
370            -r pieces/frozen/extra/RPMS -s pieces/frozen/extra/SRPMS \
371            -r pieces/frozen/RPMS -s pieces/frozen/SRPMS \
372            -r /mnt/BIG/dis/cdcom/traktopel/cd1/Mandrake/RPMS \
373            -r /mnt/BIG/dis/cdcom/traktopel/cd2/Mandrake/RPMS \
374            -r /mnt/BIG/dis/cdcom/traktopel/ViaVoice/ViaVoice/common/Mandrake/RPMS \
375            -r /mnt/BIG/dis/cdcom/traktopel/ViaVoice/ViaVoice/us/Mandrake/RPMS \
376            -r /mnt/BIG/dis/cdcom/traktopel/ViaVoice/ViaVoice/gr/Mandrake/RPMS
377            -r /mnt/BIG/dis/cdcom/traktopel/ViaVoice/ViaVoice/fr/Mandrake/RPMS
378            -k 8.0-kill 8.0-1,680000000 8.0-2,270000000 \
379            8.0-3 8.0-com1 8.0-com2 8.0-ViaVoice 8.0-com3
380          </programlisting>
381        </para>
382       
383        <para>
384          Apart from the "8.0" line, everything must be on the same line (linebreaks were added here to
385          improve readability). Following -r options are the paths of the RPMs of the distribution; the paths
386          following -s options are for srpms. Be aware that in case there is more than one file for a given
387          package, the file which lies in the first directory in the list will be chosen, regardless of its
388          version number: thus for example updates directories must be encountered <emphasis> before
389          </emphasis> regular directories in the the list of rpm dirs.
390        </para>
391       
392        <para>
393          Normally srpms must be in one-to-one correspondence with rpms, with matching version numbers; but some srpms
394          are really not useful (in the case of documentation packages for example, rpms and srpms are nearly the
395          same). Thus you may want to exlude some srpms from this correspondence checks. This is performed by the -k
396          option. It is followed by the name of a file in the input/ directory wich contains the names of the packages
397          concerned, with the same conventions as in the package list files.
398        </para>
399       
400        <para>
401          This section ends with the names of the package list files, optionally followed by a list of numbers. These
402          numbers enable to split the list of srpms corresponding to a CD (or a rpm list) in smaller subsets. For
403          example, 8.0-3,200000000,300000000 tells mkcd to split the set of srpms corresponding to the list of rpms
404          stored in the file "8.0-3" into two (possibily three) lists, the first one of total size &les; 200 MB (file
405          8.0-3.srpm.1 in config/ dir), the second one of total size &les; 300 MB (file 8.0-3.srpm.2), and the third one
406          (8.0-3.srpm.3) with the remaining rpms if there are any. In the above example, "8.0-1,680000000" enables to ensure
407          that the source CD corresponding to CD 1 is not oversized.
408        </para>
409       
410        <para>
411          The name at the beginning of the section is the product name ("8.0" in the above example). It is used in the
412          names of the isos (see <quote><link linkend=cmdline endterm="cmdline.title"></link></quote>), and
413          in the names of the subdirectories in build/, tmp/,
414          iso/ (in these three directories the files created are stored in a subdirectory specific to the product you're
415          building).
416        </para>
417       
418      </sect3>
419      <sect3>
420        <title>CD section</title>
421        <para>
422          A section corresponding to a CD looks like this :
423        </para>
424       
425        <para>
426          <itemizedlist>
427            <listitem>
428              <para>
429                A first "header" line with some fixed fields:
430               
431                <programlisting>
432                  1 CD1 1DL8000 Installation CD (x86)
433                </programlisting>
434              </para>
435            </listitem>
436            <listitem>
437              <para>
438                then a sequence of (mkcd built-in) commands, one per line. For example:
439               
440                <programlisting>
441                  generic -d Mandrake/RPMS -r pieces/frozen/extra/RPMS \
442                  -r pieces/frozen/RPMS 8.0-1.rpm
443                  advertising -d pieces/pics/advert/advertising \
444                  1-thanks.png 2-internet.png 3-graphic.png 4-develop.png \
445                  5-contcenter.png 6-user.png 7-server.png 8-games.png \
446                  9-MDKcampus.png 10-MDKexpert.png
447                  advertising -l fr -d pieces/pics/advert/advertising.fr \
448                  1-thanksFR.png 2-internetFR.png 3-graphicFR.png \
449                  4-develop.png 5-contcenterFR.png 6-userFR.png 7-serverFR.png \
450                  8-gamesFR.png 9-MDKcampusFR.png 10-MDKexpertFR.png
451                  installation_8 -b cdrom.img -i pieces/install 1/Mandrake/RPMS \
452                  2/Mandrake/RPMS2
453                </programlisting>
454              </para>
455            </listitem>
456          </itemizedlist>
457        </para>
458
459        <para>
460          there is no newline between those two parts.
461        </para>
462       
463        <sect4>
464          <title>First line of a CD section</title>
465
466          <para>
467            <table frame="all"><title>Fields in the first line</title>
468              <tgroup cols="2" align="left" colsep="1" rowsep="1">
469                <tbody>
470                  <row>
471                    <entry>1</entry>
472                    <entry>cd number : number identifying the CD (internal to mkcd)</entry>
473                  </row>
474                  <row>
475                    <entry>CD1</entry>
476                    <entry># of the CD in the distrib</entry>
477                  </row>
478                  <row>
479                    <entry>1DL8000</entry>
480                    <entry>serial # of the CD</entry>
481                  </row>
482                  <row>
483                    <entry>Installation CD (x86)</entry>
484                    <entry>name of the CD</entry>
485                  </row>
486                </tbody>
487              </tgroup>
488            </table>
489
490          </para>
491         
492          <para>
493            The difference between distrib numbers and internal numbers arises from the fact that one configuration file
494            can be used to build different releases of the same distribution (e.g. for different languages, or different
495            platforms). In that case there are more CDs in the configuration file than in each release, and one must make
496            a difference between numbers for mkcd to identify CDs and public numbers.
497          </para>
498        </sect4>
499
500        <sect4>
501          <title>mkcd commands avaliable</title>
502
503          <table frame="all"><title>Commands available</title>
504            <tgroup cols="2" align="left" colsep="1" rowsep="1">
505              <tbody>
506                <row>
507                  <entry>generic -r path/RPMS -r path2/RPMS ... -r path(n)/RPMS -d dest listname.rpm</entry>
508                  <entry>looks for the rpms listed in listname.rpm in the directories listed with the -r option, and copies them in
509                    build/product_name/cd_number/dest/</entry>
510                </row>
511                <row>
512                  <entry>cp src dest</entry>
513                  <entry>copies files from src/ to build/product_name/cd_number/dest</entry>
514                </row>
515                <row>
516                  <entry>cdcom -d dest/ path/</entry>
517                  <entry>looks for a RPMS directory in path, and copies its content in  build/product_name/cd_number/dest/
518                    <!-- ??????????????? EST-CE QUE DEST DOIT EXISTER SUR LE CD ? -->
519                  </entry>
520                </row>
521                <row>
522                  <entry>advertising -l LANGUAGE -d path/ img1.png ... img(n).png</entry>
523                  <entry>copies the images img1.png ... img(n).png  found in path/ in
524                    build/product_name/cd_number/Mandrake/share/advertising_LANGUAGE (for example LANGUAGE=fr, ru ...). These are
525                    the advertising messages that will be displayed during the installation process in the language chosen by the
526                    user.</entry>
527                </row>
528                <row>
529                  <entry>installation_8 -b image -i install_path/ path1 ... path(n)</entry>
530                  <entry>copies the content of install_path/ in build/product_name/cd_number/, computes dependency files for rpms
531                    found in directories path1 ... path(n), and uses the boot floppy disk image image to make a bootable CD.
532                    This command is of course used for install CDs, but you can call it for whatever other purpose.
533                    <!-- ???????????? QUE DEVIENNENT LES DEPENDANCES QUI SONT CALCULEES ? EST-CE LE FICHIER DEPSLIST QUE L'ON -->
534                    <!-- RETROUVE DANS build/product_name/cd_number/Mandrake/base ? --></entry>
535                </row>
536              </tbody>
537            </tgroup>
538          </table>
539        </sect4>
540      </sect3>
541      </sect2>
542    <sect2>
543      <title>Package list files</title>
544      <para>
545        In package list files, the names of the packages appear without version numbers, as following:
546      </para>
547     
548      <para>
549        <programlisting>
550          Aurora
551          Aurora-Monitor-NewStyle-Categorizing-WsLib
552          Aurora-Monitor-NewStyle-WsLib
553          Aurora-Monitor-Traditional-Gtk+
554          Aurora-Monitor-Traditional-WsLib
555          Bastille
556          ...
557        </programlisting>
558      </para>
559    </sect2>
560  </sect1>
561</article>
562
563
564
565
566
Note: See TracBrowser for help on using the repository browser.