============================================
BRAT - Basic Radar Altimetry Toolbox INSTALL
============================================



INSTALLING FROM THE BINARY DISTRIBUTION
=======================================

Full information on installing BRAT from a binary distribution
can be found in the BRAT User Manual available in the file
brat_user_manual_2.0.1.pdf in the 'doc' directory of the BRAT
distribution or installation.

The short version is as follows:

+ For Windows XP: double-click the installer file
brat-2.0.1-windows-installer.exe and follow the instructions.

+ For Linux: double-click in your desktop manager (or execute
from the command-line) the installer file
brat-2.0.1-linux-installer.bin and follow the instructions. (If
necessary use 'chmod +x <installer-filename>' to ensure the
installer is executable.)

+ For Mac OS X: double-click the image file appropriate for your
platform (brat-2.0.1-macosx-ppc.dmg for PowerPC Macintoshes,
brat-2.0.1-macosx-i386.dmg for Intel Macintoshes), and drag the
'BratGui' application to the 'Applications' folder on your
machine. You can optionally drag the 'brat' folder to a location
of your choice if you want to have the non-gui components of BRAT
installed as well.

The remainder of this INSTALL file concerns itself with compiling
and installing BRAT from source code, and assumes that you have
an understanding of the various components BRAT consists of (see
the User Manual for details).



INSTALLING FROM SOURCE
======================

Generally, installation from source will be necessary if:

+ You are on Linux or Mac OS X and you want to use the IDL or
  MATLAB interfaces to BRAT.

+ You are on a Linux system that is older than the one used to
  create the BRAT Linux binary distribution (in which case BRAT
  will fail to run if installed as a binary).

+ You are on a Windows system, and your version of MATLAB or IDL
  is not supported by the pre-compiled interfaces in the Windows
  binary distribution.

+ You are on another Unix-based system not supported by the
  binary distributions.

In summary, the process of compiling BRAT is as follows:

+ Get and unpack the source distribution.

+ Install the various software prerequisites.

+ Configure the build using CMake options.

+ Compile the build.

+ Install the build.



BRAT PREREQUISITE SOFTWARE
==========================

The prerequisite software for running BRAT (as mentioned in the
User Manual) is of course also prerequisite software for
compiling it:

  + X11 Windowing System (BRAT has been tested on Xorg Xserver
  v1.1.1 and higher)

  + GTK 2 libraries (BRAT has been tested on
  libgtk2 v2.8.20 or higher)

  + C run-time libraries (BRAT has been tested on libc6 v2.3.6 or
  higher)

