path: root/bcd.pod

=head1 NAME

bcd tools - A simple program to generate Mandriva's ISO

=head1 SYNOPSIS

bcd configuration.xml [options]

=cut

=head1 OPTIONS

=over 8

=item B<First arg must be:>

 The XML configuration file

=item B<Second arg must be:>

 stagex: update the stage1/stage2 in builddir
 isolinux: update the isolinux in builddir
 clean: clean the builddir and isodir
 media: create the list of wanted packages, create all media in builddir,
        link/copy packages in builddir/media, create the media.cfg,
	and generate the hdtlist/synthesis
 gendistrib: create the hdlists/synthesis in builddir (depends on the based_on tag)
 list: list all media and list of input/exclude (from the xml conf file)
 mediarepo: list all medias availables in the repositery
 checkrepo: rpmcheck main hdlists in the repositery
 all: run all stage in order to get an ISO
 md5: create MD5 sum of the ISO
 info: parse the configuration file (usefull to check the XML syntax)
 iso: create the final ISO from the builddir

=item B<extra arg:>

 noiso: don't build the iso (md5, isohybrid) in case of 'all' process
 copy: copy rpm instead of link them from the repositery

=back

=head1 EXAMPLES

the folowing example will do all step to create an ISO:

 bcd mdv-20091.xml all

the following example will create the build dir without creating ISO:
 bcd.pl mdv-20091.xml all noiso

same as above but copy packages instead of link them from the repositery:
 bcd.pl mdv-20091.xml all noiso copy

the following will update the isolinux in the build directory:
 bcd.pl mdv-20091.xml isolinux

to check the main hdlist in the repositery with rpmcheck
 bcd.pl mdv-20091.xml checkrepo

clean the builddir and isodir
 bcd.pl mdv-20091.xml clean

=cut

=head1 COPYRIGHT

Copyright (C) 2009 Mandriva <aginies_@_mandriva.com>

=cut

=head1 DESCRIPTION

BCD is used to create Mandriva ISO.
features are:
- configuration file is in XML format
- use of genhdlist2 with file-deps
- support the add of an isolinux entry
- change the theme on all.rdz files
- just need an input and an exclude file for package list
- write media.cfg
- support of custom rpmsrate of compssusers.pl
- support of custom advertising
- support of custom stage2
- extra filter to remove doble packages (keep latest version)
- all sub-media supported (updates, testing...)
- create the iso HEADER
- use of urpmi to calculate deps/conflicts/suggests
- create an md5 file
- create a product.id file
- create a VERSION file
- support of no-suggests option per media
- support extra external media with hdlists

=cut

=head1 USER conf

Your user must have some sudo root right to be able to use chroot, urpmi
rm, mount umount tools. IE: for user plop in /etc/sudoers file

 plop ALL=(root) NOPASSWD:/bin/mount, /bin/umount, \
	/usr/sbin/chroot, \
	/usr/sbin/urpmi, \
	/usr/sbin/urpmi.addmedia, \
	/usr/sbin/urpmi.removemedia, \
	/bin/rm

=cut

=head1 LISTS

input list:
list of rpm needed on the CD. Those list should contains the name
or the provides of a package. You may also use a CAT_XXX from the
rpmsrate file, with the wheigth parameter.

 ie: of lists/input_main
 INSTALL 1
 CAT_X 1
 CAT_GNOME 1
 CAT_AUDIO 1
 aumix
 task-lxde

exclude list:
list of unwanted packages on the CD. Be carreful to do not exclude mandatory packages
or you CD will be unusable. Rpmcheck will report any bug in hdlists at the end of 
the 'media' step process. Packages listed in exclude list will be removed from the 
DVD at the end of the build process.

extra-filter:
list of RPM you want to compare to keep the latest one. Usefull for kernel
and dkms release.

=cut

=head1 ISSUE

 - if you want to build ISO for x86_64 you must used an x86_64 system (due to urpmi)
 - can't build dual arch ISO
 - if hdlist/synthesis are corrupted in your repositery, you can't build ISO

=cut

=head1 conf.xml

Example of a commented conf.xml file. Keep in mind that most of those
parameters are correct, and you don't need to change whole of them.
Examples are available in this package, so please use one of them to 
base your configuration.

