=pod

=head1 NAME

slacktrack - build Slackware packages from B<.build> scripts

=head1 SYNOPSIS

B<slacktrack> B<[>optionsB<]> -p B<">packagename.tgzB<"> B<">buildscriptB<">


=head1 DESCRIPTION

B<slacktrack> is a packaging tool to build replicar Slackware packages 
from the official B<.build> scripts available in the distribution
source tree.  B<slacktrack> has many features available to eliminate the
majority of the manual element involved with producing packages from
these scripts.  B<slacktrack> uses the standard Slackware B<makepkg> program
to produce the resulting packages.


=head1 OPTIONS - GENERAL

=over 4

=item B<-h>, B<--help>

Show the available options and exit

=item B<-v>, B<--version>

Show the version information and exit

=back

=head1 OPTIONS - SLACKWARE 'makepkg' PACKAGE MAKER 

The values from these options are passed to the Slackware
B<makepkg> tool.

=over 4

=item B<-p>, B<--package> <package_name>  

Resulting tar file name of the package.  This will be in the format
of B<name>-B<version>-B<arch>-B<build>.tgz

For example: B<slacktrack>-B<@VERSION@>-B<i386>-B<1>.B<tgz>

=item B<-s>,  B<--nosymlinks>

Tell B<makepkg> not to search for symlinks in the package directory

=item B<-r>,  B<--setrootowner>

Tell B<makepkg> to set permissions on directories to 755 and owners to root.root

See also B<--chown-bdirs-root-bin>

=item B<--mpopts>

Supply additional options to B<makepkg>.  

Example: # B<slacktrack> --mpopts "--prepend" -Qnp foo-1.0-i486-1.tgz ./foo.build

B<Note:> You B<must> include the additional options in either
quotes (as shown in the example above) or single quotes otherwise slacktrack will take them
as options to itself.

=back

=head1 OPTIONS - SPECIFIC SLACKTRACK OPTIONS

=over 4

=item B<-t>,  B<--notidy>

Do not delete temporary package directory when slacktrack has finished.
slacktrack uses a temporary work space directory in /var/tmp (by default).
This directory contains the package.tgz contents.  This option can be
useful when you are having difficulties with building the package, or
for debugging slacktrack.
slacktrack will inform you of the (randomly named) temporary directory
when it has finished.

=item B<-b>,  B<--buildstore> <directory> 

Specify the location in which to store the built .tgz packages.
By default this is B</tmp/built-slackwarepackages>, but you may wish
to change it to another location.  If this directory does not exist 
then slacktrack will default to using B</tmp>

This directory also will contain any logs and the package description
file (if specified).


=item B<-l>,  B<--logfile> <filename>

slacktrack logs every element of the compilation and build process
that the B<build script> outputs along with slacktrack's own on-screen
output.  The log file is especially useful for debugging a failed build.
The default log path is B<E<lt>buildstore_pathE<gt>/E<lt>package_nameE<gt>.log>

This option permits the user to specify a different directory for the
logs rather than storing the .log in the same directory as the .tgz.

=item B<-n>,  B<--nologging>

Do not save the log file when slacktrack has finished.
See B<--logfile> above for a description of the contents of the log file.

The default is to log.

=item B<-i>,  B<--install>

Install resulting .tgz package.

The default is not to install.

=item B<-D>,  B<--md5sumtgz>

Create an MD5sum of the resulting .tgz package file in the package
store directory (where the resulting .tgz will be built; usually
this is F</tmp>).  The MD5sum file will be the same name as the resulting
.tgz file but with  B<.md5> suffixed (e.g. foobar-1.0-i486-5.tgz.md5).

This option does nothing if the B<--nocreatetgz> option has been
specified.

=item B<-G>,  B<--gpg-sign> [<id>]

Sign the resulting .tgz package file with the default user's GnuPG key and
placed the detached, armored signature in the package store directory (where
the resulting .tgz will be stored; usually this is F</tmp>). The GnuPG
signature file will have the same name as the resulting .tgz file but with
an extra B<.asc> suffixed (e.g. foobar-1.0-i486-5.tgz.asc).

