rocklinux/Documentation/Developers/HACKING-HOWTO

                        The ROCK Linux Hacking Howto
                        ============================
                          Written by Clifford Wolf
                          ~~~~~~~~~~~~~~~~~~~~~~~~

The Jargon File defines a "Hacker" as:

# hacker n.
#
#  [originally, someone who makes furniture with an axe] 1. A person
#  who enjoys exploring the details of programmable systems and
#  how to stretch their capabilities, as opposed to most users, who
#  prefer to learn only the minimum necessary. 2. One who programs
#  enthusiastically (even obsessively) or who enjoys programming
#  rather than just theorising about programming. 3. A person capable
#  of appreciating hack value. 4. A person who is good at programming
#  quickly. 5. An expert at a particular program, or one who frequently
#  does work using it or on it; as in `a Unix hacker'. (Definitions 1
#  through 5 are correlated, and people who fit them congregate.) 6. An
#  expert or enthusiast of any kind. One might be an astronomy hacker,
#  for example. 7. One who enjoys the intellectual challenge of
#  creatively overcoming or circumventing limitations. 8. [deprecated]
#  A malicious meddler who tries to discover sensitive information
#  by poking around. Hence `password hacker', `network hacker'. The
#  correct term for this sense is cracker.

So this "ROCK Linux Hacking Howto" has nothing to do with host- or
network-security.


	Table of Contents
	=================

0. Preface

