		__________________________________________
	       /                                          \
	      /      stowES                                \
	      \               stow Enhancement Script      /
	       \__________________________________________/

Copyright 2000 by Adam Lackorzynski <al10@inf.tu-dresden.de>

License: GPL, see the COPYING file in this distribution for details.

---------------------------------------------------------------------------


stowES is a perl script which tries to ease the use of the stow packaging
program and software which can be compiled and installed with autoconf.

You should know what stow does with its packages and how to use autoconf'ed
sources...

---------------------------------------------------------------------------

History:

At the beginning of this script there were only a few lines of code which
saved the `config.status' file for future reference so that I did not need
to look up all the options again and again. Then I encountered that
although the use of `stow' was quite easy it did not provide any option to
show which packages are installed an which packages are not. So I extended
my script. Then if you install new packages from source you have always to
do the same steps (tar, configure, make, make install prefix=...). My
script was further extended. The rest can be read here...


---------------------------------------------------------------------------

Requirements:

`stowES' should run on all platforms where stow is running what means that
these platform should know perl and supply soft links (have I missed
something?).
 
I am currently using this script under Debian/GNU Linux, Solaris and AIX.

`stowES' was tested using perl version 5.0004_4, 5.0005_3 and 5.6 without
any problems so far (if not, mail me!).

---------------------------------------------------------------------------

