=head1 NAME

stowES - the stow Enhancement Script

=head1 SYNOPSIS

B<stowES> command[,command[,...]] [options] [expressions]

=head1 DESCRIPTION

This manual page documents the stow Enhancement Script, short B<stowES>.

B<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.

=head1 REQUIREMENTS

B<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?).

=head1 COMMANDS

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

=over 4

=item B<list,ls> [regexp]

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.

=item B<checkstow,cs> [regexp]

Does the same as the list command but also checks for broken packages and
lists the size of each package scanned in blocks (normally 1KB). This is
significantly slower than I<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 I<check> will behave in the same way as the I<list> command.                                      

=item B<checktarget,ct> [regexp]

Checks if the targetdir only contains links and dirs.  Displays the
files and the wrong links it found.

=item B<install>  dir(s)|file(s)  

Calls command "untar" if the argument is a file. Then calls "make",
"makeinst" and "checkin" with the appropriate arguments.

=item B<untar>  file(s)       

Unpacks a {tar,tar.gz,tar.bz2,tgz}-source-archiv to the "dumpdir" directory.

=item B<confhelp,chlp> dir(s)|file(s)

Call 'configure --help' from a directory or
{tar,tar.gz,tar.bz2,tgz}-source-archiv.

=item B<make,mk> dir(s)

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".                         

=item B<makeinst,mkin> dir(s)      

This command checks for a file "config.status" which should be left by
the call of "configure". Then S<"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
S<"$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
package will  not be delete if the `--force' option was given!).

=back

The following commands take regular expressions or the option I<-a> as
arguments.

=over 4

=item B<checksums>

This command creates the checksums for the packages.

=item B<chkchksums>

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

=item B<depends>

This command calculates some basic dependency information. It only
checks binaries and libraries via ldd(1) for needed libraries.

=item B<checkin,ci>

Calls B<"stow"> for the package if the package is not checked in.

=item B<checkout,co>

Calls B<"stow -D"> for the package if the packges is checked in.

=item B<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.

=item B<remove,rm>

Removes a package. The use of the I<-a>-option is switched off here.

=item B<package>

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

=item B<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).

=item B<contsearch>

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

=item B<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(1). Futhermore all files with the execution bit set are checked. This
normally includes libraries which are installed this way.

=item B<showconfig>

Show the configuration of the specified packages. These are the arguments
given to the configuration script when the program is installed and are
saved in the config.status file.

=back

Misc commands:

=over 4

=item B<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).

=item B<rename> regexp newname

Renames a package. This includes the information in .config/package as
well.

=item B<exchange> oldpackregexp newpackregexp

Exchange two package with one call. oldpack is checked out and newpack is
checked in immediately. oldpackregexp and newpackregexp are regular
expressions which have to match exactly one package.

=item B<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'.

=item B<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.).

=item B<help,hlp>

Print a help screen.

=item B<config,cnf,cfg>

Print the actual configuration of all interesting variables.

=item B<version>

Print a version information.

=back

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

Commands which take the same parameters may be combined with a comma.
E.g. to to check the target and the stow dir one may use: 
  
     stowES cs,ct

=head1 OPTIONS

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.

=over 4

=item B<-s, --stowdir> dir

Default: /usr/local/stow

Stow dir. This directory contains all the packages.

=item B<-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.

I<See later> in this document on a further explanation of the use
of the stow and target dir.

=item B<--stowname> name

Default: stow

Name of the stow directory.

=item B<-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.

=item B<-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.

=item B<-v, --verbose> [level]

Default: 0

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

=item B<q, --quiet, --noquiet>

Default: noquiet

Quiet mode. Do not produce any output except error messages. Use noquiet
to switch the quiet mode off.

=item B<-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.

=item B<-f, --force>

Default: noforce

Force certain operation although there may be unusual conditions.
E.g. 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.

=item B<-d, --dumpdir> dir

Default: /tmp

Directory to store all the stuff. Sources are unpacked to this
directory.  Packages created by the `package'-command are also stored
there.

=item B<-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).


=item B<-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.

=item B<-j, --paralleljobs> [number]

Default: 1

Pass a I<-j> option to make which causes make to do builds in parallel. For
convinience the optional number behind the option differs from the meaning
it has for make! When giving a number greater or equal to one that number
will be given as is to the I<-j> option of make causing it to start as many
sub-processes in parallel. If no number or zero is given, stowES tries to
figure out how many processors are installed on the machine it is currently
running on and uses this number for make. So if you've got a quad-box you'll
automatically get four parallel sub-processes. Of course stowES needs to
know how to find out how many processors are installed. It has support for
some platforms but not for that many. If your platform is not supported you
can use the I<-j> option with an appropriate number or send the author of
stowES (me ;) a patch (see getCPUNumber sub routine in the script) or at
least a detailed description how to find out that number. If stowES cannot
find out the number it will default to one.