1. ROCK Linux directory tree
1.1. Documentation/
1.2. scripts/
1.3. package/
1.3.1. package/base/
1.3.2. package/x11/
1.3.3. package/<architecture>/
1.3.4. package/<person>/
1.4. misc/
1.5. target/
1.6. architecture/
1.7. download/
1.8. src*/ and build/
1.9. config/*

2. Build- and other scripts
2.1. ./scripts/Config
2.2. ./scripts/Download
2.3. Scripts for building stuff
2.3.1. ./scripts/Build-Target
2.3.2. ./scripts/Build-Pkg
2.3.3. ./scripts/Build-TarBz2
2.3.4. ./scripts/Build-Tools
2.3.5. ./scripts/Build-CrossCC
2.3.6. ./scripts/Build-Job
2.4. Various small Helpers
2.4.1. ./scripts/Cleanup
2.4.2. ./scripts/Create-Links
2.4.3. ./scripts/Create-PkgList
2.4.4. ./scripts/Create-PkgQueue
2.4.5. ./scripts/Create-SrcTar
2.4.6. ./scripts/Create-Diff
2.4.7. ./scripts/Create-CkSumPatch
2.4.8. ./scripts/Create-DescPatch
2.4.9. ./scripts/Create-PkgUpdPatch
2.4.10. ./scripts/Create-ErrList
2.4.11. ./scripts/Create-UpdList
2.4.12. ./scripts/Update-System
2.4.13. ./scripts/Puzzle
2.4.14. ./scripts/Help
2.4.15. ./scripts/Internal
2.5. Scripts for doing checks
2.5.1. ./scripts/Check-PkgVersion
2.5.2. ./scripts/Check-PkgFormat
2.5.3. ./scripts/Check-System
2.5.4. ./scripts/Check-Deps
2.6. Scripts for updating the source tree
2.6.1. ./scripts/Update-Src

3. Configuration System
3.1. Fundamentals
3.2. Special Commands
3.2.1. comment 'Description' ["Help"]
3.2.2. comment_id 'Description' 'ID' ["Help"]
3.2.3. bool 'Description' Variable Default ["Help"]
3.2.4. text 'Description' Variable Default ["Help"]
3.2.5. choice Variable Default Value1 'Description1' [ ... ]
3.2.6. const Variable Default
3.2.7. block_begin and block_end
3.2.8. expert_begin and expert_end
3.3. Special Variables
3.3.1. ROCKCFG_*
3.3.2. ROCKCFGSET_*
3.3.3. CFGTEMP_*
3.4. Config.in call-tree
3.5. Creation of the Packages file

4. Packages
4.1. Fundamentals
4.2. The *.desc files
4.2.1. Package Priority
4.2.2. Download URLs
4.3. The *.conf files
4.3.1. FIXME
4.4. The *.patch files
4.5. The *.doc files
4.6. The *.init files

5. Targets

6. Architectures

( created with >> perl -pe '$_="" unless /^\t?[0-9]/; s/^\t/\n/;' << )


	0. Preface
	==========

This document describes how to extend and modify the ROCK Linux Build Scripts.

You need to know shell scripting well to understand the techniques described
in this document. Some practise with building and installing software on UNIX
systems might also help.

Use the existing code (packages, targets, etc.) as examples. The explanations
given here are often very brief and looking at the code might help you to
understand.

Corrections, etc. are always welcome (unified diffs preferred).

                                   - Clifford wolf <clifford@clifford.at>


	1. ROCK Linux directory tree
	============================

1.1. Documentation/
===================

The ROCK Linux Documentation. Read everything - if you can! You should also
visit our homepage at www.rocklinux.org and subscribe to the mailing list.

1.2. scripts/
=============

All the build and helper scripts can be found here. A detailed description of
them can be found in chapter 2.

Make sure to always call them from the base directory (like "./scripts/Config")
and _do_not_ change into scripts/ and execute the script there!

1.3. package/
=============

The ROCK Linux specific part of the package sources are stored in this tree.
This is for every package at least a ".desc" file (read chapter 4 for more
details about the package format).

Within the package/ directory, every "package repository" has it's own
subdirectory. A "package repository" is an organisational unit to group
packages together. All packages with a repository do belong to the same
maintainer or maintainer-team.

Within the repository-directory, every package has it's own subdirectory.
E.g. the 'gcc' package can be found in "package/base/gcc/".

1.3.1. package/base/
--------------------

The "base" repository contains the most important core-packages. Stuff like
the compiler, the kernel and the standard unix command-packages (coreutils, ..).

The "base" packages are maintained by Clifford Wolf <clifford@rocklinux.org>.

1.3.2. package/x11/
-------------------

The "x11" repository contains the basic X11 packages. Everything you need
to  set up a graphical workstation including the most important tools.

1.3.3. package/<architecture>/
----------------------

There are some architecture specific repositories like 'alpha', 'powerpc',
'sparc', 'x86', ... They contain packages that are only useful on this one
architecture.

1.3.4. package/<person>/
----------------------

Other packages are grouped together into repositories named by the maintainer.
Those are e.g. 'clifford', 'esden', ... and many more.
But functional grouping like kde and gnome repositories are also possible.

1.4. misc/
==========

Various stuff which doesn't fit elsewhere can be found here.

1.5. target/
============

A 'target' is a ROCK Linux based distribution. The 'normal ROCK Linux' is
the 'crystal' target, built with the default settings.

Every target has it's own subdirectory in this tree.

1.6. architecture/
==================

Every architecture supported by ROCK Linux has it's own subdirectory in this
tree.

1.7. download/
==============

The original package tar files are downloaded to that directory by the
./scripts/Download script. Only the files required for building the selected
target will be downloaded.

1.8. src*/ and build/
=====================

This directories are created by the Build-Scripts. They can be easily removed
using './scripts/Cleanup'.