You should only change those one:
{nameid}
{version}
{arch}
{repo}{path}
{media}{list}*
{iso}{header}*

Fully commented file:
---------------------
first it's an xml file:
 <?xml version='1.0'?>

name of the product
 <productname desc="The Linux product">

identification of the product
 <nameid>XtreemOS</nameid>

based_on parameter define on wich version of Mandriva this product will be built.
This parameter define if we need synthesis or hdlists (since 2009.1 only synthesis are needed)
It will be use to get the path of the Mandriva repositery
 <based_on>2009.0</based_on>

Arch parameter is mandatory, it will be also used to get the path of the MDV repositery
 <arch>i586</arch>

path to the repositery
 <repo desc="Where is the repositery of the distribution">
  <path>/mnt/BIG/dis</path>
 </repo>

so the full path of the Mandriva repositery will be in our example
 </mnt/BIG/dis/2009.0/i586>

workdir is where you want to store the result of the build
 <workdir desc="Where is my working dir">
  <path>/home/xtreemos/build_bcd</path>
 </workdir>

basename of log files
 <tocopy_file>tocopy_plop</tocopy_file>

all Isolinux information
 <isolinux desc="isolinux info">
  <defaultpath>isolinux</defaultpath>

if you want to point to a custom isolinux directory
 <fullpath>/home/xtreemos/export_i386/isolinux</fullpath>

if you want to add a entry in your isolinux.cfg
 <!-- add hdt entry in syslinux.cfg -->
  <entry name="hdt" desc="Main media">
   <bin>/usr/lib/syslinux/hdt.c32</bin>
   <label>hdt</label>
   <kernel>hdt.c32</kernel>
   <append>modules=modules.pci</append>
  </entry>

some section are mandatory to keep the array structure of the xml file
  <!-- keep this entry to create an array ref -->
  <entry></entry>

if you want to copy extra files to the isolinux buildir
 <tocopy name="pcimap">
  <file>/lib/modules/2.6.31-server-2mnb/modules.pcimap</file>
 </tocopy>
 <tocopy name="ids">
  <file>/usr/share/pci.ids</file>
 </tocopy>
 <tocopy></tocopy>
 </isolinux>

all information relatives to the installer (stage2)
 <installer desc="path to the Mandriva installer (stage1/stage2)">
  <defaultpath>install</defaultpath>

if you want to use a custom installer
 <fullpath>/home/xtreemos/export_i386</fullpath>

path to custom advertising
 <advertising>
  <defaultpath>advertising</defaultpath>
  <fullpath>/home/xtreemos/Build/pieces/advertising</fullpath>
 </advertising>

full path and name of your patch for stage2 to copy in the buildir/install directory
  <patch>/home/xtreemos/Build/pieces/patch-oem.pl</patch>
 </installer>

theme to use to patch all.rdz file
theme name will be used to install mandriva-release-THEMENAME and avoid
problem of mixing theme on a same product
 <!-- theme must be available to path altx/all.rdz files -->
 <theme name="mandriva-release-Free">
  <bootsplash>Mandriva-Free</bootsplash>
  <bootsplash_path>/usr/share/bootsplash</bootsplash_path>
  <gfxboot_path>/usr/share/gfxboot</gfxboot_path>
 </theme>

media section will defined wich media you want to use and you want to create on the DVD
 <media desc="media to take into account to build the ISO">
 <!-- WARNING this media must be named "Main" because main media is mandatory for all other media-->
 <!-- Morever the "Main" media is always the Name use for an MDV repositery -->
 <!-- futur feature will provide a way to specify another name for the basic repo of an MDV distribution -->
 <!-- use the supp_media option if you needed to use media option of urpmi, usefull for external media
  wich need main and contrib to be installed, use the urpmi syntax of \-\-media (no space, media separated by coma)
 <media_supp>Main,Main Updates,Contrib,Contrib Updates</media_supp>-->
 <list name="Main" desc="Main_media">
  <!-- MANDATORY list of wanted packages on the iso -->
  <input name="base">
   <file>lists/input_main</file>
  </input>
  <input name="lang">
   <file>lists/languages</file>
  </input>
  <!-- to create an array you must keep this even if it is empty -->
  <input name="xos">
   <file>lists/xos_list</file>
  </input>

