Documentation: Tutorial

This tutorial guides you on your way into the world of OpenPKG. It explains some essential cornerstones, shows you how to bootstrap OpenPKG and shows you how to use OpenPKG to install a common and useful example application, GNU bash.

Cornerstones

Platform Support

By design, minimal assumptions about the underlying Unix flavor are made. Nevertheless, it is quixotic to assume every operating system receives equal support. Some platforms are fully supported, some are supported and the remainder might work.

Package Types

Two types of packages exist, source and binary. A source package usually contains all files necessary to build a binary package. This includes the pristine vendor sources, patches, fake syslog library configuration and run commands. It also contains a spec file which is the heart of OpenPKG. Inside are instructions how to unpack, modify, patch, build, install and otherwise transform into a installable binary package.

The source package can be thought of being a clonogenic cell which adapts to the target machine and a arbitrary prefix when being transformed into a binary package. A source package might have options which will further augment the number of binary packages by creating variants. Only binaries build for one single prefix /openpkg and using the default options are availabe for download. The OpenPKG way of deployment is to use source packages with build binary once, deploy to across many equal machines being a common scenario.

Package Classes

Packages are classified so the user can assess what quality and support level to expect. CORE packages are tweaked to work on all supported platforms and binary packages are provided. BASE packages build on all fully supported platforms and binaries are provided, too. PLUS packages are available as source packages only. They have been tested to work on all fully supported and most supported platforms.

Source packages

Source packages of CORE+BASE+PLUS packages are availabe for download. They apply to all supported platforms.

Binary packages

Binary packages prebuild for /openpkg prefix using openpkg tag are availabe for download. They apply only for the specific platform they were built for. CORE packages are available for all supported platforms. BASE packages are availbale for all fully supported platforms. No binaries are provided for PLUS packages.

While we strongly recommend using source packages whenever possible, the absence of development tools and mass rollouts are reasons which enforce the use of binaries. Let's make a quick'n'dirty but mostly useful check:

$ which gcc cc || echo "bad luck, no development tools"

The matrix below tells you about all four combinations of bootstrapping or regular installing/upgrading a package from source or binary. For the tutorial, please select the bootstrap method you prefer or require. Then come back and continue below.

Security Updates

Security updates and bugfixes are available for CORE+BASE packages. They are availabe for download as source packages.

Privileges

OpenPKG does not require root privileges to build packages. In addition, many packages including the bootstrap can be installed without root privileges but functionality might be limited. This example uses $ to indicate a user prompt and # to indicate a root prompt.

Storage

Make sure you have approximately 250MB free disk space on the filesystem were OpenPKG should be loaded. The installation procedure creates a directory for the OpenPKG instance but it also accepts a pre-existing directory or a symlink to a pre-existing directory. The downloadable binary packages use the prefix /openpkg and so does this tutorial. However, using source packages it is possible to use an arbitrary prefix and in fact the OpenPKG architecture places no artifical limit on the number of parallel and simultaneous instances on a single system.

$ mkdir  /storage/with/250MB/free
$ ln -s  /storage/with/250MB/free /openpkg

Workspace

Build processes sometimes take large amounts of temporary disk space. For our example you should have approximately 250MB of temporary disk space available somewhere. OpenPKG reads the environment variable TMPDIR to locate a large workspace.

$ TMPDIR= /var/tmp/with/250MB/free
$ export TMPDIR

System tools

We assume a Unix system with minimal toolset for binaries. Sources require development tools like make and [g]cc as well. There is no ultimate standard that tells what a minimal toolset is, so we have to traverse some fog here. The bootstrap process needs a little help and require sh and tar in PATH. Also if you want to install a compiler package from source you need a compiler. Solve this chicken-egg problem using any exising binary compiler package from the vendor, OpenPKG or a third party. Tell OpenPKG about your favorite CFLAGS and CC, see the FAQ.

Release Engineering

Those who have installed unreleased packages from CURRENT, STABLE or SNAPSHOTs should be aware of the principles behind OpenPKG release engineering. Note that the version numbers of these packages are formatted as timestamps rather than what is expected a release number. Decoding such version numbers yields very large integers. Any release package will clearly have a lower number even if it is a more mature version of the same package! Switching from a unpublished package to a released package is considered a 'downgrade' by RPM. This works by design according to the OpenPKG standards of release engineering. To easily upgrade or downgrade such uncooperative packages in general, RPM offers the options --oldpackage and --nodeps to be added to --rebuild and -Uvh instructions.

Build/Install Matrix

Example Installation

See below a video recording of a Bootstrap from source on a FreeBSD machine as a unprivileged user installing onto a NFS home directory. After bootstrap, the bash package is rebuild, installed and the bash is run.

Showcase (animated GIF)

More Information

Fine tuning

Do you want your shell to use the new OpenPKG environment so that you have the /openpkg/bin in your PATH, can read the man pages using the correct MANPATH etc.? There's a single command that does all of this for you. Place it in your favorite shell's profile.

$ eval `/openpkg/bin/openpkg rc --eval all env`

Enter these command examples to understand what 'eval' did for you.

$ set | grep /openpkg/
$ which rpm
$ man rpm

Bootstrap from source

