• NAME
• SYNOPSIS
• DESCRIPTION
• INSTALLATION
• FEATURES
• REQUIREMENTS
• OPTIONS
• PACKAGE NAMES
• EXAMPLES
• HINTS FOR SUCCESS
• ENVIRONMENT VARIABLES
• AUTHOR

NAME

stash - The solution to stubborn system administrators.

SYNOPSIS

stash [options] [package|file|regex]

DESCRIPTION

stash is a perl script that aims to make it easier for you to install, track, and maintain packages and modules in your home directory. It performs this magic by detecting what type of package or module you are installing and passing all the right command line arguments to the confgure scripts and/or makefiles.

INSTALLATION

Assuming the stash distribution was installed per the bootstrap script, add the following line to your startup script (.profile, .login, whatever).

        eval `$HOME/usr/noarch/bin/stash -pP`

Adjust the above for your custom paths, as needed.

FEATURES

stash supports the following configuration tactics:

• Support for autoconf generated configure scripts
  
• Support for some autoconf look-alike configure scripts
  
• Support for Imakefiles
  
• Support for perl Makefile.PL files
  
• Support for python setup.py files
  
• Support for PMK configure scripts
  
• Support for ant build.xml files (VERY minimal)
  
• If none of the above works, tries to auto-edit Makefiles
  
• Support for pre-configure scripts
  
• Properly handles conflicting info/dir files.
  
• Properly handles conflicting perlocal.pod files.
  The beauty of it all, is that if the package is so unique that stash cannot configure, build, and install it, you can still manually configure, build, and install it into the stash directory and then let stash track it for you.

REQUIREMENTS

stash should run on all platforms with perl 5.6 or greater. It should be fairly easy to back-port stash to run on older versions of perl, but the author currently doesn't have an older version available and has, frankly, lost interest in the effort. If you send him patches, he'll probably apply them.

OPTIONS

stash supports the following options.

-h

Display a brief overview of options. (Same as -?)

-?

Display a brief overview of options. (Same as -h)

-a

Print the machine architecture as stash detects it.

-p

Print shell environment setup commands. If the SHELL environment variable ends with 'csh', the commands are for csh compatable shells, otherwise, they are for sh compatible shells.

-P

Automatically pick the perl/python versions. Rather than just utilizing the first perl or python found in your path, stash examines your whole path for all installations of perl or python it can find. Normally, if more than one installation of perl or python is found, stash will ask you to choose which one you want to use. When this option is specified, stash will make that decision for you. It will attempt to choose the latest (highest version number) installed.

-v

Print stash configuration. This is mainly used by the author for debugging.

-V

Print the stash version string.

-O

Force override the package name. This causes stash to ignore its package name rules and use the package name specified on the command line. See PACKAGE NAMES for more details.

-f

Force stash to ignore conflicts. Even when specified, stash will NOT override existing links or files. Instead, it will just continue, rather than failing. -f can also be used to force stash to install into the active stash directory (see -N) regardless of whether or not there are binaries.

-n

Fake it, don't really do anything. This is similar to the -n option to make. This will NOT pass -n to make when it is called, instead it will print *HOW* it would have called make.

-e <file>

Auto-edit the named file. This causes stash to look for certain strings in the file and replace them with $STASH_ARCH (or with $STASH_NOARCH if -N was specified)

-E

Auto commit changes to auto-edited files. The -y option implies this.

-A

Auto relocate mis-installed files. That is, files improperly installed outside of the stash directory. This option does not affect the relocation of packages between arch/noarch stashes. The -y option implies this unless -f is also specified.

-D

This is a dumb package. Some packages won't work correctly unless they are configured with their install prefix. Normally stash configures packages with their runtime prefix. This option changes that behavior. If the package you are stashing gives an error during this install phase, try again with this flag on. This is also quite useful for packages which modify their directories while they run (like TeTeX). Using this flag will guarantee that they modify their directories inside the stash. That said, perhaps calling such packages ``dumb'' is a little harsh...

-N

Use the architecture independent stash. stash maintains two sets of runtime stash directories; architecture dependent ones and architecture independent ones. The default is to use the architecture dependent directories. This option directs stash to use the architecture independent directories. This is useful when installing a script or other non-binary package that you intend on sharing across multiple platforms where your home directory is mounted.

-T

Don't wrap calls to -c, -m, -i; go naTive! Normally, when stash calls make or configure scripts, it will 'wrap' them with a small function that does the following.

1. Exports CC=gcc if gcc is found in the path.

2. Exports CXX=g++ if g++ is found in the path.

3. Adds -I$STASH_ARCH/include to the CFLAGS, CXXFLAGS, and CPPFLAGS environment variables if the directory exists.

4. Adds -L$STASH_ARCH/lib to the LDFLAGS environment variable if the directory exists.

5. Deletes $CDPATH from the environment.

6. Deletes $ENV from the environment.

If you specify this option, this ``wrapping'' won't take place.

-c

Configure the package. stash will attempt to auto detect the type of package in the current directory and call the appropriate configure script with the right command line options/overrides.

-m

Make/Build the package. stash will attempt to auto detect the type of package in the current directory and call the appropriate build script or makefile with the right command line options/overrides.

-i [package]

Install the package. stash will attempt to auto detect the type of package in the current directory and call the appropriate install script or makefile with the right command line options/overrides.

