################################################################
# Document: FAQ
# Purpose : Preempt questions
# Author..: Stuart Winter <mozes@slackware.com>
################################################################
# It's small at the moment but if I get any repeated
# or potentially repeated questions then they'll be added
# here.
################################################################

Some of the answers here refer to another utility 'altertrack'.
This is a fork of slacktrack that does not use installwatch, 
but works in the same way as protopkg.  After installing the
slacktrack binary package, altertrack will be available in 
/usr/bin


Questions
---------

1.  slacktrack doesn't appear to work with ccache.  Why ?

2.  Do I really have to remove the existing package before
    building a new version with slacktrack ?

3.  I can't compile Perl CPAN modules via perl -MCPAN -eshell
    Why ?

4.  I want to build a package of DVD libraries and players
    but the players depend on the libraries being installed
    first.  How can I build such a package with slacktrack?

5.  How do I know when to use altertrack rather than slacktrack ?

6.  I find that slacktrack always segfaults almost instantly. Why?

7.  I removed the Slackware libsafe package and slacktrack 
    *still* segfaults. What now?

8.  I find that when building packages with altertrack, a number of 
    files are appearing in the package that do not belong there.  Why?

9.  What does altertrack's --touch-filesystem-first option do?
    why would I need it?

10. When using altertrack, I am missing some symlinks in the 
    final .tgz package.  Why?

Answers
-------

Q1. slacktrack doesn't appear to work with ccache.  Why ?

A.  By default, ccache places its work files in your home
    directory.  Therefore when it creates files, installwatch
    moves them into the to-be package's directory structure.
    This is because slacktrack (by design and thus default)
    doesn't exclude /home (or any other home directory name)
    from being included within the package.  The reason for this
    is so that users without root who (for some reason) want to
    produce packages with slacktrack will be able to do so
    within their home directory.

    The way to fix this is either to use the -x, --exclude
    option: eg
    # slacktrack -x "/tmp,/proc,/var/tmp,/usr/tmp,/dev,/home" \
                 -fenzSUIp blah-3.0-i486-2.tgz ./blah.build

    
    Or edit /usr/bin/slacktrack and find the line:

    INSTALLWATCHEXCLUDEDIRS="/tmp,/proc,/var/tmp,/usr/tmp,/dev"

    and modify that to suit your needs.



Q2. Do I really have to remove the existing package before
    building a new version with slacktrack ?

A.  No (see my zlib example), but I'd advise that you do.
    The reason that my example trackbuild scripts remove the
    existing package first (or bomb out) is because some 
    installs will get confused if they find an existing
    configuration file, try to edit it only to find it's 'gone'
    (due to the way installwatch works).
  *  This may result in either the 'make install' failing
     or missing some files from the package. *
    
    I've only ever seen this happen with Apache 1.3.??
    but it just depends on the software in question.

    It's worth noting that Slackware's 'removepkg' program
    won't always remove all files (especially config files
    which are packaged as /etc/file.new and are renamed to
    /etc/file by install/doinst.sh).

    It shouldn't be too much of an issue though.  If it's a
    brand new piece of software that you are building from 
    scratch then installwatch will pick up all new files.
    If you're rebuilding a Slackware package using a
    .build script from the source tree then it's worth
    browsing the package's contents ( # cat /var/log/packages/lftp-* 
    for example ), then running 'removepkg' and looking at its
    output. If there are any remaining config files then either
    move them to a safe place or delete them before
    building yoru package with slacktrack.

    In general though you shouldn't have any problems.
  
    Please note that you can also use altertrack's 
    --touch-filesystem-first option to avoid using removepkg,
    but this option is not recommended since it destroys the
    time stamp information on your system.
    This option should only be used by experts using a disposable
    OS installation.
    Please see FAQ question 9.    

Q3. I can't compile Perl CPAN modules via perl -MCPAN -eshell
    Why ?

A.  If you get this message:
      Unable to get Terminal Size. The TIOCGWINSZ ioctl didn't work. 
      The COLUMNS and LINES environment variables didn't work. 
      The resize program didn't work.

    the answer is to tell slacktrack to turn off logging.
    eg:
       # slacktrack -Qnp foo-1.0-i486-2.tgz ./foo.build 



Q4. I want to build a package of DVD libraries and players
    but the players depend on the libraries being installed
    first.  How can I build such a package with slacktrack?

A.  There are two ways.
    1.  You either write build scripts for each individual 
        library and create packages for each.  Once the packages
        have been built, you install them prior to building
        the player.
        You then unarchive all packages into a temporary
        directory and run makepkg over it.
    2.  Use altertrack and build them all one after another as
        you no doubt have originally attempted.
    
    I have included example build scripts for a DVD library
    package within slacktrack's source archive.



5.  How do I know when to use altertrack rather than slacktrack ?

A.  Typically I will only use altertrack when a 'make install' fails
    dramatically (this is usually when something tries to test an
    installed file or it tries to then compile something else against
    a library it believes has just been installed) and it's not going
    to be an easy or quick task to hack a fix into the Makefile.

    I would always suggest trying slacktrack first, working out
    what is wrong (by reading the error messages) and then making
    an informed decision as to whether to install it on your file
    system and use altertrack to track the changes.
    
    What is PARTICULARLY IMPORTANT here is that you do NOT remove
    certain packages in order to rebuild them. 
    For example, in Slackware's source tree you'll find that zlib
    is a .build script.   UNDER NO CIRCUMSTANCES should you ever
    removepkg zlib.  Things will break !
    (as it happens you can build zlib through slacktrack so it's
     not necessary to use altertrack), but you may face these sorts
    of problems, which is why I always recommend building on a 
    dev box that you can break without causing any trouble.
   
    In order to build a critical system package such as zlib,   
    you really would have to touch every file on the file system, then
    compare the file system before and after the installation
    and manually weed out the junk.
    checkinstall, protopkg or anything else simply will not help you.

    You can also use altertrack's --touch-filesystem-first option
    to avoid having to use removepkg. This touches the files in
    a pre-determined list of directories. 
    Please see FAQ question 9.    

