summaryrefslogtreecommitdiff
path: root/source/d/slacktrack/slacktrack-project/docs/OVERVIEW
diff options
context:
space:
mode:
Diffstat (limited to 'source/d/slacktrack/slacktrack-project/docs/OVERVIEW')
-rw-r--r--source/d/slacktrack/slacktrack-project/docs/OVERVIEW595
1 files changed, 0 insertions, 595 deletions
diff --git a/source/d/slacktrack/slacktrack-project/docs/OVERVIEW b/source/d/slacktrack/slacktrack-project/docs/OVERVIEW
deleted file mode 100644
index fb99b247..00000000
--- a/source/d/slacktrack/slacktrack-project/docs/OVERVIEW
+++ /dev/null
@@ -1,595 +0,0 @@
-##############################################################################
-# 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....: 15-May-2009
-# 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
-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.
-
- Traditionally, all packages are in '.tgz' format (a gzipped tar archive).
- Starting with Slackware v13, new compression formats are supported which
- are represented by three additional file extensions:
-
- .tgz - Gzip
- .tbz - Bzip2
- .tlz - LZMA
- .txz - XZ
-
- In this document, we use the file extension '.t?z' to represent
- one of the above file formats.
-
- 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.t?z> - install 'package.t?z'
-
- upgradepkg <package.t?z> - 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 file is named as follows:
-
- packagename-version-architecture-buildnumber.t?z
-
- 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
- i686 - packages for the x86
- s390 - packages for the IBM s/390 mainframe
- arm - packages for the ARM architecture
-
- 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 ]
-
- 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 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 package.
-
- 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.t?z (note the prefixing underscore).
-
- The SlackBuild script uses the Slackware 'explodepkg' script
- to untar the contents of the _.t?z 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 _.t?z 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 an earlier release of Slackware .
- I can't simply upgrade with -current's package because it was
- compiled for a newer GLIBC than Slackware 8.1's, for example.
- 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 ARM architecture 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; 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 package from a .build script is
- typically fairly trivial with slacktrack.
-
- If we wanted to build slackware-9.1's elvis, we could do
- # cd slackware/slackware-9.1/source/a/elvis
- # chmod 755 elvis.build
- # slacktrack -jefkzp "elvis-2.1-i386-2.tgz" ./elvis.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 .t?z 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 docs directory after installing slacktrack:
-
- /usr/doc/slacktrack*/buildscript-examples/
-
- You will also find that in Slackware versions 12.0 and upwards,
- the .build scripts are accompanied by 'trackbuild' scripts because
- slacktrack is used by the Slackware team to produce the packages.
-
- 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 documents directory
- after installing slacktrack:
-
- /usr/doc/slacktrack*/buildscript-examples/
-
- 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 resulting package.
- There are two scenarios where you may want to use this
- variable:
-
- 1. During the build:
-
- The reason you may wish to do this is to pre-populate
- the package with files that you may not wish to place directly
- onto the root filesystem.
- The package contents will only appear inside this directory
- once your build script has finished, and slacktrack has determined
- what to put into this directory.
-
- In previous slacktrack versions which used a pseudo-root filesystem
- (where the package contents were populated *during* the build), this
- made sense, but in slacktrack v2.00, it is unlikely that you'd want
- to use this vairable from the build script.
-
- 2. Post-build -- cleanups after the build:
-
- The most likely use of this script is to perform package cleanup
- tasks after the build. This is mainly to perform tasks that slacktrack
- does not handle itself - such as deleting known files/directories that
- creep into packages (due to a system daemon such as CUPS), or setting
- some file and directory permissions.
-
- An example post build script is below.
- A post build script can be specified by slacktrack's -R option:
-
- # Incase you had CUPS running:
- rm -rf etc/cups etc/printcap
- # crond:
- rm -rf var/spool/cron
- rmdir var/spool
-
- # perllocal.pod files don't belong in packages.
- # SGMLSPL creates this:
- find . -name perllocal.pod -print0 | xargs -0 rm -f
-
- # Some doc dirs have attracted setuid.
- # We don't need setuid for anything in this package:
- chmod -R a-s .
-
-
- 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 .t?z 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 follows this ordered process:
-
- [1] Scans a pre-set list of directories on the filesystem and
- logs the contents.
- [2] Launches build script which installs the package onto the
- filesystem
- [3] Scans the filesystem once again
- [4] Compares the differences in the before and after snapshots
- [5] Copies the differences into a 'package root directory' and
- runs makepkg over them.
-
- In slacktrack version 1, we used 'installwatch' which overloaded
- some of glibc's filesystem calls, creating new files and directories
- into a pseudo-root filesystem, avoiding the need to install onto
- the host's filesystem (and also allowing to build as a non-root user).
- However, this library is ill maintained and even in the early days
- when it worked well, it still had problems and workarounds were required.
-
-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.
-
- The examples are bundled in the documentation directory available
- after installing slacktrack:
-
- /usr/doc/slacktrack*/buildscript-examples/
-
-
-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] 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 BSD Licence.