TerraLib and TerraView Wiki Page

This is an old revision of the document!


TerraLib Developer's Guide - Build Instructions

Make sure you have all the third-party library dependencies listed in the section Dependencies before trying to build TerraLib/TerraView.

After cloning the TerraLib repository, choose the right branch or tag to work on.

The build/cmake folder (under the source tree) contains a CMake project for building TerraLib.

TerraLib 5.5 build has been tested on:

  • Linux Ubuntu 18.04
  • Mac OS X Sierra
  • Microsoft Windows 10

You should use at least CMake version 3.11 for building TerraLib. Older versions than this may not work properly.

Follow the build steps below according to your platform.

Building on Microsoft Windows with Microsoft Visual C++ 2017

1. Microsoft Visual Studio 2017 C++ users can download and unpack the suitable third-party libraries compiled for building 64-bit version of TerraLib with Qt5.12.3 support. Choose the right version specified by x.y.z at terralib-x.y.z-3rdparty-msvc-2017-win64:

Alternatively, download the most updated third-party library used by developers working at DEVELOP branch here.

To work in RELEASE-5.Y branches go to the 5.Y corresponding directory to access the right third party used.

2. Uncompress the third-party package into a folder:

c:\terralib5\3rdparty

3. We will assume that the codebase (all the source tree ) is located at:

c:\terralib5\codebase

4. Open the CMake GUI:

  • Set the “Where is the source code” edit text to:
c:\terralib5\codebase\build\cmake
  • Set the “Where to build the binaries” edit text to:
c:\terralib5\build
  • Mark the “Grouped” and “Advanced” check box.
  • Click in “Add entry”:
    • Add new variable named CMAKE_PREFIX_PATH1), select type as PATH and fill its value with the following dependencies paths separated by semicolon (;)
DependenciesPATH
third-party c:\terralib5\3rdparty
Qt c:\<Qt5 path>\lib\cmake (or something similar)2)
Terralib4 c:\terralib5\3rdparty\lib\cmake\terralib-4.2.2
swig c:\terralib5\3rdparty\swig
Python c:\Python366
  • Click in “Configure” button.
    • Select option “Visual Studio 15 2017 Win64”
    • If the output folder (c:\terralib5\build) does not exist, CMake GUI will prompt you for creating it: just confirm the creation.
  • if no problem occurs, set the following variables:
EntryVariableValue
CPACK CPACK_BINARY_NSYS ON 3)
TERRALIB TERRALIB_BUILD_AS_BUNDLE ON
TERRALIB TERRALIB_BUILD_AS_DEV ON
TERRALIB TERRALIB_TRACK_3RDPARTY_DEPENDENCIES ON
TERRALIB TERRALIB_QHELP_ENABLED ON
TERRALIB TERRALIB_QTRANSLATION_ENABLED ON
TERRALIB TERRALIB_MOD_VM_ENABLED ON 4)
  • Some projects may be disabled through the following variables:
TERRALIB TERRALIB_DOXYGEN_ENABLED OFF5)
TERRALIB TERRALIB_BUILD_EXAMPLES_ENABLED OFF
TERRALIB TERRALIB_BUILD_UNITTEST_ENABLED OFF
  • Press Configure again.
  • Some entries might not be filled automatically by cmake, so do it manually. Examples of entries not filled are:
Boost Boost_PYTHON_LIBRARY_RELEASE c:\terralib5\3rdparty\lib/boost_python3-mt.lib
Boost Boost_PYTHON_LIBRARY_DEBUG c:\terralib5\3rdparty\lib/boost_python3-mt-gd.lib
Qscintilla Qscintilla_LIBRARY_RELEASE c:\terralib5\3rdparty\lib/qscintilla2.lib
  • Press Configure again.
  • Press Generate: this will generate a solution file for Visual Studio 2017 under the folder c:\terralib5\build\terralib.sln 6).
  • Press Open Project to open Visual Studio 2017

5. Inside Visual Studio right click over the project ALL_BUILD and build. Before running, set it as StartUp Project and set the local environment of terraview project 7).

