  TerraLib Build Instructions
  ===========================


The build/cmake folder contains a CMake project for building TerraLib.

Until now its build has been tested on Linux Ubuntu 12.04, Mac OS X Mavericks and Microsoft Windows 7.

Future releases will be tested on Mac OS X Snow Leopard, Microsoft Windows 8 and others Linux flavours.

You should use at least CMake version 2.8.7 for building TerraLib. Older versions than this may not work properly.

Make sure you have all the third-party library dependencies listed in the DEPENDENCIES file on the root of the codebase.

Follow the build steps below according to your platform.


1. Build instructions on Linux with g++ (GNU gcc)
-------------------------------------------------

1.1. Open a Command Prompt (Shell).

1.2. We will assume that the codebase (all the source tree) is located at:
/home/user/terralib/codebase

1.3. Create a folder out of the terralib source tree, for example:
$ cd /home/user/terralib
$ mkdir build-linux
$ cd build-linux

1.4. For Linux systems you must choose the build configuration:
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_INSTALL_PREFIX:PATH="/usr/local/terralib" ../codebase/build/cmake

Notes:

       a) Some Linux flavours with different versions of GNU gcc and Boost will need more parameters such as:
          -DCMAKE_PREFIX_PATH:PATH="/usr/local;/opt/include"
          -DCMAKE_INCLUDE_PATH:PATH="/usr/local;/opt/include"
          -DCMAKE_LIBRARY_PATH:PATH="/usr/local;/opt/lib"
          -DCMAKE_PROGRAM_PATH:PATH="/usr/local/bin;/opt/bin"
          -DBOOST_ROOT:PATH="/opt/boost"

       b) Boost can also be indicated by BOOST_INCLUDEDIR (note: without an '_' separating INCLUDE and DIR):
          -DBOOST_INCLUDEDIR:PATH="/usr/local/include"

       c) The parameter -lpthread must be informed only if your Boost was not built as a shared library:
          -DCMAKE_CXX_FLAGS:STRING="-lpthread"

       d) For building with Qt5 you can provide the Qt5_DIR variable as:
          -DQt5_DIR:PATH="/usr/local/lib/cmake/Qt5"

       e) For generating a debug version set CMAKE_BUILD_TYPE as:
          -DCMAKE_BUILD_TYPE:STRING="Debug"

1.5 Building:
$ make -j 4

1.6 Installing:
$ make install


2. Building with CMake GUI
--------------------------

2.1 On Windows:

a) We will assume that the TerraLib source tree (git clone) is located at:
   C:\terralib\codebase

b) We will assume that the third party libraries, obtained from
   http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-win32-Qt5.zip
   or
   http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-win64-Qt5.zip
   are located at:
   C:\terralib\3rdparty-win32-qt5
   or
   C:\terralib\3rdparty-win64-qt5

c) Create a folder out of the TerraLib source tree to build the binaries, for example:
   C:\terralib\build-win32
   or
   C:\terralib\build-win64

d) Open CMake-GUI in order to generate a build project for Microsoft Visual C++ 2010 (32-bit or 64-bit).

f) Then assure that the following variables are set to the locations defined above:
   - Where is the source code => C:\terralib\codebase\build\cmake
   - Where to build the binaries => C:\terralib\build-win32
                                    or
                                    C:\terralib\build-win64

g) Then add an entry called CMAKE_PREFIX_PATH with the libraries location (separated by semicolons):
   - Microsoft SDK;
   - TerraLib 5 Third party path;
   - Qt CMake.

   Example: Press AddEntry button and inform the name CMAKE_PREFIX_PATH, type PATH and set its value as:
   CMAKE_PREFIX_PATH => C:/Program Files (x86)/Microsoft SDKs/Windows/v7.0A;C:/terralib/3rdparty-win32-qt5;C:/Qt/Qt5.3.0/5.3/msvc2010_opengl/lib/cmake/Qt5

h) Then press "Configure" and if no problem occurs press "Generate".
 
Note: Some projects may be disabled through the following variables:
        TERRALIB_BUILD_EXAMPLES_ENABLED => OFF
        TERRALIB_BUILD_UNITTEST_ENABLED => OFF

i) Open the generated terralib.sln solution at the folder C:\terralib\build-win32.
   Then build the "ALL_BUILD" project to build all terralib projects, including terraview application.
   
j) To run and debug TerraView application, set it as StartUp Project at Microsoft Visual C++ 2010.

k) To run and debug terralib_example_* and/or terralib_unittest_* set it as StartUp Project and make sure the data (http://www.dpi.inpe.br/terralib5-devel/data.zip) used are located at the default directory:
   TERRALIB_DATA_DIR   C:\terralib\build-win32\data
   
l) Make sure the default directory used to save the reports generated by the terralib_unittest_* exist, otherwise no report will be saved:
   TERRALIB_REPORT_DIR   C:\terralib\build-win32\report


2.2 On MacOs and Linux:

a) We will assume that the TerraLib source tree (git clone) is located at:
   /home/user/terralib5

b) We wiil assume that the build tree where will be generated the binaries is located at:
   /home/user/build_terralib5

c) We will assume that all the third-party libraries that TerraLib needs to be compiled
   are installed in your system, and the Qt5 version is used.

d) Open CMake-GUI in order to generate a build project for MacOS or Linux:

e) Then assure that the following variables are set to the locations defined above:
   - Where is the source code => /home/user/terralib5
   - Where to build the binaries => /home/user/build_terralib5

f) Then press the Add Entry button containing the following CMake variables:
   
   f.1) Name: CMAKE_PREFIX_PATH
        Type: PATH
        Value: /qt5_install_dir/lib/cmake/Qt5
 
   f.2) Name: CMAKE_BUILD_TYPE
        Type: String
        Value: Release(or Debug)
 
g) Then press "Configure" button. If it is the first time that you press this button, select
   the Generator to be used (Makefile or a selected IDE like Eclipse for Linux, or XCode for MacOS)
 
Note: Some projects may be disabled through the following variables:
        TERRALIB_BUILD_EXAMPLES_ENABLED => OFF
        TERRALIB_BUILD_UNITTEST_ENABLED => OFF

h) According to the generator selected previously, in the build tree directory(/home/user/build_terralib5) will be generated a Makefile or the file corresponding to the IDE selected.

i) TerraLib/TerraView can be compiled calling make for the Makefile Generator, Eclipse (for Linux) or XCode (for MacOS).
   
j) To run and debug terralib_example_* and/or terralib_unittest_* make it the current project and make sure the data (http://www.dpi.inpe.br/terralib5-devel/data.zip) used are located at the build directory:
   TERRALIB_DATA_DIR   /home/user/build_terralib5/data
   
k) Make sure the default directory used to save the reports generated by the terralib_unittest_* exists, otherwise no report
   will be saved:
   TERRALIB_REPORT_DIR   /home/user/build_terralib5/report

For more information on TerraLib, please, visit its main web page at: http://www.terralib.org.


  August 2014, TerraLib Team <terralib-team@dpi.inpe.br>
