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


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

Until now its build has been tested on Linux Ubuntu 18.04, Mac OS X Sierra 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 3.18 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.


IMPORTANT NOTE FROM VERSION 5.2.x (ALL PLATFORMS)
-------------------------------------------------
From versions 5.2.x the Internationalization process is done by 'Boost' instead of 'getText' directly.
Boost needs 4 executables (msgexec, msgmerge,msgfmt,xgettext) that are NOT available in terralib-3rdparty,
but you can download it from the following link for Windows OS. For LINUX/MAC, install the correspondent package.

http://www.dpi.inpe.br/terralib5-devel/3rdparty/bin/5.2/gettext0.19.8.1-iconv1.14-static-64.zip

After downloading it, unpack the zip file and add its location to CMAKE_PREFIX_PATH
Check the CMAKE variables to make sure all exec will be found:

GETTEXT (MSGFMT, MSGINIT, MSGMERGE) and
XGETTEXT_EXECUTABLE. 

Also make sure that the variable TERRALIB_TRANSLATOR_ENABLED is checked.
-----------------------------------------------------------------------


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

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

b) We will assume that the third party libraries for Visual Studio 2017, can be obtained from 3 places:
   b.1) Choose one of the files terralibx.y.z-3rdparty-msvc-2017-win64.zip where x.y.z specify the tag  
     http://www.dpi.inpe.br/terralib5/terralib5-3rdparty/
	 		   
   b.2) The 3rdparty used by developers of terralib team to work with 'develop' branch : 
     http://www.dpi.inpe.br/terralib5-devel/3rdparty/bin/terralib5-3rdparty-msvc-2017-win64.zip
	 (might not work with different tags)
	 
   b.3) The 3rdparty used by developers to correct bugs in a specific branch ('release-5.y'): 
     http://www.dpi.inpe.br/terralib5-devel/3rdparty/bin
	 choose one of the directories aligned with the release-5.y branch
	     5.5/terralib5-3rdparty-msvc-2017-win64.zip  - branch 'release-5.5'
		 5.6/terralib5-3rdparty-msvc-2017-win64.zip  - branch 'release-5.6'
		 
  NOTE: The zip file downloaded from (b.2) or (b.3) might do not work with tagged version.

   
b.1) We will assume that the 3rdparty are uncompressed at :
   
   C:\terralib\terralib5-3rdparty-msvc-2017-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++ 2017 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-2017-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-2017-win64;C:/terralib/terralib5-3rdparty-msvc-2017-win64/lib/cmake/terralib-4.2.2;C:/Qt/Qt5.12.3/5.12/msvc2017_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-2017-win64\lib;C:\Qt\Qt5.12.3\5.12\msvc2017_64\bin

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

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.y.z.ini and datasources.xml) associated with the installed version (5.y.z): 
located at C:/Users/<username>/AppData/Roaming/INPE/TerraView-5.y.z.ini
           C:/Users/<username>/AppData/Local/INPE/TerraView-5.y.z/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.

m) To Start the ''release'' version under Visual Studio, set the Terraview Properties -> Configuration Properties -> Debugging -> Environment with:
PATH=C:\terralib\terralib5-3rdparty-msvc-2017-win64\lib;C:\Qt\Qt5.12.3\5.12\msvc2017_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.


  Nov 2020, TerraLib Team <terralib-team@dpi.inpe.br>
