##############################################################################
# Document: OVERVIEW
# Purpose : Provide an overview of the Slackware package system incorporating
# the use of 'slacktrack'
# Please note that this is *not* a guide to the use of slacktrack;
# the man page and SlackBuild scripts in the 'examples' directory
# aim to fulfill that requirement.
# Date....: 18-Nov-2004
# Author..: Stuart Winter <mozes@slackware.com>
# Homepage: http://www.slackware.com/~mozes
##############################################################################
CONTENTS:
---------
1.0 Preamble
2.0 Slackware packages
2.0.1 Format of official Slackware packages
2.0.1.1 Package names
2.0.1.2 Version numbers
2.0.1.3 Architectures
2.0.1.4 Build numbers
2.1 An overview of the creation of official Slackware packages
2.1.1 'Clean' and 'dirty' builds
2.1.1.1 Clean builds
2.1.1.2 Dirty builds
2.1.1 SlackBuild and .build scripts
2.1.1.2 SlackBuild scripts
2.1.1.3 .build scripts
2.2 slacktrack in the scheme of things
2.2.1 Using slacktrack with official .build scripts
2.2.2 Writing your own .build scripts for slacktrack
2.2.2.1 Making use of slacktrack's environment variables
3.0 slacktrack in operation
3.1 How slacktrack finds which files have been installed
3.1.1 installwatch's author
4.0 Example scripts
4.0.1 non-slackware example build scripts
4.0.2 slackware example wrapper build scripts
5.0 Known problems/features of slacktrack
6.0 New features
7.0 Licence
1.0 Preamble
---------
I used to work for a company that provided web hosting and shell accounts.
When I started there were a number of shell servers all running various
releases of RedHat Linux, in various states of repair. I managed to convince
the management to let me try Slackware on there instead because I have a much
stronger understanding of how to maintain and build server using the
Slackware distribution. This trial went well and within a few months all
servers were converted to Slackware version 8.1.
In order to ease the speed of installation (and to prevent against
forgetting to install or configure something critical), I wrote a
set of post installation scripts that upgraded Slackware packages,
configured numerous config files and copied pre-compiled software
(such as courier IMAP) onto the new system.
For other software that I could not simply copy, I'd compile it on the
new server.
However, it soon became clear that due to security updates and so on,
it became incredibly time consuming (not to mention seriously boring)
to compile PHP, Apache and so on on every server.
At this point, I began to investigate how to create packages for Slackware.
2.0 Slackware packages
------------------
The Slackware Linux distribution consists of a variety of 'packages'
that make up the distribution. These packages are in '.tgz' format
(a gzipped tar archive).
Once you have initially installed Slackware from the installer screen,
you have the facilities to install, remove or upgrade new or existing
packages using the package management tools:
installpkg <package.tgz> - install 'package.tgz'
upgradepkg <package.tgz> - upgrade existing 'package' with the
new version specified at the command line.
removepkg <package> - remove specified package
Whilst the Slackware package system is not especially feature rich,
Slackware's user base (including me) like it because it is simple.
If we want to write our own package utilities then we can easily do so
by examining the existing package tools and querying and amending the
package database (text files).
2.0.1 Format of official Slackware packages
-------------------------------------
In Slackware 8.1 and up, each package .tgz is named as follows:
packagename-version-architecture-buildnumber.tgz
2.0.1.1 Package names
-------------
The package name is either the name of the single program
or the name of a collection of utilities that fall under
a single umbrella.
For example:
autoconf-2.54-noarch-1.tgz
That is the name of the autoconf package I have on my
Slackware 8.1 box.
'autoconf' is the name of the the entire collection of
binaries and associated documents that are extracted from
the autoconf source distribution archive.
However, if we consider another example:
tcpip-0.17-i386-15.tgz
There is no single piece of software called 'tcpip'.
This package contains a number of associated utilities
written by different authors but bundled into one single
'package'.
2.0.1.2 Version numbers
---------------
If the package is the name of a particular piece of software
such as 'autoconf' from the example above, then the version
number represents the version number that its authors distribute.
If the package is a 'bundle' such as 'tcpip' then the version
number increases as and when you add a new piece of software to
the package, or upgrade a particular piece of major software
contained within the package.
For example, with 'tcpip' above, the 0.17 refers to the version of
Linux Netkit. However, there are other programs included within
the Slackware tcpip package that are not part of 'Linux netkit'.
2.0.1.3 Architectures
-------------
The architecture is just that -- it tells you which architecture
the package is for.
The current values in use are:
----- [ Official Slackware architecures ]
noarch - Architecture independent files such as config files
i386 - packages for the x86 (Slackware v8.1 & 9)
i486 - packages for the x86 (Slackware 9.1+)
i586 - packages for the x86
s390 - packages for the IBM s/390 mainframe
Note: Whilst Slackware v10 is primarily built for i486, you may
find that there are some packages whose architecture versions
are higher than i486. This is for two reasons:
[a] There is no source for the package - it is a repackaged
binary distribution (SUN's j2sdk is an example).
[b] The package is not required or otherwise not suitable for
earlier revisions of the architecture (this is especially
the true with ARM and SPARC).
----- [ Unofficial ports of Slackware ]
arm - packages for the ARM architecture
sparc - packages for the SUN Sparc architecture
powerpc - packages for the PowerPC architecture
2.0.1.4 Build numbers
-------------
A build number suplements the version number and is changed
when the *package maintainer* makes a change to the package but
the original source code and version number remains the same.
For example, I build a package of 'foo' version 0.14 for the
sparc. I have never built this package before, thus it becomes
foo-0.14-sparc-1.tgz
However, I realise that I haven't configured
the 'bar' parameter correctly in /etc/foo.conf. I fix it
and re-build the package. The package is now named
foo-0.14-sparc-2.tgz
2.1 An overview of the creation of official Slackware packages
-----------------------------------------------------------
This section gives a brief introduction of the two methods of
used when building the official Slackware .tgz packages.
2.1.1 'Clean' and 'dirty' builds
--------------------------
I am assuming the reader has some experience with Makefiles
and has compiled and installed a number of software packages.
2.1.1.1 Clean builds
------------
I term a 'clean' package one where you can specify a variable
to the 'make install' which contains the directory you wish to install
the package in, rather than installing it properly over the root file system.
For example:
# ./configure --prefix=/usr --sysconfdir=/etc
# make
# make install DESTDIR=/tmp/package-foo
With a 'Makefile' that honours the DESTDIR variable, this will
install the whole package into /tmp/package-foo. This directory
effectively is the 'root' directory '/' as far as the Makefile
is concerned.
From here you can use the Slackware 'makepkg' program and build
a .tgz.
This is by far the safest and most preferred method by all
users that make packages.
You will find that DESTDIR is called prefix, TOPDIR and other names;
you need to examine the Makefile scripts in order to determine whether
it contains this functionality and if it does, then discover what
the variable name is.
2.1.1.2 Dirty builds
------------
A 'dirty' build is the name I give to source distribution archives
whose Makefile scripts do not have any provisioning to install
in an alternate directory other than root.
For these type of builds, you will typically do:
# ./configure --prefix=/usr --sysconfdir=/etc
# make
# make install
The package will then be installed on the root filesystem.
So how do you know what files were installed where and
even if you did, how do you pull all these files together in order
to run makepkg over them ?
That's the purpose of slacktrack! :-)
2.1.1 SlackBuild and .build scripts
-----------------------------
Slackware has a number of packages by a great number of authors.
Some of the packages's source Makefiles honour a DESTDIR type
variable but others do not.
2.1.1.2 SlackBuild scripts
------------------
SlackBuild scripts can be 'interesting'. They are
scripts that install into a 'clean' environment (usually /tmp).
Some of the scripts follow the make install DESTDIR=
style, if the Makefile permits.
Others have a 'framework' or 'controller tarball' which is
a _packagename.tgz (note the prefixing underscore).
The SlackBuild script uses the Slackware 'explodepkg' script
to untar the contents of the _.tgz into the /tmp-package<name>
directory.
Slackbuild then runs 'make' to compile the binaries
and libraries, but then uses the 'cat' program such as:
# cat foobar > /tmp/package-foobar/usr/bin/foobar
By using 'cat', the *new* version of 'foobar' retains
the original permissions and ownerships that are in the
controller tar ball.
However, you may be wondering how, if the package does not
have a facility to install into somewhere other than root,
do we get the file names and permissions for the
controller _.tgz in the first place.
The answer is simple:
[a] find all files on the file system and dump to a file.
[b] compile and install the software
[c] find all files on the file system and compare the file
produced by the first 'find'. After a little pruning, you
have the list of files for the controller tar ball.
2.1.1.3 .build scripts
---------------
For those software distributions whose Makefile does not hounour
the DESTDIR type system, there are Slackware's .build scripts.
These scripts literally ./configure ; make ; make install
and copy docs and other goodies into the root file system.
One of the problems with these scripts is that they are
often incomplete -- they build and install the package but
do not gzip the man pages or strip the binaries and libraries;
this is done manually afterwards.
*These* are the scripts that slacktrack and altertrack were
written for.
* Note: Whilst some software's Makefiles may appear to honour
the DESTDIR variable, the Makefile *may* be broken which can
result in files missing or corrupt within your new package.
For example: I built Apache v2.0.48 and built a package using
make install DESTDIR. However, a problem exists in that some of
the Perl scripts it installs have *temporary build paths*
hard coded into the resulting scripts.
This is why you *may* find a .build instead of a SlackBuild
script within Slackware's source tree.
However, the primary reason is because the build script just
hasn't been updated to make use of DESTDIR. *
2.2 slacktrack in the scheme of things
----------------------------------
I follow Slackware-current quite closly. Often I want to
'back port' a -current package to Slackware 8.1.
I can't simply upgrade with -current's .tgz because it was
compiled for a newer GLIBC than Slackware 8.1's.
For packages that use a 'clean' 'SlackBuild' script, this is
an easy job -- I simply run 'SlackBuild' on an 8.1 box.
However, for .build scripts, I needed a way of building packages
using Slackware's .build scripts.
I found a great program called 'CheckInstall' which fulfilled most of my
requirements. However, as time went on and I started building
more of Slackware's packages and writing my own build scripts, I found
that checkinstall was lacking some features that I required.
At this time I was also considering porting Slackware to run on
the Acorn StrongARM RiscPC series of computers and helping with the Splack
(Slackware on SPARC project), and therefore wanted a robust program
that can deal with every .build script I threw at it, and if it can't
handle it, I needed to be able to make modifications. The easiest
way of doing this was to write my own script; and thus 'slacktrack' was born.
slacktrack is based on the *idea* behind 'CheckInstall', but uses
only my own code (and contributions from other users), and only contains
Slackware-specific facilities -- it can not build Debian or RedHat packages
and never will.
slacktrack does not have all of the facilities of CheckInstall either,
but then these are not required for building Slackware packages
from .build scripts.
Also, slacktrack only works with 'official' Slackware directory locations
and /usr/local.
For example, if your make install installs binaries in /opt/packagename/bin
and the man pages in anywhere other than /usr/man or /usr/local/man, then
slacktrack's relevant options (eg stripping libs, bins, gzman) will
not detect them.
2.2.1 Using slacktrack with official .build scripts
---------------------------------------------
Building a replicar Slackware .tgz from a .build script is
typically fairly trivial with slacktrack.
If we wanted to build slackware-current's fetchmail, we could do
# cd slackware/slackware-current/source/n/fetchmail
# slacktrack -jefkzp "fetchmail-6.2.0-i386-2.tgz" "/bin/sh -x fetchmail.build"
The resulting package (by default) be stored in
/tmp/built-slackwarepackages/
As already mentioned, some of the Slackware .build scripts
are incomplete with regard to gzipping man pages, stripping binaries
and so on -- fetchmail.build is one of them.
Therefore you can specify various options to slacktrack that
will take care of this for you.
The options in the example above :
j - compress libraries
e - chown root.bin /bin,/sbin,/usr/bin,/usr/sbin directories
f - chown root.bin files in the binary dirs listed above
k - strip binaries found in the binary dirs listed above
z - gzip man pages
p - the resulting Slackware package .tgz name
The way I re-create the packages is to build a 'trackbuild' script that
launches slacktrack with the required options and the name
of the Slackware .build script. You can find examples of such
scripts within the separate examples archive that is available at
http://www.slackware.com/~mozes
2.2.2 Writing your own .build scripts for slacktrack
----------------------------------------------
There isn't any specific that you have to do to write a build
script for use with slacktrack -- the script name specified to
slacktrack doesn't even have to be a script - it can be a binary -
as long as it is executable, it is acceptable.
You can see some of my own build scripts that I have written
for use with slacktrack by looking in the separate example
archive that is available at:
http://www.slackware.com/~mozes
2.2.2.1 Making use of slacktrack's environment variables
-------------------------------------------------
slacktrack exports two environment variables:
SLACKTRACKFAKEROOT and SLACKTRACKSCRATCHDIR
SLACKTRACKFAKEROOT:
The purpose of this to allow your .build script to access the
'root' directory of the package contents which otherwise would
be difficult for your own build script to locate during the build.
One of the main reasons that you would want to know this is
to 'brute force' strip binaries, libs or gzip man pages -- it saves
you having to know the names of the files in advance.
For example: gzip all the package's man pages in /usr/man
# find ${SLACKTRACKFAKEROOT}/usr/man -type f -print0 | xargs -0 gzip -9
SLACKTRACKSCRATCHDIR:
The purpose of this variable is to provide some temporary
space to untar your source archives and so on. slacktrack
will manage the creation and deletion of this directory.
For example:
# cd ${SLACKTRACKSCRATCHDIR}
# tar zxvvf ${ORIGPATH}/source/foobar.tar.gz
You can see in some of the example 'non-slackware' scripts
how I have used these variables
3.0 slacktrack in operation
-----------------------
The basic event flow is as follows:
[1] Parse command line arguments
-> Check they are OK, if not bomb out
[2] Launch the supplied build script
[3] Run any specified functions (eg gzman, strip bins, chowns) over the
package 'root' directory and contents
[4] Run Slackware's 'makepkg' program over the package contents
[5] Move the .tgz to the specified build store path
[6] Scan for any hard links that may be in the package
-> If any found, alert the user on screen and also
log to a packagename.hardlinks.log file in the build store path
The slacktrack shell script is fairly simple and well commented; it should be
relatively easy for anybody who understands bash to quickly comprehend what
is happening and why.
3.1 How slacktrack finds which files have been installed
----------------------------------------------------
In order to track the files and directories that have been installed
or changed, slacktrack uses a shared object (library) called
'installwatch' (which is included with the slacktrack package).
slacktrack launches the supplied build script name via the
installwatch library. For a detailed description of how
installwatch works, please read installwatch's documents that are
included with the slacktrack binary package distribution.
/usr/doc/slacktrack*/installwatch*
In essence, however, what happens is that installwatch
re-locates created and modified files and directories
into another directory.
For example, if your script does:
# mkdir /etc/foobar
# echo "hostname foo.bar" > /etc/foobar/foo.conf
if you pause the script and look in /etc, you will *not*
see a directory named 'foobar'. Instead, installwatch
has created it in /var/tmp/*slacktrack*/TRANSL/etc/
(the '*slacktrack*' name is created by slacktrack
before it launches the build script and is deleted afterwards).
By doing this, it allows slacktrack to execute 'makepkg' over
the entire directory and turn it into a package.
3.1.1 installwatch's author
---------------------
I have taken the installwatch that is included with the
latest release of 'CheckInstall'
installwatch was originally written by Pancrazio `Ezio' de Mauro
but is now maintained by Felipe Eduardo Sanchez Diaz Duran
installwatch's page....: http://asic-linux.com.mx/~izto/checkinstall/installwatch.html
checkinstall's web site: http://asic-linux.com.mx/~izto/checkinstall/
I suggest that you take a look at CheckInstall if you haven't
already -- it may have some features you think are 'missing'
from slacktrack.
4.0 Example scripts
---------------
Included with the slacktrack binary distribution are a number of example
scripts that hopefully should provide you with a basis of how to use slacktrack
to build from 'dirty' source distributions.
4.0.1 non-slackware example build scripts
------------------------------------
These are full build scripts written by myself -- the only thing
they are missing is the source code to the program themselves, but
you can run 'download.source' to download it if you wish.
I have tried to include a small number of packages that range
from basic ./configure ; make ; make install
scripts to the more complex such as qmail so as to give you an
idea of how you might use slacktrack for various packages.
I make no claims that the way in which I build packages is
in any way better than anyone else's - if you think some of my
methods are inefficient then that's fine, but please don't bug
me about it -- I'm not really interested in the build scripts - they're
almost disposable and just save me doing it manually.
On the other hand if you find something that's inefficient in
slacktrack then I *am* most certainly interested! :-)
You can find my example scripts in separate examples archive
available at
http://www.slackware.com/~mozes
4.0.2 slackware example wrapper build scripts
---------------------------------------
The way I build packages using Slackware .build scripts is to
write a 'wrapper' script (a 'trackbuild') that calls
slacktrack and passes it the Slackware .build script.
The wrapper scripts can be found in the separate examples archive
available at
http://www.slackware.com/~mozes
I have not included the original Slackware .build script because
it's best if you download these (along with the sources) from
the current Slackware source tree.
For example, if you wanted to build fetchmail using my wrapper script
you would download from ftp.slackware.com,
pub/slackware/slackware-current/source/n/fetchmail
contained within the 'fetchmail' directory is the fetchmail.build
script, the slackware description file and the sources.
You may notice that for my Python and lftp build scripts, I have
made the 'trackbuild' update the Slackware .build script.
As you build Slackware packages from these .build scripts, you too
will most likely find some oddities that need fixing.
Please do NOT report these to Slackware as being broken -- they aren't -
the missing bits (eg Python's hard link in /usr/bin) are fixed
manually.
5.0 Known problems/features of slacktrack
-------------------------------------
Current problems:
[1] slacktrack doesn't have sufficient error checking.
I'm in two minds about *where* to put error checking, you see.
Do I go no further if the supplied build script exits with a non-zero
value?
No, that's a bad idea because what if you didn't write the build script?
it might be one of these qmail type binary installer programs that
you can't (easily without hacking the source) fix. The author may
have their own systems, and the program exits with a value that their
own controller script recognises as non-failure.
What should I do if makepkg has failed? You see it on screen
and in the logs anyway, plus makepkg is one of the last things
that slacktrack calls -- how can you recover?
That said, version 1.03 now has some error handling. There's still
not enough though, imo.
[2] Inherent problems due to the use of the installwatch program
File remapping problem:
Due to the way slacktrack uses installwatch, you'll find that some
programs fail when you compile and install them according
to the documentation provided by its author(s).
For example, if you compile and install qmail via
# make setup check
you will see that qmail fails to install. The reason is that
the 'check' tries to verify the files exist and does some
other checks. Whilst it can *find* the files, installwatch is
'pretending' they are there, and when the check function
probes further, it finds they aren't (because they are in /var/tmp/somewhere)
Static utilities cause some files to be missing:
In some older versions of Slackware, /bin/ln was compiled
as a static binary. This prevented installwatch from being
able to overload the normal functions (that a dynamically
linked ln would use) with its own. This resulted in symlinks
being lost.
Fortunately Slackware 8.1 and newer have a dynamically linked
version of ln. However, it's worth pointing this out because
it may affect other programs that your build scripts call.
* If you would like to use slacktrack but are finding that you
are having difficulty due to these problems, I recommend that
you try altertrack which is included with slacktrack. *
[3] No support for a default config file
I don't see the point. Each .build script is different
and although I typically use the same options to slacktrack
for most of my build scripts, I don't see why I'd need a
config file just to save 4 bytes or so in a trackbuild wrapper :-)
6.0 New features
-------------
See the TODO file in the docs directory.
If you have any specific features you would like to see
included, or have found any bugs, please
email me <mozes@slackware.com>
7.0 Licence
-------
slacktrack is distributed under the GPL version 2.
The included software 'installwatch' is also released under GPLv2.