1. Overview
===========

To build a new image, you have to:

 - be root
 - put the installation-images dir on a *local* file system (non-NFS)
 - on ia32 systems: linuxrc & syslinux installed

Then you can do:

  make initrd
    - build an initial ramdisk

  initrd=small make initrd
    - build a 'small' test initrd, suitable for 1.44MB boot images (for ia32)
    - *** This is not suitable for release on our CDs! ***

  make boot
    - build an boot image (for ia32)

  make root
    - build a root image

  demo=live make demo
  demo=eval make demo
    - build a root image for a Live/LiveEval CD

  make boot
    - build a (2.88MB) boot image (for ia32)

  demo=live make boot
  demo=eval make boot
    - build a (2.88MB) Live/LiveEval boot image (for ia32)
    - add 'boot=small initrd=small' to get a 1.44MB *test* image

The images are stored in the image directory, the contents of the
images (except for the boot image) in the tmp directory.

There is some special magic built into the scripts that make sure that the
initrd fits on the boot disk by removing/adding some of the modules. See the
description of the *.file_list format for details.

You can select the SuSE release to build for, e.g:

  suserelease=6.4 make initrd

but note:
  - This is ignored in an autobuild environment (for obvious reasons).
  - You cannot sensibly test for 'suserelease' in the various *.file_list files
    using the 'ifenv' construct.
    Use 'suse_major_release', 'suse_minor_release' or 'suse_release' instead.


2. How to make boot disks
=========================

The various boot disks differ only slightly from the installation-images stuff
(different kernel, module lists and syslinux.cfg file) and are derived from
the installation-images directory using the bin/ci_boot* scripts.

o 'boot' (*the* boot image (2.88MB, 1st CD, ia32 only)

  Whithin the installation-images directory, do a

    make boot

o 'yast2' boot disk (== boot image for 2nd CD, ia32 only)

  Running 'bin/ci_bootdis2 test' creates the necessary files in a temporary
  directory. Go there and run:

    boot=small make boot

o 'eide' boot disk (for special eide chipsets, ia32 only)

  Running 'bin/ci_bootdise test' creates the necessary files in a temporary
  directory. Go there and run:

    boot=small make boot

o 'laptop' boot disk (for laptops, ia32 only)

  Running 'bin/ci_bootdisl test' creates the necessary files in a temporary
  directory. Go there and run:

    boot=small make boot

o 'bootdisk' boot disk (the fallback *floppy*, ia32 only)

  Running 'bin/ci_bootdisk test' creates the necessary files in a temporary
  directory. Go there and run:

    initrd=initrd boot=small make boot

o 'modules' disk (ia32 only)

  Running 'bin/ci_bootdisk test' creates the necessary files in a temporary
  directory. Go there and run:

    make modules


3. Format of *.file_list files
==============================

o Lines starting with '#' are comments, empty lines are ignored.

    example:

    # some comment

o You can include other files:

    include <file>

    <file> is relative to the data/*/ tree.

o   if/elsif/else/endif

  - if <expression>

    <expression> is more or less a valid perl expression except that
    variables don't have a starting '$' and are implicitly environment
    variables. The only exceptions to this are 'abuild' and 'arch'.

    Also, you can use 'exists(PACKAGE)' to test for a specific package.

    example:

    if arch eq 'ppc' && (suse_release != 7.1 || lang eq 'fr')
    # ...
    elsif abuild && arch eq 'sparc'
    # ...
    else
    # ...
    endif 

    # note that 'suse_release' is actually $ENV{'suse_release'}; likewise
    # 'lang' etc. But 'abuild' and 'arch' are *not* $ENV{...}!

o <package_name>: [script1,script2]

  Unpack the selected package into a temporary directory. You can optionally
  give the name of rpm-scripts to extract, too. These can be run later
  with the 'e' command (see below).

  <package_name> may be empty, which matters only for disk usage accounting.
  Files are still taken from the last non-empty <package_name>.

  <package_name> can contain '*'s. In that case the latest package version
  is used. If <package_name> ends in '~' the last but one version is used.

  If <package_name> starts with a '?', the package is optional.

  examples:
  
    k_delft:
    aaa_base: prein,postin

o <action> <arg1> <arg2> ...

  Do the specified action. <action> is one of these:

  - add the file/directory tree to the image:

      <args>
    ^ there's a space!

  - add a file/directory with a different name

    m <old_name> <new_name>

  - same as 'm', but link files

    L <old_name> <new_name>

  - same as 'm', but follows symlinks

    a <old_name> <new_name>

  - add optional files (e.g. some modules in initrd)

    M <old_name> <new_name>

  - add and gunzip files

    g <src> <dst>

  - remove a file/directory tree

    r <args>

  - create directories:

    d <args>

  - create a namped pipe:

    n <name>

  - touch a file

    t <args>

  - strip

    S <args>

  - hard link (<args> as for the ln command)

    l <args>

  - symlink

    s <args>

  - apply a patch from the data/*/ tree
    (The patch *must not* contain absolute path names!)

    p <patch>

  - chown/chmod files

    c <perm> <owner> <group> <args>

  - make block device

    b <major> <minor> <name>

  - make char device

    C <major> <minor> <name>

  - add some extra files (That is, add files not from packages but from
    the data/*/ directory.)

    x <src> <dst>

  - append <src> to <dst>; <src> is from the data/*/ directory.

    A <src> <dst>

  - execute a program/rpm-script
    <program/script> is run from within the 'base' environment. $PWD will
    be at the root of the filesystem which is currently built

    e <program> <arg1> <arg2> ...
    e <script>

  - execute a program/rpm-script (with chroot)
    <program/script> is run within a chroot env. <script> must be one of the
    scripts given after the package name

    E <program> <arg1> <arg2> ...
    E <script>

  - apply a perl regexp in a sed-like fashion to a file, <regexp> may contain
    white space but not <file>

    R <regexp> <file>

    Note: if the this is a multi line regexp (ends with /s) it is applied to
    the whole file. Else the regexp is applied to each line.

  - search for a file <name> below <dir> and copy it to <dst>
    (<dst> may be omitted)

    f <dir> <name> <dst>

  - search for a file <name> (in the local system!) below <dir> and copy it
    to <dst> (<dst> may be omitted)

    F <dir> <name> <dst>

  - add files from the local system (This should be used only for
    testing!)

    X <src> <dst>


Extensions:

  - You can specify templates that are applied to groups of packages
    automatically unless there is already some other valid entry for that
    package. E.g.

  TEMPLATE rubygem-.*:
    /usr/*/ruby/gems/*/gems/*/lib
    /usr/*/ruby/gems/*/specifications

    The argument after TEMPLATE is a perl regexp matched agaist package names. If
    the regexp is empty the TEMPLATE matches _every_ package. This can be used
    to formulate a default action for packages. E.g.

  TEMPLATE:
    /

  - You can resolve dependencies and add the missing packages with the
    AUTODEPS placeholder. The solver is run only if there is an AUTODEPS entry
    somewhere.
    Note: if you don't specify any actions in AUTODEPS, templates are appied to
    each individual package. E.g.

  AUTODEPS:

  - Listing scripts after the colon (':') is now optional.

  - You can add tags (comma-separated) after the colon. The following tags
    are supported:
    - requires: create a file <package_name>.requires in the image root
    - nodeps: ignore package dependencies when solving
    - ignore: ignore package ('BuildIgnore')