you can use an external media, but this media must have a media_info directory
you must use external media if this media is not available in the repositery.
IE: restricted32 packages on a PowerPack 64bits product
 <!-- external media repositery with hdlists -->
  <external name="xos">
   <fullpath_mediadir>/home/xtreemos/repo_xos/2009.0/i586/media/xtreemos/release</fullpath_mediadir>
  </external>

Packages unwated on the DVD, they will be removed at the end of the installation process
 <!-- MANDATORY list of unwanted packages on the iso -->
  <exclude name="exclude">
   <file>lists/exclude_main</file>
  </exclude>
  <!-- to create an array you must keep this even if it is empty -->
  <exclude>
  </exclude>

switch nosuggest options to yes if you don't want to use RPMS's suggests
 <!-- nosuggests options should be yes or no -->
 <nosuggests>no</nosuggests>

I will use the media name "mediadir" and put it in the directory media/'destmedia' on the DVD
 <!-- will be taken in {repo}{version}{arch}/media -->
  <mediadir>main</mediadir>
  <destmedia>main</destmedia>

where to find the pubkey in the repositery (the path will be media/'mediadir'/'pubkey')
 <pubkey>release/media_info/pubkey</pubkey>

if you want to use backports, testing or updates sub-media, set option to yes, note: release media should be mandatory
  <release>yes</release>
  <updates>yes</updates>
  <backport>no</backport>
  <testing>no</testing>
 </list>
 <!-- keep this entry to create an array ref -->
  <list></list>
 </media>

all media_info informations are in this section
 <mediainfo desc="All files relatives to media_info dir">

version will be used to generate a good media.cfg files (we don't use hdlits.cz since 2009.1 release)
 <version>2009.0</version>

use 'fullpath' parameter to use custom files
 <!-- set fullpath if you want to use an files in a non MDV repositery -->
 <fullpath>/home/xtreemos/Build/pieces</fullpath>
 <mediainfo_dir>media/media_info</mediainfo_dir>
 <rpmsrate>rpmsrate</rpmsrate>
 <compssusers>compssUsers.pl</compssusers>
 <filedeps>file-deps</filedeps>

if you want to add an urpmi options to install packages
 <urpmi_option>-a</urpmi_option>

if you want to do some extra filter to keep latest release of a packages on the DVD 
 <filter>lists/extra-filter</filter>

media.cfg options
 <askmedia desc="add for other media ?">
  <todo>yes</todo>
 </askmedia>
 <suppl desc="add an external media ?">
  <todo>yes</todo>
 </suppl>
  <xmlinfo>
 <todo>no</todo>
  </xmlinfo>
 </mediainfo>
	
ISO section
 <iso>

tag name and some extra parameters
 <tag>rc1</tag>
 <minor>0</minor>
 <subversion>1</subversion>
 <product>Download</product>
 <branch>Devel</branch>
 <type>basic</type>
 <!-- dual arch not yet supported -->
 <dualarch>no</dualarch>
 <!-- SIZE is not YET USED !!! -->
 <size>700</size>
 <!-- media.cfg will be stored on genisoimage->{builddir}/{nameid}/{arch} -->
 <mediacfg>media/media_info/media.cfg</mediacfg>
 <hdlist>yes</hdlist>
 <synthesis>yes</synthesis>

info used by the genisoimage tool
 <header desc="Iso header info">
  <systemid>XtreemOS Linux</systemid>
  <volumeid>XOS-2.0-i586</volumeid>
  <volumesetid>XtreemOS Linux - 2.0 - i586 DVD </volumesetid>
  <publisherid>XtreemOS</publisherid>
  <datapreparer>XtreemOS-Linux</datapreparer>
  <applicationid>XtreemOS Linux - 2.0</applicationid>
  <copyrightid>XtreemOS Linux</copyrightid>
 </header>

genisoimage paramater
 <genisoimage desc="iso generation tool">
  <options>-f -r -J -hide-rr-moved -nobak -cache-inodes -no-emul-boot -boot-load-size 4 </options>
  <bootcat>isolinux/boot.cat</bootcat>
  <!-- builddir and destdir will always use the workdir -->
  <builddir>build</builddir>
  <isodir>iso</isodir>
 </genisoimage>
 </iso>
 </productname>

=cut