If the optional I<< <id> >> is used, it will be passed to GnuPG as the user
ID to use for the signature.

This option does nothing if the B<--nocreatetgz> option has been specified.


=item B<-z>,  B<--gzman>

Slackware's standard is that all man pages should be gzipped.
This option makes slacktrack gzip any man pages that exist within the
directories F</usr/man>, F</usr/local/man> and F</usr/X11R?/man>.

The default is not to gzip man pages.

Also see the B<--gzman-no-symfix>, B<--gzinfo> and B<--gzinfo-no-symfix> options.

=item B<-I>,  B<--gzinfo>

Slackware's standard is that all GNU info pages should be gzipped.
This option makes slacktrack gzip any info pages that exist within the
directories F</usr/info> and F</usr/local/info>

The default is not to gzip info pages.

Also see the B<--gzinfo-no-symfix>, B<--gzman> and B<--gzman-no-symfix> options.

=item B<-K>,  B<--delete-usrinfodir>

Delete the package's /usr/info/dir file if it exists.  This file is
a special file used by the GNU 'info' program to provide the user
with a list of the info pages present on the system.
Some software's Makefile will create a new 'dir' page that only contains
information pertaining to the newly compiled software itself, rather than 
appending to the existing list of software.

In the main you will want to use this option to avoid replacing the original
/usr/info/dir file.

However, the default is not to delete this file.


=item B<-x>,  B<--exclude> B<'>path1,path2B<'>

slacktrack uses a program called B<installwatch> to track which files
have been changed on the system in order that they can be included
within the .tgz package.  However, other files change on the system whilst the
package is being compiled and installed and need to be excluded from the
package.

By default, slacktrack passes the following list to installwatch:
B</tmp,/proc,/var/tmp,/usr/tmp,/dev,$(pwd)>

B<pwd> is the directory from which slacktrack was called.
For example, if you are in /packages/foobar
and you run the 'SlackBuild' from that directory, any changes that happen
inside that directory will be excluded from the list.

This option allows the user to specify a new list.
You may want to do this if you are building a package that creates
files in an excluded directory that are required for the package
and would otherwise be excluded.

B<Note:> B<$(pwd)> will always be excluded.

=item B<-d>,  B<--depend> B<'>package1,package2B<'> 

Ensure the given Slackware packages are installed before executing
the build script.

This is a primative method of build-time dependency checking.
It simply prevents the build from failing, or a certain feature from
being compiled out because (at build time) you had not got a certain
library installed.

The packages are wildcarded by slacktrack, thus you do not have to specify
version information.  To depend on 'oggutils' being installed, you would
specify B<-d "oggutils"> and slacktrack would find any installed version of the
Slackware oggutils package.

No depdendencies are checked by default.

=item B<-j>,  B<--striplib>

The Slackware standard is to run B<strip --strip-unneeded> over any 
shared objects.  This option causes slacktrack to strip any .so objects
in /lib, /usr/lib and /usr/local/lib

Also see option -S, --stripallexec

The default is not to strip.


=item B<-A>,  B<--striparchives>

This option causes slacktrack to run the B<strip> program against any
.a (archive) files that it finds in the package's directory.  

Only debugging symbols are stripped (B<strip -g>).

For information about such files you should read ar(1) and ranlib(1).

B<Note:> This option strips any .a files it finds within the package's directory 
rather than limiting itself to a pre-set list of directories (as with
the other strip options that slacktrack provides).

Also see option -S, --stripallexec

The default is not to strip.


=item B<-k>,  B<--stripbin>

The Slackware standard is to run B<strip --strip-unneeded> over any 
binary files.  This option causes slacktrack to strip any binaries found
in /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, /usr/local/sbin and
/usr/X11R?/bin.

Also see option -S, --stripallexec

The default is not to strip.


=item B<-S>,  B<--stripallexec>