stowES supplies the following commands which may be abbreviated to uniqueness
(some of them have shorter aliases as well):

   - list  [regexp]   
     (ls)          List all packages in StowDir (usually /usr/local).
                   The package names are prefixed with a char of the
                   following meaning:
                      I ... package is installed
                      s ... package can be checked in without any conflict
                      - ... package cannot be checked in because there
                            is a conflict with an already installed
                            package, the file in parentheses is the first
                            conflicting found
                   You may give regexps to only show specific packages, if
                   no arguments are given all packages are shown.

   - checkstow [regexp]
     (cs)          Does the same as the list command but also checks for
                   broken packages and lists the size of each package
                   scanned in KBytes. This is significantly slower than
                   "list". There is an additional prefixed char:
                      X ... package is broken, i.e. package was not fully
                            checked in (some files missing) or something
                            other is weird, in the following parentheses
                            all conflicting/missing files/directories are
                            shown (relative to the target dir).
                   Otherwise "check" will behave in the same way as
                   the list command.                                      

   - checktarget [regexp]
     (ct)          Checks if the targetdir only contains links and dirs.
		   Displays the files and the wrong links it found.

   - install  dir(s)|file(s)  
                   Calls command "untar" if the argument is a file. Then
                   calls "make", "makeinst" and "checkin" with the
                   appropriate arguments.

   - untar  file(s)       
                   Unpacks a {tar,tar.gz,tar.bz2}-source-archiv to the
                   directory specified by "dumpdir".

   - make dir(s)
     (mk)          The directory specified as a argument should contain
                   a "configure"-script which is called with the arguments
                   "--prefix=TargetDir" and the arguments you gave on the
                   command line. After this "make" and "make check" are
                   called (of course with the optional paramaters you gave).
		   "make check" is only called if the root-Makefile of the
		   package contains a rule "check".                         

   - makeinst dir(s)      
     (mkin)        This command checks for a file "config.status" which
                   should be left by the call of "configure". Then 
                   "make install prefix=StowDir/packagename" is called to
                   install the package in the appropriate place. After the
                   make run the "config.status" file is copied to
                   "$stowdir/package/.config/package" and a file with basic
                   information on the creator, date and host machine is
                   also stored there. Furthermore the commands "depends",
                   "strip" and "checksums" are called for the package. Note
                   that stripping is switched off per default. When the
                   "--removesource" option was given, the source code is
                   removed.
                   If something during this procedure failed the possibly
                   installed package will be removed since it may be broken.

 The following commands take regular expressions or the option "-a" as
 arguments.

   - checksums     This command creates the checksums for the packages.

   - chkchksums    This command verifies the checksums given in the package 
                   with the ones calculated for each file.

   - depends       This command calculates some basic dependency
                   information. It only checks binaries and libraries via
                   "ldd" for needed libraries.

   - checkin       Calls "stow" for the package if the package is not
     (ci)          checked in.

   - checkout      Calls "stow -D" for the package if the packges is
     (co)          checked in.

   - strip         Strips all files in the package. The checksums will be
                   recalculated by calling the command `checksums'. Note
                   that stripping is switched off per default.

   - remove        Removes a package. The use of the "-a"-option is
     (rm)          switched off here.

   - package       Creates an archive of the specified package and stores
                   it in the DumpDir. The filename of the created package(s)
                   can be influenced the the `--packagesuffix' option.

   - contents      Lists the contents of packages. The first column
                   displays the type of item (d:file, l:link, p:pipe,
                   s:socket, b:block special file, c:character special
                   file). The second column shows the name of file/dir. If
                   the item happens to be a file, the size of it is shown
                   in the third column (in Bytes).

   - contsearch    Searches all files in the packages for a specified
                   pattern. Useful to check if a path containing "stow" was
                   compiled into the binaries/libraries. Specify a search
                   pattern (regular expression) with the `--contentpattern'
                   option.

   - checklibs     Check if all libs for package are available.
                   If stowES thinks there's something wrong that may be so but 
                   must not be so. Some programs hide special libs in special
                   directories which are not know when testing with ldd.

 Misc options:

   - rebuild       Rebuilds the whole stow-archive.
                   Deletes everything except the stowdir from the targetdir
                   and checks in again all packages which were previously
                   checked in. Only package marked with a "I" in the list
                   mode will be checked in again (i.e. broken packages will
                   not be checked in again).

   - rename regexp newname
                   Renames a package. This includes the information in
                   .config/package as well.

   - instpack file(s)
                   Installs and checks in a package created by the
                   "package"-command. If you don't want to check in the
                   package immediately use the option `--nocheckin'.

   - shell         Starts a sub shell (taken from the environment variable
                   $SHELL). This is useful when something during a `stowES'
                   run fails and you want it to correct by hand. So you
                   have the same environment set as when `stowES' would do
                   the job (environment variables etc.).

   - help          Print a help screen.
     (hlp)
   - config        Print the actual configuration of all interesting
     (cnf,cfg)     variables.

   - version       Print a version information.


  And remember: The commands (the options as well) may be abbreviated to
  uniqueness!


 The following options are available (do "perldoc Getopt::Long" for a
 precise explanation on how to syntactically specify options). Some options
 have two options (--bar and --nobar). You may use these to override a set
 option in a configure file or environment variable.

  -s, --stowdir dir
           Default: /usr/local/stow
           Stow dir. This directory contains all the packages.

  -t, --targetdir dir
           Default: /usr/local
           Target directory. This directory is the target directory for
           all the packages installed in the stow directory. The links
           will be created from the stow directory to this target directory.
     
           See later in this document on a further explanation of the use
           of the stow and target dir

  --stowname name
           Default: stow
           Name of the stow directory.

  -p, --packagename name
           Default: none
           Alternate package name. When installing a package you may
           specify an alternative name for the package. This only works
           if you only give one package on the command line.

  -a, --allpackages
           Default: unset.     
           Proceed all packages found in $StowDir. This is the same as
           giving the regular expression "." but will not work for the
           `remove' command.

  -v, --verbose level
           Default: 0   
           Verbose mode. You may give the option -v to urge stowES to print
           out more messages. Theoretically it is possible to give the -v
           option a value (greater zero) to increase the verbosity level
           but this isn't used in stowES currently.

  -q, --quiet, --noquiet
           Default: noquiet
           Quiet mode. Do not produce any output except error messages. Use
           noquiet to switch the quiet mode off.

  -k, --continue, --nocontinue
           Default: nocontinue
           Continue after error if possible. When processing multiple
           files/dirs (e.g. in `install'-mode) stowES will not stop
           processing, it will go on with the next argument on the command
           line.

  -f, --force
           Default: noforce
           Install a package even if it already exists. StowES will not
           complain that there's already a package with the same name. 
           Useful for packages which could not be installed successfully
           in the first try.

  -d, --dumpdir dir
           Default: /tmp
           Dir to store all the stuff. Sources are unpacked to this
           directory. Packages created by the `package'-command are also
           store there.

  -m, --ambiguous, --multiple, --noambiguous, --nomultiple
           Default: noambiguous     
           Regexps may match more than one package. Normally one regular
           expression on the command line may only match one package in the
           stow directory. This options allows the regular expression to
           match to more than one package. This option is only valid to
           some commands, mostly these changing data somewhere (currently
           these are: checksums, depends, checkin, checkout, strip, remove).

  -n, --dryrun, --nodryrun
           Default: nodryrun
           Only show what to do. Affects only commands which change data on
           the disk. This options does not mean that stowES wont cause any 
           disk access, it may check if packages are checked in or not.

  -c, --configfile
           Default: none
           Specify a configfile (may be used multiple times).

  -o, --outputfile
           Default: STDOUT
           Output file. With this option it is possible to redirect the
           output to something else than STDOUT.

  -l, --logfile
           Default: /dev/null
           Log file, prints short messages what stowES is doing
           currently. Great for use with `--rotatinginstall'.

  --contentpattern pattern
           Default: \Wstow\W
           Search pattern for the search in packages with command
           `contsearch'.
 
  --contentsearchfile file
           Default: /dev/null
           Filelist of matches The given file will contain all files
           which matched the `contentpattern'.

  --configdirname dirname
           Default: .config
           Name of the directory where configuration data is
           stored. It is sane to start this name with a ".".

  --dependencyfilename file
           Default: dependencies
           Filename for dependencies in the configuration directory.

  --checksumfilename file
           Default: md5sums
           Filename for checksums in the configuration directory.

  --creatorinfofilename file
           Default: creatorinfo
           Filename for creatorinfo in the configuration directory.

  --packagesuffix string
           Default: none.
           Additional name for packages (e.g. architecture) when in command
           `package'.

  --removesource, --noremovesource
           Default: noremovesource
           Remove unpacked source after built. This is especially useful
           when using `--rotatingintall' with lots of packages (else you
           would need lots of disk space). Only applies for commands
           `makeinst' and `install'.

  --makecheck, --nomakecheck
           Default: makecheck
           Will switch on or on the call of "make check".

  --configure, --noconfigure
           Default: configure
           Will switch on or off the call of "configure". It's usefull to
           switch configure off when a "make"-call failed and you have to
           repeat the `make' or `install' comamnd.

  --depends, --nodepends
           Default: depends
           Do (or do not) create the the dependencies when installing a
           package.

  --checkin, --nocheckin
           Default: checkin
           You may switch off the check in of a package when in command
           `makeinst' or `install'.

  --chkchksums, --nochkchksums
           Default: chkchksums
           Switch on or off the check of checksums.

  --checksums, --nochecksums
           Default: checksums
           Switch on or off the creation of checksum when doing command
           `makeinst' or `install'.

  --strip, --nostrip
           Default: nostrip
           Switch on or off the call of the "strip"-program to strip a
           package.

  --prog key=program
           Default: Key==Program (see `stowES config | grep ^%Progs`)
           Specify alternate Programs. With this option you may specify
           alternative programs to be used by stowES.
           For keys see %Progs in the config screen.

  --prm-conf regexp=param | param
  --prm-make regexp=param | param
           Default: none
           Specify extra parameters for the call of `configure' and `make'.
           The parameter is used when the regexp matches the package
           currently proceeded. When giving no regexp the parameters will
           be used for every call of `configure' or `make'.
           If you only specify a parameter which contains a '=' (e.g. CC=gcc)
           you have to proceed a '=' to avoid splitting up the parameter
           itself.
           
           Examples:
             Using one paramter:
              stowES ... --prm-conf --disable-static

             Using more than one:
              stowES ... --prm-conf '--enable-foo --enable-bar'

             Using a parameter with '=':
              stowES ... --prm-make==CC=gcc
               or
              stowES ... --prm-make =CC=gcc

             Use two (or more) params for one package with '=' in the options:
              stowES ... --prm-conf emacs="--with-dialogs=athena --dynamic=no"

             Use them for all packages:
              stowES ... --prm-conf ="--with-dialogs=athena --dynamic=no"
 


  -r, --rotatinginstall, --norotatinginstall
           Default: norotatinginstall
           Loop over the packages to install as long as possible. When
           specifying this option the packages given on the command line
           will be tried to install again and again until they can be
           compiled. If the remaining packages all fail within one run
           stowES will give up. 
           This options only applies to the `install' command.  
           That effictively means that you do not need to pay attention
           on the order of the packages given on the command line
           when installing packages.
           As you may imagine, this method will not work in all cases,
           there are several problems involved (e.g. failing configures
           etc., maybe more later here on). But it is good for trying
           out a new bunch of software with the least possible waste of
           your energy :-). If it fails you can go the old way of installing
           things...
           See the examples section for more.


  As already mentioned the options can be abbreviated to uniqueness.


######################################################################

 Option handling

    There are three way to specify options for `stowES':
       o config file
       o environment variable
       o command line
    First the environment variable and the command line are checked
    for the `load config file'-option. Then the options in the config
    file are processed at first, then the options in the environment
    variable and at last the options on the command line. Config files are
    processed in the way they are given and config files given in the
    environment variable are processed before the config files given on the
    command line. `-c'-options given in a config file are not used (so, no
    recursion is possible here).

 Environment-variable `STOWES':

    You can specify an environment variable `STOWES' and store
    options in it in the same way you would do on the command line.
    These options a processed after the config-file was read and
    before the options on the command line. That means that options
    on the command line will override options given in the variable
    `STOWES' and in the config file.

 --stowdir and --targetdir options:

    If you only use the "stowdir"-option, the target dir will be the parent
    directory of the stow directory. On the other hand, if you only specify 
    the target directory, the stow directory will be "targetdir/stowname".
    
    StowDir and TargetDir options can only be used in pairs, i.e. a
    TargetDir or StowDir option will override both values from a lower
    level (e.g. a `-t'-option on the command line will override a given
    `-s'-option set in a config or in the environment variable).

    Why? It happened to me that I had something like "-t /tmp/f" in my
    config file and specified something like "-s ." on the command line
    (forgetting what was in the config file) while working on some other
    packages. Since these option do not overwrite themselves ugly target-
    and stowdirs are used...

 Config files:
    You may store any option you would write on the command line in a
    config file. These options are pushed before the arguments you gave on
    the command line, so you can overwrite options given in a config file.
    Standard configs may be placed in "/etc/stowESrc" and/or "~/.stowESrc".


 Package matching:

    By default, commands which take regexps as params are only executed
    if they match exactly one package (this counts per regexp).
    This should help to avoid messing up your packages 
    ("$0 remove glib" would remove more than just glib, at least on my 
    system...). If you want to supply a command to more packages 
    you may use the `m'-option.

 Abbreviations:

  The paramters may be abbreviated to uniqueness (see docs for 
  GetOpt::Long.pm). The same applies for commands.

 Recommendation for a backup:

  Since this is work in progress you should have a backup of your
  files when you play with my script. Normally nothing should happen to
  your files but who knows...
                                    ... I have warned you!



