  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.12 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
$ make terralib_qhelp
$ make terralib_qtranslations

1.6 Installing:
$ make install

1.7 Uninstalling:
$ make uninstall


2. Building with CMake GUI on Windows using MSVC2013
--------------------------

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 for Visual Studio 2013, can be obtained from two places:
   b.1) The tagged version:  
     http://www.dpi.inpe.br/terralib5/terralib5-3rdparty/terralib5.0.1-3rdparty-msvc-2013-win64.zip
           or
     http://www.dpi.inpe.br/terralib5/terralib5-3rdparty/terralib5.0.1-3rdparty-msvc-2013-win32.zip
		   
   b.2) The most updated version used by developers (might not work with different tags): 
     http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-msvc-2013-win64.zip
           or
     http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-msvc-2013-win32.zip
   
are uncompressed at :
   
   C:\terralib\terralib5-3rdparty-msvc-2013-win64
   o
   C:\terralib\terralib5-3rdparty-msvc-2013-win32

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

d) Open CMake-GUI in order to generate a build project for Microsoft Visual C++ 2013 (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-win64
                                  or
                                  C:\terralib\build-win32

g) Then add an entry called CMAKE_PREFIX_PATH with the libraries location (separated by semicolons):

  * TerraLib 5 Third party => C:/terralib/terralib5-3rdparty-msvc-2013-win64
  * Qt CMake => look for the Qt dir containing ''Qt5Config.cmake''

Example for win64: Press ''AddEntry'' button and inform the name ''CMAKE_PREFIX_PATH'', type ''PATH'' and set its value as:   
   CMAKE_PREFIX_PATH => C:/terralib5-3rdparty-msvc-2013-win64;C:/Qt/Qt5.4.1/5.4/msvc2013_64/lib/cmake/Qt5
 
Example for win32: Press ''AddEntry'' button and inform the name ''CMAKE_PREFIX_PATH'', type ''PATH'' and set its value as:   
   CMAKE_PREFIX_PATH => C:/terralib5-3rdparty-msvc-2013-win32;C:/Qt/Qt5.4.1/5.4/msvc2013_opengl/lib/cmake/Qt5
 

h) Then press "''Configure''" and choose:
  * "''Visual Studio 12 x64''" (win64) or "''Visual Studio 12''" (win32) and 
  * if no problem occurs press "''Generate''". Otherwise update your environment variable "PATH" with the right location of Qt and third party library (see item "j").

Note: Some projects may be disabled through the following variables(in this case press again "Configure" and "Generate"):
        TERRALIB_BUILD_EXAMPLES_ENABLED => OFF
        TERRALIB_BUILD_UNITTEST_ENABLED => OFF

i) Open the generated ''terralib.sln'' solution at the folder ''C:\terralib\build-win64'' or ''C:\terralib\build-win32''. Then build the "''ALL_BUILD''" project to build all terralib projects, including terraview application. To build the help associated with TerraView application, it is necessary to build "''terralib_qhelp''" and "''terralib_qtranslations''".
   
j) To be able to debug, add to your environment variable "PATH" the following:
  For 64 bits: C:\terralib5-3rdparty-msvc-2013-win64\lib;C:\Qt\Qt5.4.1\5.4\msvc2013_64\bin

k) To run and debug TerraView application, set terraview module as StartUp Project at Microsoft Visual C++ 2013.

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

n) If you have any TerraView version installed, the environmental variable TERRALIB_HOME is defined. 
To work as a "developer" using Visual Studio to build, please remove this variable to avoid problems related with loading/unloading plugins,

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 will 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.
   
   Note: Some QT5 related variables may not be automatically set (they have "NOT-FOUND" values) and must be set manually.
	 Example: QT_QCOLLECTIONGENERATOR_EXECUTABLE (required by the help system) must point the refered executable.
         (i.e. "/usr/bin/qcollectiongenerator-qt5")

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 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.


  September 2015, TerraLib Team <terralib-team@dpi.inpe.br>
