
## Help ##

The ./scripts/Help script displays the Help messages of the ROCK Linux Build
System. The messages are stored in the text file scripts/help.txt.

  Usage: ./scripts/Help <label>


Start reading the help at the following labels:

  {{Download}}  If you haven't downloaded the package sources yet.

  {{Config}}    If you have downloaded the package sources.


Please also read the file BUILD which can be found in the Documentation/
directory.


## Download ##

Before you can build anything, you need to download the sources of the
packages you want to build. This can be done using the ./scripts/Download
script. The script is also used to test and verify the file checksums.


There are three categories of files:

 1.) Files in pkg-archive/ and opt-archive/

       These directories contain the sources for the base system. You pretty
       sure want them all.

 2.) Files in ext-config/

       This directory contains the build configuration files for the extension
       (3rd party) packages. These files come with the ROCK Linux sources. You
       only need to download them if you want to update or add such a
       package.

 3.) Files in ext-archive/

       This directory contains the package sources for the extension packages. 
       It's up to you if you like to download them all or only some of the files.


If you want to download a single file, it's easy:

 ./scripts/Download Filename(s)

This downloads the file from its primary server. If that server is down, the
page has been moved or the host is unreachable, you can download the file
from a ROCK Linux Mirror:

 ./scripts/Download -mirror Mirror-URL Filename(s)

It is also possible to download multiple files at once. E.g. if you want to
download all files from the pkg-archive/ and opt-archive/ directory simply type:

 ./scripts/Download -pattern 'pkg-archive/*' 'opt-archive/*'

The single quotes are important! The mirror option also works here. E.g.
if you want to download all extension sources from the primary ROCK Linux
mirror, simply type:

 ./scripts/Download  \
             -mirror ftp://gd.tuwien.ac.at/opsys/linux/ROCK/ROCK-{{ver}}  \
             -pattern 'ext-archive/*'

