Find file Copy path
805 lines (590 sloc) 28 KB
BRAT - Broadview Radar Altimetry Toolbox INSTALL
Full information on installing BRAT from a binary distribution
can be found in the BRAT User Manual available in the file
brat_user_manual.pdf in the 'doc' directory of the BRAT
distribution or installation.
The short version is as follows:
+ For Windows: double-click the installer file appropriate
for your platform (brat-4.2.1-Win32-installer.exe for 32-bit
operating systems, brat-4.2.1-x64-installer.exe for 64-bit
operating systems), and follow the instructions.
+ For Linux: double-click in your desktop manager (or execute
from the command-line) the installer file appropriate for your
platform. For 32 bit operating system execute the file If necessary, use the command
'chmod +x <installer-filename>'
to ensure the installer is executable.)
Taking debian 8 as the BRAT version of reference for the Linux platform,
the following additional dependencies are required for BRAT to run:
These dependencies are provided with the operating system but not
necessarily installed by default. Other dependencies may be necessary
for the packages that must be build, and not simply insalled, as
explained below.
Linux users can find more details and a precise installation procedure
targeting Debian 8 in the document SampleBuild.pdf, in the doc folder
of BRAT source package.
+ For Mac OS X: double-click the image file appropriate for the
type of application you want to install: brat-4.2.1-macosx-i386.dmg
for 32 bit BRAT applications, or brat-4.2.1-macosx-x86_64.dmg for
64 bit BRAT applications (Intel only). Then, drag the '' and
'' bundles to the 'Applications' folder on your machine.
For a full installation, documentation included, copy the mounted
image folder to the 'Applications' folder; this is the recommended
way if you plan to use several BRAT versions on the same machine.
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).
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.
Depending on the software you have installed on your machine,
it may be necessary to install additional packages, provided by
your operating system but that it does not install by default.
CMake, which orchestrates the BRAT builds, can help in pointing
the missing software. Besides these operating system dependencies,
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, BRAT was developed with GNU g++
(version 4.7.x or higher), for Windows with Visual Studio
C++ 2015, for Mac OS X with GNU g++ 4.2 (BRAT 3.2.0, 32 bit) and
clang 6.x (BRAT 4.2.1, 32 bit and 64 bit). In Mac OS X you should
make sure you have installed the Developer Tools. Both 32 bit and
64 bit builds use SDK 10.8 and libc++.
+ CMake v3.1.0
CMake is a multi-platform makefile generator.
+ Perl v5.8.x (or higher)
Perl is a multi-platform scripting language. On Windows, the
ActiveState Perl (
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
+ Qt v5.7.0
Qt is an applications development framework, including GUI and tools.
+ QGIS v2.16.1
QGIS is a Geographic Information System application and library.
+ OSG v3.4.0
OSG (OpenSceneGraph) is an high performance 3D graphics toolkit.
+ osgEarth v2.7
osgEarth is a Geospatial SDK for OpenSceneGraph.
+ Qwt v5.2.3
Qwt is a graphics extension to Qt providing 2D plotting.
+ QwtPlot3D v0.2.7
QwtPlot3D is a Qt/OpenGL-based programming library providing 3D plotting.
+ CodeSynthesis XSD v4.0
CodeSynthesis XSD is a cross-platform W3C XML Schema to C++ data binding compiler.
+ QCA v2.1.0
QCA stands for Qt Cryptographic Architecture.
+ GEOS v3.4.2
GEOS (Geometry Engine - Open Source) is a C++ port of the Java Topology Suite.
+ Python v3.2
Python programming language platform and libraries.
+ BitRock InstallBuilder v15.1.0
InstallBuilder is a commercial product; a license is needed.
(Licenses for GPL applications are available from BitRock at no
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.)
IDL MATLAB and Fortran are optional dependencies:
+ Fortran compiler
A Fortran compiler is needed to build the Fortran interface to
+ IDL V6.3 (or higher)
With IDL installed you will be able to build the CODA and BRATHL
IDL interfaces.
+ Matlab V8.1/R2013a (or higher)
With MATLAB installed you will be able to build the CODA and
BRATHL MATLAB interfaces.
The prerequisite software packages may themselves have dependencies
that may or may not already be present on your system. This INSTALL
file only covers BRAT-specific compilation details, and assumes
all sub-dependencies are covered.
On the other hand, different operating system versions often require
adjustments of compilation settings, even within the same platform family.
BRAT v4.2.1 elected some versions as target for each supported platform
and architecture, versions where the software is known to build and run
according to the requirements and the documented procedures, and that
can be taken as reference for adjusting the build settings to different
environments. BRAT v4.2.1 reference operating system versions are the
- Linux platform: debian 8, 32 and 64 bit versions;
- Windows platform: Windows 7 Professional, 32 and 64 bit versions;
- Mac OS X platform - version 10.10.5 (Yosemite).
Building the source package (Linux)
The build instructions in this document have necessarily a
certain degree of incompleteness, given the great diversity not
only of Linux distributions but also of the possibly different
configurations or updates in each concrete system. For a precise
installation procedure, targeting the reference OS version for
Linux (Debian 8), please see instead the document SampleBuild.pdf,
in the doc folder of BRAT source package.
The following steps will guide you through the process of
building the BRAT libraries and executables (including CODA,
HDF5, NetCDF and the C, IDL, MATLAB and Python interfaces) on
a Linux-based platform:
+ Download brat-x.y.z.tar.gz, where x.y.z is the appropriate
version number, and unpack it to a directory of
your choice:
$ gzip -d brat-x.y.z.tar.gz
$ tar xf brat-x.y.z.tar
+ 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. Invoke cmake as in this example, replacing the
appropriate values as explained in the rest of this section:
$ cmake \
-DEXTERNAL_DATA_DIR=$S3ALTB_ROOT/project/user-data \
-DCMAKE_CXX_FLAGS:STRING="$cxx_arch_flags" \
-DCMAKE_C_FLAGS:STRING="$arch_flags" \
-DINSTALL_BUILDER_DIR:PATH=$S3ALTB_ROOT/compilers/installbuilder-15.1.0/bin \
<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.
There are several options and environment settings
you pass to cmake in the form of -D<option>=<value>
Most of these options, as can easily be recognized by their
names, consist in header and library directories of the pre-
installed BRAT dependencies listed above. Other kind of
options have different meanings.
replace $ARCHITECTURE by i386 for 32 bit builds and
by x86_64 for 64 bit builds.
-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.
Replace $CONFIGURATION by Debug or Release. 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.
Use this option to enable building BRAT and SCHEDULER.
Don't run tests for any of the enclosed modules, such as
3rd party libraries built in integration with BRAT, like
Replace "$arch_flags" by "-m32 -std=c++11" for 32 bit builds and
by "-m64 -std=c++11" for 64 bit builds.
-DINSTALL_BUILDER_DIR=<InstallBuilder executable directory>
Only required if you intend to build a binary installer.
This will tell CMake where the InstallBuilder executable is
This set of options is relted with HDF5 (the first two) and
NetCDF (the remaining two). If you enable DAP, the curl
library must be installed on your system, except in Windows,
where it is not provided by the operating system and so BRAT
itself provides it.
The following additional options were inherited from
BRAT 3.1.0 and, with the exception of MATLAB support for 64
bit, so far they are supported only to the extent where they
are compatible without changes with BRAT 4.2.1.
Build the Fortran example program. An installed Fortran
compiler is required (and should automatically be detected
by CMake).
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 '/').
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 for the architecture you are targetting in your
build (32 bit or 64 bit).
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").
+ 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/brat, please 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
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
Building the source package (Windows)
As CMake is a cross-platform tool, building BRAT on Windows is
similar to building it on Linux. Except in the cases explicitly
detailed in this section, which are Windows specific, you can
refer to the section about building BRAT in Linux for an
explanation of the meaning of the remaining options.
As in the Linux case, most of the build options consist in header
and library directories of the pre-installed BRAT dependencies
listed above, as suggested by their names.
Create a build directory and cd into it from a Visual Studio
2015 console, like you have done when building VTK for Windows.
Then invoke CMake as in the following example, making the
appropriate replacements as explained in the rest of the section:
cmake -G "NMake Makefiles" \
-DEXTERNAL_DATA_DIR=%S3ALTB_ROOT%/project/user-data \
-DQGIS_CORE_LIBRARY=%QGIS_DIR%/lib/qgis_core.lib \
-DQGIS_GUI_LIBRARY=%QGIS_DIR%/lib/qgis_gui.lib \
-DQGIS_ANALYSIS_LIBRARY=%QGIS_DIR%/lib/qgis_analysis.lib \
-DXercesC_INCLUDE_DIR=%XERCES_DIR%/include \
-DQWT_LIBRARY=%QWT_DIR%/lib/qwt%DBG_SUF%5.lib \
-DQWTPLOT3D_INCLUDE_DIR=%QWT3D_DIR%/source/include \
-DGEOS_LIBRARY=%OSGEO4W_DIR%/lib/geos_c.lib \
<path to brat-x.y.z unpacked source directory>
Replace %ARCHITECTURE% in the example by Win32 (for 32 bit
builds) or by x64 (for 64 bit builds). When building for the 64
bit architecture add also -DTARGET_CPU=amd64 to the list of
options shown in the example.
-DCMAKE_INSTALL_PREFIX=<BRAT installation directory>
For the meaning of these options refer to the section
about building BRAT in Linux.
-DINSTALL_BUILDER_DIR=<InstallBuilder executable directory>
For the meaning of these options refer to section
about building BRAT in Linux.
Replace %MATLAB_OPTIONS%, in the example, by the variables
described in the Linux section about building the MATLAB
interface. Additionally, use the -DMEXEXT:STRING=mexw64
option when building a 64 bit interface or
-DMEXEXT:STRING=mexw32 when building a 32 bit interface.
Replace %HDF5_OPTIONS% and %NETCDF_OPTIONS% in the example
by the variables and values described in the Linux section
that are related with the HDF5 and NetCDF options, respectively.
If want curl to be built without OpenSSL support, add the option
+ Instead of 'make', the Visual C++ build utility 'nmake' is
necessary. So the build and installation commands become
'nmake' and 'nmake install' respectively.
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 go to 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 source package (Mac OS)
BRAT dependencies, namely QGIS, require some libraries to be installed
in the system's /usr/local/lib directory. These libraries, distributed
with the binary installers, are the following:
The minimum Mac OS X version where BRAT can be built is 10.8, but
note that these binaries, as distributed with the BRAT installers,
were built as a convenience for installation in the BRAT's target
system Yosemite. Some of the respective libraries may require
specific compilation for previous versions.
For the build process, take Linux section as reference, with the
following differences:
1. Replace "$arch_flags" in the Linux example by
"-mmacosx-version-min=10.8 -fvisibility=hidden -Wno-deprecated -isysroot /SDKs/MacOSX$MACOSX_SDK.sdk std=$STANDARD -stdlib=libc++"
adding, for 32 bit builds, "-arch i386" and for 64 bit builds "-arch x86_64"
2. Add the options
replacing /SDKs/MacOSX10.7.sdk by the location of your
Mac OS X 10.8 SDK if installed elsewhere.
3. Remove the option for the BitRock InstallBuilder. The Mac OS X
build with CMake creates specific platform installer files with
the dmg extension.
Installing the source package (Mac OS)
As for Linux. In order to create a binary distribution (image
file) for Mac OS X, run the command:
$ make bdist
which will generate the appropriate image file for the platform
(32 bit or 64 bit) the compilation was configured to target.
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 (, the
GraphViz graph visualization system (,
and the LaTeX typesetting system (the TeXLive distribution from works well).
These prerequisites are available for all platforms and can be
installed without special configurations.
There are examples for the C, Fortran, Python, 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_python, 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).
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 :
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).
For BRAT the delivered libraries have been build with Visual C++
13.0 on Windows, g++ 4.7.x on Linux and clang 6.x on Mac OS X.
If necessary, suplement the instructions given below taking
as reference the appropriate flags and options used to build BRAT.
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
Link your programs with the option "-L<BRAT installation
directory>/lib". Add a "-l<library>" for each needed BRAT library
(for instance, brathl, netcdf, hdf5, 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.
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 14 2015" (32 bit builds)
-G "Visual Studio 14 2015 Win64" (64 bit builds)
which will generate a BRAT.sln project file you can open in the
On Mac OS X
As for Linux, but may require the specification of some
Mac-specific compiler and linker options. Again, take as
reference the flags used when building BRAT itself for
Mac OS X.