This option performs B<--striplib>, B<--stripbin> and B<--striparchives> but rather than
limiting itself to a pre-set list of directories, it strips any files (with execute permissions) 
that the B<file> program reports as being unstripped ELF binaries.  This includes
B<.a archives>.

The purpose of this command is to strip binaires and shared object files
that are B<not> in the normal locations.  An example of a known deviations is B</opt>

Using this option is slower (especially when used with packages containing many
files in deep directory structures) than using B<--striplib>, B<--stripbin> or B<--striparchives> 
options individually.

If this option is also specified with B<--striplib>, B<--stripbin> or B<--striparchives> then
those options are dropped in favour of the B<--stripallexec> mode of operation.

The default is not to strip objects of any type.

=item B<-c>,  B<--createdescription>

From Slackware 8.1 and upwards, the package series directories contain
a B<name>-B<version>-B<arch>-B<build.txt> along with the .tgz

Using this option causes slacktrack to create such a file in the 
build store directory (see the B<--buildstore> option)

The default is not to create a description file.

=item B<-e>,  B<--chown-bdirs-root-bin>

The Slackware standard is to have the /bin, /sbin, /usr/bin, /usr/sbin,
/usr/local/sbin, /usr/local/bin and /usr/X11R?/bin directories owned by root:bin.  

B<Note:> If you use the B<--setrootowner> option then B<makepkg> will
reset the directory permissions to root.root

The default is not to set these ownerships.

=item B<-f>,  B<--chown-bfiles-root-bin>

The Slackware standard is to have binaries contained within 
the /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/sbin, /usr/local/bin 
and /usr/X11R?/bin directories owned by root:bin.

The default is not to set these ownerships.

=item B<-g>,  B<--chmod644docs>

Often when installing documents, the permissions vary wildly. 
It is preferable if documents are chmod 644 and owned by
the user 'root' and group 'root'.

Using this option causes slacktrack to set all files contained
within F</usr/doc> to chmod 644 and runs chmod -R root.root on the package's
F</usr/doc> directory.

The default is not to set these permissions.

=item B<-U>,  B<--nousrtmp>

When compiling some programs (such as Apache), B<installwatch> picks up
the /usr/tmp symlink.  This symlink is part of another Slackware package
and therefore should not be present in other packages.

Using this option causes slacktrack to prevent this symlink from appearing
in the resulting .tgz package.

This behaviour is not the default.

=item B<-Q>, B<--standard>

This option is the combination of the following slacktrack's options:
B<--gzman> (B<-z>), B<--gzinfo> (B<-I>), B<--delete-usrinfodir> (B<-K>),
B<--stripallexec> (B<-S>), B<--createdescription> (B<-c>),
B<--chown-bdirs-root-bin> (B<-e>), B<--chown-bfiles-root-bin> (B<-f>),
B<--chmod644docs> (B<-g>) and B<--nousrtmp> (B<-U>). 

It can be considered the quick way to build a package which follows 
the Slackware standard without specifying each
individual command line switch.

You would use this option as follows:

# B<slacktrack> -Qp foo-2.0-i486-1.tgz ./foo.build


=item B<-T>,  B<--tempdir> B<'><path>B<'>

slacktrack uses a temporary work space to store the package contents.
By default, slacktrack will choose one in /var/tmp.  However, you may wish
to change it to another location should there not be enough space in 
/var/tmp to hold the temporary files.

=item B<-C>,  B<--nocreatetgz>

Do not execute the Slackware B<makepkg> program when the build script
finishes.  You may wish to use this option if you want to run makepkg
by hand.

Using this option implies B<--notidy>

The default is to execute B<makepkg>

=item B<-L>,  B<--nologhardlinks>

Some software distribution archive build scripts will use ln (hard link)
instead of ln -s (soft link).  Hard links which should not be 
allowed to make their way into a .tgz package that is to be distributed.

By default, hard links are logged to screen and an additional 
.hardlinks.log file will be created in the build store directory.

=item B<-O>,  B<--chmod-og-w>

Run 'chmod -R og-w' over the package directory.

