1 ------------------------------------------------------------------------
   2         MNI-BIC software bundle for the Freesurfer environment
   3 ------------------------------------------------------------------------
   4 
   5 Contained in mni.srcbuild.tar.gz are the source files for a subset of  
   6 the MNI-BIC software commonly used in a Freesurfer working environment.
   7 
   8 (Note that the MNI-BIC binaries necessary to run Freesurfer are already
   9 included with the current Freesurfer distribution, so building from
  10 source is generally not necessary.)
  11   
  12 A Makefile has been created to build, install and test this software.  
  13 Some of the source files have been modified to ensure correct build and 
  14 test across the many platforms that Freesurfer supports.  These mods
  15 should not affect the functionality of the software.  The files
  16 prefaced with 'diffs-*' detail the changes.  Not shown in these diffs
  17 is the change made to numerous files whereby 'Status' was changed to
  18 'VIO_Status', after removing the 'typedef Status VIO_Status' in the
  19 minc/volume_io.h file, to allow building with the gcc flag -Werror.
  20 
  21 The software included in this special bundle:
  22 
  23         NetCDF          v3.6.0-p1
  24         MINC            v1.4
  25         MNI Perllib     v0.07
  26         N3              v1.10
  27         EBTKS           v1.4
  28         Getopt-Tabular  v0.3
  29         MNI autoreg     v0.98r
  30         MNI models      v1.03
  31         BICPL           v1.4.1
  32         Register        v1.3.5
  33         Display         v1.3.9
  34 
  35 Note: the software was downloaded from the main MNI-BIC website:
  36 
  37         http://www.bic.mni.mcgill.ca/software/distribution/
  38 
  39 except netcdf, which was downloaded from:
  40 
  41         http://www.unidata.ucar.edu/software/netcdf/
  42 
  43 The platforms upon which that this bundle has successfully built and 
  44 tested, using the given Makefile, include:
  45 
  46         Linux CENTOS 4
  47         Linux RHEL 4
  48         Linux Redhat 9.0
  49         Linux Redhat 7.3
  50         Max OS X Darwin 8.1.0 (Tiger)
  51         Mac OS X Darwin 7.9.0 (Panther)
  52         Windows Cygwin
  53 
  54 To build, install and test this bundle on your system, assuming you 
  55 have already untar'd/gunzip'd the file mni.srcbuild.tar.gz, first,
  56 declare MNI_INSTALL_DIR, which defines where the files are to be 
  57 installed.  The ideal (default) location on non-MGH machine (which 
  58 already have MNI installed in this location) is:
  59 
  60         setenv MNI_INSTALL_DIR   /usr/pubsw/packages/mni/current
  61 
  62 Root access is usually required to install here.  Installing here
  63 creates the least conflicts with certain Freesurfer tools that
  64 assume this path.
  65 
  66 Next, PERL5LIB must be declared.  PERL5LIB defines where perl will 
  67 look for its MNI utils, like MNI/Startup.pm.  Usually, for Linux
  68 systems, this location is $MNI_INSTALL_DIR/lib/perl5/5.8.5, but, the 
  69 version of perl seems to vary considerably across platform, and so
  70 the proper PERL5LIB must be determined manually.  Type:
  71 
  72         make mni_perllib
  73 
  74 to build the mni Perl libs, which will install them somewhere in the 
  75 $MNI_INSTALL_DIR/lib dir.  Go there and look for something like a 
  76 'perl5/5.8.5' directory (the actual version number might be different). 
  77 PERL5LIB should be set to whatever directory contains the 'MNI' 
  78 directory (which contains the file Startup.pm).  Once this directory
  79 is determined, then declared PERL5LIB, for instance:
  80 
  81         setenv PERL5LIB $MNI_INSTALL_DIR/lib/perl5/5.8.5
  82  
  83 If PERL5LIB is not set properly, then the autoreg package will fail 
  84 to build. 
  85 
  86 Now that MNI_INSTALL_DIR and PERL5LIB are declared, type
  87 
  88         source SetupMniEnv.csh
  89 
  90 Notice that you can declare your own MNI_INSTALL_DIR and PERL5LIB
  91 settings in your .cshrc, and follow that with the 
  92 'source SetupMniEnv.csh' statement to setup the remaining vars.
  93 
  94 Once these are declared in your environment, type the following to
  95 build and install all the remaining packages:
  96 
  97         make
  98 
  99 Following this, to run all the built-in tests, type:
 100 
 101         make check
 102 
 103 If all checks pass (ie, if the message 'Successful make check' appears
 104 after all tests execute), then the object files and other non-essentials
 105 can be removed by typing:
 106 
 107         make distclean
 108 
 109 Remember that it will be necessary to declare MNI_INSTALL_DIR and 
 110 PERL5LIB, followed by SetupMniEnv.csh, in your .cshrc file.
 111 
 112 Common sources of build failures include:
 113 
 114 1) Improper PERL5LIB.  
 115 If building autoreg fails with a complaint about not finding 
 116 MNI/Startup.pm, or it says 'Can't locate Getopt/Tabular.pm in @INC',
 117 then the PERL5LIB path is incorrect.  To discover the correct path 
 118 for PERL5LIB, type:
 119 
 120         make mni_perllib
 121 
 122 to create and install the MNI perl files.  It puts them where it deems 
 123 appropriate, ie, not completely a user-defined spec.  Note that in 
 124 this instance, the PERL5LIB variable is not used, and can be wrong.
 125 Next, goto $MNI_INSTALL_DIR/lib and hunt around for the file Startup.pm.  
 126 It should be in a directory called MNI.  
 127 PERL5LIB should be set to the directory containing MNI. Edit your
 128 SetupMniEnv.csh file with this new PERL5LIB (usually involving just a
 129 few minor edits to the existing PERL5LIB setting) and source it again.
 130 
 131 2) tag=CC not recognized.  
 132 This can happen when building Register or Display, and the default
 133 configure settings are not working for your platform.
 134 The correction is to change to the offending directory (such as 
 135 Register-1.3.5-src or Display-1.3.9-src) and type:
 136 
 137         aclocal
 138         libtoolize --force 
 139         autoreconf --force
 140 
 141 a few times, then change back to the main directory, and rebuild 
 142 the failed-build package by typing:
 143 
 144         make register
 145 
 146 or
 147 
 148         make display
 149 
 150 3) 'make_model' not found.
 151 The SetupMniEnv.csh script must be executed, which sets the path to
 152 the $MIN_INSTALL_DIR/bin directory.
 153 
 154 Note: The minc 'make check' tests fail if built with gcc 4.0. 
 155 Note: Succesful build/install/tests have used gcc versions 2.9.6, 3.3, 
 156 & 3.4.3.
 157 
 158 Please let me know if additional packages should be included in this 
 159 special bundle, if build failures occur, or if it is successful for you.
 160 
 161 ------------------------------------------------------------------------
 162 Nick Schmansky, Engineer             email: nicks at nmr.mgh.harvard.edu
 163 MGH/MIT/HMS Martinos Center for Biomedical Imaging
 164 149 Thirteenth Street, Room 2301     Charlestown, MA 02129           USA
 165 ------------------------------------------------------------------------
 166 Document update: 15 November 2005