The MNI Perl Library 
Greg Ward

This is free software, and may be distributed under the same terms as
Perl itself.


INTRODUCTION
------------

The MNI Perl Library is a collection of Perl modules originally designed
to help writing glorified shell scripts -- that is, programs that
(mainly) run other programs.  Its intended area of use is in writing
Perl programs that are long-running, but spend most of their time
waiting around for low-level number crunching programs to do the real
work.  (The reason these types of programs are called "glorified shell
scripts" is because they often start out as shell scripts, and are only
converted to Perl when it is realized that some degree of arithmetic or
logic is needed to control the program in an intelligent and efficient
manner, but the pain and aggravation of doing this in any shell is too
much -- which of course is the niche that Perl has always filled
nicely.)

As it happens, many of the modules in the library are quite handy in all
sorts of areas, but the assumption that programs are used for
long-running scientific computation means that certain parts of the
library are biased in favour of rigor, robustness and reliability rather
than speed -- after all, what's half a second of compiling a bunch of
Perl code compared to twenty minutes (or twenty hours) of
number-crunching?  (Spending that extra half-second is even less
resented when, six months down the road, it helps you track down exactly
how a particular result was generated at a particular time.  Making this
sort of rigorous logging easy is one of the main goals of the library.)


PORTABILITY
-----------

The library is primarily intended for use on POSIX/Unix systems.  The
MNI::FileUtilities and MNI::PathUtilities modules in particular are full
of assumptions about the nature of filenames, the filesystem, and file
permissions.  In addition, I have freely used long filenames (and
subroutine names) that will cause problems on brain-damaged systems with
pathetically short filenames.

The test suite makes many more assumptions than the actual library about
the nature of the system on which it's running -- for instance, / must
be a read-only directory, /dev/null must exist, /tmp must be a writeable
directory, certain conditions must elicit particular error messages, and
so forth.  The test programs are written such that they should crash
noisily if any of these assumptions are not met; if you see errors of
that kind, it does not necessarily mean the library is buggy or your
system is non-standard.  It may mean that I have assumed too much about
the typical Unix system, in which case I will have to fix the test
suite.  Also, failed tests do not necessarily mean the library is buggy;
again it may mean that I have assumed too much.  In any case, I want to
hear about such problems, so please notify me if you encounter them!

BUILDING
--------

The library is built, tested, and installed like any other Perl module
(or bundle of modules):

   perl Makefile.PL
   make
   make test
   make install

Some notes on this process: 

  1) If you're not running at least Perl 5.002, stop now.  You will need
     to download, configure, build, and install an up-to-date version of
     Perl before going any farther.

  2) Running Makefile.PL is not completely automatic -- you will be
     asked to supply the name of a directory that will be used as a
     repository of supplementary data used by various brain-imaging
     software packages from the MNI.  This directory is then hard-coded
     into the MNI::DataDir module, which will be used by various MNI
     packages to install and find supplementary files such as model data
     or configuration files.

     For instance, the N3 package (the first release to use this scheme)
     will install some model data to the 'N3' subdirectory under
     whichever directory you specify here.  For the time being, disk
     space is not a concern (N3 only installs about 64k of data), but
     you should consider the future possibility of large amounts of data
     being installed here.  For instance, the MNI AutoReg package will
     soon be adapted to use the MNI::DataDir scheme, and it requires
     about 10 MB of space for its model data.  ANIMAL, an extension of
     MNI AutoReg to non-linear registration, will require a further 20
     MB of space.

  3) If you are going to install the MNI Perl Library in the standard
     system Perl library directory (the recommended course of action),
     you will need super-user (root) privileges to run the "make
     install" command.

     If you can't or do not wish to install the library alongside the
     system Perl library, you will have to add a few parameters when
     running Makefile.PL.  The easiest way to do this is to install the
     library to ~/lib/perl5; this is done by simply setting the "prefix"
     when running Makefile.PL:

        perl Makefile.PL PREFIX=~ INSTALLDIRS=perl

     (The INSTALLDIRS=perl keeps the library from being installed to
     ~/lib/perl5/site_perl, which doesn't make a lot of sense -- if the
     library is under your personal ~/lib directory, of course it's
     site-specific!  Unless, of course, the standard Perl library is
     also installed there -- in which case you don't need to specify
     PREFIX at all; you just build the library as usual.)

  4) If you do have super-user privileges, it is recommended that you
     *not* use them for the "make test" step.  This is because some of
     tests exercise the library's error-handling capabilities, and
     some of the errors handled are of the "permission denied" variety.
     Since the super-user by definition never encounters these errors,
     the test suite detects when it is being run by root and skips those
     tests.  Thus, running "make test" as root means a few bits of the
     library will not be completely exercised.


MODULES
-------

The modules fall into several thematically arranged groups.

First, the heart and soul of the library is formed by MNI::Startup and
MNI::Spawn; use these two modules in all your Perl programs, and you
will go a long way towards having programs that thoroughly log
themselves and each other, allowing you to reconstruct a particular
execution long after the event.

   MNI::Startup      common startup/shutdown code for writing
                     intelligent, robust, flexible programs: generates
                     temporary directory name and various other
                     ubiquitous values on startup; provides a
                     command-line option table (for use with
                     Getopt::Tabular, also included in the library) to
                     allow the user to override these values; and takes
                     care of cleaning up the temporary directory in any
                     form of program termination short of a catastrophic
                     system crash.

   MNI::Spawn        run child programs with (optional) exhaustive
                     logging of command lines, output redirection/
                     capture, and many other features intended to
                     greatly increase reliability and usability.  (Think
                     of MNI::Spawn as a very limited Unix shell, but
                     with a Perl interface rather than a command line)

There are also several modules that are collections of more-or-less
independent utility subroutines:

   MNI::FileUtilities    manipulate/check/validate/search files and directories
   MNI::PathUtilities    recognize, parse, and tweak POSIX file and path names
   MNI::NumericUtilities common trivial numeric operations
   MNI::MincUtilities    various MINC file hacks using external utilities
   MNI::MiscUtilities    miscellaneous and unclassifiable utility routines


There is a lone module (so far) in its own category (eventually more
will join it, and I'll figure out what the common theme is when that
happens):

   MNI::DataDir      find directory containing supplementary data for a 
                     package; used to ensure a single method for finding
                     such data for all MNI brain-imaging software packages

Finally, there is one "auxiliary module", which is sufficiently
general-purpose that it's not part of the "MNI::" namespace, but stands
on its own (and in fact has been independently released):

   Getopt::Tabular   table-based command-line parsing with strong,
                     customizable checking of arguments for type and
                     number

One or two more general-purpose modules will join Getopt::Tabular in
future releases.


DOCUMENTATION
-------------

Each module is thoroughly documented using the 'pod' embedded
documentation convention for Perl modules.  This means that after
installation, you should be able to get the full documentation on, say,
MNI::Spawn by just typing "man MNI::Spawn".  (This might not work if
Perl wasn't configured to install module man pages to the system man
page directory.  In this case, you'll have to specify a custom search
path to 'man', or use the 'perldoc' command to find and display the
documentation: "perldoc MNI::Spawn").

You can also create a complete printable manual from all the man pages,
as long as you have LaTeX2e and dvips installed.  Just do the following
from the top-level distribution directory:

   cd doc
   make