Building and Configuring

How to Build TerraME

This small tutorial describes the steps to build and configure TerraME from its source code. In all the platforms, TerraME depends on the external packages and libraries listed bellow. They must be installed separately.

Mandatory

• CMake 3.X
• TerraLib 5.X
• Qt 5.X
• Protocol Buffers Library
• QtLua 2.0 (Customized version found on TerraME repository)
• QtLua-Extras (Customized version Found on TerraME repository)

Optional

• Postgres 9.X with Postgis extensions
• SourceTree Git & Mercurial client for Windows or Mac
• SmartGit for Linux

---

## Mac OSX environment (ref. OS X El Capitan)

CMake 3.X (ref. 3.5.1)

Download CMake and put cmake command in the PATH environment variable:

export PATH=$PATH:/path/to/cmake/bin  

Xcode (ref. 7.3)

To build TerraME and TerraLib components in Mac OSX environment you must install Xcode (found in AppStore) as well as Xcode command-line tools (https://developer.apple.com/downloads/index.action?=command%20line%20tools).

TerraME 2.X

Clone TerraME from git:

https://github.com/TerraME/terrame.git

It is recommended to create a structure of directories like:

-- terrame
     |
      -- depends
      -- build-cmake
      -- git
          |
           -- terrame (clone here)

TerraLib 5.X (ref. release-5.1)

Clone TerraLib from git. If you are using Sourcetree, go to Sourcetree, Preferences, Git, and then check Disable SSL certificate validation (note: potentially insecure) to allow downloading TerraLib.

Clone TerraLib from the following Git repository:

https://gitlab.dpi.inpe.br/terralib/terralib.git

It is recommended to create a structure of directories like:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
      -- git
          |
           -- terralib (clone here)

Compile the dependencies of TerraLib folowing the instructions available at Mac OS X found here.

It is recommended to use the structure of directories as follows:

-- terralib
     |
      -- 3rdparty
          |
           -- terralib-3rdparty-macosx-el-capitan.tar.gz (put here)
           -- install-3rdparty-macosx-el-capitan.sh (put here)
           -- libs (here is TERRALIB_DEPENDENCIES_DIR)
      -- build-cmake
      -- git 

If you need credentials to download the TerraLib dependencies, put this:

user = terralib5 
password = newterralib5

Or use this command:

wget --user=terralib5 --password=newterralib5 http://www.dpi.inpe.br/terralib5-devel/3rdparty-src/terralib-3rdparty-macosx-el-capitan.tar.gz

Run install-3rdparty-macosx-el-capitan.sh to compile and install all TerraLib dependencies.

Copy the scripts terralib-conf.cmake and terralib-conf.sh from .../terrame/git/terrame/build/scripts to .../terralib/build-cmake

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake (put here)
           -- terralib-conf.sh (put here)
      -- git 

In terralib-conf.sh, set the variable:

export _TERRALIB_3RDPARTY_DIR=/.../terralib/3rdparty/libs

Go to .../terralib/build-cmake and run terralib-conf.sh.

After that, the build directory that contains the TerraLib Xcode project terralib.xcodeproj will be created:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake
           -- terralib-conf.sh
           -- build (created)
      -- git 

Enter into build directory and open terralib.xcodeproj.

Now in Xcode, firstly build ALL_BUILD and then build install.

At this point the directory /install that contains all libraries of TerraLib will be created.

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake
           -- terralib-conf.sh
           -- build
           -- install (created)
      -- git 

libqtlua 2.0 (fork in TerraME repository)

Download zip libqtlua from the following Git repository (you do not need to clone it):

https://github.com/TerraME/libqtlua

It is recommended to use the structure of directories created:

-- terrame
     |
      -- depends
          |
           -- libqtlua (put here)
           -- build-cmake
           -- git 

qtluae (fork in TerraME repository)

Download zip file with qtluae from the following Git repository (you do not need to clone it):

https://github.com/TerraME/qtluae

It is recommended to use the structure of directories created:

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae (put here)
      -- build-cmake
           -- git 

Protobuf (ref. master)

Download zip protobuf from the following Git repository (you do not need to clone it):

https://github.com/google/protobuf

It is recommended to use the structure of directories created:

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae
           -- protobuf (put here)
      -- build-cmake
           -- git 

Copy the script terrame-deps-conf.sh from .../terrame/git/terrame/build/scripts to .../terrame/depends.

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae
           -- protobuf
           -- terrame-deps-conf.sh (put here)
      -- build-cmake
           -- git 

Put Qt5 in the PATH environment variable:

export PATH=$PATH:/path/to/qt5/version/bin

Open terrame-deps-conf.sh and set LUA_PATH variable to where Lua is located, like:

LUA_PATH=.../terralib/3rdparty/libs

Run terrame-deps-conf.sh. After that, the /install directory that contains the necessary libraries to compile TerraME will be created.

TerraME 2.X (ref. 2.0)

Copy the scripts terrame-conf.cmake and terrame-conf.sh from .../terrame/git/terrame/build/scripts to .../terrame/build-cmake

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake (put here)
           -- terrame-conf.sh (put here)
      -- git 

In terrame-conf.sh, set the variables:

export _TERRALIB_3RDPARTY_DIR=/.../terralib/3rdparty/libs
export _TERRAME_DEPENDS_DIR=/.../terrame/depends/install
export _TERRALIB_MODULES_DIR=/.../terralib/build-cmake/install
export _QT5_DIR=/path/to/qt5/version

Go to .../terrame/build-cmake and run terrame-conf.sh.

After that, the build directory that contains the TerraME Xcode project terrame.xcodeproj will be created:

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake
           -- terrame-conf.sh
           -- build (created here)
      -- git 

Enter into build directory and open terrame.xcodeproj.

Now in Xcode, firstly build ALL_BUILD. Second build install. At this point, the directory install, that contains all libraries and executable of TerraME, will be created.

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake
           -- terrame-conf.sh
           -- build
           -- install (created here)
      -- git 

To run TerraME, it is necessary to set some paths in environment or to create a ~/.bash_profile like:

export TME_ROOT_PATH=/.../terrame/build-cmake/install
export TME_PATH=$TME_ROOT_PATH/bin
export DYLD_LIBRARY_PATH=$TME_ROOT_PATH/lib

Run terrame command from the terminal to see if everything went fine:

terrame -version

Compile TerraME as Bundle

See Bundle Structures on Mac Page for details about Bundle.

In terrame-conf.cmake, set TERRAME_BUILD_AS_BUNDLE to ON. Be careful not to have it defined as an environmental variable or in your ~/.bash_profile.

Go to .../terrame/build-cmake and run terrame-conf.sh.

Enter in build directory and open terrame.xcodeproj.

Build install in Xcode.

After that, a bundle of TerraME in /install directory will exist. To work with bundle, it is necessary to set PATH environment variable to .../bin within TerraME directory or set this command in ~/.bash_profile:

export PATH=$PATH:/.../terrame/build-cmake/install/terrame.app/Contents/bin

Run terrame command in terminal for test:

terrame -version

Create TerraME installer DMG

With bundle enabled, it is only necessary to run the command in build directory:

cd /.../terrame/build-cmake/build && /Applications/CMake.app/Contents/bin/cpack -G DragNDrop -C Release --config ./CPackConfig.cmake

## Ms Windows (ref. 8.1 x64)

CMake 3.X (ref. 3.3.2)

Download CMake and put cmake command in the PATH environment variable:

set PATH=%PATH%;path\to\cmake\bin  

Ms Visual Studio (ref. 2013)

To build TerraME and TerraLib components in Windows you need to install Ms Visual Studio 2013.

TerraME 2.X

Clone TerraME from git:

https://github.com/TerraME/terrame.git

It is recommended to create a structure of directories like the one below:

-- terrame
     |
      -- depends
      -- build-cmake
      -- git
          |
           -- terrame (clone here)

TerraLib 5.X (ref. release-5.1)

Clone TerraLib from git. If you are using Sourcetree, go to Sourcetree, Preferences, Git, and then check Disable SSL certificate validation (note: potentially insecure) to allow downloading TerraLib. Clone it from the following Git repository:

https://gitlab.dpi.inpe.br/terralib/terralib.git

It is recommended to create a structure of directories like the one below:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
      -- git
          |
           -- terralib (clone here)

Compile the dependencies of TerraLib folowing the instructions available at Ms Windows found here.

It is recommended to use the structure of directories like the one below:

-- terralib
     |
      -- 3rdparty
          |
           -- terralib5-3rdparty-msvc-2013-win64 (extract here)
      -- build-cmake
      -- git 

If you need credentials to download TerraLib dependencies, use:

user = terralib5 
password = newterralib5

SWIG (3.0.8)

SWIG is an interface compiler that connects programs written in C and C++ with scripting languages such as Lua, Perl, Python, etc. Download SWIG for Windows here.

It is recommended to use the created structure of directories:

-- terralib
     |
      -- 3rdparty
          |
           -- terralib5-3rdparty-msvc-2013-win64
           -- swigwin (extract here and rename)
      -- build-cmake
      -- git 

Copy the scripts terralib-conf.cmake and terralib-conf.bat from .../terrame/git/terrame/build/scripts to .../terralib/build-cmake

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake (put here)
           -- terralib-conf.bat (put here)
      -- git 

In terralib-conf.bat, set the variable:

export _TERRALIB_3RDPARTY_DIR=/.../terralib/3rdparty/terralib5-3rdparty-msvc-2013-win64

Go to .../terralib/build-cmake and run terralib-conf.bat.

After that, a build directory that contains the TerraLib MSVC solution terralib.sln will exist:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake
           -- terralib-conf.bat
           -- build (created)
      -- git 

Enter in build directory and open terralib.sln.

Now in Visual Studio, firstly build ALL_BUILD and after that build INSTALL.

At this point, the directory install (that contains all libraries of TerraLib) will be created.

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake
           -- terralib-conf.bat
           -- build
           -- install (created)
      -- git 

libqtlua 2.0 (fork in TerraME repository)

Download zip libqtlua from the following Git repository (you do not need to clone it):

https://github.com/TerraME/libqtlua

It is recommended to use the created structure of directories:

-- terrame
     |
      -- depends
          |
           -- libqtlua (put here)
      -- build-cmake
           -- git 

qtluae (fork in TerraME repository)

Download zip qtluae from the following Git repository (you do not need to clone it):

https://github.com/TerraME/qtluae

It is recommended to use the created structure of directories:

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae (put here)
      -- build-cmake
      -- git 

Copy the script terrame-deps-conf.bat from .../terrame/git/terrame/build/scripts to .../terrame/depends.

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae
           -- terrame-deps-conf.bat (put here)
      -- build-cmake
      -- git 

Open terrame-deps-conf.bat and set the variables:

set LUA_PATH=...\terralib\3rdparty\terralib5-3rdparty-msvc-2013-win64
set Qt5_DIR=Qt\5.X\msvc2013_64

Run terrame-deps-conf.bat.

After run, a build directory that contains the soluctions to compile QtLua and QtLua-Extras will exist.

Open qtlua.sln in Visual Studio and execute the following steps:

1. build only qtlua;
2. in qtlua > Properties > Configuration Properties > Generalchange Target Extension to .lib and Configuration Type to Static library (.lib);
3. in qtlua_app > Properties > Linker > System change SubSystem to Console (/SUBSYSTEM:CONSOLE).

Build ALL_BUILD and next build INSTALL.

Open qtlua-extras.sln in Visual Studio. To build it, it is necessary the follow configuration: in qtluae > Properties > Linker > Input > Additional Dependencies > edit put the full path of Lua library, like:

D:\terralib\3rdparty\terralib5-3rdparty-msvc-2013-win64\lib\lua.lib  

Build ALL_BUILD and next build INSTALL.

After that, an install directory that contains QtLua and QtLua-Extras dependencies will exist.

Protobuf (ref. 2.6.1)

Download zip protobuf from the following Git repository (you do not need to clone it):

https://github.com/google/protobuf/releases/tag/v2.6.1

It is recommended to use the created structure of directories:

-- terrame
     |
      -- depends
          |
           -- libqtlua
           -- qtluae
           -- terrame-deps-conf.bat
           -- protobuf (extract here and rename)
      -- build-cmake
      -- git 

Protobuf already contains Visual Studio Solution located in protobuf/vsprojects. Open the solution protobuf.sln. If the configuration is Win32, change it to x64.

Build libprotobuf, libprotobuf-lite, libprotoc and protoc.

Run extract_includes.bat from vsprojects to generate include directory. Copy libs libprotobuf.lib, libprotobuf-lite.lib, libprotoc.lib to .../terrame/depends/install/lib. Copy google directory located in include to .../terrame/depends/install/include. Copy protoc.exe to .../terrame/depends/install/bin.

MinGW

Download mingw-get-setup.exe. Install MinGW, open MinGW installation Manager and install msys-base and msys-unzip.

TerraME 2.X (ref. 2.0)

Copy the scripts terrame-conf.cmake and terrame-conf.bat located in .../terrame/git/terrame/build/scripts to .../terrame/build-cmake

-- terrame
     |
      -- depends
          |
           -- build-cmake
           -- terrame-conf.cmake (put here)
           -- terrame-conf.bat (put here)
      -- git 

In terrame-conf.bat, set the variables:

set _TERRALIB_3RDPARTY_DIR=...\terralib\3rdparty\terralib5-3rdparty-msvc-2013-win64
set _TERRAME_DEPENDS_DIR=...\terrame\depends\install
set _TERRALIB_MODULES_DIR=...\terralib\build-cmake\install
set _QT5_DIR=path\to\qt5\version\msvc2013_64
set _MSYS_DIR=MinGW\msys\1.0\bin

Go to .../terrame/build-cmake and run terrame-conf.bat.

After that, a build directory will be created. It contains the TerraME Visual Studio soluction terrame.sln:

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake
           -- terrame-conf.bat
           -- build (created here)
      -- git 

Enter in build directory and open terrame.sln.

Now in Visual Studio, firstly build ALL_BUILD and then build INSTALL.

At this point, a directory install will be created. It contains all libraries and executable of TerraME.

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake
           -- terrame-conf.bat
           -- build
           -- install (created here)
      -- git 

To run the TerraME, it is necessary set some paths in environment like:

set TME_PATH=.../terrame/build-cmake/install/bin
set PATH=%PATH%;%TME_PATH%

Run terrame command in terminal for test:

terrame -version

Compile TerraME as Bundle

In terrame-conf.cmake, set TERRAME_BUILD_AS_BUNDLE to ON.

Go to .../terrame/build-cmake and run terrame-conf.bat.

Enter in build directory and open terrame.sln.

Build INSTALL in Visual Studio.

To run the TerraME, it is necessary set some paths in environment like:

set TME_PATH=.../terrame/build-cmake/install/bin
set PATH=%PATH%;%TME_PATH%

Run terrame command in terminal for test:

terrame -version

Create TerraME installer

Firtly, download end install NSYS (ref. 2.50).

With bundle enabled, it is only necessary build PACKAGE in Visual Studio:

The installer is generated in .../terrame/build-cmake/build directory.

## Linux environment (ref. Ubuntu 14.04 LTS)

CMake 3.X (ref. 3.5.2)

sudo apt-get install build-essential
wget http://www.cmake.org/files/v3.2/cmake-3.2.2.tar.gz
tar xf cmake-3.2.2.tar.gz
cd cmake-3.2.2
./configure
make -j4
sudo make install

TerraME 2.X

Clone TerraME from git:

https://github.com/TerraME/terrame.git

It is recommended to create a structure of directories like:

-- terrame
     |
      -- 3rdparty
      -- build-cmake
      -- git
          |
           -- terrame (clone here)

TerraLib 5.X (ref. release-5.1)

Clone TerraLib from the following Git repository:

https://gitlab.dpi.inpe.br/terralib/terralib.git

It is recommended to create a structure of directories like:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
      -- git
          |
           -- terralib (clone here)

Compile the dependencies of TerraLib folowing the instructions available at Linux Ubuntu 14.04 found here*.

Get the install-3rdparty-linux-ubuntu-14.04.sh customized to TerraME in .../terrame/git/terrame/build/scripts/linux. Get the terralib-3rdparty-linux-ubuntu-14.04.tar.gz customized to TerraME in <>.

It is recommended to use the structure of directories as follows:

-- terralib
     |
      -- 3rdparty
          |
           -- terralib-3rdparty-linux-ubuntu-14.04.tar.gz (put here)
           -- install-3rdparty-linux-ubuntu-14.04.sh (put here)
           -- libs (here is TERRALIB_DEPENDENCIES_DIR)
      -- build-cmake
      -- git 

If you need credentials to download the TerraLib dependencies, put this:

user = terralib5 
password = newterralib5

Or use this command:

wget --user=terralib5 --password=newterralib5 http://www.dpi.inpe.br/terralib5-devel/3rdparty-src/terralib-3rdparty-linux-ubuntu-14.04.tar.gz

Run TERRALIB_DEPENDENCIES_DIR="/home/developer/terralib/3rdparty/libs" ./install-3rdparty-linux-ubuntu-14.04.sh to compile and install all TerraLib dependencies.

Copy the scripts terralib-conf.cmake and terralib-conf.sh from .../terrame/git/terrame/build/scripts to .../terralib/build-cmake

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake (put here)
           -- terralib-conf.sh (put here)
      -- git 

In terralib-conf.sh, set the variable:

export _TERRALIB_3RDPARTY_DIR=/.../terralib/3rdparty/libs

Go to .../terralib/build-cmake and run terralib-conf.sh.

After that, the build and install directory that contains the project and all libraries of TerraLib will be created:

-- terralib
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terralib-conf.cmake
           -- terralib-conf.sh
           -- build (created)
           -- install (created)
      -- git 

qtluae (fork in TerraME repository)

Download zip file with qtluae from the following Git repository (you do not need to clone it):

https://github.com/TerraME/qtluae

It is recommended to use the structure of directories created:

-- terrame
     |
      -- 3rdparty
          |
           -- qtluae (put here)
      -- build-cmake
           -- git 

Protobuf (ref. master)

Download zip protobuf from the following Git repository (you do not need to clone it):

https://github.com/google/protobuf

It is recommended to use the structure of directories created:

-- terrame
     |
      -- 3rdparty
          |
           -- qtluae
           -- protobuf (put here)
      -- build-cmake
           -- git 

Copy the script terrame-deps-conf.sh from .../terrame/git/terrame/build/scripts/linux to .../terrame/3rdparty.

-- terrame
     |
      -- 3rdparty
          |
           -- qtluae
           -- protobuf
           -- terrame-deps-conf.sh (put here)
      -- build-cmake
           -- git 

Open terrame-deps-conf.sh and set LUA_PATH variable to where Lua is located, like:

LUA_PATH=.../terralib/3rdparty/libs

Run terrame-deps-conf.sh. After that, the /install directory that contains the necessary libraries to compile TerraME will be created.

TerraME 2.X (ref. 2.0)

Copy the scripts terrame-conf.cmake and terrame-conf.sh from .../terrame/git/terrame/build/scripts to .../terrame/build-cmake

-- terrame
     |
      -- 3rdparty
      -- build-cmake
          |
           -- terrame-conf.cmake (put here)
           -- terrame-conf.sh (put here)
      -- git 

In terrame-conf.sh, set the variables:

export _TERRALIB_3RDPARTY_DIR=/.../terralib/3rdparty/libs
export _TERRAME_DEPENDS_DIR=/.../terrame/3rdparty/install
export _TERRALIB_MODULES_DIR=/.../terralib/build-cmake/install
export _QT5_DIR=/path/to/qt5

Go to .../terrame/build-cmake and run terrame-conf.sh.

After that, the build and install directory that contains the TerraME will be created:

-- terrame
     |
      -- depends
      -- build-cmake
          |
           -- terrame-conf.cmake
           -- terrame-conf.sh
           -- build (created here)
           -- install (created here)
      -- git 

To run TerraME, it is necessary to set some paths in environment or append in ~/.bashrc like:

export TME_PATH=/.../terrame/build-cmake/install/bin
export PATH=$PATH:$TME_PATH
export LD_LIBRARY_PATH=$TME_PATH

Run terrame command from the terminal to see if everything went fine:

terrame -version

Create TerraME installer <>

With everything built, it is only necessary to run the command in build directory: <>

cd /.../terrame/build-cmake/build && cpack -G TGZ -C Release --config ./CPackConfig.cmake