1.9. config/*
=============

The build configurations (created with './scripts/Config') are stored in
the config/ tree. Every configuration has it's own subdirectory there.


	2. Build- and other scripts
	===========================

Most scripts print a help text, containing a description of syntax and
options, when started with the '-help' option.

2.1. ./scripts/Config
=====================

./scripts/Config is the main configuration script. If no configuration name
is specified via the option -cfg <config-name> the name 'default' is used.
It parses the metaconfig files described in chapter 3 and creates the files
in config/<config-name>/. If a config-name is specified it also has to
be passed to the other scripts, too.

2.2. ./scripts/Download
=======================

The ./scripts/Download script is the tool for downloading the package sources.
Calling the script without any parameters prints out the help message.

You can download single files:
	./scripts/Download download/mirror/l/linux-2.4.18.tar.bz2

All files for a single package:
	./scripts/Download -package linux24

All files required for building the configured target:
	./scripts/Download -required

Or simply everything:
	./scripts/Download -all

If you don't specify a mirror using the -mirror option, the script will
contact www.rocklinux.org and auto-detect the best mirror.

Downloading all files required from a local (mounted) cdrom:
	./scripts/Download -mirror file:///mnt/cdrom/ -required

2.3. Scripts for building stuff
===============================

2.3.1. ./scripts/Build-Target
-----------------------------

Builds the configured target. Depending on your hardware and the configuration
made with ./scripts/Config this may take a few days (or a week or even longer)
to complete.

2.3.2. ./scripts/Build-Pkg
--------------------------

Builds a single package. Calling this script without any option prints
out a usage message. In most cases the options are only needed by Build-Target
when building the entire distribution.

Building a single package:
	./scripts/Build-Pkg gawk

Warning: Re-building a package might overwrite or remove config files - using
the option -update backups modified files and restores them after the package
build.

2.3.4. ./scripts/Build-Tools
----------------------------

This script creates the 'build/xxxxxx/ROCK/tools' directory (where 'xxxxxx' is the
config id) which contains various helper applications needed by Build-Pkg and
other scripts.

When the script is called with the -cleanup option, a rebuild of the files in
the tools directory is forced. In most cases this script will be called by
other scripts (and not by the user).

2.3.5. ./scripts/Build-CrossCC
------------------------------

For cross-building ROCK Linux you need a cross-compiler. This script creates
the cross-compiler for you. The cross-compiler and cross-binutils will be
installed in the build/ tree where the Build-Pkg script expects them to be.

2.3.6. ./scripts/Build-Job
--------------------------

This script is the client when you run ./scripts/Target in parallel
build (cluster) mode.

2.4. Various small Helpers
==========================

2.4.1. ./scripts/Cleanup
------------------------

The Cleanup script can be used to remove the src* and build* directories which
are created by the build scripts. Never remove these directories manually!!!

On default ./scripts/Cleanup only removes the src* directories. the build*
directories are only removed when the -full option is passed.

2.4.2. ./scripts/Create-Links
-----------------------------

This very simple script creates symlinks from you ROCK Linux base directory
to another directory. This can be useful if you have the ROCK Linux sources
on one harddisk (NFS Share, etc) and want to build somewhere else:

	/disks/raid/archive/os/rock# mkdir -p /disks/fast/rock
	/disks/raid/archive/os/rock# ./scripts/Create-Links /disks/fast/rock

2.4.3. ./scripts/Create-PkgList
-------------------------------

Creates a list of all packages available. If an architecture name is passed
as parameter, only the packages available on that architecture are listed.

This script is used by ./scripts/Config in the process of creating the
packages file.

2.4.4. ./scripts/Create-PkgQueue
--------------------------------

Creates a list of packages which could be built next. The first parameter is
the maximum number of packages to print (0=no limit) and the 2nd parameter is
the root directory where the script can find the /var/adm/... information it
needs. E.g.:

     # ./scripts/Create-PkgQueue 3 build/default-TRUNK-x86-generic/
     2 X --2------9 010.050 base strace 4.4 / development/tool 159
     2 X --2------9 010.052 base ltrace 0.3.10 / development/tool 85
     2 X --2-4----9 010.055 base perl5 5.6.1 / development/interpreter 125

The script is primarily used by ./scripts/Build-Target.

2.4.5. ./scripts/Create-SrcTar
------------------------------

Creates a .tar.bz2 file containing the ROCK Linux sources. This script is
used by the ROCK Linux core developers when releasing snapshots or releases.

2.4.6. ./scripts/Create-Diff
----------------------------

This script is the recommended tool for creating diff patches. (When you
made a change to the ROCK Linux sources and want to share your work).

E.g.: ./scripts/Create-Diff ../rock-src.orig . > mychanges.diff

2.4.7. ./scripts/Create-CkSumPatch
----------------------------------

This script can be used by ROCK Linux developers to automatically create the
download checksums in the .desc files in one or more package repositories.

E.g.: ./scripts/Create-CkSumPatch glibc | patch -p1

2.4.8. ./scripts/Create-DescPatch
---------------------------------

This script can be used by ROCK Linux developers to automatically adopt the
format of the package .desc files.

E.g.: ./scripts/Create-DescPatch -repository base | patch -p1

2.4.9. ./scripts/Create-PkgUpdPatch
-----------------------------------

This script can be used by ROCK Linux developers to automatically create
package update patches (after evaluating the output of the
./scripts/Check-PkgVersion script). E.g.:

	./scripts/Create-PkgUpdPatch | patch -p1 << EOT
		automake-1.6.1, bin86-0.16.3, bison-1.35, curl-7.9.6,
		diffutils-2.8.1, dump-0.4b28, ifhp-3.5.7, net-snmp-4.2.4,
		ntp-4.1.1, pciutils-2.1.10, sendmail.8.12.3, silo-1.2.5,
		tree-1.4b2, util-linux-2.11q, whois_4.5.25
	EOT

2.4.10. ./scripts/Create-ErrList
--------------------------------

Outputs the list of packages which failed to build (including the stage
numbers) in the right order.

2.4.11. ./scripts/Create-UpdList
--------------------------------

Create a list of packages which are active in the current configuration and
have changed since the binaries installed on the local system have been
generated. The compare is done using the package source checksums stored
in /var/adm/packages/<package-name>.

2.4.12. ./scripts/Update-System
-------------------------------

Update (re-build) all packages on the local system for which newer versions
are available. Create-UpdList is used to generate the list of packages which
do need an update.

2.4.14. ./scripts/Help
----------------------

This script expects the filename of a script in ./scripts/ and jumps to
the right position in this document. It's a very simple wrapper for 'less'.

2.4.15. ./scripts/Internal
--------------------------

This script is used by Clifford Wolf to release snapshots and to keep the
FTP Mirrors up-to-date.

2.5. Scripts for doing checks
=============================

2.5.1. ./scripts/Check-PkgVersion
---------------------------------

This script is used by the ROCK Linux developers to check for new package
versions. The results of the last run are always stored in a directory called
checkver/ and if there is a difference in the current run, a *.msg file will
be written to checkver/.  (read the script for details)

E.g.: ./scripts/Check-PkgVersion -repository base
      for x in checkver/*.new ; do mv -f $x ${x%.new}.txt ; done
      cat checkver/*.msg > todo.txt

Note: An old *.msg file will automatically removed when you run
Check-PkgVersion the next time.

2.5.2. ./scripts/Check-PkgFormat
--------------------------------

This script does a few very simple tests to auto-detect errors in the package
*.desc and *.conf files.

E.g.: ./scripts/Check-PkgFormat -repository base

2.5.3. ./scripts/Check-System
-----------------------------

This script does a very simple tests to auto-detect possible problems
with the host linux system.

2.5.4. ./scripts/Check-Deps
---------------------------

This command checks if the current package build order is ok for solving all
package dependencies.

2.6. Scripts for updating the source tree
=========================================

2.6.1. ./scripts/Update-Src
---------------------------

Update the source tree with rsync from www.rocklinux.org.
Warning: This will remove the changes you have made to the source tree.


	3. Configuration System
	=======================

3.1. Fundamentals
=================

The configuration script ./scripts/Config generates the files in the
config/${config}/ directory:

	config		the configuration options
	packages	the packages which are build in this configuration

./scripts/Config defines some special shell functions and contains the
main-loop of the configuration program. The structure of the config menus
is stored in scripts/config.in (and other config.in files included by it).
Have a look at scripts/config.in for more information on which file is
including which other files.

3.2. Special Commands
=====================

Whenever the menu is displayed (i.e. after starting ./scripts/Config and
whenever a change has been made), scripts/config.in is executed and is using
the following special commands to write the 'config' file and add items to the
menu.

3.2.1. comment 'Description' ["Help"]
-------------------------------------

Add a comment to the config menu (an item without any function). E.g.:

	comment '- Architecture, CPU and Optimisation' "
	Select which CPU optimalization is right for your machine."

<Description>	Title of the item in the config menu (comment text)

<Help>		This is an optional field where you can add a longer comment 
		that will be displayed when you highlight this comment line 
		and hit the Help button

3.2.2. comment_id 'Description' 'ID' ["Help"]
---------------------------------------------

Add a comment to the config menu (an item without any function). E.g.:

	comment '- Architecture, CPU and Optimisation' COMMENT_ARCH_CPU_OPT "
	Select which CPU optimalization is right for your machine."

<Description>	Title of the item in the config menu (comment text)

<ID>		ID which will be used to identify a comment. It is
		useful when you use config.hlp files to store help

<Help>		This is an optional field where you can add a longer comment 
		that will be displayed when you highlight this comment line 
		and hit the Help button

3.2.3. bool 'Description' Variable Default ["Help"]
---------------------------------------------------

Add a bool (on/off) menu item. E.g.:

	bool 'Abort when a package-build fails' ROCKCFG_ABORT_ON_ERROR 1 "
	When you select this option Build-Target will abort when a packet 
	fails to compile"

<Description>	Title of the item in the config menu
<Variable>	Name of the config variable triggered by this menu item
<Default>	'1' = On, '0' = Off
<Help>		This is an optional field where you can add a longer comment 
		that will be displayed when you highlight this item line 
		and hit the Help button

The variable will be set to '1' or '0'.

3.2.4. text 'Description' Variable Default ["Help"]
---------------------------------------------------

Add a text menu item. If the text must fit a special pattern, modify the
config variable _before_ calling the text function. E.g.:

	ROCKCFG_MAKE_JOBS="`echo $ROCKCFG_MAKE_JOBS | sed 's,[^0-9],,g'`"
	text 'Number of parallel make jobs (make -j)' ROCKCFG_MAKE_JOBS 1

<Description>	Title of the item in the config menu
<Variable>	Name of the config variable triggered by this menu item
<Default>	Default value
<Help>		This is an optional field where you can add a longer comment 
		that will be displayed when you highlight this item line 
		and hit the Help button

3.2.5. choice Variable Default Value1 'Description1' [ ... ]
------------------------------------------------------------

Add a multiple-choice menu item. E.g.:

	choice ROCKCFG_INTEL_OPT generic   \
		generic "No special optimisation"          \
		i386    "Optimised for Intel 386"          \
		i486    "Optimised for Intel 486"          \
		i586    "Optimised for Intel Pentium"      \
		i686    "Optimised for Intel Pentium-Pro"  \
		k6      "Optimised for AMD K-6"            \
		k7      "Optimised for AMD Athlon"

<Variable>	Name of the config variable triggered by this menu item
<Default>	Default value

<ValueN>	Value for option N
<DescriptionN>	Title of the item in the config menu if option N is active

3.2.6. const Variable Default
-----------------------------

Sets the given variable to the given default value without displaying any
menu item.

3.2.7. block_begin and block_end
--------------------------------

A set of menu items which belongs together should be surrounded with
block_begin and block_end. block_begin expects a numeric parameter which
specifies the number of characters the menu item titles should be shifted
to the right. E.g.:

    comment '---   Default compiler for building (almost) everything'
    block_begin 5
        choice ROCKCFG_PKG_GCC_DEFAULT_CC gcc2 $list

        if [ $ROCKCFG_PKG_GCC_DEFAULT_CC = 'gcc2' ] ; then
            bool 'Use GCC Stack-Smashing Protector' ROCKCFG_PKG_GCC_STACKPRO 0
            [ $ROCKCFG_PKG_GCC_STACKPRO = 1 ] &&
                                ROCKCFG_ID="$ROCKCFG_ID-stackprotector"
        else
            ROCKCFG_ID="$ROCKCFG_ID-$ROCKCFG_PKG_GCC_DEFAULT_CC"
        fi
    block_end


3.2.8. expert_begin and expert_end
----------------------------------

Options which should only be displayed if the 'expert mode' is active should be
surrounded with expert_begin and expert_end.

3.3. Special Variables
======================

3.3.1. ROCKCFG_*
----------------

All Configuration variables should start with "ROCKCFG_". Non-core variables
have extended prefixes:

Arches:   ROCKCFG_ARCH_<Arch-Name>_*
Targets:  ROCKCFG_TRG_<Target-Name>_*
Packages: ROCKCFG_PKG_<Pkg-Name>_*

Some variables are handled by ./scripts/Config in a special way:

ROCKCFG_ID	Is the short-description of the configuration. Important
		config options should append something to this variable.

ROCKCFG_EXPERT	If set to '0', config items between expert_begin and
		expert_end will not be displayed and the default values
		for those options will be used.

3.3.2. ROCKCFGSET_*
-------------------

The ROCKCFGSET_* variables can be used to preset an option (e.g. in a target).
If e.g. ROCKCFGSET_STRIP is set to 1, ROCKCFG_STRIP will have the value 1
when you start configuring this target. Note that these options can still
be overwritten in scripts/Config, they are merely different default values.

3.3.3. CFGTEMP_*
----------------

This variables can be used for data-exchange between the various config.in
files. Non-core variables have extended prefixes:

Arches:   CFGTEMP_ARCH_<Arch-Name>_*
Targets:  CFGTEMP_TRG_<Target-Name>_*
Packages: CFGTEMP_PKG_<Pkg-Name>_*

E.g. dynamic creation of a multiple-choice option:

architecture/intel/preconfig.in:
	CFGTEMP_ARCHLIST="$CFGTEMP_ARCHLIST intel IBM_PCs_and_compatible"

architecture/powerpc/preconfig.in:
	CFGTEMP_ARCHLIST="$CFGTEMP_ARCHLIST powerpc PowerPC_Workstations"

scripts/config.in:
	choice ROCKCFG_ARCH $ROCKCFG_ARCH $CFGTEMP_ARCHLIST

3.4. Config.in call-tree
========================

All config.in files are executed from scripts/config.in the the following
order:

	- architecture/*/preconfig.in

	* Selecting Architecture
	* architecture/$ROCKCFG_ARCH/config.in

	- target/*/preconfig.in
	- package/*/*/preconfig.in

	* Selecting Target
	* target/$ROCKCFG_TARGET/config.in

	* package/*/*/config.in
	* Various common build options

	- package/*/*/postconfig.in
	- architecture/$ROCKCFG_ARCH/postconfig.in
	- target/$ROCKCFG_TARGET/postconfig.in

