
  Section of Biomedical Image Analysis
  Department of Radiology
  University of Pennsylvania
  3600 Market Street, Suite 380
  Philadelphia, PA 19104

  Web:   http://www.rad.upenn.edu/sbia/
  Email: sbia-software at uphs.upenn.edu

  Copyright (c) 2012, 2013 University of Pennsylvania.
  See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.



INTRODUCTION
============

  This document contains the build and installation instructions.

  For general build and installation instructions which apply to any software
  developed on top of the SBIA Build system And Software Implementation
  Standard (BASIS) [1], please refer to the respective how-to guide of the
  BASIS documentation [2].



OBTAINING A COPY OF THE SOFTWARE
================================

  Please see the corresponding section of the BASIS how-to guide [2].



INSTALLING A BINARY DISTRIBUTION PACKAGE
========================================

  Please see the corresponding section of the BASIS how-to guide [2].



RUNTIME REQUIREMENTS
====================

  This software requires the following langauge interpreters:

  - Bash

    Web Site: http://www.gnu.org/software/bash/
    Download: n/a

  - Perl

    Web Site: http://www.perl.org/
    Download: http://www.perl.org/get.html

  - Python

    Web Site: http://www.python.org/
    Download: http://www.python.org/download/

  Additionally, the following modules have to be installed for these languages:

  - NumPy

    Web:      http://numpy.scipy.org/
    Download: http://sourceforge.net/projects/numpy/files/NumPy/
    Ubuntu:   python-numpy

  - PyNIfTI
  
    Web:      http://niftilib.sourceforge.net/pynifti/
    Download: http://sourceforge.net/projects/niftilib/files/pynifti/
    Ubuntu:   python-nifti



BUILDING THE SOFTWARE FROM SOURCES
==================================

  In the following, only the additional build dependencies and CMake settings
  available to configure this software package are summarized. For a list of
  general build dependencies and step-by-step instructions on how to use CMake
  and GNU Make to build and install the software, please refer to the
  corresponding section in the INSTALL-basis document [2].


  Bundle Build
  ------------

  For the convenient build of this software together with its prerequisites,
  a CMake configuration file which uses CMake's ExternalProject command in
  order to download, configure, build, and install the prerequisites, and then
  this software can be found in the build/ directory of the source distribution
  package.
  
  Of all prerequisites, the bundle build only includes the following. All other
  prerequisites yet need to be installed separately.

  - BASIS 2.1.4
  - GSL 1.15

  Note: This bundle build may require an internet connection if not all required
        packages are included in the build/ directory to be able to download the
        source packages of the prerequisites.

  The steps for building the entire bundle of this software package are:

  1. Change into the build/ directory of the source package:

     $ cd dtidroid-1.1.0-source/build

  2. Run CMake to configure the build:

     $ ccmake .

     In particular, configure the CMAKE_INSTALL_PREFIX where the software and
     its prerequisites should be installed.

  3. Build and install the software and its prerequisite libraries:

     $ make

     Note that if the CMAKE_INSTALL_PREFIX is only writable by the super user,
     you need to run GNU Make either as root user or with sudo.

  4. Remove all temporary source and build files from build/ directory (optional):

     $ make clean


  Build Dependencies
  ------------------

  Attention: The Bash, Perl, Python, and the NumPy and PyNifti modules have to
             be installed prior to the build of this software. See the runtime
             requirements for more details on these dependencies.

  The following software has to be installed (if not optional).

  - BASIS 2.1 or greater

    Web Site: http://www.rad.upenn.edu/sbia/software/basis/
    Download: http://www.rad.upenn.edu/sbia/software/distributions/basis-current-source.tar.gz

    This project is based on BASIS, a meta-project developed at SBIA to
    standardize and simplify the software development.

  - GNU Scientific Library (GSL) 1.13 or greater

    Web Site: http://www.gnu.org/software/gsl/
    Download: http://gnu.mirrorcatalogs.com/gsl/gsl-1.15.tar.gz
    Ubuntu:   libgsl0-dev


  Build Steps
  -----------

  The common steps to build, test, and install software based on CMake,
  including this software, are as follows:

  1. Extract source files.
  2. Create build directory and change to it.
  3. Run CMake to configure the build tree.
  4. Build the software using selected build tool.
  5. Test the built software.
  6. Install the built files.

  On Unix-like systems with GNU Make as build tool, these build steps can be
  summarized by the following sequence of commands executed in a shell,
  where $package and $version are shell variables which represent the name
  of this package and the obtained version of the software.

  $ tar xzf $package-$version-source.tar.gz
  $ mkdir $package-$version-build
  $ cd $package-$version-build
  $ ccmake -DBASIS_DIR:PATH=/path/to/basis ../$package-$version-source

    - Press 'c' to configure the build system and 'e' to ignore warnings.
    - Set CMAKE_INSTALL_PREFIX and other CMake variables and options.
    - Continue pressing 'c' until the option 'g' is available.
    - Then press 'g' to generate the configuration files for GNU Make.

  $ make
  $ make test    (optional)
  $ make install (optional)

  An exhaustive list of minimum build dependencies, including the build tools
  along detailed step-by-step build, test, and installation instructions can
  be found in the corresponding "Building the Software from Sources" section
  of the BASIS how-to guide on software installation [2].

  Please refer to this guide first if you are uncertain about above steps or
  have problems to build, test, or install the software on your system.
  If this guide does not help you resolve the issue, please contact us at
  <sbia-software at uphs.upenn.edu>. In case of failing tests, please attach
  the output of the following command to your email:
 
  $ ctest -V >& test.log

  In the following, only package-specific CMake settings available to
  configure the build and installation of this software are documented.


  CMake Options
  -------------

  GSL_CONFIG          Path of gsl-config executable, e.g., /usr/bin/gsl-config.
  PythonModules_DIR   Paths to NumPy and PyNifti packages, separated by ';' if
                      these are installed in different locations.


  Advanced CMake Options
  ----------------------

  BASH_EXECUTABLE            The installed Bash executable (i.e., usually /bin/bash).
  GSL_INCLUDE_DIR            Directory of include files of GSL.
  PERL_EXECUTABLE            The installed Perl interpreter executable.
  PYTHON_EXECUTABLE          The installed Python interpreter executable.
  PythonModules_numpy_PATH   Path to installed NumPy package (containing numpy/ subdirectory).
  PythonModules_nifti_PATH   Path to installed PyNifti package (containing nifti/ subdirectory).



REFERENCES
==========

  [1] http://www.rad.upenn.edu/sbia/software/basis/

  [2] http://www.rad.upenn.edu/sbia/software/basis/howto/install/