Some packages (such as PHP 4.3.0) install globally writeable files 
when it should not.  This option runs chmod -R og-w over the entire
package directory.

This behaviour is not the default.

=item B<-Z>,  B<--gzman-no-symfix>

Do not repair broken man page symlinks caused by the B<--gzman> option

Some man pages are symlinks to other man pages.  When the
original file is gzipped, its name changes to name.x.gz
and thus the symlink is broken.  

This option repairs such broken symlinks by renaming the 
symlink to name.x.gz and pointing it to the new .gz man page file.
The symlink also has to be named .gz otherwise the B<man> program
fails because it doesn't know that it is expecting a gzipped file.

The default behaviour is to repair any broken symlinks.

=item B<-F>,  B<--gzinfo-no-symfix>

Do not repair broken info page symlinks caused by the B<--gzinfo> option

Some info pages are symlinks to other info pages.  When the
original file is gzipped, its name changes to name.gz
and thus the symlink is broken.

This option repairs such broken symlinks by renaming the
symlink to name.gz and pointing it to the new .gz info page file.

The GNU B<info> program is capable of working with broken symlinks
but it is desirable to have the symlink corrected.

The default behaviour is to repair any broken symlinks.


=item B<-M>, B<--extra-mandir> <path>

Append additional man page directories to the default list (F</usr/man>, F</usr/local/man>, F</usr/X11R?/man>).

You would want to use this option if you are storing man pages in non-system
locations such as /opt/kde/man and wish to gzip them using slacktrack's B<--gzman> option.

Extra paths can be comma separated as shown below:
 B<# slacktrack --extra-mandir /opt/kde/man,/opt/prog/man>

B<Warning:> Do B<not> specify paths other than directories that will
contain man pages, otherwise normal files will become gzipped !


=item B<-W>, B<--extra-infodir> <path>

Append additional info page directories to the default list (F</usr/info>, F</usr/local/info>).

You would want to use this option if you are storing info pages in non-system
locations such as /opt/kde/info and wish to gzip them using slacktrack's B<--gzinfo> option.

Extra paths can be comma separated as shown below:
 B<# slacktrack --extra-infodir /opt/kde/info,/opt/prog/info>

B<Warning:> Do B<not> specify paths other than directories that will
contain info pages, otherwise normal files will become gzipped !


=item B<-E>, B<--extra-libdir> <path>

Append additional shared object (library) directories to the default list (/lib, /usr/lib, /usr/local/lib).

You would want to use this option if you are storing shared objects in non-standard locations
and wish slacktrack to strip them using the B<--striplib> option.

Multiple paths may be supplied by comma separating them.

=item B<-B>, B<--extra-bindir> <path>

Append additional binary directories to the default list 
(/bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, /usr/local/sbin, /usr/X11R?/bin).

You would want to use this option if you are storing binaries in non-standard locations
and wish slacktrack to strip them using the B<--stripbin> option.

Multiple paths may be supplied by comma separating them.

=item B<-N>, B<--strip-prog> <path>

Specify a different binary name for the B<strip> program.  You may need
to use this option if you are cross compiling and wanting to strip
the resulting binaries.

Example:
# B<slacktrack> --strip-prog /usr/local/arm/2.95.3/bin/arm-linux-strip -fenzSIP foo-2.0-arm-1.tgz

By default slacktrack will use the version of strip that it finds 
in the $PATH.


=item B<-R>, B<--run-after> <command>

Run the specified command/script after the specified build script has finished
and prior to creating the package.

The purpose of this is to allow the user to inspect and if required, modify
the contents of the package before the .tgz is created.

B<Note:> The CWD (working directory) is changed to the package's root
directory before the specified command is executed.  This allows you to
specify (for example) /usr/bin/mc (Midnight Commander) and have
it automatically display the contents of the package.

Example:

The following slacktrack command would run the Midnight Commander program
F<mc> prior to creating the package B<foo-2.0-arm-1.tgz>.

# B<slacktrack> -Rmc -fenzSIP foo-2.0-arm-1.tgz

By default slacktrack does not execute any commands prior to creating
the package.