Only scripts marked with '*' may interact with the user (create menu
items). The others may only set and modify various variables.

3.5. Creation of the Packages file
==================================

The ./scripts/Config script creates a 'packages' file with all packages
available for the selected architecture before calling scripts/config.in.
Every config.in file might now modify this Packages file by creating a
Packages.new file and renaming it to Packages. E.g.:

	if [ $ROCKCFG_TRG_GENERIC_BUILDSF != 1 ] ; then
                awk '$4 != "sourceforge" { print }' \
			< config/$config.$swpid/packages \
			> config/$config.$swpid/packages.new
                mv config/$config.$swpid/packages.new config/$config.$swpid/packages
        fi

The packages file is blank-separated and easy to parse with grep, sed and awk.
The fields are:

X/O	'X' = packages is active,  'O' = package is not active
	If you don't want another config.in to re-activate a package you might
	also simply remove the line from the file.

Stages	Stage levels as specified in the packages [P] tag (see next chapter)

Pri.	Priority as specified in the packages [P] tag (sort-key for the file)

Rep.	Repository name where the package is found

Name	Package Name

Ver.	Package Version

Prefix	Package prefix (with leading '/')

Cat.	Package categories (always lower case, contain at least one /)

Flags	Package flags (always upper case)

Counter	Simply ignore that field

