HOWTO: Use the stow command to keep /research updated with new versions of your
 program/library/etc.

stow is a program that lets us easily update the version of various programs 
without changing the way people have to run those programs. To do this, we have
 a directory /research/stow, which contains many different sub directories, 
which we'll call 'packages'. The contents of a subdirectory will be several 
more directories, indicating where the information should be stored, and those 
directories contain the actual executables, libraries, etc.

Example:
/research/stow/ksim-1.0 has the following subdirectories:
   /research/stow/ksim-1.0/bin
   /research/stow/ksim-1.0/src

These contain:
   /research/stow/ksim-1.0/bin:
	ksim (the ksim executable)
   /research/stow/ksim-1.0/src:
	write_temperature_file.m (a matlab source for auxilary program)


When properly used on this package ('ksim-1.0'), stow will take those files and
 link them into the proper directories. For this example, it should place
      /research/stow/ksim-1.0/bin/ksim -> /research/bin/ksim
and   /research/stow/ksim-1.0/src/write_temperature_file.m -> 
                                  /research/src/write_temperature_file.m

Note how the subdirectory of the package determines where it will be placed.

USEFUL SECTION:

How do I prepare something to be stowed?
 You should first make a package directory under /research/stow, and 
subdirectories appropriate to where you'd like the information placed, usually
bin, src, etc are the most commonly used. Every file you then place in those 
subdirectories will get linked when you run stow, so it is common to compile 
your binary first, then copy it into the appropriate place ('packagename/bin')

How do we stow a package?
   cd /research/stow
   stow 'packagename'
:Note: packagename is just the directory, ie for our previous example, the 
command would be 'stow ksim-1.0'.

How do we update a new version of our package?
   cd /research/stow
   stow -D 'oldpackagename'
   stow 'newpackagename'
Notes: For example, say I wanted to use ksim-2.0's new binary and sources, but 
i've already stowed the ksim-1.0 version. I would then make sure I have the 
ksim-2.0 package as I want in it /research/stow, and then do this:
   cd /research/stow
   stow -D ksim-1.0/
   stow ksim-2.0/

What if I just want to update the same 'package' directory with a new version?
   This is ok to do, but for various aesthetic reasons it probably shouldn't
be done. A quick example is this: You get the shiny new package "ksim-2.0" and
just copy it over the /research/stow/ksim-1.0 package directory. You then run
stow and everything updates ok (assuming the names are the same, or there are
only new files). However, two days later, you find out that ksim-2.0 seg faults
badly in some special cases. You now have to reconstruct the old version's 
stow package. Had you just made a new directory, all you'd have to do to be
up and running again would be 'stow -D ksim-2.0/' ; 'stow ksim-1.0'.

What if I want to add some new files to an existing package?
  This is fine, just run stow as usual to link the new files to the correct
  directories. For example, I want to add two variant versions of ksim, which
  use different memory parameters. I have the binaries for these, 'ksim_lowmem'
  and 'ksim_highmem'. I copy these into /research/stow/ksim-1.0/bin, and 
  then 'cd /research/stow' and 'stow ksim-1.0' and they get added just fine.


This HOWTO created 6/1 by JS. Please edit as necessary and list update times 
after this line. Thank you!