====== TerraLib 5.0.0-alpha - Build and Install ====== Useful links: * [[wiki:terralib5_build#general_information| General Informationm]] * [[wiki:terralib5_build#Cmake-GUI| Using the Cmake-GUI]] * [[wiki:terralib5_build#Cmake_Command_Line| Using Cmake Command line]] * [[wiki:terralib5_build#ccmake| Using Ccmake]] * [[wiki:terralib5_build#building_the_examples| Examples]] ===== Building Terralib ===== This section explains how to build the TerraLib from source in some platforms. ==== General Information==== We will refer to your TerraLib local working directory as and the building directory as The local working directory is where the source code is located and the building directory is where CMake will create the build system for your chosen platform and compiler, and also where the libraries will be compiled. Under //''/build''// you will see CMake files and the following sub-folders: ^ Folder ^ Content ^ | examples| general CMakeLists.txt scripts for all examples and subfolders to each TerraLib example with a specific CMakeLists.txt script | | modules| CMake utility files, such as finds and package generators | | terralib| general .cmake script for all TerraLib and subfolders to each TerraLib module with a specific CMakeLists.txt script | | terralib_qt_plugins| general .cmake script for all the qt plug-ins | | terraview| Files used to configure TerraView | | third-party | Files used to build third-party libraries | | unittest| general CMakeLists.txt script for all unittests and subfolders to each TerraLib unittest with a specific CMakeLists.txt script | Pay attention to some variables used by CMake and explained below: ^Variable^Comment^Value^ | TE_DEPENDENCIES_DIR | path where the third party libraries are located | it can be defined as an environmental variable otherwise define it at CMake interface using ''Add Entry'' button, type ''PATH'', value ''//C:\\terralib_3rdparty_win32//''| | TE_BIN_DIR | path where the executable will be generated | it is automatically set by CMake based on ''///bin32//'' | | QT_QMAKE_EXECUTABLE | path where Qt4 qmake.exe is located | . It is only necessary if CMake can not find Qt4. In this case, define it at CMake interface using ''Add Entry'' button, type ''PATH'' and a value such as ''//C:/Qt/4.8.5/bin/qmake.exe//''| | TE_HELP_DIR | path where the TerraView HELP files are located | it can be defined as an environmental variable otherwise define it at CMake interface using ''Add Entry'' button, type ''PATH'', value ''//C://terraview_help//'' | ==== Cmake-Gui ==== Using the Graphic Interface (cmake-gui) to build the compilation projects. To run CMake from the cmake-gui, you will: * Execute the cmake-gui system, found in the CMake binary folder. * In the "Where is the source code", put the path where is the CMakeLists main file. For terralib it is /build * In the "Where to build the binaries", put the path where you want the CMake generate the files. For terralib it can be /terralib. * (Optional) Set up the TE_DEPENDENCIES_DIR. Press the Add Entry button and adjust the path to the dependencies directory, for example: {{ :wiki:add-entry.png?400 |}} * Click "Configure" and select the generator for the project. * Review the "BUILD" group and check which module you want to build. * 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. * Click "Generate" After these steps, the build files will have been generated and the cmake-gui will look like this: {{ :wiki:cmake-gui.png?1080 |}} Now all you need to do is go to the selected building directory and run the appropriate building tool according to the generator you selected. (e.g. for Unix Makefiles just run "make"). ==== CMake command line ==== 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 | | BUILD_TERRALIB4 | Enable/disable [ON/OFF] the TerraLib4 module | -DBUILD_TERRALIB4=OFF | | 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= | | TE_DEPENDENCIES_DIR | Used as an easy and convenient way to locate terralib's dependencies | -DTE_DEPENDENCIES_DIR=/terralib_3rdparty_win32 | | 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: * 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 | ==== CCmake ==== Using the curses based Interface (ccmake) to build the compilation projects. On some Unix platforms, you can install a curses based cmake gui that is a terminal based text application and can be used as well. The commands are basically the same as before, but instead of using "cmake" use "ccmake" instead. Example: ccmake /home//source/terralib5/build (Executed from the ) {{ :wiki:ccmake.png?1080 |}} Once executed, the user can manually adjust the variables and customize the compilation. Once the options have been adjusted type c to configure the project and then type g to generate the build files and exit ccmake. ===== Building the Examples ===== This section will detail the proccess of building the examples after building or installing Terralib. Some examples are listed here: ^ Folder ^ Content ^ | example_ado| It shows how to interact with Microsoft Access driver. | | example_dataaccess| It shows how to interact with DataAccess Module and drivers PostGIS, ORG and GDAL| | example_geometry| It shows how to create geometries and some Spatial Operators.| | terralib_raster| It shows how to manipulate raster data.| | example_rp| It show how use the raster processing module.| | example_srs| It shows how to use the sapatial reference system manager. | | example_st| It show how to use the Spatial Temporal Module.| | example_vp| It shows how to use the Vector Processing Module.| The proccess is similar to Terralib's proccess, steps such as using the cmake-gui or command line are similar, however, there a few differences worth mentioning. First, in order to build either the examples cmake must be told where is the CMakeLists main file which is /build/examples. Also, examples use a few variables that can edited, they are: ^Variable^Comment^Value^ |terralib_DIR | Where terralib has been built/installed | it can either be defined as an environmental variable or be defined at the CMake interface using the Add Entry button, type PATH, value /terralib | | DATA_DIR | where the data used by the examples will be downloaded and unpacked | Inform the path where you downloaded the http://www.dpi.inpe.br/terralib5/data.zip | After pressing ''Configure'', Review the "EXAMPLE" group and check which example you want to build. Some are already checked and you can keep or change the examples that will be compiled, for example: {{:wiki:examples-compilation.png|}} You can edit these variables in the same way used to configure terralib's variables. Once you are done, just ''Configure'' and ''Generate'' the build files in the same way explained on the terralib section.