Because of the 'counter' field, categories and flags are always pre- and
postfixed with a ' '. So you can e.g. easy remove all not dietlibc-ready
packages with a command like:

	grep ' DIETLIBC ' < config/$config.$swpid/packages \
				> config/$config.$swpid/packages.new

Read the existing config.in files for details.


	4. Packages
	===========

4.1. Fundamentals
=================

Every package has it's own subdirectory in package/<repository>/. The
repositories are organisational units to group packages. Every repository
belongs to one ROCK Linux developer or developer group. The per-package
directory must have the same name as the package.

The Package name is 2-25 characters long and must match the regular expression:

	/^[a-z0-9][a-z0-9\.\+_-]*[a-z0-9\+]$/

(Minimum of 2 characters. First one: lower case letter or number. Last
one: lower case letter, number or '+'. Rest: lower case letter, number
or one of '.', '+', '_' or '-'.)

A package name must not be used in more than one repository.

Other (non-package) subdirectories are allowed, if they don't begin with
a lower case letter or number (so e.g. "CVS" subdirectories are ok) and
do not contain any *.desc files.

This per-package directory contains all information needed to download and
build a package.

4.2. The *.desc files
=====================

Every Package _must_ have a <packagename>.desc file. It contains all the
meta-information for the package. Have a look at the PKG-DESC-FORMAT file
for a description of the available tags. The more complex ones are described
in detail in this howto.

