2005-04-19 Benoit PAPILLAULT <benoit.papillault@sourcemage.org>

== Rules for building SourceMage GNU/Linux ISO ==

*  ISO should be able to install a bootable Source Mage GNU/Linux system
* stable ISO must use the stable sorcery and stable grimoire. See
http://lists.ibiblio.org/pipermail/sm-discuss/2005-February/009651.html
* test ISO could use a modified grimoire. See
http://lists.ibiblio.org/pipermail/sm-discuss/2005-February/009695.html

== Building SourceMage GNU/Linux ISO ==

=== Supported platforms ===

Currently, the process described here has been working on x86, ppc and
x86-64. It should work on sparc and sparc64 as well, but it has not been
thoroughly tested.

=== Getting started ===

In order to have a reproducible ISO build process, the same sorcery and
grimoire revision need to be used throughout the whole process. To achieve such
goal, you need to download sorcery and grimoire tarballs in this directory (the
one containing this README).

  ./mk-init

=== Creating the initial chroot ===

In order to build an ISO without breaking your running system, all the software
that will be shipped on the ISO is compiled inside a chroot.

The mk-first script is used to generate this initial chroot. The default
location of the chroot is work/image-stage3 (for historical reason). This
directory can be changed either by editing the default value in config-auto or
by defining an IMAGE env. var.

This script will use the resurect feature of sorcery, combined with the
INSTALL_ROOT feature. It will also install stable sorcery and stable grimoire
from the tarball we have previously downloaded.

Note: You need to use a sorcery/grimoire combination on your build system that
properly support the resurrect and INSTALL_ROOT features. Since stable ISO are
build using stable sorcery/grimoire, you should probably use this combination
as well on your build system.

  export IMAGE=work/image-stage3
  ./mk-first

=== Updating the initial chroot ===

Over time, stable sorcery and stable grimoire will be updated and will need to
be reinstalled in the chroot. You can either use the following commands in the
chroot:

  sorcery update
  scribe update

Or follow our reproducible procedure:

  ./mk-init
  ./install-sorcery-grimoire

Next, you need to ensure that caches (files in the /install directory of the
chroot) have been correctly updated.

  ./mk-next

=== Building the final ISO ===

This steps will create the final .iso file, which you can burn to get a
bootable ISO. Three main steps are involved here and will be detailled, along
with a script that does all 3 steps at once.

==== Creating the ISO content ====

This step use the caches built in the previous step. It will populate the
work/iso-root directory (you should be able to chroot there indeed). It will
make sure that all spells listed in src/iso_root/spell-iso-root* are installed,
along with their dependencies. It will also copy all the caches for the spells
listed in src/iso_root/installerdata/install-list* and
src/iso_root/installerdata/optional-list*, along with their dependencies.

This step is done using:

  ./mk-iso-root

==== Creating an initrd ====

An initrd is needed on the ISO to locate the CD-ROM drives at boot time. It is
built using softwares installed in the previous step (it cannot be done from
caches since we need only few files). The initrd can be either in cramfs or
ext2 format. To change the format, edit the file "config".

This step is done using:

  IMAGE=work/iso-root ./mk-initrd

==== Creating a bootable ISO ====

A last steps is required to compressed the ISO content in a squashfs filesystem
(using squashfs filesystem is entirely optional, but it saves a lot of space)
and to copy the initrd to the correct location and copy all the files needed to
make the ISO bootable. Once this is done, the ISO is created using platform
specific mkisofs options (each platforms requires different options since the
mechanism used to make the ISO bootable are platform specific).

Currently, this script will produce a bootable ISO on the following platforms:
* x86
* x86-64
* ppc
* sparc
* sparc64

This step is done using:

  IMAGE=work/iso-root ./mk-iso

==== All steps together ====

To create a final ISO using caches from /install (this done the three steps we
have detailled above):

  ./mk-final

Configuration is done in the "config" file.

== Testing SourceMage GNU/Linux ISO ==

Currently, the ISO is tested using the following method:
* the ISO must be bootable
* the installed system must be bootable
* the installed system must successfully passed "sorcery rebuild" twice

== References ==

This document is available:
* on the wiki: http://wiki.sourcemage.org/index.php?page=ISO+generation+guide
* on perforce: http://perforce.smee.org:8080/@@//sgl/cauldron/proj/proj3/README
