TerraLib and TerraView Wiki Page

TerraLib 5.0.0-alpha - Build and Install

Building Terralib

This section explains how to build the TerraLib from source in some platforms.

General Information

We will refer to your TerraLib local working directory as <terralib_root> and the building directory as <building_dir>

The local working directory is where the source code is located and the building directory is where CMake will create the build system for your chosen platform and compiler, and also where the libraries will be compiled.

Under <terralib_root>/build you will see CMake files and the following sub-folders:

Folder Content
examples general CMakeLists.txt scripts for all examples and subfolders to each TerraLib example with a specific CMakeLists.txt script
modules CMake utility files, such as finds and package generators
terralib general .cmake script for all TerraLib and subfolders to each TerraLib module with a specific CMakeLists.txt script
terralib_qt_plugins general .cmake script for all the qt plug-ins
terraview Files used to configure TerraView
third-party Files used to build third-party libraries
unittest general CMakeLists.txt script for all unittests and subfolders to each TerraLib unittest with a specific CMakeLists.txt script

Pay attention to some variables used by CMake and explained below:

VariableCommentValue
TE_DEPENDENCIES_DIR path where the third party libraries are located it can be defined as an environmental variable otherwise define it at CMake interface using Add Entry button, type PATH, value C:\<unpack-dir>\terralib_3rdparty_win32
TE_BIN_DIR path where the executable will be generated it is automatically set by CMake based on <building_dir>/bin32
QT_QMAKE_EXECUTABLE path where Qt4 qmake.exe is located . It is only necessary if CMake can not find Qt4. In this case, define it at CMake interface using Add Entry button, type PATH and a value such as C:/Qt/4.8.5/bin/qmake.exe
TE_HELP_DIR path where the TerraView HELP files are located it can be defined as an environmental variable otherwise define it at CMake interface using Add Entry button, type PATH, value C:/<cloned-dir>/terraview_help

Cmake-Gui

Using the Graphic Interface (cmake-gui) to build the compilation projects.

To run CMake from the cmake-gui, you will:

  • Execute the cmake-gui system, found in the CMake binary folder.
  • In the “Where is the source code”, put the path where is the CMakeLists main file. For terralib it is <terralib_root>/build
  • In the “Where to build the binaries”, put the path where you want the CMake generate the files. For terralib it can be <building_dir>/terralib.
  • (Optional) Set up the TE_DEPENDENCIES_DIR. Press the Add Entry button and adjust the path to the dependencies directory, for example:

  • Click “Configure” and select the generator for the project.
  • Review the “BUILD” group and check which module you want to build.
  • Review the options related to third-party libraries (e.g. “Boost” or “Gdal”) and make sure that CMake found the needed library file(s) and include directoriy. If any of the dependencies is not found you must manually enter the path to it. Just click on the line of the dependency and type the path.
  • Click “Generate”

After these steps, the build files will have been generated and the cmake-gui will look like this:

Now all you need to do is go to the selected building directory and run the appropriate building tool according to the generator you selected. (e.g. for Unix Makefiles just run “make”).

CMake command line

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
BUILD_TERRALIB4 Enable/disable [ON/OFF] the TerraLib4 module -DBUILD_TERRALIB4=OFF
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>
TE_DEPENDENCIES_DIR Used as an easy and convenient way to locate terralib's dependencies -DTE_DEPENDENCIES_DIR=<unpack_dir>/terralib_3rdparty_win32
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:

  • 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

CCmake

Using the curses based Interface (ccmake) to build the compilation projects.

On some Unix platforms, you can install a curses based cmake gui that is a terminal based text application and can be used as well. The commands are basically the same as before, but instead of using “cmake” use “ccmake” instead.

Example: ccmake /home/<username>/source/terralib5/build (Executed from the <building_dir>)

Once executed, the user can manually adjust the variables and customize the compilation. Once the options have been adjusted type c to configure the project and then type g to generate the build files and exit ccmake.

Building the Examples

This section will detail the proccess of building the examples after building or installing Terralib. Some examples are listed here:

Folder Content
example_ado It shows how to interact with Microsoft Access driver.
example_dataaccess It shows how to interact with DataAccess Module and drivers PostGIS, ORG and GDAL
example_geometry It shows how to create geometries and some Spatial Operators.
terralib_raster It shows how to manipulate raster data.
example_rp It show how use the raster processing module.
example_srs It shows how to use the sapatial reference system manager.
example_st It show how to use the Spatial Temporal Module.
example_vp It shows how to use the Vector Processing Module.

The proccess is similar to Terralib's proccess, steps such as using the cmake-gui or command line are similar, however, there a few differences worth mentioning.

First, in order to build either the examples cmake must be told where is the CMakeLists main file which is <terralib_root>/build/examples. Also, examples use a few variables that can edited, they are:

VariableCommentValue
terralib_DIR Where terralib has been built/installed it can either be defined as an environmental variable or be defined at the CMake interface using the Add Entry button, type PATH, value <building_dir>/terralib
DATA_DIR where the data used by the examples will be downloaded and unpacked Inform the path where you downloaded the http://www.dpi.inpe.br/terralib5/data.zip

After pressing Configure, Review the “EXAMPLE” group and check which example you want to build. Some are already checked and you can keep or change the examples that will be compiled, for example:

You can edit these variables in the same way used to configure terralib's variables.

Once you are done, just Configure and Generate the build files in the same way explained on the terralib section.