-s [package]

Stash the package. After a package is installed, it won't become available until it is stashed. Stashing a package simply means creating a bunch of symbolic links, where necessary, in order to make the package contents show up in the $STASH_ROOT directory.

-u [package]

Unstash the package. The opposite of -s. This will remove all links to this package from the the $STASH_ROOT directory. Any directories that are empty after the links are removed will also be removed.

-R [package]

Restash (Unstash/Stash) the package. If no package is specified, ALL packages are restashed.

-r [package]

Remove/Delete the package. This will remove the package directory from the $STASH directory. Before being removed, the package is unstashed (-u) just to be sure.

-l [regex]

List packages. Perl compatible regular expressions can be used as a filter. The package list will be formatted like: X: package1 X: package2 etc...

Where X indicates the status of the package and is one of: I: Installed S: Stashed M: Package is stashed, but with missing files. C: Package is stashed, but with changed files.

For speed reasons, only the first 5 files found in the package are checked in order to compute the above status. See the -L option if you want to verify all files in the listed packages. If the status is preceded by an asterisk (*), then the package is stashed in the $STASH_NOARCH_STASH directory (as opposed to the $STASH_ARCH_STASH directory).

-L [regex]

List packages like the -l option, but use all files in the package to compute the status of the package. Also report package sizes. The -l option used to visit every file in all matched packages, but that can be quite slow.

-q [package]

Query package contents.

-C

Same as -c.

-M

Same as -cm.

-I

Same as -cmi.

-S

Same as -cmis.

-y

Auto-answer 'y' to all questions asked by stash. This option does not affect the package being installed. That is, if the package being installed, asks questions, you will still have to answer them.

-z

Compress the package. Before being compressed, the package is unstashed (-u) just to be sure.

-Z

Uncompress the package. After being compressed, the package must be stashed (-s) in order to become available again.

PACKAGE NAMES

If you don't specify a package name on the command line, stash attempts to auto-detect what the package name is based on the contents of the current directory. If configure scripts or makefiles exist in the current directory, the directory name is used as the package name. If READMEs, ChangeLogs, etc exist in the current directory AND the directory ends in a version number, the directory name is used as the package name. If the parent directory of the current directory is $STASH, the directory name is used as the package name.

If you specify a package name (without the -O option), then if a directory by that name exists under the $STASH directory, your package name is used. Otherwise, your package name is used as a regular expression to match against all directories in the $STASH directory.

If you specify a package name along with the -O option, then that is the package name that is used. This is useful if you have a tarball that doesn't contain the version number in the directory name. You can add the version number to the package name, override it, and configure, make, install, and stash as normal. It is important to note, however, that if you use the -O option during any stage of the compile, make, install, stash process, you shoud use during ALL the stages for consistency.

EXAMPLES

New Package - The optimistic method

   $ tar zxvf foo-1.0.tar.gz
   $ cd foo-1.0
   $ stash -S

This method will configure, build, install, and stash the package. Assuming this is a well-behaved package, this will work without errors.

New Package - The method the author uses

   $ tar zxvf foo-1.0.tar.gz
   $ cd foo-1.0
   $ stash -I
   $ stash -s

This approach gives you a chance to make sure everything installed the way you wanted it to before the package is stashed.

New Package - The conservative method

   $ tar zxvf foo-1.0.tar.gz
   $ cd foo-1.0
   $ stash -c
   $ stash -m
   $ stash -i
   $ stash -s

This approach allows you complete control between each step in the process.

Passing arguments to the underlying configure script

   $ tar zxvf foo-1.0.tar.gz
   $ cd foo-1.0
   $ stash -c -- --use-some-option --with-some-dir="/path/to/somewhere"
   $ stash -mis

List Packages

   $ stash -l

Unstash Package

   $ stash -u foo

Remove Package

   $ stash -r foo

HINTS FOR SUCCESS

• If a package that utilizes libtool during install dies with an error similar to:
  

      error: cannot install `somelib' to a directory not ending in somedir

  Try starting over again and specifying the -D option.

ENVIRONMENT VARIABLES

ARCH

This is NOT an external environment variable. It is listed here because it is used below. The internal value of $ARCH can be seen by executing 'stash -a'.

STASH_ROOT

The ``root'' of all stash directories. Defaults to $HOME/usr.

STASH_ARCH

The architecture specific runtime directory. Defaults to $STASH_ROOT/$ARCH.

STASH_NOARCH

The architecture independent runtime directory. Defaults to $STASH_ROOT/noarch.

STASH_ARCH_STASH

The architecture specific stash directory. Defaults to $STASH_ARCH/stash.

STASH_NOARCH_STASH

The architecture independent stash directory. Defaults to $STASH_NOARCH/stash.

STASH_DEFAULT_PYTHON

The default python binary.

STASH_DEFAULT_PERL

The default perl binary.

STASH_LIB

The directory of the stash supporting modules. Defaults to $STASH_NOARCH/lib/Stash.

STASH_CUSTOMS

When set (by you, the user) this variable points to the location of a file that contains lines formatted as follows:

   regex|p|PackageName

          or

   regex|o|-Options

This can be used to customize your stash install! See the Stash::Custom package for examples and further details.

AUTHOR

Rob Wyrick <rob@wyrick.org>