=item B<-c, --configfile> file

Default: none

Specify a configfile (may be used multiple times).

=item B<-o, --outputfile> file

Default: STDOUT

Output file. With this option it is possible to redirect the output to
something else than STDOUT.

=item B<-l, --logfile>

Default: /dev/null

Log file, prints short messages what stowES is doing currently. Great
for use with `--rotatinginstall'.

=item B<--subdir> name

Default: none

This option can be primarily used with the make and makeinst commands.

With this option it is possible to install a package into a sub
directory inside your targetdir, e.g. you have some beta software
you want to install into your stowdir but you do not want it to
mess up with your stable packages.

    stowES make foo-cvs-latest --subdir beta

will install this package into $TargetDir/beta but will check it
in in your normal stow dir.

=item B<--contentpattern> pattern

Default: \Wstow\W

Search pattern for the search in packages with command `contsearch'.

=item B<--contentsearchfile> file

Default: /dev/null

Filelist of matches The given file will contain all files which matched
the `contentpattern'.

=item B<--configdirname> dirname

Default: .config

Name of the directory where configuration data is stored inside each
package (or target dir). It is sane to start this name with a ".".

=item B<--dependencyfilename> file

Default: dependencies

Filename for dependencies in the configuration directory.

=item B<--checksumfilename> file

Default: md5sums

Filename for checksums in the configuration directory.

=item B<--creatorinfofilename> file

Default: creatorinfo

Filename for creatorinfo in the configuration directory.

=item B<--packagesuffix> string

Default: none.

Additional name for packages (e.g. architecture) when in command
`package'.

=item B<--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'.

=item B<--makecheck, --nomakecheck>

Default: makecheck

Will switch on or on the call of "make check".

=item B<--configure, --noconfigure>

Default: configure

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

=item B<--make, --nomake>

Default: make

Will switch the call of "make" on or off. It's useful to switch make off
when a "configure"-call did not fail but produced an undesired result
and you want to try to find the right setting.

=item B<--use-saved-options, --nouse-saved-options>

Default: --nouse-saved-options

This option is used in the I<make> and I<makeinst> commands and tries to
reuse a configuration from an already installed package. The algorithm seems
to work for the most common versioning schemes of packages but may fail on
more obscure ones. It should not happen that another package is taken,
normally it should fail in a way that simply no configuration could be
found. If you have any better ideas for the algorithm (see in
function GetSavedOptionsFromOlderPackage) I'd love to receive patches :).
Furthermore, if output isn't surpressed, stowES will wait three seconds
before continuing so that you have a chance to check if the right options
were taken.

=item B<--depends, --nodepends>

Default: depends

Do (or do not) create the the dependencies when installing a package.

=item B<--checkin, --nocheckin>

Default: checkin

You may switch off the check in of a package when in command `makeinst'
or `install'.

=item B<--chkchksums, --nochkchksums>

Default: chkchksums

Switch on or off the check of checksums.

=item B<--checksums, --nochecksums>

Default: checksums

Switch on or off the creation of checksum when doing command `makeinst'
or `install'.

=item B<--strip, --nostrip>

Default: nostrip

Switch on or off the call of the "strip"-program to strip a package.

=item B<--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. The Program-param may contain additional
arguments (e.g. --prog foo='bla arg1 arg2').  For keys see %Progs in the
config screen.

=item B<--prm-conf> regexp=param | param
=item B<--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=xy --dynamic=no"

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


=item B<-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 L</examples> S< >for more.

=back

As already mentioned the options can be abbreviated to uniqueness.

=head1 OPTION HANDLING

There are three way to specify options for B<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
order they are given and config files given in the environment variable
are processed before the config files given on the command line.
I<-c>-options given in a config file are not used (so, no recursion is
possible here).

The last options set is valid (overwriting the previously set ones).

=head1 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 are
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.

=head1 --stowdir and --targetdir options

If you only use the "stowdir"-option, the target directory 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 I<`-t'>-option on the command line will override a given
I<`-s'>-option set in a config or in the environment variable).

Why? It happened to me that I had something like I<"-t /tmp/f"> in my
config file and specified something like I<"-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...

=head1 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".

The system wide configuration file is read first.

=head1 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 ("stowES 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.

=head1 Locale

Currently locale information are only used to get the thousands seperator
for figures. Nevertheless your locale environment should be properly
set up.

=head1 Abbreviations

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


=head1 RETURN VALUE

B<stowES> return with 0 if operation was successful and with 1 otherwise.

=head1 EXAMPLES

Suppose you would like to install gnome... lots 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:

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

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

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

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

Use this if you want to get rid of autoconf.

  > stowES remove autoconf

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.

  > 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


=head1 AUTHOR

Adam Lackorzynski <adam@lackorzynski.de>

=head1 SEE ALSO

ldd(1), stow(1)

=cut