=item B<--froot>

This option starts the fakeroot server (if 'faked' can be found) so that
any of the chown root:bin (or other changes) that slacktrack performs
over the package's contents, will make it into the resulting .tgz package
file.  

The purpose of running fakeroot is that if you are not running slacktrack
as root, there is no way of ensuring that the package .tgz contains the 
correct user and group names.

fakeroot is only started once the build script finishes, and as such
it can only detect the changes made by slacktrack; any ownership changes
made by the build script or 'make install' will be lost.  The reason for
running fakeroot after the build script is that fakeroot can cause
some configure scripts to fail.  If you require that certain ownerships
make it into the package, and you cannot ever be root on the machine,
it is suggested that you use slacktrack's B<-R> option.  You could then
make a script as follows:

B< cd ${SLACKTRACKFAKEROOT}
 chown -R daemon.daemon etc/radius>

The other method would be to start slacktrack via fakeroot, as follows.

B< fakeroot ./trackbuild.program>

You would however, need to be sure that any configure scripts or
makefiles did not fail under fakeroot.

fakeroot may be obtained from http://www.interlude.org.uk/unix/slackware

=item B<--showdeps>

This option lists the B<installed> Slackware packages (those that appear in 
F</var/log/packages>) that contain shared libraries upon which your new 
package depends.  

The purpose of this option for interest only but you may 
find it useful to ensure that you haven't built a package on a box that 
Xfree86 (for example) installed but intend to install and use the package 
on a box that does not, when the package has become linked against X's 
libraries.

