  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 and Microsoft Windows 10.

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.1.0-3rdparty-msvc-2013-win64.zip
 
		   
   b.2) The most updated version used by developers (might not work with different tags): 
     http://www.dpi.inpe.br/terralib5-devel/3rdparty-bin/terralib5-3rdparty-msvc-2013-win64.zip
   
are uncompressed at :
   
   C:\terralib\terralib5-3rdparty-msvc-2013-win64

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

d) Open CMake-GUI in order to generate a build project for Microsoft Visual C++ 2013 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
 

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''
  * Terralib4 Cmake => look for the dir containing terralib4Config.cmake under TerraLib 5 Third party dir

Example for win64: Press ''AddEntry'' button and inform the name ''CMAKE_PREFIX_PATH'', type ''PATH'' and set its value as:   
   CMAKE_PREFIX_PATH => C:/terralib/terralib5-3rdparty-msvc-2013-win64;C:/terralib/terralib5-3rdparty-msvc-2013-win64/lib/cmake/terralib-4.2.2;C:/Qt/Qt5.4.1/5.4/msvc2013_64/lib/cmake/Qt5
 
h) Then press "''Configure''" and choose:
  * "''Visual Studio 12 x64''" (win64) and 
  * if no problem occurs: 
  
   Set the following variables:
     CPACK => See the CPACK entries and keep ON just the NSIS package generator (used in release). All other kind of packages must be disabled.
     TERRALIB_BUILD_AS_BUNDLE => ON
	 TERRALIB_TRACK_3RDPARTY_DEPENDENCIES => ON
     TERRALIB_QHELP_ENABLED => ON

   Some project may be disabled through the following variables:
     TERRALIB_DOXYGEN_ENABLED => OFF  => if you want to distribute the API documentation this should be turn to on. But keep in mind that this option may take a considerable time, so you should do this only for final tests.
     TERRALIB_BUILD_EXAMPLES_ENABLED => OFF
     TERRALIB_BUILD_UNITTEST_ENABLED => OFF
	   
   Press ''Configure'' and ''Generate'' again.
   
  * Otherwise update your environment variable "PATH" with the right location of Qt and third party library (see item "j").
   
i) Open the generated ''terralib.sln'' solution at the folder ''C:\terralib\build-win64''. 
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 
to have the translations available it is necessary to build "''terralib_qtranslations''".
   
j) To be able to ''debug'', set the debbuging environment with:
 Terraview Properties -> Configuration Properties -> Debugging -> Environment with:
PATH=C:\terralib\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) If you already have the same TerraView version installed, the environmental variable TERRALIB_HOME is defined, 
and there are two other files (TerraView-5.x.x.ini and datasources.xml) associated with the installed version (5.x.x): 
located at C:/Users/<username>/AppData/Roaming/INPE/TerraView-5.2.1.ini
           C:/Users/<username>/AppData/Local/INPE/TerraView-5.2.1/datasources.xml 
		   
To work as a "developer" using Visual Studio to build, please remove TERRALIB_HOME variable to avoid problems 
related with loading/unloading plugins.
Also, it is recommended to remove the two files mentioned and uninstall TerraView, before start TerraView under Visual Studio (debug or release).

m) To Start the ''release'' version under Visual Studio, set the Terraview Properties -> Configuration Properties -> Debugging -> Environment with:
PATH=C:\terralib\terralib5-3rdparty-msvc-2013-win64\lib;C:\Qt\Qt5.4.1\5.4\msvc2013_64\bin

n) 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-win64\data
   
o) 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-win64\report

p) If you are not getting the most updated Help files, remove the C:\Users\username\AppData\Local\QtProject\Assistant\help.qhc

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


  February 2016, TerraLib Team <terralib-team@dpi.inpe.br>