6. If TERRALIB_BUILD_EXAMPLES_ENABLED ⇒ ON or TERRALIB_BUILD_EXAMPLES_ENABLED ⇒ ON: to run and debug one of the terralib_example_* or terralib_unitest_*, set it as StartUp Project and make sure the data ( data.zip) used by these examples/unittest are uncompressed at the default directory specified by TERRALIB_DATA_DIR :

 TERRALIB_DATA_DIR   C:\terralib\build-win64\data
 

Adding Plugin TerraPrint as part of TerraView/TerraLib

Building Plugin TerraPrint with Visual C++ 2017

TerraPrint is a plugin originally developed externally and its source code is maintained in a separated directory structure. As it depends on TerraLib, firstly it is necessary to built TerraPrint according with the instructions below:

  • Make a new folder to host TerraPrint source code:
$ mkdir C:/TPrint
$cd TPrint
  • Make a local copy of TerraPrint repository and go to the right branch:
$ GIT_SSL_NO_VERIFY=true git clone -b release-1.4 https://gitlab.dpi.inpe.br/terralib/terraprint.git .
$ git pull
  • Open the CMake GUI:
  • Set the “Where is the source code” edit text to:
   C:/TPrint/build/cmake
  • Set the “Where to build the binaries” edit text to:
   C:/TPrint_build
  • Mark the “Grouped” and “Advanced” check box.
  • Click in “Add entry”:
    • Add new variable named CMAKE_PREFIX_PATH8), select type as PATH and fill its value with the following dependencies paths separated by semicolon (;)
DependenciesPATH
third-party c:\terralib5\3rdparty
Terralib4 c:\terralib5\3rdparty\lib\cmake\terralib-4.2.2
Qt C:\Qt\5.12.3\msvc2017_64\lib\cmake\Qt5; (or something similar)9)
Qt C:\Qt\5.12.3\msvc2017_64\lib\cmake\Qt5LinguistTools
  • Click in “Configure” button.
    • Select option “Visual Studio 15 2017 Win64”
    • If the output folder (C:/TPrint_build) does not exist, CMake GUI will prompt you for creating it: just confirm the creation.
  • if no problem occurs, set the following variables:
EntryVariableValue
CPACK CPACK_BINARY_NSYS ON 10)
TERRALIB TERRALIB_BUILD_AS_BUNDLE OFF
TERRALIB TERRALIB_BUILD_EXAMPLES_ENABLED OFF
TERRALIB TERRALIB_BUILD_LAYOUT_TEST_ENABLED OFF
TERRALIB TERRALIB_MOD_LAYOUT_ENABLED ON
TERRALIB TERRALIB_MOD_QT_PLUGINS_ENABLED ON
TERRALIB TERRALIB_TRACK_3RDPARTY_DEPENDENCIES ON
TERRALIB_DIR_VAR_NAME<remove it because you will use your build version specified in terralib_DIR>
  • Press Configure again.
  • Some entries might be filled automatically by cmake with the wrong values.

Check under Ungrouged Entries which terralib is set 11): and set the one you just built before:

terralib_DIRc:\terralib5\build building dir used by terralib/terraview
  • Press Configure again.
  • Press Generate: this will generate a solution file for Visual Studio 2017 under the folder C:/TPrint_build 12).
  • Press Open Project to open Visual C++ interface using C:/TPrint_build\terralib_layout.sln 13)
  • On Visual Studio C++ 2017 interface, build ALL_BUILD on debug version first (some problems must be solved here) and afterwards the release version.
  • Close Visual Studio
  • Go back to Terralib/TerraView CMAKE and set the path to the plugin just built:
terralib_layout_DIR C:/TPrint_build informe where is Directory containing a CMake configuration file for TerraPrint
  • Press Configure and Generate to generate the solution including the plugin as part of package.
  • Press Open Project to open Visual C++
  • On Visual Studio C++ 2017 interface, build ALL_BUILD to build TerraView with TerraPrint as its plugin
  • Rebuild the project called PACKAGE to generate the TerraView installer with TerraPrint plugin.
  • Install the c:\terralib5\_CPack_Packages\win64\NSIS\TerraView-5.5.0-win64.exe to check the TerraPrint plugin 14)