Using this option will also flag up 'orphaned' libraries (ones that 
do not belong to an installed package, which is especially handy 
if you're going to be distributing a package).

The package dependencies (and orphans, if any) will be logged (regardless 
of whether logging is turned off) in text files that will be stored 
in the package build store (usually /tmp) under the following names:

packagename.orphaned_ld_deps.log

packagename.ld_deps.log

B<Note:> Slackware does not have any form of dependency checking and
as such any file you produce will not be considered by
pkgtools.  However, third parties have developed a standard that uses
a single file to assist with the handling of automated dependency checking 
(when the package is installed via 3rd party package managers such as 
swaret, slapt-get et al).  This file resides within the package as 
F</install/slack-required>. You may like to use this feature of 
slacktrack to help you generate such a file.

The default behaviour is not to display dependencies.

=back


=head1 SPECIAL SLACKTRACK ENVIRONMENT VARIABLES

slacktrack makes a small number of environment variables available to the
build script(s).  The variables allow build scripts to gain access to 
various inner-workings of slacktrack and installwatch.

=over 4

=item B<SLACKTRACKFAKEROOT>

This directory is the 'root' directory of the package.  You may wish
to access this directory during build time so that you can perform
special operations that slacktrack itself cannot perfom.

For example, whilst slacktrack is able to strip all ELF objects, it may
be that a small number of the objects will not function when stripped, yet 
the rest will.  Therefore you cannot use slacktrack's stripping options
to accomplish this task; instead you can access the package's directory
directly.  

Example:

B<( cd ${SLACKTRACKFAKEROOT} 
      strip usr/bin/foo
      strip bin/bar ) >

You may use any shell commands once inside the package's root directory
but be careful never to specify any paths within the B<real> root directory (for example
F</usr> rather than F<usr>) in any of your commands.


=item B<SLACKTRACKSCRATCHDIR>

This directory provides a temporary 'scratch' directory for use by the
build scripts.  Its purpose is to allow the author to simplify the build scripts 
by removing the need to create and manage temporary directories where
the source archives will be unpacked.

Example usage:

B<   cd ${SLACKTRACKSCRATCHDIR}
   tar jxf /path/to/source/ball.bz2
   cd ball-2.3
   ./configure && make install >

This directory is subject to the same command line options as the
rest of the slacktrack temporary build tree; if --notidy is specified
then this directory will remain, otherwise it is deleted.

=back


=head1 EXAMPLES

=over 4

=item # B<slacktrack> -p foo-0.10-i386-1.tgz '/bin/sh -x foo.build'

This is the minimum selection of options you must pass to slacktrack.
You are simply telling slacktrack the name of the resulting package file
and specifying that slacktrack should launch "foo.build" via "/bin/sh"

=item # B<slacktrack> -jefkznp bar-3.20-sparc-5.tgz ./bar.build

We are telling slacktrack to strip libraries, chown root:bin /bin 
/sbin, /usr/bin, /usr/sbin, /usr/local/sbin, /usr/local/bin and /usr/X11R?/bin directories, 
chown root:bin files in the binary dirs, strip binaries found in the binary dirs listed above 
and gzip man pages.  

The resulting Slackware package name is 'bar-3.20-sparc-5.tgz'

Note that I have compounded the various options;  the above option list could
also be specified as B<-j -e -f -k -z -n -p bar-3.20-sparc-5.tgz>

=back

There are various example scripts in F</usr/doc/slacktrack-@VERSION@/examples>

=head1 WARNINGS

=over 4


=item B<Do not use slacktrack on production machines>

Please do not run slacktrack on a production machine.  Infact, it is advisable
not build B<any> packages (either B<SlackBuild> or B<.build>) on production machines.

Always use a development box.


=item B<Slackware versions>

slacktrack has only been tested on Slackware 8.1 & Slackware-9 and Splack (Slackware on SPARC, 
using Slackware 9's pkgtools & tar-1.13).

It may works on previous releases of Slackware, it may not.

=item B<slacktrack default working space>

By default, slacktrack puts its work space in B</var/tmp/>

It is essential that you have enough disk space on the
partition on which /var/tmp resides.  If you do not then you 
can pass B<--tempdir> to slacktrack to change the base temporary directory:

# B<slacktrack> --tempdir /tmp/slacktrack -jefknzp "foobar-4.1-sparc-2.tgz" "/bin/sh foobar.build">


=head1 RETURN VALUES

These are the exit codes that slacktrack will produce when it encounters
certain problems. You may wish to use these return codes to indicate
success or failure when slacktrack is called from unattended auto builder
scripts. 

=over 4

=item B<0>
Clean exit

slacktrack exited without encountering any errors.
This is the default exit code.

=item B<1>
Reserved

This error code is not currently used.

=item B<2>
Missing command line parameters

slacktrack was called with insufficient parameters or a parameter 
that requires a value was specified but no value was given.

=item B<3>
Slackware package dependencies failed

slacktrack was asked to check that certain Slackware packages were installed.
It didn't find at least one of the specified packages.

=item B<4>
Missing external helper 

slacktrack failed to find a required external helper.  Currently the external helpers
are the installwatch library and the Slackware 'makepkg' utility.

=item B<5>
Zero files found in installwatch's working directory

slacktrack failed to find any files in installwatch's working directory.
This error may be due to any of the following reasons:

B<1.> The build script or command line specified did not exist or could not be executed.

B<2.> The build script/command line exists but failed to be executed or executed and died with an error

B<3.> The build script/command worked as expected but installwatch failed to detect any activity.

It is suggested that you run B<slacktrack> with the --notidy option and inspect
the working space directory in /var/tmp/ to discover what the problem is.

=back

=head1 FILES

F</usr/bin/slacktrack> the slacktrack script

F</usr/lib/installwatch.so> the installwatch shared object

F</usr/doc/slacktrack-@VERSION@/LICENCE> a copy of the GPLv2 licence

F</usr/doc/slacktrack-@VERSION@/OVERVIEW> an overview of the Slackware package system & build scripts

F</usr/doc/slacktrack-@VERSION@/PACKAGE_BUILDING_CHECKLIST> a checklist for package builders

=head1 AUTHOR

Stuart Winter <stuart@polplex.co.uk> 

=head1 SEE ALSO

=over 4

B<makepkg>(8), B<installpkg>(8), B<explodepkg>(8), B<removepkg>(8), B<pkgtool>(8), B<upgradepkg>(8), B<slackdtxt>(8)

=cut