TerraLib and TerraView Wiki Page

TerraLib 5.0 - General guide for Building and Install

Building Terralib

This section explains how to build the TerraLib from source code in some platforms. The most updated instructions are in BUILD-INSTRUCTIONS file located at the root of the terralib codebase directory. Here are the general instructions and might not have all variables needed for a specific release.

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  => C:/Program Files (x86)/Microsoft SDKs/Windows/v7.0A
 TerraLib 5 Third party => C:/terralib/3rdparty-win32-qt5
 Qt CMake => C:/Qt/Qt5.3.0/5.3/msvc2010_opengl/lib/cmake/Qt5
 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 examples and/or unittests 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 unittests 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 wil 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:

 
 Name: CMAKE_PREFIX_PATH
 Type: PATH
 Value: /qt5_install_dir/lib/cmake/Qt5          and 
 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.

CMake command line notes

Using the CMake command line to build the compilation projects.

If you do not have or do not wish to use the CMake-Gui, it is possible to run CMake via command line. Here is some information on how to do it:

First, a quick warning, by default the building directory will be the same directory you invoked the CMake command from. It is advisable to avoid in-source compilations, so you should manually create a building directory and invoke CMake from it, or invoke the CMake command referring a path to an existing build.

From the command line, invoke the CMake command setting the options as you see fit. This is done with using the syntax: -DVARIABLE:TYPE=VALUE. The table bellow exemplifies some variables that can be set in cmake command line.

VariableEffectExample
CMAKE_BUILD_TYPE Sets the build type. Such as Debug or Release -DCMAKE_BUILD_TYPE=Debug
QWT_INCLUDE_DIR Sets the include path of the QWT library -DQWT_INCLUDE_DIR=<DIRECTORY>
QWT_LIBRARY_DEBUG Sets the path of the QWT library in Debug -DQWT_LIBRARY_DEBUG=<LIBRARY_FILE_PATH>
QWT_LIBRARY_RELEASE Sets the path of the QWT library in Release -DQWT_LIBRARY_RELEASE=<LIBRARY_FILE_PATH>
LOG4CXX_INCLUDE_DIR Log4Cxx headers include path -DLOG4CXX_INCLUDE_DIR=<DIRECTORY>
LOG4CXX_LIBRARY_DEBUG Log4Cxx debug library file path -DLOG4CXX_LIBRARY_DEBUG=<LIBRARY_FILE_PATH>
LOG4CXX_LIBRARY_RELEASE Log4Cxx release library file path -DLOG4CXX_LIBRARY_RELEASE=<LIBRARY_FILE_PATH>
BOOST_INCLUDEDIR Boost headers include path -DBOOST_INCLUDEDIR=<DIRECTORY>
GDAL_INCLUDE_GCORE GDAL headers include path -DGDAL_INCLUDE_GCORE=<DIRECTORY>
GDAL_INCLUDE_ALG GDAL headers include path -DGDAL_INCLUDE_ALG=<DIRECTORY>
GDAL_INCLUDE_OGR GDAL headers include path -DGDAL_INCLUDE_OGR=<DIRECTORY>
GDAL_INCLUDE_PORT GDAL headers include path -DGDAL_INCLUDE_PORT=<DIRECTORY>
GDAL_LIBRARY_DEBUG GDAL debug library file path -DGDAL_LIBRARY_DEBUG=<LIBRARY_FILE_PATH>
GDAL_LIBRARY_DEBUG GDAL release library file path -DGDAL_LIBRARY_DEBUG=<LIBRARY_FILE_PATH>
GEOS_INCLUDE_DIR GEOS headers include path -DGEOS_INCLUDE_DIR=<DIRECTORY>
GEOS_LIBRARY_DEBUG GEOS debug library file path -DGEOS_LIBRARY_DEBUG=<LIBRARY_FILE_PATH>
GEOS_LIBRARY_RELEASE GEOS release library file path -DGEOS_LIBRARY_RELEASE=<LIBRARY_FILE_PATH>

When using cmake from the command line you should specifiy the generator as follows:

-G <generator-name>

Some commonly used generators are:

NamePlatformExample
Visual Studio 10 Generates Visual Studio 10 project -G “Visual Studio 10”
Unix Makefiles Generates standard UNIX makefiles -G “Unix Makefiles”
Apple XCode Generates XCode project -G Xcode

A few examples of how to call CMake to build terralib:

  • Calling from a building dir while pointing to the source (main CmakeLists location), specifying Unix Makefiles as a generator, compiling in Release
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH="/usr/local/terralib" ../codebase/build/
  • Specifying Visual Studio 10 as the generator, using source code located at C:\Dev\Terralib\build and setting the option to generate a NSIS installer as true:
$ cmake -G 'Visual Studio 10' C:\Dev\Terralib\build -DTE_DEPENDENCIES_DIR=C:/Libs/terralib_3rdparty_win32 -DCPACK_BINARY_NSIS=True
  • Calling from a building dir while pointing to the source (main CmakeLists location), specifying Unix Makefiles as a generator, compiling in Release and adjusting the QWT references to the path of a locally compiled version:
$ cmake -G 'Unix Makefiles' /home/<user>/terralib5/build -DCMAKE_BUILD_TYPE=Release -DQWT_INCLUDE_DIR=/usr/local/qwt-6.1.0/include -DQWT_LIBRARY_RELEASE=/usr/local/qwt-6.1.0/lib/libqwt.so.6.1.0
Notes for Linux build

If using non-Standard third party library locations with cmake the following environmental variables must be configured before running cmake:

VariableEffectExample
LD_LIBRARY_PATH A colon-separated set of directories where third party libraries should be searched for first, before the standard set of directories LD_LIBRARY_PATH=/home/user/mylibraries