4.2.1. Package Priority
-----------------------

The [P] tag is used to set the "package priority". The [P] tag has three
fields:
	[P] X --3-----9 010.066

The first field ('X' or 'O') specifies if this package should be built per
default (X) or not (O). This is 'X' for almost all packages. This flag might
be overwritten by the configuration (see chapter 3).

The 2nd field lists the stages in which the package should be built. There
are 10 stages (0-9). Build-Target will start with building stage one, then
stage 2 and so on. Stage 9 is only built if 'Make rebuild stage (stage 9)'
is activated in the configuration. Stages 0 and 1 are cross-build stages and
should only contain packages which can be cross-built. So, the stages can be
used to specify the build order (e.g. stage 3 is built before stage 5) and
to re-build a package multiple times.

The 3rd field is used to specify the build order within the stages. It's
simply text-sorted.

4.2.2. Download URLs
--------------------

Usually a package must download one or more original source file. This files
are downloaded using the ./scripts/Download script and stored in the
directory 'download/<repository-name>/<package-name>/'.

Every file which should be downloaded has it's own [D] tag in the package
*.desc file. The [D] tag has three fields:

	[D] 354985877 gcc-2.95.3.tar.gz ftp://ftp.gnu.org/pub/gnu/gcc/

The first field is the checksum for this file. Those checksums are created
with e.g.:

	./scripts/Download -mk-cksum download/base/gcc2/gcc-2.95.3.tar.bz2

