SYNOPSIS
stowES command[,command[,...]] [options] [expressions]
DESCRIPTION
This manual page documents the stow Enhancement Script, short stowES.
stowES is a perl script which tries to ease the use of the stow packag-
ing program and software which can be compiled and installed with auto-
conf.
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?).
COMMANDS
stowES supplies the following commands which may be abbreviated to
uniqueness (some of them have shorter aliases as well).
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 argu-
ments are given all packages are shown.
checkstow,cs [regexp]
Does the same as the list command but also checks for broken pack-
ages and lists the size of each package scanned in blocks (normally
1KB). This is significantly slower than list. There is an addi-
tional 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,ct [regexp]
Checks if the targetdir only contains links and dirs. Displays the
files and the wrong links it found.
install dir(s)|file(s)
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,mkin dir(s)
This command checks for a file "config.status" which should be left
by the call of "configure". Then "make install prefix=StowDir/pack-
agename" 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 informa-
tion 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!).
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(1) for needed libraries.
checkin,ci
Calls "stow" for the package if the package is not checked in.
checkout,co
Calls "stow -D" for the package if the packges is 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,rm
Removes a package. The use of the -a-option is 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
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 execu-
tion bit set are checked. This normally includes libraries which
are installed this way.
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.
Misc commands:
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.
exchange oldpackregexp newpackregexp
Exchange two package with one call. oldpack is checked out and new-
pack is checked in immediately. oldpackregexp and newpackregexp are
regular expressions which have to match exactly one package.
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,hlp
Print a help screen.
config,cnf,cfg
Print the actual configuration of all interesting variables.
version
Print a version information.
-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' com-
mand.
-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
Directory to store all the stuff. Sources are unpacked to this
directory. Packages created by the `package'-command are also
stored 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.
-j, --paralleljobs [number]
Default: 1
Pass a -j option to make which causes make to do builds in paral-
lel. 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 -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 pro-
cessors 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 auto-
matically 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 -j option with an appropriate num-
ber 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.
-c, --configfile file
Default: none
Specify a configfile (may be used multiple times).
-o, --outputfile file
Default: STDOUT
Output file. With this option it is possible to redirect the output
to something else than STDOUT.
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.
--contentpattern pattern
Default: \Wstow\W
Search pattern for the search in packages with command `con-
tsearch'.
--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 inside
each package (or target dir). 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
switch configure off when a "make"-call failed and you have to
repeat the `make' or `install' comamnd.
--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 unde-
sired result and you want to try to find the right setting.
--use-saved-options, --nouse-saved-options
Default: --nouse-saved-options
This option is used in the make and makeinst commands and tries to
reuse a configuration from an already installed package. The algo-
rithm seems to work for the most common versioning schemes of pack-
ages 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 GetSavedOptionsFromOlder-
Package) 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.
--depends, --nodepends
Default: depends
Do (or do not) create the the dependencies when installing a pack-
age.
--checkin, --nocheckin
Default: checkin
You may switch off the check in of a package when in command `make-
inst' 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 `make-
inst' or `install'.
--strip, --nostrip
Default: nostrip
Switch on or off the call of the "strip"-program to strip a pack-
age.
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"
-r, --rotatinginstall, --norotatinginstall
Default: norotatinginstall
Loop over the packages to install as long as possible. When speci-
fying 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 effic-
tively 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 "examples" 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
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.
--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 "target-
dir/stowname".
StowDir and TargetDir options can only be used in pairs, i.e. a Target-
Dir 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 con-
fig file and specified something like "-s ." on the command line (for-
getting what was in the config file) while working on some other pack-
ages. 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 con-
fig 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.
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.
Locale
Currently locale information are only used to get the thousands sepera-
tor for figures. Nevertheless your locale environment should be prop-
erly set up.
Abbreviations
The paramters may be abbreviated to uniqueness (see docs for
GetOpt::Long.pm). The same applies for commands.
RETURN VALUE
stowES return with 0 if operation was successful and with 1 otherwise.
EXAMPLES
> 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 pack-
age 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
AUTHOR
Adam Lackorzynski <adam@lackorzynski.de>
SEE ALSO
ldd(1), stow(1)
0.5.4 2008-01-14 STOWES(1)
Man(1) output converted with
man2html