There are also some aliases available. If you want to download only
the base packages (pkg-archive/* and opt-archive/*):

 ./scripts/Download -base

And if you want to download all the ext packages (ext-archive/*
and ext-config/*):

 ./scripts/Download -ext

If you want to download all files you can simply use the command:

 ./scripts/Download -all

You can also let the Download script autodetect which files are needed
for building a package. E.g. if you would like to build xfree86:

 ./scripts/Download -package xfree86

or

 ./scripts/Download -package pkg-config/xfree86


If you want to test the file checksums simply add the '-check' option.
E.g. test the checksums of all files:

 ./scripts/Download -check -all  |  grep ERROR

Without the '| grep ERROR' you would also get a lot of non-error messages.
When the script finds a file with a wrong checksum it automatically renames
it to '<old-filename>.cksum-err'.

When downloading a file, it is automatically checked, unless the -nock option
is used.

 The checksums for the base packages are stored in scripts/cksum.cache, the
checksums for the ext packages are stored in their ext file in 'ext-config/'.
If you want to update/fix the cksum of a package, you can use the -mk-cksum
option to generate a files cksum:

 ./scripts/Download -mk-cksum <filename>

You need to run './scripts/Puzzle' after updating any checksums.

You can also check if there are any (old) files which are not known by the
Download script:

 ./scripts/Download -list-unknown

Or if there are any files which still need to be downloaded:

 ./scripts/Download -list-missing

When downloading a file, the script creates a lock file in src/ to make sure
that no other process also tries to download the same file. That makes it
possible to run multiple download processes parallel as long as they share
the same src/ directory (so every download process can see the lock files
of all other download processes).


## Config ##

Before you can build anything, you need to configure the ROCK Linux build
system. This can be done by creating a file called 'Config' directly in the
root of the ROCK Linux source tree. From now on we will call this file ./Config.

In the ./Config file is a shell script containing variable assignments.
The following variables can be used in the ./Config file:

  arch ............ This variable specifies the target architecture. Simply
                    Type './scripts/Config list-arch' to get a list of
                    possible architecture names.
                      There is no default value for this variable and if you
                    don't set it, the build scripts won't run. All other
                    variables are optional.

  stripbins ....... On default the build system removes all debugging symbols
                    from the produced binaries. If you don't like this you
                    have to set this variable to '0'.

  makerebuild ..... When building the entire distribution the build scripts
                    build every package twice to deal with cross-dependences.
                    For sure this costs a lot of time. If you don't like
                    this set this variable to '0'.

  buildoptpkgs .... If you don't like to build the optional packages (they
                    are marked with an 'o' in the ./scripts/packages file)
                    you need to set this variable to '0'.

  buildextpkgs .... If you don't like to build the extension (3rd party)
                    packages you need to set this variable to '0'.

  abortonerror .... On default the build scripts abort when a package fails
                    to build. Set this variable to '0' if you want the build
                    script to continue with the next package instead.

  dontprintlogs ... On default the output of the build process is only
                    written to a log file in '/var/adm/logs/'. If you also
                    want to see it on the terminal during the build process
                    you need to set this variable to '0'.

  useflwrapper .... The flist wrapper library (a part of the build system
                    which is used to map files to packages) doesn't work
                    on older versions of the glibc. Set this variable to '0'
                    if you think, that the flist wrapper library is broken
                    on your system (the build scripts will tell you).


For most Intel PCs the following will be OK for creating the ./Config file:

  localhost:/rock-linux# echo 'arch=intel' > Config


There is also a configuration utility which can be used for creating
and editing the ./Config file. You can start it with:

  ./scripts/Config text


See Also:  {{Build-All}}  {{Build-Pkg}}  {{Build-Tar}}


## Build-All ##

The ./scripts/Build-All script rebuilds the entire distribution. It will take
a lot of time and disk space.

The Build-All script creates a chroot-target for building the packages. In
order to reach the source packages and build scripts from within that chroot
environment.

 E.g:  ./scripts/Build-All 


See Also:  {{Config}}  {{Build-Pkg}}  {{Puzzle}}  {{Create-Links}}

           {{Build-Stage}}  {{Build-Subdist}}  {{Cleanup}}  {{Create-CD}}


## Build-Pkg ##

The ./scripts/Build-Pkg script (re-)builds one or more packages. It
automatically detects if the package is a base or extension package
and runs the appropriate scripts.

Usage: ./scripts/Build-Pkg [ -1 .. -5 ] [ -noclearsrc ] [ -maketar ]  \
                           [ -norebuild ] pkg-name(s)

Options:  -1 .. -5     Specifies the stage level. The default is '5'.

          -noclearsrc  Don't remove all content of src/ before and after
                       building the package.

          -maketar     Create the package .tar.bz2 file after building
                       the package.

          -norebuild   Don't build the package if there is already a
                       build log for that package in /var/adm/logs/.


Instead of the pkg-name you can also use 'pkg-config/pkg-name'
or 'ext-config/pkg-name.ext'.


See Also:  {{Build-All}  {{Build-Tar}}


## Build-Tar ##

The ./scripts/Build-Tar script creates the package .tar.bz2 files from the
files on the harddisk and the package meta-data in /var/adm/*.

Usage:  ./scripts/Build-Tar  root-dir  pkg-name(s)

If you would like to create the .tar.bz2 file from the running system,
use / as the root-dir option. If you built the packages in a chroot target
you need to speficy the path name here.

The package tar files are saved as '<rock-base>/tars/<arch>-<pkg>.tar.bz2'.

This scripts also creates the package md5sums and cksums.


## Build-Stage ##

The ./scripts/Build-Stage script can be used for building all packages in
one stage level.

  Usage: ./scripts/Build-Stage  1 | 2 | 3 | 4 | 5 | E

If called with the 'E' parameter the script will build all extension packages.


See Also:  {{Build-All}}


## Build-Subdist ##

The ./scripts/Build-Subdist script can be used for building a subdistribution.

  Usage: ./scripts/Build-Subdist  subdist-name

Normally building a subdistribution requires that you built the base
distribution first and the produced packages are now where the Build-All
script placed them. Details can be found in the subdistributions documentation.


See Also:  {{Build-All}}


## Create-Links ##

Usually one does not work directly in the rock source tree. Instead, you have
an pkg-archive directory (let's call it '/rock-orig') and a work directory (let's
call it '/rock-linux').

All the source packages and build scripts are stored in /rock-orig. The
according directories are linked to /rock-linux to make them accessable
from there. These links can be created with:

   localhost:/rock-orig# ./scripts/Create-Links /rock-linux

There are multiple reasons for having an pkg-archive directory and one or more
work directories:

 1.) The pkg-archive directory has to be reachable via NFS (See {{Build-All}}
     for details). But the work directory does not.

 2.) It is not possible to run more than one build script in the same work
     directory. If you create an pkg-archive- and multiple work directories you
     can also start multiple scripts (E.g. one for rebuilding the entire
     distribution in the background and another for writing packages).

 3.) You can put the pkg-archive directory on a (slow) NFS server or a CD-ROM.


See Also:  {{Build-All}}


## Cleanup ##

The ./scripts/Cleanup script removes all files and directories produced by
the build scripts - except the final product of Build-All.

It's invoked several times by the Build-All script so, when a build aborted
a new run of Build-All will restart the entire build with the first package
after Cleanup has removed the old stuff. You can change this by creating a
file with the name _nodel_ in the base directory:

  touch _nodel_

That disables the Cleanup script. You can remove the file from another console
as soon as the Build-All script starts building new packages.


## Create-CD ##

The ./scripts/Create-CD script can be used to create the CD-ROM images.

  Usage: ./scripts/Create-CD  source | arch

If the parameter is 'source' the CD image containing the ROCK Linux sources
will be created. If the parameter is different from 'sources' it's the name
of a ROCK Linux architecture (like 'intel', 'powerpc' or 'k6') and it will
create a CD image containing the binary distribution for that architecture.
In that case you first need to build the binary distribution using the
Build-All script.


See also:  {{Build-All}}


## Create-CrossCC ##

The Create-CrosCC script creates a cross binutils and cross compiler for the
target architecture specified in the ./Config file. It's only needed for
cross-building ROCK Linux (which is only done once for every new platform
ROCK Linux is ported to).


## Create-SrcTar ##

The Create-SrcTar script creates the ROCK Linux source tar file.


## Internal ##

The Internal script implements a number of small features needed by the ROCK
Linux core maintainers.


## Puzzle ##

The Puzzle script creates all auto-created files in the ROCK Linux build system.
E.g. if you modified any of the *.pz files in the source tree you need
to run this script to rebuild scripts/packages, pkg-archive/INDEX and other
automatically created files.