If the checksum is simply '0', this means that no checksum has been created so
far. The script ./scripts/Create-CkSumPatch can be used for creating a patch
which fills in those checksums.

For files which should not have a checksum for one or another reason (e.g.
because the content on the original site is changing often), a checksum-string
consisting of only 'X' characters can be used. E.g.:

	[D] XXXXXXXXXX RFCs3001-latest.tar.gz ftp://ftp.rfc-editor.org/in-notes/tar/

The 2nd field is the filename. Files with the postfix *.gz or *.tgz are
automatically converted to *.bz2 or *.tbz2 files by the ./scripts/Download
script.

The 3rd parameter is the download URL without the filename part. If the local
filename differs from the remote filename, the URL must be prefixed with a '!'
character. E.g.:

	[D] 2447691734 services.txt !http://www.graffiti.com/services

The ./scripts/Check-PkgVersion script is also using this [D] tags for checking
for new package versions. The ./scripts/Check-PkgVersion can also be directly
configured using the tags [CV-URL], [CV-PAT] and [CV-DEL].

Download from a Subversion repository:
	[D] X somethingfromsubversion.tar.bz2 svn://svn:publicuser:publicpassword@server:12345:/path::revision

The svn:// download method has this syntax
	svn://mode:[login[:password]@]server[:port]:/path::revision/