Building on Linux Ubuntu 18.04 with GNU G++

1. Open a Command Prompt (Shell).

2. We will assume that the codebase (all the source tree) is located at:

/home/user/mydevel/terralib/codebase

3. Create a folder out of the TerraLib source tree to generate the build system, for example:

$ cd /home/user/mydevel/terralib
$ mkdir build-release
$ cd build-release

Note: for the sake of simplicity create this directory in the same level as the source tree (as shown above).

4. For Linux systems you must choose the build configuration:

$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_INSTALL_PREFIX:PATH="/home/user/myinstall/terralib" -DCMAKE_PREFIX_PATH:PATH="/home/user/mylibs" ../codebase/build/cmake

5. Building (with 4 process in parallel):

$ make -j 4

6. Installing:

$ make install

7. Uninstalling:

$ make uninstall

Notes:

  • Some Linux flavours with different versions of GNU gcc and Boost will need more parameters such as:
-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"
  • Boost can also be indicated by BOOST_INCLUDEDIR (note: without an '_' separating INCLUDE and DIR):
  -DBOOST_INCLUDEDIR:PATH="/usr/local/include"

* The parameter -lpthread must be informed only if your Boost was not built as a shared library:

  -DCMAKE_CXX_FLAGS:STRING="-lpthread"
  • For building with Qt5 you can provide the Qt5_DIR variable as:
  -DQt5_DIR:PATH="/usr/local/lib/cmake/Qt5"
  • For generating a debug version set CMAKE_BUILD_TYPE as:
  -DCMAKE_BUILD_TYPE:STRING="Debug"
  • If you are using default Ubuntu Desktop, you may have problems with menus. In this case, you may need to set the QT_QPA_PLATFORMTHEME environment variable before running Qt applications such as TerraView:
export QT_QPA_PLATFORMTHEME=""

Building on Mac OS X Sierra

1. Open a Command Prompt (Shell).

2. We will assume that the codebase (all the source tree) is located at:

/Users/user/mydevel/terralib/codebase

3. Create a folder out of the TerraLib source tree to generate the build system, for example:

$ cd /Users/user/mydevel/terralib
$ mkdir build-release
$ cd build-release

Note: for the sake of simplicity create this directory in the same level as the source tree (as showned above).

4. For Mac OS X systems you must choose the build configuration:

$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_INSTALL_PREFIX:PATH="/Users/user/myinstall/terralib" -DCMAKE_PREFIX_PATH:PATH="/Users/user/mylibs;/Users/user/mylibs/terralib5/lib/cmake;/Users/user/Qt5.12.3/lib/cmake" ../codebase/build/cmake

Note: Please, in the cmake call above, take special attention to the key *CMAKE_PREFIX_PATH* and Qt location.

5. Building (with 4 process in parallel):

$ make -j 4

6. Installing:

$ make install

7. Uninstalling:

$ make uninstall

Notes:

  • You have to specify valid paths for CMAKE_PREFIX_PATH. If you have a Qt version installed as a framework in your home directory, you have to tell CMake where to locate its CMake support. For instance, if you have Qt version 5.12.3 installed, you have to add to CMAKE_PREFIX_PATH the following directory:
/Users/user/Qt5.12.3/lib/cmake
  • You can also generate an Xcode project by using the “Xcode generator” option:
-G "Xcode"
  • There are some useful variables that can be set inside Xcode in order to run an application. The following environment variable can be set:
DYLD_FALLBACK_LIBRARY_PATH
DYLD_FALLBACK_FRAMEWORK_PATH

Building on Microsoft Windows with Microsoft Visual C++ 2013 (not supported anymore)

1. Microsoft Visual Studio 2013 C++ users can download and unpack the suitable third-party libraries compiled for building 64-bit version of TerraLib with Qt5.12.3 support. Choose the right version specified by x.y.z at terralib-x.y.z-3rdparty-msvc-2013-win64:

Alternatively, download the most updated third-party library used by developers at binary package with all the dependencies

2. Uncompress the above package into a folder:

c:\terralib5\3rdparty

3. We will assume that the codebase (all the source tree ) is located at:

c:\terralib5\codebase

