6- How to install BRAT ====================== BRAT binaries are available for Windows 2000/XP and Linux (Redhat EL 4). The software is delivered two way: a single binary installation package file (for windows or for linux), and a source package. The names of the installation packages have the format: brat-VERSION-PLATFORM-installer.extension, where VERSION is the version of brat, PLATFORM is the destination platform (windows or linux) and extension is a more or less platform specific extension (exe for windows, bin for linux). The name of the source package has the format: brat-VERSION.tar.gz, with the same convention as above. 6.1- Windows binaries --------------------- Double-click on the installation package or installation program and follow the installer instructions. By default, the software will be put in C:\Program Files\brat-VERSION\ if you have write access to this directory or in your user profile (normally C:\Documents and settings\ACCOUNT\brat-VERSION). You can choose another directory, if you wish to. 6.2- Linux binaries ------------------- Execute the installation package or installation program from your file navigator or a console window and follow the installer instructions. If you have got the installation package by a network it may not be set as executable so you can issue the command "chmod +x brat-VERSION-linux-installer.bin" in order to make it runable. By default, the software will be put in /usr/local if you have root permissions or in $HOME/brat-VERSION. You can choose another directory, if you wish to. 6.3- From source ---------------- If you want or need to rebuild BRAT, you may install only the source files. Get the source package and expand it where you prefer. - Windows: use winzip/winrar or a similar tool able to expand gzipped tar file. - Unices: gunzip -c brat-VERSION.tar.gz | tar xvf - It will expand in a directory named brat-VERSION Then have a look at this directory and read the files README (this file) and INSTALL. The last one gives you information about the dependencies (what must be installed before) and the specific options which may be used. If you have got the package from a delivered DVD, you may find more informations in the README.txt file of the 'source' directory (which is the INSTALL file in the top directory of the source installation package). NOTE: All README.txt files in the DVD have DOS/Windows convention for end of lines ( followed by character) while all text files in the expanded source tree have unix convention ( character). 7- How to uninstall BRAT ======================== While BRAT is installed the whole installation process is registered and everything created can be removed (not what may be created after that). 7.1- When installed from Windows binaries ----------------------------------------- Like any other windows program, go to the control panel the click on "Add/Remove programs" and select the Brat entry. Everything created during installation will be removed. Note that a shortcut is also in the installation directory which you can click to do the same thing. 7.2- When installed from Linux binaries --------------------------------------- In the installation directory (the default one or the one chosen), there is a script called uninstall-brat-VERSION-linux which can be executed to remove everything created during installation. There is also a shortcut, called "Uninstall Basic Radar Altimetry Toolbox.desktop", which can be used from within your desktop manager (KDE, GNOME) and do the same thing. 7.3- When installed from source ------------------------------- If you have built BRAT from source, you may have to remove everything by hand. The directory containing the source files may be removed entirely 8- Description of some files ============================ 8.1- Executable files (commands) -------------------------------- Windows: BratGui.exe Linux: BratGui ==> BRAT Graphical User Interface (GUI) Windows: BratDisplay.exe Linux: BratDisplay ==> BRAT Visualisation Interface (GUI) Windows: BratCreateYFX.exe Linux: BratCreateYFX ==> BRAT Data Export to NetCDF Tools for an 'Y=f(X)' (curve) Windows: BratCreateZFXY.exe Linux: BratCreateZFXY ==> BRAT Data Export to NetCDF Tools for a 'Z=f(X,Y)' Windows: BratExportAscii.exe Linux: BratExportAscii==> BRAT Data Export to Ascii Tools (Dump Tools) For a quick help about how use these files in command line, type 'executable_name' --help. You can also refer to the BRAT user's manual. 8.2- Libraries -------------- When you have chosen the "Development files" option (unchecked by default), 2 more directories are installed: 'include' and 'lib'. They give the necessary files to use the C/C++ API. The 'lib' directory also contains (.a files are for linux, .lib for windows): libbrathl.a brathl.lib: library which contains all routines made available by .h files. libbrat.a brat.lib: low level file access library used by brathl. libnetcdf.a netcdf.lib: library used by brathl to access netcdf files. libudunits.a udunits.lib: used by brathl to handle formal units (as text strings) and compute conversions. IMPORTANT: These are libraries provided by BRAT but there might be some missing ones, like HDF4, for example. See the prerequisites of the source distribution for more details. NOTE: For MS-Windows, there is a subdirectory 'release' under the 'lib' directory. This is used to indicate that these libraries have been compiled in 'release mode' and not in 'debug mode': compilers and windows don't allow mixing objects compiled both modes. If you want the debug mode libraries install brat from source. For others systems (like Linux) this does not matter. 9- Linking with and using the Application Programming Interface (API) ===================================================================== 9.1- Linux ---------- Compile your source files with the "-Iinstalldir/include" option where 'installdir' is the base directory where you installed BRAT. If you did install BRAT with root privileges this option can normally be avoided since the compiler already knows it have to check this directory. Link your programs with the option "-Linstalldir/lib" option where 'installdir' is the base directory where you installed BRAT. If you did install BRAT with root privileges this option can normally be avoided since the compiler already knows it have to check this directory. Then add a "-llibrary" for each needed library where 'library' is the name of the library file without 'lib' and '-a'. So, normally, compiling and linking a new program written as a single source file can look like with gcc (command lines are cut for readability but it must reside on the same line): Compiling the source file: c++ -O3 -DNDEBUG -I/installation/directory/include -DSTL_USING_ALL -Wall -Werror -Werror -o BratCreateYFX.o -c BratCreateYFX.cpp Linking the program: c++ -O3 -DNDEBUG -fPIC BratCreateYXF.o -o BratCreateYFX -L/installation/directory/lib -lbrathlProcessUtilities -lbrathl -lbrat -ldf -lmfhdf -lz -ljpeg -lnetcdf -ludunits -lm 9.2- 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 (see note above). At the date of June 2007 (it may change), the delivered libraries have been build with Visual C++ 6.0 (for C and C++) and Compaq Visual Fortran 6.1 (for fortran) with multithreaded mode. Here are the options used when compiling a program (BratCreateYFX, for example) with nmake makefiles generated with cmake (command lines are cut for readability but it must reside on the same line). If you want to compile within the Visual Studio IDE you have to set the appropriate options (look at VS user manual). If you compile with something else (like mingw) you have to use the equivalent options (or recompile all from source since we do not garantee it works with other compilers). Compiling the source file: CL.exe /nologo /DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR /MD /O2 /Ob2 /D NDEBUG -IC:\installation\directory\include -DSTL_USING_ALL /TP /FoBratCreateYFX.obj /FdBratCreateYFX.pdb -c BratCreateYFX.cpp Linking the program: CL.exe /nologo /DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR /MD /O2 /Ob2 /D NDEBUG BratCreateYFX.obj /FeBratCreateYFX.exe /FdBratCreateYFX.pdb -link /version:0.0 /STACK:10000000 /machine:I386 /INCREMENTAL:NO /subsystem:console -LIBPATH:c:\installation\directory\lib\Release -LIBPATH:C:\HDF42r1\release\lib -LIBPATH:C:\zlib123\release\lib -LIBPATH:C:\jpeg-6b\Release\lib brathlProcessUtilities.lib brathl.lib brat.lib ws2_32.lib hd421m.lib hm421m.lib zlib.lib libjpeg.lib netcdf.lib udunits.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib 10- Further information ======================= For software updgrades, documentation updates and the on line tutorial, including use cases go to http://earth.esa.int/brat or http://www.altimetry.info BRAT has been developed under contract with ESA and CNES.