====== Tutorial de Build e Instalação da TerraLib/TerraView ======

TODO: introdução TerraLib/TerraView

===== Source Code Instructions =====

In the root directory of TerraLib codebase (the source code tree) there are some text files explaining the details of the codebase:
  * **[[http://dpi.inpe.br/terralib5|BRANCHES-AND-TAGS]]:** Notes on how to switch to the right branch to work on or the right tag to get the source code.
  * **[[http://dpi.inpe.br/terralib5|BUILD-INSTRUCTIONS]]:** Notes on how to compile and install TerraLib for each platform.
  * **[[http://dpi.inpe.br/terralib5|CHANGELOG]]:** List of changes in TerraLib source code. **Not available yet!**
  * **[[http://dpi.inpe.br/terralib5|DEPENDENCIES]]:** The list of third-party library you must install before building TerraLib.
  * **[[http://dpi.inpe.br/terralib5|LICENSE]]:** Licence statement in plain txt format.
  * **[[http://dpi.inpe.br/terralib5|README]]:** Contains instructions about how to build and how is organized TerraLib plataform source code.

If you want to build TerraLib from source, first take a look at the section **[[:wiki:documentation:build#dependencies|Dependencies]]** and read the right tip for automatically building the dependencies in your platform.

===== Source Code Organization =====

  * **[[http://dpi.inpe.br/terralib5|build/cmake]]:** Contains the CMake scripts with commands, macros and functions used to build the environment for compiling libraries and executables in different platforms using the CMake tool.
  * **[[http://dpi.inpe.br/terralib5|examples]]:** Some examples on how to use TerraLib API.
  * **[[http://dpi.inpe.br/terralib5|install]]:** Bash scripts for helping building and installing TerraLib.
  * **[[http://dpi.inpe.br/terralib5||licenses]]:** Copyright notices of third-party libraries used by TerraLib. **Not available yet!**
  * **[[http://dpi.inpe.br/terralib5|resources]]:** Fonts, images, sql, and xml files among other resources of general use.
  * **[[http://dpi.inpe.br/terralib5|share]]:** XML Schema (.xsd), JSON files, plugin manifest files, translations files and OGC specifications that is shared and installed with TerraLib.
  * **[[http://dpi.inpe.br/terralib5|src]]:** Contains the source code of TerraLib and TerraView.
  * **[[http://dpi.inpe.br/terralib5|unittest]]:** **TODO**.
 
===== Dependencies =====

The file named **[[http://dpi.inpe.br/terralib5|DEPENDENCIES]]** in the root of TerraLib source tree contains the official list of third-party libraries and tools that you must install before building TerraLib from source.

If you want to build yourself TerraLib/TerraView then you need to install some third-party libraries. Below we show the list of third-party libraries dependencies and its versions:
  * **Boost (Mandatory):** TerraMA² is built on top of Boost libraries. You will need to have them installed in order to build TerraMA2. Make sure to have at least version 1.54.0 installed. If you prefer to install from source, download it from: http://www.boost.org.
  * **Qt (Mandatory):** Make sure you have an installed Qt version 5.2.1 or later. Linux users may use any package manager to perform an easy installation. Mac OS X can use package managers such as Homebrew (http://brew.sh) or MacPorts (http://www.macports.org) in order to have an easy installation. If you prefer to install from source, download it from: http://qt-project.org/downloads.
 
==== Bash script for building all dependencies on Linux Ubuntu 14.04 ====

We have prepared a special bash script for building and installing the dependencies on Linux Ubuntu 14.04. This script can be found in TerraLib source tree under **install** folder. Follow the steps below:
  * Download the third-party libraries package used by the development team: [[http://www.dpi.inpe.br/terralib5-devel/3rdparty/terralib-3rdparty-linux-ubuntu-14.04.tar.gz|terralib-3rdparty-linux-ubuntu-14.04.tar.gz]].
  * Copy the script [[http://dpi.inpe.br/terralib5|install-3rdparty-linux-ubuntu-14.04.sh]] to the same folder you have downloaded the **terralib-3rdparty-linux-ubuntu-14.04.tar.gz** package.
  * Open the shell command line and call the script **install-3rdparty-linux-ubuntu-14.04.sh** setting the target to install all the stuffs from these third-party libraries and tools:
<code bash>
$ TERRALIB_DEPENDENCIES_DIR="/home/user/mylibs" ./install-3rdparty-linux-ubuntu-14.04.sh
</code>

**Note:** Don't choose as target location a system folder such as //**/usr**// or //**/usr/local**//. Try some user specifiic folder. The best suggestion is to replace the folder named //**user**// by your user name.

==== Bash script for building all dependencies on Mac OS X ====

We have prepared a special bash script for building and installing the dependencies on Mac OS X. This script can be found in TerraLib source tree under //**install**// folder. Follow the steps below:
  * Download the third-party libraries package used by the development team:
    * [[http://www.dpi.inpe.br/terralib5-devel/3rdparty/terralib-3rdparty-macosx-yosemite.tar.gz|terralib-3rdparty-macosx-yosemite.tar.gz]].
    * [[http://www.dpi.inpe.br/terralib5-devel/3rdparty/terralib-3rdparty-macosx-el-capitan.tar.gz|terralib-3rdparty-macosx-el-capitan.tar.gz]].
  * Copy one of the scripts to the same folder you have downloaded the 3rd-party package:
    * [[http://dpi.inpe.br/terralib5|install-3rdparty-macosx-yosemite.sh]].
    * [[http://dpi.inpe.br/terralib5|install-3rdparty-macosx-el-capitan.sh]]. 
  * Open the shell command line.
  * Make sure your Qt and CMake environment can be found in your PATH:
<code bash>
$ export PATH=$PATH:/Users/user/Qt5.4.1/5.4/clang_64/bin:/Applications/CMake.app/Contents/bin
</code>
  * In the shell command line, call the script //**install-3rdparty-macosx-yosemite.sh**// (or the El-Capitan one) setting the target to install all the stuffs from these third-party libraries and tools:
<code bash>
$ TERRALIB_DEPENDENCIES_DIR="/Users/user/mylibs" ./install-3rdparty-macosx-yosemite.sh
</code>

**Note:** Don't choose as target location a system folder such as //**/usr**// or //**/usr/local**//. Try some user specifiic folder. The best suggestion is to replace the folder named *user* by your user name.

==== Prepared dependencies for Microsot Windows ====

**THIS SECTION IS UNDER DEVELOPMENT**

For Microsoft Visual C++ users we have prepared a zip file containing all the third-party libraries in a binary format. You can download this package from http://www.dpi.inpe.br/terralib5-devel/3rdparty-bin. In that folder you will find:

  - **terralib-3rdparty-msvc-2013-win64.zip:** all the third-party libraries for building a 64-bit version of Terralib/TerraView with Qt 5.4.1 support.
  - **terralib-3rdparty-msvc-2013-win32.zip:** all the third-party libraries for building a 32-bit version of Terralib/TerraView with Qt 5.4.1 support.

Microsoft Windows users must install Qt 5.4.1 to use the 3rdparty packages above.


===== Cloning TerraLib/TerraView Repository =====

  * Open the shell command line.

  * Make a new folder to host TerraLib source code:
<code bash>
$ mkdir -p /home/user/mydevel/terralib/codebase
</code>

  * Change the current directory to that new folder:
<code bash>
$ cd /home/user/mydevel/terralib/codebase
</code>

  * Make a local copy of TerraLib repository:
<code bash>
$ GIT_SSL_NO_VERIFY=true git clone https://tester:terralibdpi@git.dpi.inpe.br/terralib5 .
</code>

===== Branches =====
You can check all branches available (remotes and local) and see the current one (marked with "*"):
<code bash>
$ git branch -a
</code>

The output of above command will be something like:
<code bash>
  * master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
</code>

In the above output the "* master" means that the current branch is master.

We have the following branches:
  * **master:** This is the branch where the development team is working to add new features to future versions of TerraMA². It may be instable although the codebase is subject to automatic tests (regression and unittests). We don't recommend to generate production versions of TerraMA² from this branch. Use it for testing new features and get involved with TerraMA² development.

  * **b-4.0.0-alpha:** This will be the first branch in TerraMA²'s codebase for the generation 4.

**TODO:** under-devel

To switch to one of the branches listed above, use the checkout command and create a local branch to track the remote branch. The syntax of ''git checkout'' is:
<code bash>
$ git checkout -b <local_branch_name> <remote_branch_name without this part "remotes/">
</code>

In order to switch to branch *b-4.0.0-alpha* you can use the following command:
<code bash>
$ git checkout -b b-4.0.0-alpha origin/b-4.0.0-alpha
</code>

===== Tags =====

Also there are tags which usually are originated from a release branch. For instance, tag *t-4.0.0-alpha1* will be originated from branch *b-4.0.0-alpha*.

To check all tags available, use:

<code bash>
$ git tag -l           (list all tag names)
  t-4.0.0-alpha1
  t-4.0.0-alpha2
  t-4.0.0-beta1
  t-4.0.0-rc1
  t-4.0.0
  ...
</code>

If you want to checkout a specific version given by a tag and create a local branch to work on you can use the following git command:
<code bash>
$ git checkout -b <local_branch_tag_name> <one_of_tag_name_listed>
</code>

For instance, to checkout *t-4.0.0-alpha1* you can enter the following command:
<code bash>
$ git checkout -b t-4.0.0-alpha1  t-4.0.0-alpha1
</code>

===== Build Instructions =====

After choosing the right branch or tag to work on, follow the instructions on **[[:wiki:documentation:build#dependencies|DEPENDENCIES]]** section. Make sure you have all the third-party library dependencies listed in this section before trying to build TerraLib/TerraView.

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

Until now its build has been tested on:
- Linux Ubuntu 14.04
- Mac OS X Yosemite and El Capitan
- Microsoft Windows 7

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

Follow the build steps below according to your platform.

==== Building on Linux with GNU G++ ====

1.1. Open a Command Prompt (Shell).

1.2. We will assume that the codebase (all the source tree) is located at:
<code bash>
/home/user/mydevel/terralib/codebase
</code>

1.3. Create a folder out of the TerraLib source tree to generate the build system, for example:
<code bash>
$ cd /home/user/mydevel/terrama2
$ mkdir build-release
$ cd build-release
</code>

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

1.4. For Linux systems you must choose the build configuration:
<code bash>
$ 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
</code>

1.5 Building (with 4 process in parallel):
<code bash>
$ make -j 4
</code>

1.6 Installing:
<code bash>
$ make install
</code>

1.7 Uninstalling:
<code bash>
$ make uninstall
</code>

Notes:
  * Some Linux flavours with different versions of GNU gcc and Boost will need more parameters such as:
<code>
  -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"
</code>

  * Boost can also be indicated by BOOST_INCLUDEDIR (note: without an '_' separating INCLUDE and DIR):
<code>
  -DBOOST_INCLUDEDIR:PATH="/usr/local/include"
</code>

 * The parameter -lpthread must be informed only if your Boost was not built as a shared library:
<code>
  -DCMAKE_CXX_FLAGS:STRING="-lpthread"
</code>

  * For building with Qt5 you can provide the Qt5_DIR variable as:
<code>
  -DQt5_DIR:PATH="/usr/local/lib/cmake/Qt5"
</code>

  * For generating a debug version set CMAKE_BUILD_TYPE as:
<code>
  -DCMAKE_BUILD_TYPE:STRING="Debug"
</code>

==== Building on Mac OS X Yosemite and El Capitan ====

1.1 Open a Command Prompt (Shell).

1.2. We will assume that the codebase (all the source tree) is located at:
<code>
/Users/user/mydevel/terrama2/codebase
</code>

1.3. Create a folder out of the TerraMA² source tree to generate the build system, for example:
<code>
$ cd /Users/user/mydevel/terrama2
$ mkdir build-release
$ cd build-release
</code>

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

1.4. For Mac OS X systems you must choose the build configuration:
<code>
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_INSTALL_PREFIX:PATH="/Users/user/myinstall/terrama2" -DCMAKE_PREFIX_PATH:PATH="/Users/user/mylibs;/Users/user/mylibs/terralib5/lib/cmake;/Users/user/Qt5.4.1/5.4/clang_64/lib/cmake" ../codebase/build/cmake
</code>

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

1.5. Building (with 4 process in parallel):
<code>
$ make -j 4
</code>

1.6. Installing:
<code>
$ make install
</code>

1.7. Uninstalling:
<code>
$ make uninstall
</code>

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.4.1 installed, you have to add to *CMAKE_PREFIX_PATH* the following directory:
<code>
/Users/user/Qt5.4.1/5.4/clang_64/lib/cmake
</code>

  * You have also to tell where TerraLib? CMake support is located. Add to CMAKE_PREFIX_PATH where TerraLib? is installed, for example:
<code>
/Users/user/MyLibs/terralib/lib/cmake
</code>

  * You can also generate an Xcode project by using the "Xcode generator" option:
<code>
-G "Xcode"
</code>

  * There are some useful variables that can be set inside Xcode in order to run an application. The following environment variable can be set:
<code>
DYLD_FALLBACK_LIBRARY_PATH
DYLD_FALLBACK_FRAMEWORK_PATH
</code>

==== Building on Microsoft Windows with Visual C++ ====

**TO BE DONE**


===== Quick Notes for Developers =====

If you have built TerraMA² in Debug mode and you want to run it inside the build tree, you may need to set some environment variables:
  * For Mac OS X, you can set the following variables:
<code>
$ export DYLD_FALLBACK_LIBRARY_PATH=/Users/user/mylibs/lib
$ export DYLD_FALLBACK_FRAMEWORK_PATH=/Users/user/mylibs/lib/
</code>

  * For Linux, you can set the following variable:
<code>
$ export LD_LIBRARY_PATH=/home/user/mylibs/lib
</code>

If you want to use QtCreator on Linux Ubuntu 14.04 you can install it through the following command:
<code>
$ sudo apt-get install qtcreator
</code>

On Linux Ubuntu 14.04 you can install git through the following command:
<code>
$ sudo apt-get install git
</code>

If you have experienced  any problem building any of the third-party tool on Mac OS X, try to install Xcode command line tools:
<code>
$ xcode-select --install
</code>

===== Reporting Bugs ======

Any problem should be reported to terralib-team@dpi.inpe.br.

For more information on TerraLib, please, visit its main web page at: http://www.dpi.inpe.br/terralib.