The ROCK Linux Hacking HowTo

From RockWiki

Jump to: navigation, search

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.



Contents

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>

ROCK Linux Directory Tree

You can browse the latest revision of the ROCK Linux directory tree in our SVN repository.

Documentation/

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

Documentation for developers is found in the Developers/ subdirectory.

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!

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 within 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/.

package/base/

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

The base packages are maintained by the ROCK Linux core developers.

package/x11/

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

package/<architecture>/

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

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.

misc/

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

misc/archive/

Some small special-purpose scripts and C programs are stored here.

misc/config/

Generic (package, architecture and target independent) config.in files are placed in this directory.

misc/desktop/

Contains the parse-config responsible for automatic .desktop file adaptions during package builds.

misc/isomd5sum/

Contains C source code for implanting and checking md5sum checksums of ISO images.

misc/jailing/

Contains the files for jailing support (building packages in a "jail", protecting the build system from modifications).

misc/output/

Configuration files for various build output plugins are stored here.

misc/pkgsel/

Package preselection templates are placed here. The templates are defined using one or more package sets, which are located in the sets/ subdirectory.

misc/rockdialog/

The ROCK version of the dialog program, used in ./scripts/Config.

misc/tools-source/

The sources of ROCK build tools, like flist and other wrappers, the .desc file parser or the pseudo-native handler.

target/

A "target" is a set of rules to create ROCK Linux based distributions. The "normal ROCK Linux" is the crystal target, built with the default configuration settings.

Every target has it's own subdirectory in this tree. Read chapter 5 and Creating Targets for details.

architecture/

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

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.

Re-distributable files are downloaded to a subdirectory of download/mirror/, non-distributable file to the equivalent download/nodist/ directory. Only re-distributable files are available on ROCK Linux mirrors.

src*/ And build/

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

Compiled build tools are placed in src/, as well as some intermediate files from ./scripts/Config. ./scripts/Download stores a list of failed downloads in src/Download-Errors.

For each package build a separate src.<pkg>-<id>/ directory is created. This package build directory contains the extracted package sources (if any), the wrapper logs, a debug script and supplemental data. Symbolic links to all download files of this package exist in the archdir/ subdirectory.

Target builds create and use a separate directory below build/ for each configuration. It is used as the root directory of the target distribution. The ROCK/ subdirectory is linked to the ROCK base directory during the build process (for the chroot environment).

config/*

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

Read chapter 3 for details.

Build- And Other Scripts

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

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

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

Scripts For Building Stuff

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

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

./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).

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

./scripts/Build-Job

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

Various Small Helpers

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

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

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

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

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

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

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

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

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

./scripts/Create-ErrList

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

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

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

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

./scripts/Internal

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

Scripts For Doing Checks

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

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

./scripts/Check-System

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

./scripts/Check-Deps

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

Scripts For Updating The Source Tree

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

Configuration System

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.

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.

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

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

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

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

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

const Variable Default

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

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


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.

Special Variables

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.

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.

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

config.in Call-Tree

All config.in files are executed from scripts/config.in in 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.

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.

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 !https://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 https://www.research.ibm.com/trl/projects/security/ssp/ .

URL(s):
  https://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.

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.

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
Retrieved from "https://www.rocklinux.net/wiki/The_ROCK_Linux_Hacking_HowTo"