Dowload from a CVS server:
	[D] X gatos-ati.4.4.0-2004-08-09.tar.bz2 cvs://pserver:anonymous@cvs.gatos.sourceforge.net:/cvsroot/gatos::ati.4.4.0/!2004-08-09/

The cvs:// download method has this syntax
	cvs://mode:[login[:password]@]server[:port]:/path::module!revision/

4.3. The *.conf files
=====================

./scripts/Build-Pkg has a semi-intelligent code for building and installing a
package. It's the build_this_package() shell function which can be found in
./scripts/functions. This script is configured using various variables
which can be set or modified in the *.conf file. A list of those variables
can be found in the PKG-BUILD-VARS file in this directory. Read the existing
*.conf files for examples.

4.4. The *.patch files
======================

All *.patch files in the package directory are automatically applied after the
package source tar file has been extracted. The *.patch.<architecture> patch
files are only applied when building for the specified architecture.

4.5. The *.doc files
====================

All *.doc files in the package directory are automatically copied to the
package documentation directory (e.g. /usr/share/doc/$pkg) without the ".doc"
postfix.

4.6. The *.init files
=====================

Init scripts are installed using the shell function install_init. This function
is converting a *.init file into a SysV Init Script. Have a look at

	package/base/devfsd/devfsd.conf and
	package/base/devfsd/devfsd.init
or
	package/base/sysklogd/sysklogd.conf   and
	package/base/sysklogd/sysklogd.init

for small examples. The conversion from *.init files to SysV Init Scripts is
done using m4 and the macro file 'package/base/sysvinit/init_macros.m4'.


	5. Targets
	==========

A ROCK Linux target is a distribution based on ROCK Linux. It can alter the
package selection, force some special configuration to be used, supply
additional patches to each package, modify any build aspect of a package and
more.

The most important file of a target is the 'preconfig.in' file where the
target needs to register itself via:

	CFGTEMP_TARGETLIST="$CFGTEMP_TARGETLIST target_name Long_Visible_Name"

When a target is selected the file 'config.in' is evaluated. Here options
can be forced to be set/unset and new options can be introduced.

The file build.sh is executed for the build of the target. If the target is
a straight-forward build only the ROCK Linux auto-build-system needs to be
called:

	pkgloop

or to also generate some database files for the install-cd the generic
build.sh can be reused:

	. target/generic/build.sh

A target specific .conf file or patch for a package may easily be added
by placing it under the name pkg_$pkg.conf or pkg_$pkg.patch in the target's
directory. Where $pkg is the name of the respective package.

Some packages might have target specific hooks, like the linux* package which
uses a kernel.conf.sh in the target's directory to perform additional config
work on the kernel's .config file. 

	6. Architectures
	================

Aside from the fact that each architecture needs at least to register itself
to the ROCK Linux build system, it might provide patches and kernel
configuration to work properly.

The registering works via the preconfig.in file - just like for the targets:

	CFGTEMP_ARCHLIST="$CFGTEMP_ARCHLIST arch_name4 Long_Visible_Name"

The usual config.in can be used to force options to be set/unset or to
introduce new options (just like the config.in in several other places).

The file gcc-options controls additional options passed to GCC.

The files kernel{$treever,}.conf{m4,sh,} and  kernel-disable{treever,}.lst
are used to control the options used for the linux kernel build.

As already mentioned in the explanation of packages, architecture specific
patches are added to the respective package with a patch.$arch suffix.

A archtest.out or archtest.sh file should be present to define some constants
like:

	arch_sizeof_short=2
	arch_sizeof_int=4
	arch_sizeof_long=4
	arch_sizeof_long_long=8
	arch_sizeof_char_p=4
	arch_bigendian=yes
	arch_machine=powerpc
	arch_target=powerpc-unknown-linux-gnu