summaryrefslogtreecommitdiff
path: root/source/d/slacktrack/slacktrack-project/man/slacktrack.pod
diff options
context:
space:
mode:
Diffstat (limited to 'source/d/slacktrack/slacktrack-project/man/slacktrack.pod')
-rw-r--r--source/d/slacktrack/slacktrack-project/man/slacktrack.pod949
1 files changed, 949 insertions, 0 deletions
diff --git a/source/d/slacktrack/slacktrack-project/man/slacktrack.pod b/source/d/slacktrack/slacktrack-project/man/slacktrack.pod
new file mode 100644
index 00000000..07eac6a4
--- /dev/null
+++ b/source/d/slacktrack/slacktrack-project/man/slacktrack.pod
@@ -0,0 +1,949 @@
+=pod
+
+=head1 NAME
+
+slacktrack - build Slackware packages from B<.build> scripts
+
+=head1 SYNOPSIS
+
+B<slacktrack> B<[>optionsB<]> -p B<">packagefilenameB<"> B<">buildscriptB<">
+
+
+=head1 DESCRIPTION
+
+B<slacktrack> is a packaging tool to build Slackware packages
+from simple B<.build> scripts, some of which can be found 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<-D>, B<--md5sum>
+
+Create an MD5sum of the resulting package file in the package
+store directory (where the resulting package will be built; usually
+this is F</tmp>). The MD5sum file will be the same name as the resulting
+package 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> <key id>
+
+Sign the resulting package file with specified GnuPG key and
+placed the detached, armored signature in the package store directory (where
+the resulting package will be stored; usually this is F</tmp>). The GnuPG
+signature file will have the same name as the resulting package file but with
+an extra B<.asc> suffixed (e.g. foobar-1.0-i486-5.tgz.asc).
+
+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<-P>, B<--delete-perllocalpod>
+
+Delete any B<perllocal.pod> files found in the package's /usr/lib directory.
+
+These files contain information about a system's Perl packages installed
+in addition to the vendor's Perl distribution. Typically these files are
+created by the installation script of the additional Perl add-on package.
+
+However, they are snapshots of the particular system on which the Slackware
+package is made - and most likely will not reflect the target system's
+environment (the target is unlikely to have an identical set of additional
+Perl modules installed); thus these files should not be present in Slackware packages.
+
+The default is not to delete these files.
+
+=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<pattern for egrep>
+
+slacktrack traverses the filesystem using the UNIX 'find' utility and generates
+a 'snapshot' of the contents. grep -E (or B<'egrep'>) is then used to remove
+a number of paths and specific files from this snapshot; this is because
+these paths/directories either are locations that should never be installation
+destinations for software, or are system files that are subject to change
+moment to moment.
+
+This option allows you to replace the entire default pattern.
+
+By default, slacktrack excludes the following:
+
+EXCLUDE_LIST="${PWD}$|${PWD}|/etc/ntp/drift|/var/run/|/var/run$|/var/lib/dhcpcd|/var/lib/dhcpcd$|/etc/dhcpc/|/etc/dhcpc$|/var/cache/|/var/cache$|/run$|/run/|/media$|/media/|/srv$|/srv/|/selinux$|/selinux/|/var/lib/rpm|/var/lib/rpm$|/var/yp$|/var/yp/|/sys$|/sys/|/initrd$|/initrd/|/dev/bus$|/dev/bus/|/dev/char$|/dev/char/|/dev/rfkill|/dev/input$|/dev/input/|/dev/.udev/|/dev/.udev$|/dev/vc$|/dev/vc/|/dev/console|/dev/pts$|/dev/pts/|/dev/ptmx|/dev/tty|/var/log|/etc/mtab|/etc/resolv.conf|/etc/ld.so.cache|/tmp|/root|/proc|/var/tmp|/var/run/utmp|/var/spool/cron/cron|/var/lib/NetworkManager|/var/lib/NetworkManager$|/usr/man/whatis|/usr/local/man/whatis|/var/lib/pgsql$|/var/lib/pgsql|/var/lib/mysql$|/var/lib/mysql"
+
+This is a pattern for grep -E. Please familiarise yourself with the grep man page
+if you wish to make changes.
+
+It is recommended that these defaults are unchanged.
+
+In addition, slacktrack excludes the PWD (present working directory) from which slacktrack
+was invoked. This allows a package's source directory to be in a non-default excluded
+path and receive updates (such as log files) and avoid slacktrack including them in the
+newly created package file.
+
+=item B<-o>, B<--no-fs-search> B<pattern for find -regex (pre and post file system scans)>
+
+Prior to beginning a build, and post build, slacktrack uses the 'find' command to scan
+the OS' file system, and stores these records. The difference between the two records are used to
+determine the package's contents.
+
+There are some directory paths that should never be included within packages. By default
+this list is:
+
+SEARCH_EXCLUDE_LIST='mnt\|sys\|proc\|tmp\|home\|lib/udev/devices'
+
+B<Note:> The list uses escaped pipes and does not have a leading forward slash. The regex is
+applied to the --rootdir argument, so the excluded paths should be relative to that.
+
+This is a good set for a default Slackware installation, but some users have data
+in other directories which should never be included in a package. Scanning these additional
+directories takes extra time and serves no purpose.
+
+While the B<-x,--exclude> operator is applied to the final package contents list, B<-o, --no-fs-search> is applied
+before and can be used to significantly speed up the searches that build the before/after file lists.
+
+=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
+/usr/lib, /usr/lib64, /lib64, /lib, /usr/local/lib and /usr/libexec
+
+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 package.
+
+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>
+
+Prior to Slackware v11, the standard was to have the /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/sbin, /usr/local/bin and /usr/X11R?/bin directories owned by root:bin.
+
+Slackware v11 changed binary directory ownerships to 'root:root'.
+B<If you are building packages for a version of Slackware prior to version 11,
+you should use this operator>.
+
+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>
+
+Prior to Slackware v11, the standard was 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.
+
+B<If you are building packages for a version of Slackware prior to version 11,
+you should use this operator>.
+
+The default is not to set these ownerships.
+
+=item B<-m>, B<--chown-bins-root-root>
+
+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:root.
+
+If you are intending on building Slackware compliant packages, please use this
+operator.
+
+B<If you are building packages for Slackware versions prior to 11,
+please see the two operators listed above>.
+
+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), slacktrack sometimes 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 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<-m>), B<--chown-bins-root-root> (B<-f>),
+B<--chmod644docs> (B<-g>), B<--delete-perllocalpod> (B<-P>) 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.
+
+Please note that if the temporary directory (either automatically chosen by
+slacktrack or specified using this operator) already exists, slacktrack
+will exit with error code B<6>; the directory should be deleted prior
+to invoking slacktrack.
+
+=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 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 -mnzSIP 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 package file 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 -mnzSIP foo-2.0-arm-1.tgz
+
+By default slacktrack does not execute any commands prior to creating
+the package.
+
+=item B<--run-after-withlog> <command>
+
+This option is the same as B<-R>, B<--run-after>, with the only difference being that
+any output from that script is logged to the slacktrack build log.
+
+If any of your post build scripts perform any checks that should be inspected
+manually after the package build completes, you'd be best choosing this option; but
+note that logging may not work properly for any scripts that require keyboard
+input or use curses based applications (such as 'dialog').
+
+=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.
+
+=item B<-X>, B<--delete-overlapping>
+
+After the filesystem comparison has been completed, slacktrack determines whether there
+are any files that overlap between the new package and those already installed on the
+running system. Normally there should be no overlapping files; however, some packages
+that provide additional Python or Perl libraries often re-process or re-compile some parts
+of the vendor-supplied package contents, causing slacktrack to correctly identify that
+the files have changed after the package build process has finished.
+
+It is undesirable for packages to have overlapping files because it is not
+possible to identify which is the master package. One of the side effects may be that
+the end user has problems with the installation order of the packages.
+
+slacktrack will identify any overlapping files and match them with the package(s) to which the file also belongs.
+Using this operator, slacktrack will erase any overlapping files from the content of the newly
+created package.
+
+The best practice is to review the package build log and investigate any overlapping files.
+It is the responsibility of the package builder (you) to determine why the file is overlapping
+and decide what to do with them.
+
+=item B<--allow-overlapping>
+
+Allow the package to contain files that overlap with packages that are already installed
+on the system. This is the default behaviour, if if you like to use slacktrack's -Q option to build
+an otherwise Slackware standards compliant package, you will need to supply this option afterwards
+to permit files to overlap.
+
+=item B<--touch-filesystem-first>
+
+Use the UNIX touch(1) tool to touch (set the objects' time stamps to the current system time)
+a pre-defined list of directories and their contents prior to generating the
+snapshot of the filesystem.
+
+The pre-defined paths are:
+ /opt /bin /boot /dev /etc /install /lib /sbin /usr /var
+
+It B<excludes> by default '/lib/udev/devices' since this contains
+live device data that doesn't take kindly to being touched.
+You may see errors from 'touch' about certain binaries, including
+/sbin/vol_id because this is a symlink into /lib/udev/devices.
+
+This is intended to be used on a throwaway development installation
+that's reinstalled daily or more often.
+
+The reason behind this is that if you run slacktrack and your build
+partially fails, then it will leave some data on the filesystem.
+You then fix the problem and re-try: this time the build may succeed.
+However, if the original data on the filesystem from the first
+part-failed build has *not* changed (for example, if it was some static data that
+was copied with cp -a (preserved time stamp & ownership)) between
+the first part-failed build and second successful build, slacktrack
+will miss this data from the final package file.
+
+This option updates the file stamps contained within standard package
+directories, therefore allowing slacktrack to detect changes
+(even if the data contains an *old* time stamp from 1982, it will still
+detect the difference).
+
+B<Note:> This is an expert option and is not recommended for use unless
+you are working on a throw-away development installation.
+
+=item B<--touch-filesystem-faster>
+
+This operator performs the same function as B<--touch-filesystem-first> except
+that it uses a faster method; except that potentially speed comes at a price.
+
+If this method finds files or directories with spaces in the name, it
+may create empty files in your package's source build directory.
+
+For example:
+
+B</usr/doc/prog-2.0/FILE WITH A SPACE IN IT>
+
+You may find that you have six new files, "FILE", "WITH", "A", "SPACE," "IN", and "IT" existing
+in your package's build source directory.
+
+However, if you know that there are no files or directories with spaces in their names,
+feel free to use this option in preference to B<--touch-filesystem-first>.
+
+B<Note:> This is an expert option and is not recommended for use unless
+you are working on a throw-away development installation.
+
+
+=item B<-Y>, B<--delete-orphaned-pyc>
+
+After the build has completed, this option scans the contents of the new package,
+and if it finds any '*.pyc' files without a matching '*.py' file, the *.pyc file
+will be removed from the package contents (but not from the filesystem).
+
+This scan only checks the content of the B<package> not the filesystem. There may be
+a corresponding '*.py' file on the filesystem, but it wasn't created or modified
+during the build process of this particular package.
+
+When building Slackware's 'ap/linuxdoc-tools' package, we found that 'gnome doc-tools'
+was causing some Python '*.py' system files from the Python package to be recompiled
+(generating '*.pyc' files) but was not modifying the original '*.py' files.
+This meant that slacktrack was correctly detecting the changed '*.pyc' files and including
+them in the 'linuxdoc-tools' package; but this meant that we had file overlap
+with the 'd/python' package. Since the original '*.py' files were not modified,
+and the '*.pyc' files already existed in the Slackware Python package, they didn't
+need to be included in the 'linuxdoc-tools' package - and the overlapping files
+would have caused problems with package upgrades.
+
+This option is not on by default because it's quite conceivable that the user
+may wish to include '*.pyc' files without '*.py' files.
+
+If the directories and parent directories containing the *.pyc files become
+empty after this operation, then these directories are removed from the package.
+
+=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.
+
+=over 4
+
+=item B<SLACKTRACKFAKEROOT>
+
+This directory is the 'root' directory of the package. You may wish
+to access this directory during build or post-build time so that you can perform
+special operations that slacktrack itself cannot perfom.
+
+However, the to-be-packaged contents won't exist in this directory until
+B<after> the build script finishes and the package has installed itself
+to the filesystem; but you can still pre-populate it with content if you wish,
+although typically you'd perform these actions directly onto the filesystem
+and let slacktrack take care of packaging it.
+
+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.
+
+You could do this using the following script, called from slacktrack
+using the B<-R, --run-after> operator:
+
+=item # B<slacktrack> -R $CWD/postbuildfixes.sh -Qp foo-1.0-i486-2.tgz ./foo.build
+
+
+B<Example post build script 1:>
+
+
+Where the 'postbuildfixes.sh' script contains:
+
+B<( cd ${SLACKTRACKFAKEROOT}
+ strip usr/bin/foo
+ strip bin/bar ) >
+
+
+B<Example post build script 2:>
+
+Another example would be to remove known files that were detected by slacktrack
+as being changed/added/updated during the build process, but that we do not want
+to be packaged. This is an easier method than using the B<-x,--exclude> operator.
+
+B<# 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 .
+>
+
+B<Note:> 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.
+
+=back
+
+
+=over 4
+
+
+=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> -jmkznp bar-3.20-sparc-5.tgz ./bar.build
+
+We are telling slacktrack to strip libraries, chown root:root /bin
+/sbin, /usr/bin, /usr/sbin, /usr/local/sbin, /usr/local/bin and /usr/X11R?/bin directories,
+chown root:root 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 -m -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">
+
+=back
+
+=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
+is the Slackware 'makepkg' utility.
+
+=item B<5>
+Zero files found in slacktrack's package-content-tracking working directory
+
+slacktrack failed to find any files installed as part of the build process.
+
+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 slacktrack 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.
+
+=item B<6>
+Possibly unsafe to continue operation.
+
+slacktrack determined that it was possibly unsafe to continue. This may be
+because it found the temporary directory to already exist (slacktrack needs
+to wipe the temporary directory), or it may get to a point where it needs to
+overwrite an existing file which would require manual intervention.
+
+Since slacktrack is designed to be scriptable, it will never prompt for human
+interaction - just fail with pre-set error codes which can be collected by
+caller scripts.
+
+=back
+
+=head1 FILES
+
+F</usr/bin/slacktrack> the slacktrack script
+
+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 <mozes@slackware.com>
+
+=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)
+
+=back
+=cut
+
+