====== TerraLib 5.0 - General guide for Building and Install ====== Useful links: * [[wiki:terralib5_build#CMake_Command_Line_Notes| Using Cmake Command line]] ===== Building Terralib ===== This section explains how to build the TerraLib from source code in some platforms. The most updated instructions are in BUILD-INSTRUCTIONS file located at the root of the terralib codebase directory. Here are the general instructions and might not have all variables needed for a specific release. ==== 1. Build instructions on Linux with g++ (GNU gcc) ==== ----------------------------------------------------------- 1.1. Open a Command Prompt (Shell). 1.2. We will assume that the codebase (all the source tree) is located at: /home/user/terralib/codebase 1.3. Create a folder out of the terralib source tree, for example: $ cd /home/user/terralib $ mkdir build-linux $ cd build-linux 1.4. For Linux systems you must choose the build configuration: $ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING="Release" -DCMAKE_INSTALL_PREFIX:PATH="/usr/local/terralib" ../codebase/build/cmake Notes: a) Some Linux flavours with different versions of GNU gcc and Boost will need more parameters such as: -DCMAKE_PREFIX_PATH:PATH="/usr/local;/opt/include" -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" b) Boost can also be indicated by BOOST_INCLUDEDIR (note: without an '_' separating INCLUDE and DIR): -DBOOST_INCLUDEDIR:PATH="/usr/local/include" c) The parameter -lpthread must be informed only if your Boost was not built as a shared library: -DCMAKE_CXX_FLAGS:STRING="-lpthread" d) For building with Qt5 you can provide the Qt5_DIR variable as: -DQt5_DIR:PATH="/usr/local/lib/cmake/Qt5" e) For generating a debug version set CMAKE_BUILD_TYPE as: -DCMAKE_BUILD_TYPE:STRING="Debug" 1.5 Building: $ make -j 4 1.6 Installing: $ make install ==== 2. Building with CMake GUI ==== -------------------------- 2.1 On Windows: a) We will assume that the TerraLib source tree (git clone) is located at: C:\terralib\codebase b) We will assume that the third party libraries, obtained from http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-win32-Qt5.zip or http://www.dpi.inpe.br/terralib5-devel/terralib5-3rdparty-win64-Qt5.zip are located at: C:\terralib\3rdparty-win32-qt5 or C:\terralib\3rdparty-win64-qt5 c) Create a folder out of the TerraLib source tree to build the binaries, for example: C:\terralib\build-win32 or C:\terralib\build-win64 d) Open CMake-GUI in order to generate a build project for Microsoft Visual C++ 2010 (32-bit or 64-bit). f) Then assure that the following variables are set to the locations defined above: Where is the source code => C:\terralib\codebase\build\cmake Where to build the binaries => C:\terralib\build-win32 or C:\terralib\build-win64 g) Then add an entry called CMAKE_PREFIX_PATH with the libraries location (separated by semicolons): Microsoft SDK => C:/Program Files (x86)/Microsoft SDKs/Windows/v7.0A TerraLib 5 Third party => C:/terralib/3rdparty-win32-qt5 Qt CMake => C:/Qt/Qt5.3.0/5.3/msvc2010_opengl/lib/cmake/Qt5 Example: Press AddEntry button and inform the name CMAKE_PREFIX_PATH, type PATH and set its value as: CMAKE_PREFIX_PATH => C:/Program Files (x86)/Microsoft SDKs/Windows/v7.0A;C:/terralib/3rdparty-win32-qt5;C:/Qt/Qt5.3.0/5.3/msvc2010_opengl/lib/cmake/Qt5 h) Then press "Configure" and if no problem occurs press "Generate". Note: Some projects may be disabled through the following variables: TERRALIB_BUILD_EXAMPLES_ENABLED => OFF TERRALIB_BUILD_UNITTEST_ENABLED => OFF i) Open the generated terralib.sln solution at the folder C:\terralib\build-win32. Then build the "ALL_BUILD" project to build all terralib projects, including terraview application. j) To run and debug terraview application, set it as StartUp Project at Microsoft Visual C++ 2010. k) To run and debug examples and/or unittests make sure the data (http://www.dpi.inpe.br/terralib5-devel/data.zip) used are located at the default directory: TERRALIB_DATA_DIR C:\terralib\build-win32\data l) Make sure the default directory used to save the reports generated by the unittests exist, otherwise no report will be saved: TERRALIB_REPORT_DIR C:\terralib\build-win32\report 2.2 On MacOs and Linux: a) We will assume that the TerraLib source tree (git clone) is located at: /home/user/terralib5 b) We wil assume that the build tree where will be generated the binaries is located at: /home/user/build_terralib5 c) We will assume that all the third-party libraries that TerraLib needs to be compiled are installed in your system, and the Qt5 version is used. d) Open CMake-GUI in order to generate a build project for MacOS or Linux: e) Then assure that the following variables are set to the locations defined above: Where is the source code => /home/user/terralib5 Where to build the binaries => /home/user/build_terralib5 f) Then press the Add Entry button containing the following CMake variables: Name: CMAKE_PREFIX_PATH Type: PATH Value: /qt5_install_dir/lib/cmake/Qt5 and Name: CMAKE_BUILD_TYPE Type: String Value: Release(or Debug) g) Then press "Configure" button. If it is the first time that you press this button, select the Generator to be used (Makefile or a selected IDE like Eclipse for Linux, or XCode for MacOS) Note: Some projects may be disabled through the following variables: TERRALIB_BUILD_EXAMPLES_ENABLED => OFF TERRALIB_BUILD_UNITTEST_ENABLED => OFF h) According to the generator selected previously, in the build tree directory(/home/user/build_terralib5) will be generated a Makefile or the file corresponding to the IDE selected. i) TerraLib/TerraView can be compiled calling make for the Makefile Generator, Eclipse (for Linux) or XCode (for MacOS). j) To run and debug terralib_example_* and/or terralib_unittest_* make it the current project and make sure the data (http://www.dpi.inpe.br/terralib5-devel/data.zip) used are located at the build directory: TERRALIB_DATA_DIR /home/user/build_terralib5/data k) Make sure the default directory used to save the reports generated by the terralib_unittest_* exists, otherwise no report will be saved: TERRALIB_REPORT_DIR /home/user/build_terralib5/report For more information on TerraLib, please, visit its main web page at: http://www.terralib.org. ==== CMake command line notes==== Using the CMake command line to build the compilation projects. If you do not have or do not wish to use the CMake-Gui, it is possible to run CMake via command line. Here is some information on how to do it: First, a quick warning, by default the building directory will be the same directory you invoked the CMake command from. It is advisable to avoid in-source compilations, so you should manually create a building directory and invoke CMake from it, or invoke the CMake command referring a path to an existing build. From the command line, invoke the CMake command setting the options as you see fit. This is done with using the syntax: -DVARIABLE:TYPE=VALUE. The table bellow exemplifies some variables that can be set in cmake command line. ^Variable^Effect^Example^ | CMAKE_BUILD_TYPE | Sets the build type. Such as Debug or Release | -DCMAKE_BUILD_TYPE=Debug | | QWT_INCLUDE_DIR | Sets the include path of the QWT library | -DQWT_INCLUDE_DIR= | | QWT_LIBRARY_DEBUG | Sets the path of the QWT library in Debug | -DQWT_LIBRARY_DEBUG= | | QWT_LIBRARY_RELEASE | Sets the path of the QWT library in Release | -DQWT_LIBRARY_RELEASE= | | LOG4CXX_INCLUDE_DIR | Log4Cxx headers include path | -DLOG4CXX_INCLUDE_DIR= | | LOG4CXX_LIBRARY_DEBUG | Log4Cxx debug library file path | -DLOG4CXX_LIBRARY_DEBUG= | | LOG4CXX_LIBRARY_RELEASE | Log4Cxx release library file path | -DLOG4CXX_LIBRARY_RELEASE= | | BOOST_INCLUDEDIR | Boost headers include path | -DBOOST_INCLUDEDIR= | | GDAL_INCLUDE_GCORE | GDAL headers include path | -DGDAL_INCLUDE_GCORE= | | GDAL_INCLUDE_ALG | GDAL headers include path | -DGDAL_INCLUDE_ALG= | | GDAL_INCLUDE_OGR | GDAL headers include path | -DGDAL_INCLUDE_OGR= | | GDAL_INCLUDE_PORT | GDAL headers include path | -DGDAL_INCLUDE_PORT= | | GDAL_LIBRARY_DEBUG | GDAL debug library file path | -DGDAL_LIBRARY_DEBUG= | | GDAL_LIBRARY_DEBUG | GDAL release library file path | -DGDAL_LIBRARY_DEBUG= | | GEOS_INCLUDE_DIR | GEOS headers include path | -DGEOS_INCLUDE_DIR= | | GEOS_LIBRARY_DEBUG | GEOS debug library file path | -DGEOS_LIBRARY_DEBUG= | | GEOS_LIBRARY_RELEASE | GEOS release library file path | -DGEOS_LIBRARY_RELEASE= | When using cmake from the command line you should specifiy the generator as follows: -G Some commonly used generators are: ^Name^Platform^Example^ | Visual Studio 10 | Generates Visual Studio 10 project | -G "Visual Studio 10" | | Unix Makefiles | Generates standard UNIX makefiles | -G "Unix Makefiles" | | Apple XCode | Generates XCode project | -G Xcode | A few examples of how to call CMake to build terralib: * Calling from a building dir while pointing to the source (main CmakeLists location), specifying Unix Makefiles as a generator, compiling in Release $ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH="/usr/local/terralib" ../codebase/build/ * Specifying Visual Studio 10 as the generator, using source code located at C:\Dev\Terralib\build and setting the option to generate a NSIS installer as true: $ cmake -G 'Visual Studio 10' C:\Dev\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//terralib5/build -DCMAKE_BUILD_TYPE=Release -DQWT_INCLUDE_DIR=/usr/local/qwt-6.1.0/include -DQWT_LIBRARY_RELEASE=/usr/local/qwt-6.1.0/lib/libqwt.so.6.1.0 == Notes for Linux build == If using non-Standard third party library locations with cmake the following environmental variables must be configured before running cmake: ^Variable^Effect^Example^ | LD_LIBRARY_PATH | A colon-separated set of directories where third party libraries should be searched for first, before the standard set of directories | LD_LIBRARY_PATH=/home/user/mylibraries |