A warning is due for all who decide to bootstrap OpenPKG with existing OpenPKG installations, because bootstrapping into an existing OpenPKG hierarchy (such as /openpkg) discards the contents of its internal RPM database! When learning OpenPKG, it is safest to bootstrap into an empty directory which OpenPKG will automatically create for you if not existing.

Should an upgrade of the actual OpenPKG itself be desired, this is not carried out by bootstrapping again. Rather, install the next OpenPKG version just as any other package. Go back to the matrix to see the upgrade options again.

$ cd $TMPDIR $ ftp ftp.openpkg.org Connected to ftp.openpkg.org. 220 ftp.openpkg.org OpenPKG Anonymous FTP Server ready. Name (ftp.openpkg.org): anonymous 331 Anonymous login ok, send your email address as your password. Password: you@example.com 230- [...] Welcome to OpenPKG.org! [...] 230 Anonymous access granted, restrictions apply. ftp> bin 200 Type set to I. ftp> cd release//SRC ftp> get openpkg-.0-.0.src.sh ftp> bye 221 Goodbye.

Choose the prefix, tag, user and group of your choice. You can omit all but prefix. Unprivileged users must choose their login and primary group which is their default anyway.

$ sh openpkg-.0-.0.src.sh \\ --prefix=/openpkg --tag=openpkg --user=openpkg --group=openpkg $ su \# cd $TMPDIR \# sh openpkg-.0-.0.arch-os-openpkg.sh \# exit $

Back to the matrix.

Bootstrap from binary

$ cd $TMPDIR
$ ftp ftp.openpkg.org
Connected to ftp.openpkg.org.
220 ftp.openpkg.org OpenPKG Anonymous FTP Server ready.
Name (ftp.openpkg.org): anonymous
331 Anonymous login ok, send your email address as your password.
Password: you@example.com
230- [...] Welcome to OpenPKG.org! [...]
230 Anonymous access granted, restrictions apply.
ftp> bin
200 Type set to I.
ftp> cd release//BIN
ftp> get arch-os/openpkg-.0-.0.arch-os-openpkg.sh
ftp> bye
221 Goodbye.
$ su
\# cd $TMPDIR
\# sh openpkg-.0-.0.arch-os-openpkg.sh
\# exit
$

Back to the matrix.

Regular installation/update from source

$ /openpkg/bin/openpkg rpm --rebuild \\
    ftp://ftp.openpkg.org/release//SRC/foo-X.Y-.0.src.rpm
$ su
\# /openpkg/bin/openpkg rpm -Uvh \\
    /openpkg/RPM/PKG/foo-X.Y-.0.arch-os-openpkg.rpm

Example URL

    ftp://ftp.openpkg.org/release//SRC/bash--.0.src.rpm

Example PKG paths

    /openpkg/RPM/PKG/ ...
    ... bash--.0.hppa-hpux11.11
    ... bash--.0.ix86-debian3.0
    ... bash--.0.ix86-debian3.1
    ... bash--.0.ix86-fedora2
    ... bash--.0.ix86-freebsd4.10
    ... bash--.0.ix86-freebsd5.3
    ... bash--.0.ix86-gentoo1.5.3
    ... bash--.0.ix86-mandrake10.0
    ... bash--.0.ix86-netbsd1.6.2
    ... bash--.0.ix86-rhel3
    ... bash--.0.ix86-solaris10
    ... bash--.0.ix86-solaris9
    ... bash--.0.ix86-suse9.2
    ... bash--.0.ix86-suse9
    ... bash--.0.sparc64-solaris10
    ... bash--.0.sparc64-solaris2.6
    ... bash--.0.sparc64-solaris8
    ... bash--.0.sparc64-solaris9

Back to the matrix.

Regular installation/update from binary

$ su
\# /openpkg/bin/openpkg rpm -Uvh \\
    ftp://ftp.openpkg.org/release//BIN/platform/foo-X.Y-.0.arch-os-openpkg.rpm

Example URLs

    ftp://ftp.openpkg.org/release//BIN/ ...
    ... hppa-hpux11.11/bash--.0.hppa-hpux11.11
    ... ix86-debian3.0/bash--.0.ix86-debian3.0
    ... ix86-debian3.1/bash--.0.ix86-debian3.1
    ... ix86-fedora3/bash--.0.ix86-fedora3
    ... ix86-freebsd4.11/bash--.0.ix86-freebsd4.11
    ... ix86-freebsd5.3/bash--.0.ix86-freebsd5.3
    ... ix86-gentoo1.6.9/bash--.0.ix86-gentoo1.6.9
    ... ix86-mandrake10.2/bash--.0.ix86-mandrake10.1
    ... ix86-netbsd2.0/bash--.0.ix86-netbsd2.0
    ... ix86-rhel3/bash--.0.ix86-rhel3
    ... ix86-solaris10/bash--.0.ix86-solaris10
    ... ix86-solaris9/bash--.0.ix86-solaris9
    ... ix86-suse9.2/bash--.0.ix86-suse9.2
    ... ix86-suse9.1/bash--.0.ix86-suse9.1
    ... sparc64-solaris10/bash--.0.sparc64-solaris10
    ... sparc64-solaris8/bash--.0.sparc64-solaris8
    ... sparc64-solaris9/bash--.0.sparc64-solaris9

Back to the matrix.