The following additional software must be installed before any
component of BRAT can be compiled:

  + C++ Compiler
  Most Unix platforms come with their own C++ compiler (or one can
  be downloaded using the native package manager) so this should
  not be a problem. For Linux and Mac OS, BRAT was developed with
  GNU g++ (version 4.0.x or higher), for Windows with Visual Studio
  C++ 6.0 service pack 5 (higher versions may require tweaking). On
  Mac OS X you should make sure you have installed the Developer
  Tools.

  + CMake v2.6.1
  Link: http://www.cmake.org/

  CMake is a multi-platform makefile generator. Earlier versions
  than 2.6.1 will not work; nor will v2.6.2.

  + Perl v5.8.x (or higher)
  Link: http://www.perl.com/

  Perl is a multi-platform scripting language. On Windows, the
  ActiveState Perl (http://www.activestate.com/activeperl/)
  distribution works well.

With a compiler and CMake and Perl in place, you should be able
to build the CODA and BRATHL libraries and the Console
Applications.

  + IDL V6.3 (or higher)
  Link: http://www.ittvis.com/idl/

With IDL installed you will be able to build the CODA and BRATHL
IDL interfaces.

  + Matlab V7.5/R15 (or higher)
  Link: http://www.mathworks.com/

With MATLAB installed you will be able to build the CODA and
BRATHL MATLAB interfaces.

  + wxWidgets v2.8.9 (or higher)
  Link: http://www.wxwidgets.org/, http://www.wxpython.org/

  WxWidgets is a multi-platform GUI building tool. On Linux and
  MacOS the instructions below will refer to the wxPython
  distribution (which contains wxWidgets), for Windows we refer
  to the wxMSW distribution.

  + VTK v5.0.4

  Multi-platform graphic tool.
  Link: http://www.vtk.org/files/release/5.0/

  VTK is a (3D) computer graphics and visualisation toolkit. Note
  that BRAT absolutely requires VTK v5.0.4 -- more recent VTK
  versions will cause compatibility problems.

  Note that v5.0.4 is no longer explicitly linked to on the VTK
  home or download pages. It can still be found in the VTK
  release archive at the link given above, however.

VTK and wxWidgets are only necessary if you want to build the GUI
Applications (BratDisplay and BratGui). They are large, complex
packages, so if you do not need to compile the GUI applications,
you can save a lot of time and effort. Many Linux package
managers offer pre-installed versions of VTK and wxWidgets, but
these versions are often not compiled with the exact options BRAT
requires. Separate compilation is recommended.

  + BitRock InstallBuilder v5.4.13

  Link: http://www.bitrock.com
  InstallBuilder is a commercial product; a license is needed.
  (Licenses for GPL applications are available from BitRock at no
  cost).

InstallBuilder allows you to build the binary installer for the
Windows and Linux platforms. (The MacOS X images can be generated
without the help of additional software.)

  + Fortran compiler

A Fortran compiler is needed to build the Fortran interface to
BRATHL.



PLATFORM-SPECIFIC INSTRUCTIONS FOR SOURCE BUILDING
==================================================

Building the prerequisites (Linux)
----------------------------------

Note: VTK and wxWidgets may themselves have dependendencies on
other (development versions of) software packages that may or may
not already be present on your system. This INSTALL file only
covers BRAT-specific compilation details, and assumes all
subdependencies are covered. Please consult the installation
instructions for VTK and wxWidgets found in their source
directories for more detailed information on their prerequisites.

+ VTK

Unpack the VTK sources. Create a build directory, cd into it and
call CMake with the following flags:

    $ cmake -DCMAKE_INSTALL_PREFIX:PATH=<vtk-install-path> \
        -DBUILD_TESTING:BOOL=OFF \
        -DCMAKE_BUILD_TYPE:STRING=Release \
        -DBUILD_SHARED_LIBS:BOOL=OFF \
        -DVTK_WRAP_PYTHON:BOOL=OFF \
        -DVTK_WRAP_TCL:BOOL=OFF \
        -DVTK_USE_TK:BOOL=OFF \
        <vtk-source-path>

Note that whatever CMAKE_BUILD_TYPE you specify (Release, Debug,
etc.), you must later use exactly the same one when compiling
BRAT (see below).

Call "make", "make install", and then specify <vtk-install-path>
as the value for VTK_DIR when building BRAT (see below).

Note: it is important that VTK is compiled with the
VTK_USE_ANSI_STDLIB flag set to "ON". Because should be the case
by the default, it is not listed in the invocation given above,
but it is something to watch out for when debugging or using an
existing installation. You can find a log of the settings with
which a particular installation of VTK was compiled in the file
<vtk-install-path>/lib/vtk-5.0/VTKConfig.cmake.

Note: VTK 5.0.4 will not compile out of the box with GNU g++ 4.3
or higher (earlier versions are no problem). The fix is very
simple. Add the line:

     #include <cstring>

to each of the following source files:

    <vtk-source-path>/Utilities/DICOMParser/DICOMFile.cxx
    <vtk-source-path>/Utilities/DICOMParser/DICOMParser.cxx
    <vtk-source-path>/Utilities/DICOMParser/DICOMAppHelper.cxx

+ WxWidgets

Unpack the WxWidgets sources (the following assumes you are using
the wxPython distribution -- follow the wxWidgets instructions
for other versions). Create a build directory, cd into it, and
call the configure script (wxWidgets is not a CMake application,
but uses the GNU autotools) with the following flags:

    $ <wxwidgets-source-path>/configure \
        --prefix=<wxwidgets-install-path> \
        --enable-monolithic \
        --disable-shared \
        --disable-unicode \
        --with-opengl \
        --enable-geometry \
        --enable-display \
        --with-expat=builtin \
        --with-libpng=builtin \
        --with-libjpeg=builtin \
        --with-libtiff=builtin

Call "make", "make install", and then specify
<wxwidgets-install-path>/bin/wx-config as the value for
wxWidgets_CONFIG_EXECUTABLE when building BRAT (see below).


Building the source package (Linux)
-----------------------------------

The following steps will guide you through the process of
building the BRAT libraries and executables (including CODA and
the IDL and MATLAB interfaces) on a Linux-based platform:

  + Go to the directory that contains the downloaded
    brat-x.y.z.tar.gz file and unpack this package:

    $ gzip -d brat-x.y.z.tar.gz
    $ tar xf brat-x.y.z.tar

    Make sure you replace x.y.z with the appropriate version number.

    You should now have a brat-x.y.z directory.

  + Create your so-called build directory. This should be a new
    empty directory, preferably located outside of the brat-x.y.z
    directory. Go to this directory:

    $ mkdir build
    $ cd build

  + Next you will have to configure and run CMake. This will
    check what system you are on and set up the build
    environment. There are several options and environment
    settings you can pass to cmake in the form of
    -D<option>=<value> flags:

    -DCMAKE_BUILD_TYPE=<string value>

    This will instruct CMake to build the sources with e.g.
    debugging information included (if value = Debug) or not
    (value = Release). If uncertain, use Debug. Consult the CMake
    documentation for more info.

    -DCMAKE_INSTALL_PREFIX=<BRAT installation directory>

    By default, if you perform an installation of the BRAT
    package (see further below on how to do this) all files are
    installed in subdirectories under /usr/local/brat/.
    Executables will appear under /usr/local/brat/bin/, libraries
    under /usr/local/brat/lib/, etc. However, installing the
    files into the default places requires you to have
    administrator privileges, which you may not have. In order to
    install BRAT in a different location where you do have
    permission to copy files to, you can use this option to
    provide a different installation directory. For instance, you
    can use --prefix=$HOME/brat to install BRAT in the
    subdirectory 'brat' of your home directory.

    -DBRAT_BUILD_GUI=ON

     By default BRAT is built without the BratGui and BratDisplay
     applications. Use this option to enable building of these
     application. This option requires properly configured and
     installed VTK and wxWidgets sources, and is typically
     useless without also passing accompanying VTK_DIR and
     wxWidgets_CONFIG_EXECUTABLES variables to CMake (see below).

    -DwxWidgets_CONFIG_EXECUTABLE=<wx-config location>

     Specify the full pathname to the wx-config utility in your
     wxWidgets installation (typically this is located in the bin/
     subdirectory of your wxWidgets root install).

    -DVTK_DIR=<VTK root directory>

     The <VTK root directory> is the root directory of your VTK
     installation.

    -DBRATHL_BUILD_FORTRAN=ON

     Build the Fortran example program. An installed Fortran
     compiler is required (and should automatically be detected
     by CMake).

    -DBRATHL_BUILD_IDL=ON

     By default BRAT is built without the IDL interface. Use this
     option to enable building of the interface to IDL.

    -DIDL_DIR=<IDL root directory>

     If you want to build the IDL interface you should also use
     this option to tell CMake where you have installed IDL. The
     <IDL root directory> is the root directory of your IDL
     installation. It should contain for instance the 'bin'
     directory with the idl executable and an 'external'
     directory containing the file 'export.h'. Also make sure
     that you provide an absolute path for the IDL root directory
     (i.e. starting with a '/').

    -DBRATHL_BUILD_MATLAB=ON

     By default BRAT is built without the MATLAB interface.
     Use this option to enable building of the interface to MATLAB.

    -DMATLAB_DIR=<MATLAB root directory>

     If you want to build the MATLAB interface you should also
     use this option to tell CMake where you have installed
     MATLAB. The <MATLAB root directory> is the root directory of
     your MATLAB installation. It should contain for instance the
     'bin' directory with the matlab and mex executables (or
     symbolic links to them) and an 'extern/include' subdirectory
     containing the file 'mex.h'. Also make sure that you provide
     an absolute path for the MATLAB root directory (i.e.
     starting with a '/').

     Make sure to configure mex such that the C++ compiler
     version matches the one used for BRAT compilation (consult
     the MATLAB documentation for details on how to do this --
     basically: run "mex -setup").

    -DINSTALL_BUILDER_DIR=<InstallBuilder executable directory>

     Only required if you intend to build a binary installer.
     This will tell CMake where the InstallBuilder executable us
     located.

     You should now call CMake with the options that are
     appropriate for you. For instance, if you want to install
     BRAT in the default location (/usr/local/brat) and if you want to
     build the IDL interface (but not the MATLAB interface) with
     IDL installed in /usr/local/rsi/idl then your invocation of
     CMake could be:

      $ cmake \
          -DCMAKE_BUILD_TYPE=Release \
          -DBRAT_BUILD_GUI=ON \
          -DBRATHL_BUILD_IDL=ON \
          -DIDL_DIR=/usr/local/rsi/idl \
          -DwxWidgets_CONFIG_EXECUTABLE=/usr/local/wxWidgets/bin/wx-config \
          -DVTK_DIR=/usr/local/VTK \
          <path to brat-x.y.z unpacked source directory>

     Note that CMake should always be invoked from within your
     build directory, with as a final argument the location of
     the source directory.

  + If CMake completes successfully, you are now able to build
    the library by executing the `make' command:

       $ make

    If everything was successful, you are now ready to install
    the package (this installation step is not optional! You will
    have to install BRAT before you can use it).


Installing the source package (Linux)
-------------------------------------

In order to make use of the BRAT libraries and interfaces, you
should install the BRAT software. If you do not want to install
BRAT in its default location /usr/local/bratPlease make sure you
have passed the appropriate installation directory option
(-DCMAKE_INSTALL_PREFIX=<installdir>) to CMake, as explained in
the previous section. After that, issue the following command:

    $ make install

If you also want to use the BRAT (or CODA) IDL or MATLAB
interfaces, the final step is to tell these applications where
they can find the interface files.

For IDL you will have to add <BRAT installdir>/idl to your
DLM_PATH. You do this by setting an IDL_DLM_PATH environment
variable and add this setting to your system shell startup script
(if you don't now how to set environment variables or add these
to your shell startup script, please ask your system
administrator). The variable should be set to "<IDL_DEFAULT>"
appended with the BRAT DLM directories. If, for instance, you
have installed BRAT in /usr/local/brat then you should set the
IDL_DLM_PATH environment variable to
"<IDL_DEFAULT>:/usr/local/brat/idl".

For MATLAB you should create a startup.m file in a 'matlab'
directory in your home directory (~/matlab/startup.m) that
contains the lines:

    addpath <BRAT installdir>/matlab

(or you can set and save the path manually from within the MATLAB
application).


Building the prerequisites (Windows)
------------------------------------

+ VTK

As per the instructions for Linux (see above): because VTK uses
the cross-platform CMake, it can be built and installed the same
way.

However, unlike on Linux, on Windows the VTK_USE_ANSI_STDLIB flag
is set to OFF by default, so be sure to add:

    -DVTK_USE_ANSI_STDLIB:BOOL=ON

to the CMake invocation.


+ WxWidgets

On Windows, use the wxMSW distribution. Follow the instructions
in the the INSTALL file for that packages, and compile and
install. Options are specified in a different way for wxMSW then
for wxWidgets on Linux. So when using 'nmake' for instance, the
relevant compilation step would be to descend into
wxMSW-x.y.z\build\msw and run:

    > nmake -f makefile.vc BUILD=release USE_OPENGL=1

Make sure to check the wxMSW instructions to verify no other
compilation parameters have to be supplies (in particular,
UNICODE should be 0, whic h in MSW 2.8.9 is the default on
Windows).


Building the source package (Windows)
-------------------------------------

As CMake is a cross-platform tool, building BRAT on Windows is
fairly similar to building it on Linux. Follow the guidelines in
the previous section to configure the build process.

The differences are:

+ Use a 'cmd' command-line window to execute the various
  commands.

+ On Windows, the default install location is C:/Program
  Files/brat-x.y.z/. Again, you can use the CMAKE_INSTALL_PREFIX
  to overrule this.

+ Instead of 'make', the Visual Studio C++ build utility 'nmake'
  is necessary. So the build and installation commands become
  'nmake' and 'nmake install' respectively. This requires nmake
  to be in your executable path. Consult the Visual Studio
  documentation for info on how to do this.

+ In addition, you should also pass the flag:

    -G "NMake Makefiles"

  to your CMake invocation, in order to tell CMake to generate
  'nmake'-compatible Makefiles.

+ Instead of passing the location of the wx-config utility to
  CMake in the wxWidgets_CONFIG_EXECUTABLE variable, use:

    -DwxWidgets_ROOT_DIR=<wxwidgets root directory>

   where <wxwidgets root directory> is the root directory of your
   wxMSW installation.


Installing the source package (Windows)
---------------------------------------

+ Use 'nmake install'.

+ For IDL you will have to add <BRAT installdir>\idl to your
  DLM_PATH for IDL versions 6.3 and higher. You do this by
  setting an IDL_DLM_PATH environment variable. On Windows NT,
  2000, and XP open the 'System' control panel of your Windows
  operating system and goto the 'Advanced' tab. Then click on
  'Environment Variables' and create a new system variable with
  the name 'IDL_DLM_PATH' and value '<IDL_DEFAULT>;C:\Program
  Files\brat-x.y.z\idl'. If you have installed BRAT in a
  different location then replace this part in the value by the
  installation directory you chose when installing BRAT.

+ For MATLAB you will have to start MATLAB and go to the 'Set
  Path...' menu item in the 'File' menu. Here you should add the
  directory 'C:\Program Files\brat-x.y.z\matlab'. If you have
  installed BRAT in a different location from the default,
  replace this part of the directory by the installation
  directory you had chosen when you installed BRAT.


Building the prerequisites (Mac OS)
-----------------------------------

Building on the Mac OS and Linux is similar, but Mac OS requires
some platform-specific options in certain places.

+ VTK

As for Linux, but invoke CMake as follows:

    $ cmake -DCMAKE_INSTALL_PREFIX:PATH=<vtk-install-path> \
        -DBUILD_TESTING:BOOL=OFF \
        -DCMAKE_BUILD_TYPE:STRING=Release \
        -DBUILD_SHARED_LIBS:BOOL=OFF \
        -DVTK_WRAP_PYTHON:BOOL=OFF \
        -DVTK_WRAP_TCL:BOOL=OFF \
        -DVTK_USE_TK:BOOL=OFF \
        -DVTK_USE_CARBON:BOOL=ON \
        -DVTK_USE_COCOA:BOOL=OFF \
        -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk \
        -DCMAKE_CXX_FLAGS:STRING='-mmacosx-version-min=10.4' \
        -DCMAKE_C_FLAGS:STRING='-mmacosx-version-min=10.4' \
        <vtk-source-path>


+ WxWidgets

The proces is similar to that for Linux, but with the following
additions:

If you are building on powerpc architecture, you will have to
apply a patch to wxWidgets. After unzipping the wxWidgets source
package edit the file src/mac/corefoundation/utilsexc_cf.cpp and
change line 34 to '#define USE_POLLING 1' (i.e. in both cases we
need to have USE_POLLING set to 1).

For both intel and powerpc the configure script for wxWidgets
should be invoked as follows:

    $ <wxwidgets-source-path>/configure \
        --prefix=<wxwidgets-install-path> \
        --enable-monolithic \
        --disable-shared \
        --disable-unicode \
        --with-opengl \
        --enable-geometry \
        --enable-display \
        --with-expat=builtin \
        --with-libpng=builtin \
        --with-libjpeg=builtin \
        --with-libtiff=builtin \
        --with-mac \
        --with-macosx-sdk=/Developer/SDKs/MacOSX10.4u.sdk \
        --with-macosx-version-min=10.4


Building the source package (Mac OS)
------------------------------------

As for Linux, but to your CMake invocation add the following flags:

    -DCMAKE_OSX_SYSROOT:STRING=/Developer/SDKs/MacOSX10.4u.sdk \
    -DCMAKE_CXX_FLAGS:STRING='-mmacosx-version-min=10.4' \
    -DCMAKE_C_FLAGS:STRING='-mmacosx-version-min=10.4' \


Installing the source package (Mac OS)
--------------------------------------

As for Linux. In order to create a binary distribution (image
file) for Mac OS, run the command:

    $ make bdist

which will generate the appropriate image file for the platform
(PowerPC or Intel) the compilation is being run on.


64-bit support
--------------

The BRAT applications have been successfully compiled and run on
64-bit Linux platforms, but 64-bit architectures are not
officially supported in this release and have not been
extensively tested. In particular, the compilation of the MATLAB
and IDL interfaces on 64-bit machines has not been attempted. We
welcome feedback from users concerning their experiences.


Documentation
-------------

The BRAT Source archive contains pre-built versions of the BRAT
user manual and the reference manual. The reference manual can be
regenerated by running the command:

    $ make refman

This requires additional software to be installed: the Doxygen
documentation generation system (http://www.doxygen.org/), the
GraphViz graph visualisation system (http://www.graphviz.org/),
and the LaTeX typesetting system (the TeXLive distribution from
http://www.tug.org/texlive/ works well).

These prerequisites are available for all platforms and can be
installed without special configurations.


Examples
--------

There are examples for the C and Fortran Library and the IDL and
MATLAB interfaces included with both the source and binary
packages of BRAT. For the source package they can be found both
in the unpacked source package in libbrathl/brathl_c,
libbrathl/fortran, libbrathl/brathl_idl, and
libbrathl/brat_matlab. Under the BRAT installation directory they
are in the top-level subdirectory examples/ (brat/examples on Mac
OS X).


Feedback
--------

If you encounter any problems while trying to build, install or
run one or more components of the BRAT package you can send an
e-mail to :

    helpdesk@altimetry.info

Apart from problems, we would also appreciate to hear from you if
you have any ideas, suggestions, or comments that may help us to
improve the quality or functionality of BRAT.



Using the Application Programming Interface (API)
================================================

The API is documented in the BRAT reference manual, available in
the doc/ subdirectory of your installation. A good source of
knowledge is also to look at how e.g. the Brat Console
Applications themselves are written (and compiled).


On Linux
--------

Compile your C++ source files with the "-I<BRAT installation
directory>/include" option where '<BRAT installation directory>'
is the CMAKE_INSTALL_PREFIX base directory where you installed
BRAT. Make sure to include an appropriate STL flag (such as
-DSTL_USING_ALL -- see the file include/Stl.h for more details).

Link your programs with the option "-L<BRAT installation
directory>/lib". Add a "-l<library>" for each needed BRAT library
(brathl, netcdf, udunits, or coda).


On Windows
----------

Compiling and linking under windows is a bit more complicated
because compilers and windows don't allow mixing objects and
libraries built different way.

In BRAT 2.0 the delivered libraries have been build with Visual
C++ 6.0 (for C and C++) on Windows, and g++ 4.x on Linux and Mac
OS..

Again, a good source of information is the BRAT source build
itself, and tracing the compiler and linking options generated by
nmake to build the BRAT components.

If you want to compile within the Visual Studio IDE you have to
set the appropriate options (look at VS user manual).
Specifically, you must invoke CMake with:

   -G "Visual Studio 6"

which will generate a BRAT.dsp project file you can open in the
IDE.


On Mac OS X
-----------

As for Linux, but may require the specification of some
Mac-specific compiler and linker options.