
                      =====================================================================
												Building Procedures 
                      =====================================================================
  
In order to compile TerraLib, Examples and Unittest projects you need to install the CMake tool that
builds the compiling environment for Windows, Linux, and Mac platforms, Cmake is a cross-platform family of tools designed to build, test and package software.

The CMake tool can be found at "http://www.cmake.org" and it builds the environment used to compile the 
libraries and executables based on files named CMakeLists.txt that contain CMake scripts with commands,
macros, and functions.
  
===================================
In-source vs Out-of-source Building
===================================

We have to consider where to put the resulting object files, libraries, and executables.
There are two different approaches commonly used:
- in-source build:     the binary files are produced in the same directory as the source files;
- out-of-source build: the binary files are put into a separate tree that has the same structure as the source tree.

In the examples below we will use the "out-of-source build" because it doesn't pollute the source directories where 
the CMake scripts are located, making easy the clean up of the binaries built.

=========================================================
Directory Root Where TerraLib is Supposed to be Installed
=========================================================

Depending on the platform used, we will suppose that TerraLib5 is installed in the following directory:
  - Windows:       "C:/Users/<user_name>/terralib5"
  - Linux and Mac: "/home/<user_name>/terralib5"
  
We will refer to this directory as the TerraLib Root Directory, or plainly as <terralib_root>.

=====================================================
Directory Where The Projects Are Supposed to be Built
=====================================================

Depending on the platform used, we will suppose that TerraLib, the Examples and Unittest
projects will be built in the following directory:
  - Windows:       "C:/Users/<user_name>/terralib_build"
  - Linux and Mac: "/home/<user_name>/terralib_build"
  
This directory will be referred as the Building Directory, or plainly as <building_dir>.

==============================================
Instructions for Compiling TerraLib with CMake
==============================================

The directory "<terralib_root>/build" contains a CMakeLists.txt with references to all the TerraLib
projects (all project), while each of their sub-directories contain the script specific for a TerraLib project:
    
To obey the same tree structure as the "<terralib_root>/build" we will create a terralib directory in
<building_dir>:

     mkdir <building_dir>/terralib
     
where will be generated the compiling environment for the target platform.

There are two ways for compiling TerraLib:
- Using the CMake GUI;
- Using the Command Prompt.

-------------------------------
Cmake - General User Interface
-------------------------------

1. Execute the cmake-gui system, found in the CMake binary folder.

2. In the Where is the source code, put the path where is the CMakeLists main file. Example: <terralib_root>/build

3. In the Where to build the binaries, put the path where you want the CMake generate the files. It can be the same path where the source code is, however, try to avoid this.

(Optional) Set up the TE_DEPENDENCIES_DIR. Press the Add Entry button and adjust the path to the dependencies directory, for example:

		 Name: TE_DEPENDENCIES_DIR
		 Type: PATH
		 Value: <unpack-dir>\terralib_3rdparty_win32
		 
4. Click "Configure" and select the generator for the project.

5. Review the "BUILD" group and check which module you want to build.

6. 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.

7. Click "Generate"

8. Go to the selected building directory  in step 3 and run the appropriate building tool according
 to the generator you selected in step 4. (e.g. for Unix Makefiles just run "make").

------------------------
Cmake - Command Prompt
------------------------

1. In the Command Prompt, go to the directory "<building_dir>/terralib"

    cd <building_dir>/terralib

2. Invoke the cmake command adjusting any options you may want to, This is done with a -DVARIABLE:TYPE=VALUE syntax on the command line.
 such as:

a. Build type (debug or release). Ex: -DCMAKE_BUILD_TYPE=Release
b. Weather or not to build certain Terralib modules (QT_Widgets, TerraView, etc.) Ex: -DBUILD_TERRAVIEW=false

The Generator must be specified as: -G <generator-name>

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

  Specifying Visual Studio 10 as the generator, using source code located at C:/Users/<user_name>/terralib_build and setting the option to generate a NSIS installer as true:
  
	cmake -G 'Visual Studio 10' C:\Users\<user_name>\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=/usr/local/qwt-6.1.0/lib/libqwt.so.6.1.0

3. Go to the building directory selected in step 1 and run the appropriate building tool according
  to the generator you selected in step 2. (e.g. for Unix Makefiles just run "make").
   
===================================================
How to Build a Specific TerraLib Module Using CMake
===================================================

If you want to build a specific TerraLib module, for example the common module, that is found in the
directory "<terralib_root>/terralib/terralib_common", you can proceed the same steps as described above:

  - Create the directory "<building_dir>/terralib/terralib_common"
  
  - Using the CMake GUI:
  
      Where is the source code:    <terralib_root>/build/terralib/terralib_common
      Where to build the binaries: <building_dir>/terralib/terralib_common
      
  - Using the Command Prompt:
     
      cd "<building_dir>/terralib/terralib_common"
      
      cmake -G "Visual Studio 10"   "<terralib_root>/build/terralib/terralib_common"  (for Windows)
      
      cmake -G "Unix Makefiles"     "<terralib_root>/build/terralib/terralib_common"  (for UNIX-style platforms)

      
===============================================
Compiling TerraLib Using Eclipse CDT4 Generator
===============================================

It is mandatory to use the Command Prompt to generate the Debug version for the
TerraLib projects using the Eclipse CDT4 Generator, through the following commands:

  cd "<building_dir>/terralib"

  cmake -G "Eclipse CDT4 - Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug "<terralib_root>/build/terralib"

The command above will create the files .project and .cproject in the directory "<building_dir>/terralib"

Import the created project file into Eclipse:
     - Import project using Menu File->Import
     - Select General->Existing projects into workspace:
     - Browse where your build tree is and select the directory "<building_dir>/terralib".
       Keep "Copy projects into workspace" unchecked.
     - You get a fully functional eclipse project.
     
     
====================================================================
Instructions for Compiling Examples and Unittest projects with CMake
====================================================================

The proceedings for compiling the Examples and Unittest projects are similar to the 
TerraLib projects.

The source code directory will be:
  
  <terralib_root>/build/examples  (for the Examples projects)
  <terralib_root>/build/unittest  (for the Unittest projects)
  
The building directory will be:
  
  <building_dir>/examples  (for the Examples projects)
  <building_dir>/unittest  (for the Unittest projects)
  
  

