
Mini-HOWTO

Author: Stefan Koerner (ripclaw@rocklinux.org)
editor:	vim 5.4 (rocklinux-1.3.7/linux-2.3.34; en-DE)
URL: www.rocklinux.org/people/ripclaw/articles/rock-package-HOWTO
Revision History:
	29th April 2000		released first version
	21st May 2000		integrated all the changes

Copyleft 2000 Stefan Koerner for Rock Linux.
This Document is published in source under the terms of the GPL.
(I looked at the FDL, but I dislike it).


I`ve been getting a lot of questions regarding packages recently, so i`ve
decided to write some documentation on that.
To say it with Alan Cox:
"Documentation is worth it just to be able to answer all your mail with `RTFM`"


So what will I be explaining here ?
- what types of packages exist in rocklinux
- where to look for a pkg or ext.
- what`s the philosophical difference between pkg and ext
- writing an extension
- the environment of the extension

what will not be explained here:
- package handling - man pkg-tools !
- the flists - ls /var/adm/flists !
- the package info - ls /var/adm/packages !


The different packages in ROCK Linux:

	Starting shortly after release 1.2.0, ROCK Linux was changed
	to ease the maintainance of a large number of packages for
	the developers - the result was the split between two types
	of software packages:
	"pkg" - the core package.
	"ext" - the extension package.

	The package itself is mostly a tarball, so i will talk about
	the files needed to create a package for ROCK Linux here as
	the "package".

	The core packages are the most basic part of ROCK Linux
	and are mostly packages other tools rely on:
	the kernel, libs, vi, the init-scripts, etc.
	The core packages are maintained by a single person and
	thus are designed to be easy to maintain for one person.
	Whether a package is a core package or not is not 100%
	fully defined, but the basic definition is:
	"It`s a core package if the system depends on it and it`s
	absolutely necessary to have it on the first install CD."
	(Sure - nethack *is* extremely necessary for sysadmin sanity !)

	Everything else is an extension package.
	Extension packages are designed to be easily maintained by a
	large number of persons at different sites, and also easily
	collected by the single core package maintainer.
	Also note that the system should work completely without
	any extensions.

	Finally I have to note that the extension and core are nothing
	but some configuration for the scripts - which will automatically
	create the final tar-bz2-ball and a set of info used to install
	the finished data.


Where to look for the diffenent packages:

	The sources to these packages can be found in the ROCK Linux
	tarballs at ./pkg-config/ and ./ext-config/ respectively.
	A sample developer tree of packages can be found at
	http://www.rocklinux.org/people/ripclaw/ext/
	which is the copy of my stable tree of extensions.
	
	If you decide to help with a package, try to find out the
	maintainer and contact her/him directly if possible, this
	keeps the traffic on the mailinglist down.

	If you have any questions regarding packages, feel free to
	contact me (ripclaw) or kent skaar.


Writing an extension:

	ROCK Linux extensions are very simple:
	The ".ext" is wrapped by a script and used to configure
	the final distribution package.

	You can use normal bourne shell (sh) commands in the
	extension.

	As examples check out the nasm.ext or balsa.ext files,
	which are cliffords and my sample extension respectively.
	Cliffords package has a lot of comments, i suggest you read it.
	./misc/ext-intern/TEMPLATE.ext is also a good place to start
	with your extension.

	I`ll now start explaining the structure based on my balsa.ext,
	version 0.8.0pre1-20000424. I indented the original data two tabs. 

The extension:

begin of package data

		# ROCK Linux balsa extension package

not required, but nice to do: include the package name.

		#
		# Written by Ripclaw (xripclaw@gmx.net)

you ought to include the authors (your) name and email address
so you can be easily contacted in case of problems.

		# download field
		# [D] 2782121170 balsa-0.8.0-pre1.tar.gz ftp://ftp.newton.cx/pub/balsa/

the [D] flag is the download data field - this is parsed.
the series of numbers is the output of cksum, a checksum generator
used on the *UNCOMPRESSED* package tarball you downloaded.
you can generate this in an easier way by using
	"./scripts/Download -mk-cksum $FILENAME"
then follows the original name of the file.
the last thing listed is the *FULL* path to where the tarball is stored
on the net - including the last slash ("/") !
mind the slash, as per definition of the URL anything not ending with it
is downloadable data - and in our case will just concatenate the filename
to the URL and get you some error that is hard to track...

		# was : http://www.balsa.net/

nothing special - just kept the original location around for documentation.


		# requires glib >= 1.2.1; GTK >= 1.2.1; Imlib >= 1.9.2; gnome-libs >= 1.0.8

it`s nice to note at least in the extension file what your package needs.

		# priority field
		# cliff said: default value is >5<!
		# [P] 5025

the priority field is required for the order in which to build the package,
to reduce problems with dependencies. The default value for Applications
or other extensions is 5.
since the values are interpreted as a string, 500 is smaller then 51 and
thus built earlier. Keep that in mind. If you have no idea why I use
four-digit numbers here, check out STYLE in my extension tree -
I did this mainly to get a halfway sane way of solving the dependencies
between my extensions without leaving the 5* space. I never said this
is the only way to do this, so feel free to do like you please,
as long as you document the way you add the numbers after the 5.

		# version field
		# [V] 0.8.0pre1-20000424

the version number field - the version number of the package.
you may choose to append the version number of the ".ext"-file or
the modification time (e.g. YYYYMMDD) to it.

		# description text
		# [T] Balsa - a lightweight gnome mail-client.
		# [T] Supports local mailboxes, IMAP and POP3.
		# [T] Author: Stuart Parmenter (pavlov@balsa.net)
		# [T] Author: Jay Painter (jpaint@balsa.net)
		# [T] Copyright: GPL 2.0
		# [T] URL: http://www.balsa.net

the extension description text is what you will get as info at install
time and later. It`s nice to add the original author`s name, the
type of copyright and the software`s homepage in there.

		mkdir -p /opt/$pkg/bin /opt/$pkg/man/man1

we create the directories to store the build-data in.
the same for almost all packages.

		tar xIvf $archdir/balsa-0.8.0-pre1.tar.bz2 ; cd balsa-0.8.0-pre1

we unpack the package ( see the bz2 ! packages are converted
to bz2 after download to save space !) and cd into the directory

		./configure $confopts

we configure with the ROCK Linux default configuration options -
this should work with all GNU standard building packages.

		make
		make install

selfexplanatory.

		# EOF

End Of File marker - i include these for no particular reason.
end of package data.

from nasm.ext, a short list of avialable environment variables:
$base		the base directory of the ROCK Linux sources
$archdir	the directory where all the files from the [D]
		rules are stored (yes - you can have many files in there)
$confopt	the options to pass to ./configure in GNU builds -
		normally `--prefix=/opt/<ext-name> --host=<host-type>`.
$target		the host type we are compiling for.
$arch_machine	the systems CPU Type.
$pkg		the package name specified in the INDEX file.

now, go out and check nasm.ext and try creating your own package.
(nasm.ext will probably contain some newer additions and also shows
you some of the finer things you can do...)

HEY ! WAIT !

How does the system know which package ".ext" file to get from where
and how to include it ?

Have a look at INDEX.ripclaw - it`s just added to the INDEX file in the
./ext-config/ directory of the ROCK Linux tarball - in there the
category of the file (e.g. multimedia/mp3) is given as a directory path
followed by the package name and the URL that hosts the package.ext
files.

Now leave and bring us a lot of packages, and try to keep a tree similar
to mine - this saves yourself and us some work.

EOF
