====== Building and Configuring GeoDMA ======

This small tutorial describes the steps to build and configure GeoDMA from its source code. It can be built and has been tested in Windows, Linux and Mac OSX Platforms. In all the platforms, GeoDMA dependes the external packages and libraries listed below. These libraries must be installed and configured separately.

===== External Dependencies =====

== Mandatory == 
   * CMake 3.11.X or Later (https://cmake.org/)
   * TerraLib 5.4.X (http://www.dpi.inpe.br/terralib5)
   * Qt 5.10.X (5.10.1  recomended - https://download.qt.io/official_releases/qt/5.10/5.10.1/)
   * CGAL 4.X (http://www.cgal.org)
   * Boost 1.65 (In windows, it comes together with TerraLib dependencies)
   * C5.0 Decision Trees Library (https://github.com/rvmaretto/c50_decisionTrees)
   * Python 2.7.X (https://www.python.org) -- **Required** for Code Style checking

== Optional ==
  * Google Test 1.X / Google Mock (https://github.com/google/googletest) -- **Mandatory** to the generate unit tests
  * NSIS 3.X -- **Mandatory** to generate installers on Windows environment.
  * Doxygen -- **Mandatory** to generate code documentation
  * LaTeX -- **Mandatory** for generating Doxygen code Documentation 
  * Ghostscript -- **Mandatory** for generating Doxygen code Documentation
  * SourceTree Git client for Windows or Mac (recomended)
  * SmartGit Git client for Linux (recomended)
  * Ms Visual Studio for Windows (2017 recomended)
  * XCode for Mac OSX (recomended)

===== Windows Environment (ref. 10 x64) =====

==== CMake 3.11.X (ref. 3.12.3) ====

Download CMake setup file and install it, adding the cmake command to the PATH environment variable (installer alread has an option to set up this option).

==== Ms Visual Studio (ref. 2017) ====

In order to build GeoDMA, TerraLib and other dependencies on Windows Environment, Ms Visual studio will be needed. We strongly recomend to use the 2017 version, once other versions were not tested.

==== NSIS (ref. 3.01) ====

Download NSIS from [[http://nsis.sourceforge.net/Download]]. Run the installer.

==== Python 2.7.X (ref. 2.7.13) ====

Download python 2.7.X from [[https://www.python.org/downloads/]]. Run the installer. We recomend to install it in the default folder //C:/python27//.

==== LaTeX Distribution (ref. MiKTeX 2.9) ====

Download one of the LaTeX distributions from [[https://www.latex-project.org/get/]] and install it. It is necessary to correctly generate some formulas in the Doxygen documentation.

==== Ghostscript (ref. 9.21 32-bit) ====

Download Ghostscript from [[https://www.ghostscript.com/download/gsdnld.html]] and install it. It is necessary to correctly generate some formulas in the Doxygen documentation. The default folde for instalation is //C:\Program Files (x86)\gs\gs9.21//. After installed, add the folder //C:\Program Files (x86)\gs\gs9.21\bin// in the //PATH// environment variable. 

==== Doxygen (ref. 1.8.13) ====

Download Doxygen from [[http://www.stack.nl/~dimitri/doxygen/download.html]]. Run the installer. We recomend to install it in the default folder //C:/Program Files/doxygen//.

==== Qt5.X (ref. 5.10.1) ====

Download Qt setup file and install it. After the installation is finished, add the following folders from Qt to the PATH environment variable. If you had installed Qt 5.10.1 the default configurations, it will be located at:
   C:/Qt/Qt5.10.1/5.10.1/msvc2017_64/lib/cmake/Qt5
   
   C:/Qt/Qt5.10.1/5.10.1/msvc2017_64/lib/cmake/Qt5LinguistTools

==== TerraLib 5.4.X (ref. release-5.4) ====

Clone TerraLib from git. In order to do that, you need to first disable the "SSL certificate validation" in your git client. If you are using SourceTree, go to //SourceTree// >> //Preferences// >> //Git// and then check //Disable SSL certificate validation (note: potentially insecure)// to allow downloading TerraLib. Then, clone it from the following Git repository:

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

After cloning the repository, set the current branch to the //release-5.4//, which is the currently used by GeoDMA. Further instructions for clonning TerraLib repository, if needed, can be found [[http://www.dpi.inpe.br/terralib5/wiki/doku.php?id=wiki:documentation:devguide:cloning|here]].
TerraLib has several external dependencies. For windows, a package with all of them is provided, already compiled with //Ms Visual Studio 2017//. This package can be downloaded through the following URL: 

http://www.dpi.inpe.br/terralib5-devel/3rdparty/bin/5.4/

Instructions to compile these dependencies in MS Windows, if needed, can be found [[http://www.dpi.inpe.br/terralib5/wiki/doku.php?id=wiki:documentation:devguide:dependencies|here]].

If you need credentials to download TerraLib, use:

  user = terralib5
  password = newterralib5
  
After downloading or compiling the TerraLib 3rdparty package, add its root directory to the PATH environment variable.

Detailed instructions to build TerraLib can be found [[http://www.dpi.inpe.br/terralib5/wiki/doku.php?id=wiki:documentation:devguide:build|here]]

To build TerraLib, open the CMake GUI, put in //Where is the source code// field the path to the folder //terralib/build/cmake//. Create a directory to build the binaries. We recomend to create the folder //terralib/built//, and put its path in the field //Where to build the binaries//. Then click //Configure//. In the pop up window, select "//Visual Studio 15 2017 Win64//". After the project has finished to configure, click //Generate//. A Visual studio solution called //terralib.sln// will be generated in the binaries folder. Now, just open it and build.

=== Tips and Tricks ===

Following topics present some tricks to configurate TerraLib environment and its CMake Variables:

  * If you will work with TerraLib in its working environment, instead of install it in your machine, check the Variable //TERRALIB_BUILD_AS_DEV//. In the same way, it must be unchecked if you will install it in your machine and work with it in the installation directory structure. 
  * In Windows environments, TerraLib Examples and UnitTests take a long time to build. Thus, if you will not work directly with the examples and tests, we recomend to uncheck CMake variables //TERRALIB_BUILD_EXAMPLES_ENABLED// and //TERRALIB_BUILD_UNITTEST_ENABLED//.
  * To Correctly generate installers, you must check variables //TERRALIB_BUILD_AS_BUNDLE// and //TERRALIB_TRACK_3RDPARTY_DEPENDENCIES//.

==== Google Test and Google Mock (ref. 1.8) ====

Download Google Test from its [[https://github.com/google/googletest/releases|releases page on GitHub]]. It will be a .zip file with the source code and some projects to build it. Unzip this file. We suggest to unzip at //C:/googletest-1.8.0// (this is the default directory where GeoDMA CMake will look for google test, thus, if you use another folder, you will need to change the value of the variable //GTEST_ROOT// in GeoDMA CMake) . Inside this folder, there are two projects, //googletest// and //googlemock//. First, build googletest. 

==== Google Test ====
Go to the folder //googletest-1.8.0/googletest/msvc//.
Inside this folder, there are two Visual Studio solutions. Open the solution called //gtest-md.sln//. This solution was built in an older version of Visual Studio, but Visual Studio automatically convert it to the current version (2017) without problems. After opened, some configurations must be set. This project was built for 32-bit compiling, but we will configure it to generate 64-bit projects. To do this, follow these steps: 

  - Inside Visual Studio Environment, Right click the solution and go to //Properties//. Then, click "//Configuration Manager...//" button. It will open a pop up window.
  - In the field //Active Solution Platform//, select //<new>//.
  - In the new pop up window, in the combo box //Type or select the new platform//, select //x64//. In the field //Copy settings from//, select //win32//.
  - Then, do the next steps for each one of the four projects in the solution:
    - Right click the project and go to //Properties// >> //Configuration Properties// >> //General//.
    - In the field //Output Directory//, replace the current value by //$(SolutionName)/$(Configuration)\//
    - Go to //Configuration Properties// >> //C/C++// >> //Code Generation//.
    - In the field //RuntimeLibrary//, change the value to //Multi-threaded DLL (/MD)// in the Release Configuration and to //Multi-threaded Debug (/MTd)// in the Debug configuration.
    - Switch the project configuration to Release and repeat the two steps above.
  - Build the solution for Debug AND Release. Some errors may occur in the project //gtest_unittest//, **ignore it**. Warnings can either be ignored.

==== Google Mock ====

Go to the folder //googletest-1.8.0/googlemock/msvc/2010//.
Inside this folder, open the solution called //gmock.sln//. This solution was built in an older version of Visual Studio (2010), but Visual Studio automatically convert it to the current version (2017) without problems. After opened, some configurations must be set. Like google test, this project was either built for 32-bit compiling, but we will configure it to generate 64-bit projects. To do this, follow these steps: 

  - Inside Visual Studio Environment, Right click the solution and go to //Properties//. Then, click "//Configuration Manager...//" button. It will open a pop up window.
  - In the field //Active Solution Platform//, select //<new>//.
  - In the new pop up window, in the combo box //Type or select the new platform//, select //x64//. In the field //Copy settings from//, select //win32//.
  - Then, do the next steps for each one of the three projects in the solution:
    - Right click the project and go to //Properties// >> //Configuration Properties// >> //General//.
    - In the field //Output Directory//, replace the current value by //$(SolutionName)/$(Configuration)\//
    - In the field //Target Name//, replace the current value by //$(ProjectName)d//
    - Go to //Configuration Properties// >> //C/C++// >> //Code Generation//.
    - In the field //RuntimeLibrary//, change the value to //Multi-threaded DLL (/MD)// in the Release Configuration and to //Multi-threaded Debug DLL (/MDd)// in the Debug configuration.
    - Switch the project configuration to Release and repeat the two steps above.
  - Build the solution for Debug AND Release. Some errors may occur in the project //gmock_test//, **ignore it**. Warnings can either be ignored.

==== CGAL 4.X (ref. 4.10) ====

Download CGAL installer (CGAL-4.10-Setup.exe) from [[https://github.com/CGAL/cgal/releases|the release area of its GitHub repository]]. This setup will only install the source code to your machine. Run it, selecting 64-bits platform. When asked to the //Destination Folder//, we suggest you to put it in //C:/dev/CGAL-4.10// (default folder). When asked to set environment variables //CGAL_DIR// and //PATH//, agree with the setting of both.
After the configuration of this setup, the code is ready to be configured and built. 

If you are using pre-compiled dependencies of TerraLib (3rdparty package), you will need to insert some flags in CGAL CMake files.

  * **In the file //CGAL-4.10/src/CGAL/CMakeLists.txt//, insert the following lines:**

   if(MSVC)
       add_definitions(-DBOOST_ALL_NO_LIB -DBOOST_FILESYSTEM_VERSION=3 -DBOOST_UBLAS_TYPE_CHECK=0 -DBOOST_LOG_DYN_LINK)
   endif()
   
and replace the following line:
  
   target_link_libraries(CGAL ${CGAL_3RD_PARTY_LIBRARIES})
   
by:
  
   target_link_libraries(CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${Boost_LIBRARIES})
   

  * **In the file //CGAL-4.10/src/CGAL_Core/CMakeLists.txt//, insert the following lines:**

   if(MSVC)
       add_definitions(-DBOOST_ALL_NO_LIB -DBOOST_FILESYSTEM_VERSION=3 -DBOOST_UBLAS_TYPE_CHECK=0 -DBOOST_LOG_DYN_LINK)
   endif()
   
and replace the following line:
  
   target_link_libraries( CGAL_Core CGAL ${CGAL_3RD_PARTY_LIBRARIES})
   
by:
  
   target_link_libraries( CGAL_Core CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${Boost_LIBRARIES})


  * **In the file //CGAL-4.10/src/CGAL_ImageIO/CMakeLists.txt//, insert the following lines:**

   if(MSVC)
       add_definitions(-DBOOST_ALL_NO_LIB -DBOOST_FILESYSTEM_VERSION=3 -DBOOST_UBLAS_TYPE_CHECK=0 -DBOOST_LOG_DYN_LINK)
   endif()
   
and replace the following line:
  
   target_link_libraries( CGAL_ImageIO CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${CGAL_ImageIO_3RD_PARTY_LIBRARIES})
   
by:
  
   target_link_libraries( CGAL_ImageIO CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${CGAL_ImageIO_3RD_PARTY_LIBRARIES} ${Boost_LIBRARIES})


  * **In the file //CGAL-4.10/src/CGAL_Qt5/CMakeLists.txt//, insert the following lines:**

   if(MSVC)
       add_definitions(-DBOOST_ALL_NO_LIB -DBOOST_FILESYSTEM_VERSION=3 -DBOOST_UBLAS_TYPE_CHECK=0 -DBOOST_LOG_DYN_LINK)
   endif()
   
and replace the following line:
  
   target_link_libraries( CGAL_Qt5 CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${CGAL_Qt5_3RD_PARTY_LIBRARIES} )
   
by:
  
   target_link_libraries( CGAL_Qt5 CGAL ${CGAL_3RD_PARTY_LIBRARIES} ${CGAL_Qt5_3RD_PARTY_LIBRARIES} ${Boost_LIBRARIES})

Create the folder //C:/dev/CGAL-4.10/built//. Then, open CMake Gui. In the field //Where is the source code//, put the folder //C:/dev/CGAL-4.10//. In the field //Where to build the binaries//, put the folder //C:/dev/CGAL-4.10/built// and click //Configure//. In the pop up window, select “Visual Studio 15 2017 Win64” and click //Finish//. After the project has finished to //Configure//, click Generate. A Visual studio solution called //CGAL.sln// will be generated in the binaries folder. Now, just open it and build for Debug and Release configurations.

After the solution was built for Debug and Release, you will need to install CGAL in the system. To execute this step, Visual Studio will need administrator privileges. Close Visual Studio. After closed, right click on it and go to //Run as Administrator//. After Visual Studio was opened with administrator privileges, open the solution //CGAL.sln// and build the project //INSTALL// for Debug and Release, respectively.

==== C5.0 Decision Trees Library ====

Clone //C5.0 Decision Trees Library// from the following GitHub repository: 

  https://github.com/rvmaretto/c50_decisionTrees
  
To build the library, open the CMake GUI, put in //Where is the source code// field the path to the folder //c50_decisionTree/build/cmake//. Create a directory to build the binaries. We recomend to create the folder //c50_decisionTree/built//, and put its path in the field //Where to build the binaries//.

Click //Configure//.

In the pop up window, select “//Visual Studio 15 2017 Win64//”. After the project has finished to configure, click //Generate//. A Visual studio solution called c50_decisionTree.sln will be generated in the binaries folder. Now, just open it and build.


==== Building GeoDMA ====

After installing all the dependencies above, you can build GeoDMA. Clone it from git, in the following repository: 

   https://git.dpi.inpe.br/geodma
   
If you need credentials to clone the repository, put this: 

   user = geodma
   password = geodma

To build GeoDMA, open the CMake GUI, put in //Where is the source code// field the path to the folder //geodma/build/cmake//. Create a directory to build the binaries. We recomend to create the folder //geodma/built//, and put its path in the field //Where to build the binaries//.

If cmake can not find any of the dependencies, or if they were not installed in the default directories, set the following variables for the corresponding //not found// dependency:

^ Dependency   ^  Variable     ^ Description                              ^ Default value             ^
| TerraLib     | terralib_DIR  | Folder containing cmake configuration file for TerraLib  | C:/Program Files/terralib5.4.0 |
| TerraLib     | terralib_DEPENDENCIES_DIR | Root folder of TerraLib 3rdparty package | ${GEODMA_ROOT_DIR}/../dependencies/terralib5-3rdparty-msvc-2013-win64 |
| TerraLib     | terralib_ROOT | Root folder of TeraLib                | No default value, automatically searched by CMake |
| Google Test  | GTEST_ROOT    | Root folder of Google Test            | C:/gtest-1.8.0/googletest |
| Google Mock  | GMOCK_ROOT    | Root folder of Google Mock            | C:/gtest-1.8.0/googlemock |
| CGAL  | CGAL_DIR    | Folder containing cmake configuration file for CGAL  | No default value, automatically searched by CMake |

Click //Configure//.

In the pop up window, select “//Visual Studio 15 2017 Win64//”. After the project has finished to configure, click //Generate//. A Visual studio solution called geodma.sln will be generated in the binaries folder. Now, just open it and build.

===== Linux Environment (ref. ....) =====

<html>
<span style="color:red;font-size:150%;">Under construction</span>
</html>

===== Mac OSX Environment (ref. ....) =====

<html>
<span style="color:red;font-size:150%;">Under construction</span>
</html>