4. Open the CMake GUI:

  • Set the “Where is the source code” edit text to:
c:\terralib5\codebase\build\cmake
  • Set the “Where to build the binaries” edit text to:
c:\terralib5\build
  • Mark the “Grouped” and “Advanced” check box.
  • Click in “Add entry”:
    • Add new variable named CMAKE_PREFIX_PATH, select type as PATH and fill value with the dependencies path: c:\terralib5\3rdparty.
  • At the same CMAKE_PREFIX_PATH variable, add the following locations separeted by “;”:
    • Qt5 path: c:\<Qt5 path>\lib\cmake (or something similar)15).
    • Terralib4 path: c:\terralib5\3rdparty\lib\cmake\terralib-4.2.2
    • Swig path: c:\terralib5\3rdparty\swig
  • Click in “Configure” button.
    • Select option “Visual Studio 12 2013 Win64”
    • If the output folder does not exist, CMake GUI will prompt you for creating it: just confirm the creation.
  • if no problem occurs, set the following variables:
    • CPACK ⇒ See the CPACK entries and keep ON onlythe NSIS package generator (used in release). All other kind of packages must be disabled.
    • TERRALIB entry ⇒ See the TERRALIB entries and set
      • TERRALIB_BUILD_AS_BUNDLE ⇒ ON
      • TERRALIB_BUILD_AS_DEV ⇒ ON
      • TERRALIB_TRACK_3RDPARTY_DEPENDENCIES ⇒ ON
      • TERRALIB_QHELP_ENABLED ⇒ ON
    • Some projects 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 releases.
    • TERRALIB_BUILD_EXAMPLES_ENABLED ⇒ OFF
    • TERRALIB_BUILD_UNITTEST_ENABLED ⇒ OFF
  • Press Configure again.
  • Press “Generate”: this will generate a solution file for Visual Studio 2013 under the folder c:\terralib5\build 16).

5. Open the solution file located at:

c:\terralib5\build\terralib.sln or press ''Open Project''

6. Build ALL_BUILD 17), and before running, set it as StartUp Project and set the local environment of terraview project 18).

7. If TERRALIB_BUILD_EXAMPLES_ENABLED ⇒ ON or TERRALIB_BUILD_EXAMPLES_ENABLED ⇒ ON: to run and debug one of the terralib_example_* or terralib_unitest_*, set it as StartUp Project and make sure the data ( data.zip) used by these examples/unittest are uncompressed at the default directory specified by TERRALIB_DATA_DIR :

 TERRALIB_DATA_DIR   C:\terralib\build-win64\data
1) as a example c:\terralib5\3rdparty;c:\terralib5\3rdparty/lib/cmake/terralib-4.2.2;C:\Qt\5.12.3\msvc2017_64\lib\cmake\Qt5;c:\terralib5\3rdparty\lib\cmake\wtss_cxx-0.4.0;c:\Python366
2) , 9) , 15) This is the folder where the dir Qt5 containing the Qt5Config.cmake file can be find
3) , 10) package generator (used in release)-disable the others
4) it enable TERRALIB_MOD_VM_PYTHON_ENABLED,TERRALIB_MOD_VM_LUA_ENABLED
5) 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 releases
6) , 12) , 16) The location set in “Where to build the binaries”
7) , 18) terraview→Properties→Configuration Properties→ Debugging, set the Environment entry as PATH=c:\terralib5\3rdparty\lib;c:\<Qt5 path>\bin
8) as a example c:\terralib5\3rdparty;c:\terralib5\3rdparty/lib/cmake/terralib-4.2.2;C:\Qt\5.12.3\msvc2017_64\lib\cmake\Qt5;C:\Qt\5.12.3\msvc2017_64\lib\cmake\Qt5LinguistTools
11) in my case an old one were set C:/Program Files/terralib5.2.2/lib/cmake/terralib-5.2.2
13) or Open the solution file located at C:/TPrint_build\terralib_layout.sln - TerraPrint is internally defined by terralib_layout_DIR
14) Plugins|Manage Plugins…|TerraPrint
17) Inside Visual Studio, right click over the project ALL_BUILD and build