6.  I find that slacktrack segfaults almost instantly.  Why?
 
A.  If you have installed libsafe from slackware/extra then this is
    the likely cause of the problem.  The problem exists because of
    the way installwatch (the library that tracks which files are
    going where) works.

    You can reither remove libsafe or use altertrack.  Unfortunately
    there is no way around this.

7.  I removed the Slackware libsafe package and slacktrack
    *still* segfaults. What now?

A.  Slackware's libsafe package is similar to the glibc
    package in that the paths to the libraries contained within
    the .tgz are not the paths where the library will reside
    on your system once installed.

    The package's installer script also appends (or most likely
    creates, in the case of most people's system) a file called
    /etc/ld.so.preload which tells the system to load the libsafe
    library.

    removepkg has no way of knowing that the libsafe library has
    moved from lib/incoming into /lib and that /etc/ld.so.preload
    has been modified or created.  Therefore when you remove the
    package, you aren't really removing the core of libsafe.

    # cat /etc/ld.so.preload
    If there isn't anything else but libsafe in there:
    # rm -f /etc/ld.so.preload
    Otherwise remove the libsafe line and save the file.

    Remove the libsafe library:
    # rm -f /lib/libsafe.so.2*

    You should find that installwatch no longer segfaults.

        
8.  I find that when building packages with altertrack, a number of
    files are appearing in the package that do not belong there.  Why?

A.  The way that altertrack works is that it:
    [a] takes a snapshot of the files and directories on the file system;
    [b] runs the build scriptl
    [c] makes another snapshot of the files & dirs on the file system;
    [d] compares the two snapshots and determines the differences
    [e] the differences between the two snapshots constitute the package
        contents

    The problem with this approach is that other running programs can 
    make modifications to files & dirs on the file system during the 
    build/compilation process.  altertrack will consider these modifications
    to be part of the package -- altertrack does not directly track what the
    build process does: it *only* compares the differences between the 
    file system snapshots.

    Major culprits for this are:
     cups
     crond (running cron jobs)
     Window Managers and X
     
    When using altertrack you are advised to reduce the number of
    processes to the minimum, and try to ensure that there are no processes
    running which will modify the file system during the build process.

    If you cannot do this then you there are a number of work arounds:
    [a] Using the -x (--exclude) operator. 
        With this operator you can specify a list of
        paths to exclude from the file system snapshots, thus excluding them
        from the resulting .tgz package.
    [b] Use the -R (--run-after) operator.
        With this operator you can specify a command that will be run after
        altertrack has compiled the package contents.
        You may wish to run 'mc' (Midnight Commander) or perhaps just a 'bash'
        shell; this will enable you to inspect and modify the contents of the
        package prior to it being turned into a .tgz.

9.  What does altertrack's --touch-filesystem-first option do?
    why would I need it?

    This option touches all files this pre-set location on the host's
    filesystem:
    /opt /bin /boot /dev /etc /install /lib /sbin /usr /var

    It *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 will touch every file within those directories, destoying all the
    timestamp information.
    This is intended to be used on a throwaway development installation
    that's reinstalled daily or more often.  Builds will often leave
    residue strewn about, so don't use this on your "good" machine and
    think you're managing it properly.  :-)

    The reason behind this is that if you run altertrack 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 (ie 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, altertrack
    will miss this data from the final .tgz package.

    This option updates the file stamps contained within standard package
    directories, therefore allowing altertrack to detect changes
    (even if the data contains an *old* time stamp from 1982, it will still
    detect the difference).

*****  This is an expert option: Please don't use this option unless you do
       not care about your operating system installation *****


10. When using altertrack, I am missing some symlinks in the 
    final .tgz package.  Why?

A.  Because most software installations only use 'ln -s' rather than 
    ln -fs, which means that the time stamp doesn't get updated
    even if you use altertrack's --touch-filesystem-first operator.

    Example:

    turrican [tmp] # ln -s /etc/passwd moose
    turrican [tmp] # ls -la moose
    lrwxrwxrwx 1 root root 11 2007-04-08 09:51 moose -> /etc/passwd
    turrican [tmp] # date
    Sun Apr  8 09:52:34 BST 2007
    turrican [tmp] # touch moose
    turrican [tmp] # ls -la moose
    lrwxrwxrwx 1 root root 11 2007-04-08 09:51 moose -> /etc/passwd
    turrican [tmp] #

    See? the time stamp of 'moose' did not change, but /etc/passwd did:
    turrican [tmp] # ls -la /etc/passwd
    -rw-r--r-- 1 root root 719 2007-04-08 09:52 /etc/passwd
    turrican [tmp] #

    So, this means that if you have previously made symlinks of the
    same name as those that are being installed by your build script,
    the chances are that altertrack won't detect them.

    There are two solutions I know of:
    1.  removepkg <package> prior to building
        but see FAQ question 2.
    2.  A hacky solution:

cd /bin
mv ln ln.real
echo '#!/bin/bash
/bin/ln.real -f $@' > ln
chmod 755 ln

    Now if we try again:
    turrican [tmp] # ln -s /etc/passwd moose
    turrican [tmp] # ls -la moose
    lrwxrwxrwx 1 root root 11 2007-04-08 10:01 moose -> /etc/passwd
    turrican [tmp] #

    Because 'ln' is now a shell script wrapper which calls ln with the
    -f option (force symlink creation), the symlink gets re-created
    and thus the time stamp is updated.

