-
Notifications
You must be signed in to change notification settings - Fork 6
/
README
201 lines (161 loc) · 9.16 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
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