Packages

From RockWiki

Contents 1 Packages 1.1 Fundamentals 1.2 The *.desc Files 1.2.1 Package Priority 1.2.2 Download URLs 1.3 The *.conf Files 1.4 The *.patch Files 1.5 The *.doc Files 1.6 The *.init Files 1.7 Binary Package Format (Draft)

Packages

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.

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.

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.

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/

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.

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.

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.

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'.

Binary Package Format (Draft)

One main purpose of the ROCK build scripts is to build and install packages described by the files mentioned above: the build scripts create binary packages from source packages.

These binary packages can come in various forms: they can be installed on disk, or they can be wrapped up in package archives.

Generally speaking, each binary package consists of a set of files. All types of files are allowed, but the rule for symlinks, pipes, block and character device files and sockets is that the file per se is part of the package, not the file or device it points to.

Files are recognized by their full names, stripped of the leading path to the package root directory (e.g. usr/bin/gcc). Each file must be part of at most one package, else it is called a 'shared' file. Shared files are best avoided, since packages that share a file are prone to place and expect different contents inside it.

Since the raw set of files alone would be hard to e.g. update or remove, ROCK binary packages additionally contain meta-data, stored as regular files in subdirectories of var/adm/. Each package contains files named after the package in each meta-data directory below var/adm/.

The minimum set of meta-data files required for each package are as follows:

• var/adm/flists/<pkg> contains a newline separated list of files contained in this package. The list is sorted (using the C locale) and files are listed with the path to the root directory stripped (e.g. usr/src/linux). Additionally each file name is prefixed with <pkg>: and a space character. All meta-data files for this package are listed here as well.
  Directories in this file are treated specially: if a package is removed, all empty directories listed here will be removed, too. In any other case empty directories will not be removed. Put another way, the package 'owns' directories listed here.
• var/adm/packages/<pkg> is a human-readable summary of the package description. No specific format is imposed, so here's only an example:

Package Name and Version: gcc40 4.0.3 0
Package Size: 72.68 MB, 121 files
ROCK Linux Package Source Checksum: f1b98ce807d6b71bd7357ac7ee79f682
ROCK Linux Version and Architecture: TRUNK x86
Build on Linux jumbo 2.6.16.1 i686 unknown
Build [1] at 03/30/2006 from 22:35:00 to 22:42:05 CEST
Build [2] at 03/30/2006 from 23:02:05 to 23:33:21 CEST
Status: Stable,  License: GPL

  The GNU Compiler Collection (aka GNU C Compiler)

  This package contains the GNU Compiler Collection. It includes compilers
  for the languages C, C++, Objective C, Fortran 77, Java and others ...

  This GCC contains the Stack-Smashing Protector Patch which can be enabled
  with the -fstack-protector command-line option. More information about it
  ca be found at http://www.research.ibm.com/trl/projects/security/ssp/ .

URL(s):
  http://gcc.gnu.org/ The GCC Homepage

Original Author(s):
  The GNU Project / FSF

ROCK Package Maintainer(s):
  Clifford Wolf <clifford@clifford.at>

Download URL(s):
  ftp://gcc.gnu.org/pub/gcc/releases/gcc-4.0.3/gcc-4.0.3.tar.bz2

• var/adm/md5sums/<pkg> contains newline separated pairs of
  <checksum> <filename>
  for each non-directory file listed in var/adm/flists/<pkg>, in the same order. <checksum> is generated by md5sum run with each <filename> as argument.
  Since it is not desirable to calculate or compare checksums of special files (symlinks, pipes, device files, sockets) with respect to package management, those files' checksums will be set to X. Files with a checksum of X and directories will be considered as always unmodified.
  Because of their self-referrential nature, checksums for var/adm/md5sums/<pkg> and var/adm/cksums/<pkg> are also set to X.
  A checksum equal to zero means a checksum hasn't been created yet (usually to save build time). Corresponding files should be considered as always modified.
• var/adm/cksums/<pkg>: everything for var/adm/md5sums/<pkg> applies to this file as well, except that each line corresponds to the output of cksum, not md5sum.