==========================================================================
  
  Examples:

    Suppose you would like to install gnome... lot's of work?
    Consider this:

    > cd /plenty/space; mkdir gnome; cd gnome
    > ncftpget ftp://ftp.gnome.org/pub/GNOME/stable/latest/sources/*
    > stowES install -r --removesource -t /some/space *

    Now have a cup of coffee or tea or make something else, this will take
    some time to finish. When your prompt reappears you should have gnome
    installed from source (with all the default options for each package
    taken).

    Now a bit smaller:

    > S install store/src/autoconf/autoconf-2.14.tar.gz 

    will unpack, compile and install autoconf in /usr/local.

    > S chkchksums -a
    Checking checksums for package autoconf-2.14...ok.

    If you have only autoconf installed a call of chkchksums may give this
    output.

    > S remove autoconf

    Use this if you want to get rid of autoconf.

    > S ls window
    Listing packages in /usr/local/stow matching [ window ] (3 matches):
    - WindowMaker-0.61.1 (GNUstep/Apps/WPrefs.app/WPrefs)
    I WindowMaker-0.62.1
    I WindowMaker-extra-0.1

    Here you see that I have three packages matching "window" installed.
    Two of them a checked in and can be used. The WindowMaker-0.61.1
    package is currently not checked in, it conflicts with some other
    package, so it can't even be checked in if wanted.

    


    
 Adam Lackorzynski <al10@inf.tu-dresden.de>   
