CGAL 4.12 - Manual
Installation

# Introduction

This document describes how to install CGAL on Windows, Unix-like systems, and MacOS X.

Ideally, setting up CGAL amounts to:

cd CGAL-4.12 # go to CGAL directory
cmake . # configure CGAL
make # build the CGAL libraries


Compiling an example or a demo shipped with CGAL is similarly simple:

cd examples/Straight_skeleton_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-4.12 . # configure the examples make # build the examples  cd demo/Straight_skeleton_2 # go to a demo directory cmake -DCGAL_DIR=$HOME/CGAL-4.12 . # configure the demos
make # build the demos


Compiling an own non-shipped program is also close:

cd /path/to/program
cgal_create_CMakeLists -s executable

# Multiple Variants of Makefiles (out-of-source build)

While you can choose between release or debug builds, and shared or static libraries, it is not possible to generate different variants during a single configuration. You need to run CMake in a different directory for each variant you are interested in, each with its own selection of configuration parameters.

CMake stores the resulting makefiles and project files, along with several temporary and auxiliary files such as the variables cache, in the directory where it is executed, called CMAKE_BINARY_DIR, but it takes the source files and configuration scripts from CMAKE_SOURCE_DIR.

The binary and source directories do not need to be the same. Thus, you can configure multiple variants by creating a distinct directory for each configuration and by running CMake from there. This is known in CMake terminology as out-of-source configuration, as opposite to an in-source configuration, as showed in the previous sections.

You can, for example, generate subdirectories CGAL-4.12/cmake/platforms/debug and CGAL-4.12/cmake/platforms/release for two configurations, respectively:

mkdir CGAL-4.12/cmake/platforms/debug
cd CGAL-4.12/cmake/platforms/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../..
mkdir CGAL-4.12/cmake/platforms/release
cd CGAL-4.12/cmake/platforms/release
cmake -DCMAKE_BUILD_TYPE=Release ../../..


# Configuring and Building Programs Using CGAL

Ideally, configuring and compiling a demo/example/program amounts to

cd CGAL-4.12/examples/Straight_skeleton_2
cmake -DCGAL_DIR=$HOME/CGAL-4.12 . make In this ideal world, as for all shipped examples and demos of CGAL, the required CMakeLists.txt is already provided. CMake can also be used to configure and build user programs via such CMake-scripts. In this less ideal world, one has to provide the CMakeLists.txt script either manually, or with the help of a shell-script that is introduced below. For a user program executable.cpp, the ideal world looks like this: cd /path/to/program cgal_create_CMakeLists -s executable cmake -DCGAL_DIR=$HOME/CGAL-4.12 .
make


In both examples we specify the CGAL_DIR: During configuration of the CGAL libraries a file named CGALConfig.cmake is generated in CGAL's root directory (in contrast to CGAL's source directory that has been used for installation). This file contains the definitions of several CMake variable that summarize the configuration of CGAL. In order to configure a program, you need to indicate the location of that config file in the CMake variable CGAL_DIR (as indicated in the example above). CGAL_DIR can also be an environment variable. Setting CGAL_DIR makes particular sense if having multiple out-of-source builds of CGAL as in Section Multiple Variants of Makefiles (out-of-source build).

If you have installed CGAL, CGAL_DIR must afterwards be set to $CMAKE_INSTALLED_PREFIX/lib/CGAL. Note that CGAL is recommended to be installed in release mode when using it to build programs. ## Creating a CMake Script for a Program Using CGAL For compiling a non-shipped program, it is recommended, to also rely on a CMake-supported configuration using a CMakeLists.txt used for configuration. Use the following Bourne-shell script for programs that are relatively simple to configure: ## cgal_create_CMakeLists The Bourne-shell script cgal_create_CMakeLists.txt resides in the CGAL-4.12/scripts directory. It can be used to create CMakeLists.txt files for compiling CGAL applications. Executing cgal_create_CMakeLists.txt in an application directory creates a CMakeLists.txt containing rules to build the contained application(s). Three command line options determine details of the configuration. -s source If this parameter is given the script will create a single executable for 'source' linked with compilations of all other source files (*.cc, *.cp, *.cxx, *.cpp, *.CPP, *.c++, or *.C). This behaviour is usually needed for (graphical) demos. If the parameter is not given, the script creates one executable for each given source file. -c com1:com2:... Lists components ("com1", "com2") of CGAL to which the executable(s) should be linked. Valid components are CGAL's libraries (i.e. "Core", "ImageIO", and "Qt5") and all preconfigured 3rd party software, such as "MPFI", "RS3"). An example is -c Core:GMP:RS3:MPFI -b boost1:boost2:... Lists components ("boost1", "boost2") of Boost to which the executable(s) should be linked. Valid options are, for instance, "filesystem" or "program_options". This options should suffice to create CMakeLists.txt script for most directories containing programs. However, in some special cases, it might still be required to create the script manually, for instance, if some source files/executables need a different linking than other source files. ## cgal_create_cmake_script Such a shell-script simply creates a CMake script. Processing it with CMake, searches for CGAL using find_package. If found, the variable CGAL_USE_FILE is set to a compilation environment CMake file. Including this file within a CMake script sets up include paths and libraries to link with CGAL and essential third party libraries. Beyond, find_package can demand for COMPONENTS of CGAL, that is, all CGAL libraries libCGAL_Core (Core), libCGAL_ImageIO (ImageIO), and libCGAL_Qt5 (Qt5) or optional 3rd party software such as MPFI, RS3. A user is free to create the CMakeLists.txt without calling the script (manual creation). ## Custom Flags in the Programs Using CGAL Normally, programs linked with CGAL must be compiled with the same flags used by the compilation of CGAL libraries. For this reason, the very first time a program is configured, all the flags given by the CMake variables CMAKE_*_FLAGS are locked in the sense that the values recorded in CGALConfig.cmake are used to override any values given by CMake itself or yourself. This does not apply to the additional flags that can be given via CGAL_*_FLAGS. Such inherited values are then recorded in the current CMake cache for the program. The flags are then unlocked in the sense that at any subsequent configuration you can provide your own flags and this time they will not be overridden. When using the interactive cmake-gui the first press on Configure unlocks the flags, so that you can edit them as needed. Advanced The locking of flags is controlled by the variable CGAL_DONT_OVERRIDE_CMAKE_FLAGS which starts out FALSE and is toggled right after the flags have been loaded from CGALConfig.cmake. If you use the command line tool you can specify flags directly by setting the controlling variable right up front: cd CGAL-4.12 cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-g . cd CGAL-4.12/examples/Straight_skeleton_2 cmake -DCGAL_DIR=CGAL-4.12 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS=-O2 -DCGAL_DONT_OVERRIDE_CMAKE_FLAGS=TRUE .  # Summary of CGAL's Configuration Variables Most configuration variables are not environment variables but CMake variables. They are given in the command line to CMake via the -D option, or passed from the interactive interface of cmake-gui. Unless indicated differently, all the variables summarized below are CMake variables. ## Component Selection The following boolean variables indicate which CGAL components to configure and build. Their values can be ON or OFF. Variable Default Value WITH_examples OFF WITH_demos OFF WITH_CGAL_Core ON WITH_CGAL_Qt5 ON WITH_CGAL_ImageIO ON ## Compiler and Linker Flags The following variables specify compiler and linker flags. Each variable holds a space-separated list of command-line switches for the compiler and linker and their default values are automatically defined by CMake based on the target platform. Have in mind that these variables specify a list of flags, not just one single flag. If you provide your own definition for a variable, you will entirely override the list of flags chosen by CMake for that particular variable. The variables that correspond to both debug and release builds are always used in conjunction with those for the specific build type. Program Both Debug and Release Release Only Debug Only C++ Compiler CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_RELEASE CMAKE_CXX_FLAGS_DEBUG Linker (shared libs) CMAKE_SHARED_LINKER_FLAGS CMAKE_SHARED_LINKER_FLAGS_RELEASE CMAKE_SHARED_LINKER_FLAGS_DEBUG Linker (static libs) CMAKE_MODULE_LINKER_FLAGS CMAKE_MODULE_LINKER_FLAGS_RELEASE CMAKE_MODULE_LINKER_FLAGS_DEBUG Linker (programs) CMAKE_EXE_LINKER_FLAGS CMAKE_EXE_LINKER_FLAGS_RELEASE CMAKE_EXE_LINKER_FLAGS_DEBUG ## Additional Compiler and Linker Flags The following variables can be used to add flags without overriding the ones defined by cmake. Program Both Debug and Release Release Only Debug Only C++ Compiler CGAL_CXX_FLAGS CGAL_CXX_FLAGS_RELEASE CGAL_CXX_FLAGS_DEBUG Linker (shared libs) CGAL_SHARED_LINKER_FLAGS CGAL_SHARED_LINKER_FLAGS_RELEASE CGAL_SHARED_LINKER_FLAGS_DEBUG Linker (static libs) CGAL_MODULE_LINKER_FLAGS CGAL_MODULE_LINKER_FLAGS_RELEASE CGAL_MODULE_LINKER_FLAGS_DEBUG Linker (programs) CGAL_EXE_LINKER_FLAGS CGAL_EXE_LINKER_FLAGS_RELEASE CGAL_EXE_LINKER_FLAGS_DEBUG ## Miscellaneous Variables Variable Description Type Default Value CMAKE_BUILD_TYPE Indicates type of build. Possible values are 'Debug' or 'Release' CMake Release CMAKE_CXX_COMPILER Full-path to the executable corresponding to the C++ compiler to use. CMake platform-dependent CXX Idem Environment Idem ## Variables Used Only When Building Programs (Such as Demos or Examples) Variable Description Type Default Value CGAL_DIR Full-path to the binary directory where CGAL was configured Either CMake or Environment none ## Variables Providing Information About 3rd-Party Libraries The following variables provide information about the availability and location of the 3rd party libraries used by CGAL. CMake automatically searches for dependencies so you need to specify these variables if CMake was unable to locate something. This is indicated by a value ending in NOTFOUND. Since 3rd-party libraries are system wide, many of the CMake variables listed below can alternatively be given as similarly-named environment variables instead. Keep in mind that you must provide one or the other but never both. ## Boost Libraries In most cases, if Boost is not automatically found, setting the BOOST_ROOT variable is enough. If it is not, you can specify the header and library directories individually. You can also provide the full pathname to a specific compiled library if it cannot be found in the library directory or its name is non-standard. By default, when Boost binary libraries are needed, the shared versions are used if present. You can set the variable CGAL_Boost_USE_STATIC_LIBS to ON if you want to link with static versions explicitly. On Windows, if you link with Boost shared libraries, you must ensure that the .dll files are found by the dynamic linker, at run time. For example, you can add the path to the Boost .dll to the PATH environment variable. Variable Description Type BOOST_ROOTThe environment variable can be spelled either BOOST_ROOT or BOOSTROOT Root directory of your Boost installation Either CMake or Environment Boost_INCLUDE_DIR Directory containing the boost/version.hpp file CMake BOOST_INCLUDEDIR Idem Environment Boost_LIBRARY_DIRS Directory containing the compiled Boost libraries CMake BOOST_LIBRARYDIR Idem Environment Boost_(xyz)_LIBRARY_RELEASE Full pathname to a release build of the compiled 'xyz' Boost library CMake Boost_(xyz)_LIBRARY_DEBUG Full pathname to a debug build of the compiled 'xyz' Boost library CMake ## GMP and MPFR Libraries Under Windows, auto-linking is used, so only the directory containing the libraries is needed and you would specify GMP|MPFR_LIBRARY_DIR rather than GMP|MPFR_LIBRARIES. On the other hand, under Linux the actual library filename is needed. Thus you would specify GMP|MPFR_LIBRARIES. In no case you need to specify both. CGAL uses both Gmp and Mpfr so both need to be supported. If either of them is unavailable the usage of Gmp and of Mpfr will be disabled. Variable Description Type CGAL_DISABLE_GMP Indicates whether to search and use Gmp/Mpfr or not CMake GMP_DIR Directory of Gmp default installation Environment GMP_INCLUDE_DIR Directory containing the gmp.h file CMake GMP_INC_DIR Idem Environment GMP_LIBRARIES_DIR Directory containing the compiled Gmp library CMake GMP_LIB_DIR Idem Environment GMP_LIBRARIES Full pathname of the compiled Gmp library CMake MPFR_INCLUDE_DIR Directory containing the mpfr.h file CMake MPFR_INC_DIR Idem Environment MPFR_LIBRARIES_DIR Directory containing the compiled Mpfr library CMake MPFR_LIB_DIR Idem Environment MPFR_LIBRARIES Full pathname of the compiled Mpfr library CMake Under Linux, the Gmpxx is also searched for, and you may specify the following variables: Variable Description Type GMPXX_DIR Directory of gmpxx default installation Environment GMPXX_INCLUDE_DIR Directory containing the gmpxx.h file CMake GMPXX_LIBRARIES Full pathname of the compiled Gmpxx library CMake ## Qt5 Library You must set the cmake or environment variable Qt5_DIR to point to the path to the directory containing the file Qt5Config.cmake created by your Qt5 installation. If you are using the open source edition it should be <path>/qt-everywhere-opensource-src-<version>/qtbase/lib/cmake/Qt5. ## LEDA Library When the LEDA libraries are not automatically found, yet they are installed on the system with base names 'leda' and 'ledaD' (for the release and debug versions resp.), it might be sufficient to just indicate the library directory via the LEDA_LIBRARY_DIRS variable. If that doesn't work because, for example, the names are different, you can provide the full pathnames of each variant via LEDA_LIBRARY_RELEASE and LEDA_LIBRARY_DEBUG. The variables specifying definitions and flags can be left undefined if they are not needed by LEDA. Variable Description Type WITH_LEDA Indicates whether to search and use LEDA or not CMake LEDA_DIR Directory of LEDA default installation Environment LEDA_INCLUDE_DIR Directory containing the file LEDA/system/basic.h CMake LEDA_LIBRARIES Directory containing the compiled LEDA libraries CMake LEDA_INC_DIR Directory containing the file LEDA/system/basic.h Environment LEDA_LIB_DIR Directory containing the compiled LEDA libraries Environment LEDA_LIBRARY_RELEASE Full pathname to a release build of the LEDA library CMake LEDA_LIBRARY_DEBUG Full pathname to a debug build of the LEDA library CMake LEDA_DEFINITIONS Preprocessor definitions CMake LEDA_CXX_FLAGS Compiler flags CMake LEDA_LINKER_FLAGS Linker flags CMake ## MPFI Library CGAL provides a number type based on this library, but the CGAL library itself does not depend on Mpfi. This means that this library must be configured when compiling an application that uses the above number type. When Mpfi files are not on the standard path, the locations of the headers and library files must be specified by using environment variables. Variable Description Type MPFI_DIR Directory of MPFI default installation Environment MPFI_INCLUDE_DIR Directory containing the mpfi.h file CMake MPFI_INC_DIR Idem Environment MPFI_LIBRARIES_DIR Directory containing the compiled Mpfi library CMake MPFI_LIB_DIR Idem Environment MPFI_LIBRARIES Full pathname of the compiled Mpfi library CMake ## RS and RS3 Library As said before, only the CGAL univariate algebraic kernel depends on the library Rs. As the algebraic kernel is not compiled as a part of the CGAL library, this library is not detected nor configured at installation time. CMake will try to find Rs in the standard header and library directories. When it is not automatically detected, the locations of the headers and library files must be specified using environment variables. Rs needs Gmp 4.2 or later and Mpfi 1.3.4 or later. The variables related to the latter library may also need to be defined. Variable Description Type RS_DIR Directory of Rs default installation Environment RS_INCLUDE_DIR Directory containing the rs_exports.h file CMake RS_INC_DIR Idem Environment RS_LIBRARIES_DIR Directory containing the compiled Rs library CMake RS_LIB_DIR Idem Environment RS_LIBRARIES Full pathname of the compiled Rs library CMake Similar variables exist for Rs3. Variable Description Type RS3_DIR Directory of Rs3 default installation Environment RS3_INCLUDE_DIR Directory containing the file rs3_fncts.h file CMake RS3_INC_DIR Idem Environment RS3_LIBRARIES_DIR Directory containing the compiled Rs3 library CMake RS3_LIB_DIR Idem Environment RS3_LIBRARIES Full pathname of the compiled Rs3 library CMake ## NTL Library Some polynomial computations in CGAL's algebraic kernel are speed up when Ntl is available. As the algebraic kernel is not compiled as a part of the CGAL library, this library is not detected nor configured at installation time. CMake will try to find Ntl in the standard header and library directories. When it is not automatically detected, the locations of the headers and library files must be specified using environment variables. Variable Description Type NTL_DIR Directory of NTL default installation Environment NTL_INCLUDE_DIR Directory containing the NTL/ZZX.h file CMake NTL_INC_DIR Idem Environment NTL_LIBRARIES_DIR Directory containing the compiled Ntl library CMake NTL_LIB_DIR Idem Environment NTL_LIBRARIES Full pathname of the compiled Ntl library CMake ## Eigen Library Eigen is a header-only template library. Only the directory containing the header files of Eigen 3.1 (or greater) is needed. Variable Description Type EIGEN3_INCLUDE_DIR Directory containing the file signature_of_eigen3_matrix_library CMake EIGEN3_INC_DIR Idem Environment ## QGLViewer Library Some demos require the GLViewer library. In most cases, if QGLViewer is not automatically found, setting the QGLVIEWERROOT environment variable is sufficient. If it is not, you can specify the directory containing the header files and the full pathnames of the release and debug libraries Variable Description Type QGLVIEWERROOT Root directory of the QGLViewer library Environment QGLVIEWER_INCLUDE_DIR Directory containing the QGLViewer/qglviewer.h file CMake QGLVIEWER_LIBRARY_RELEASE Full pathname to a release build of the QGLViewer library CMake QGLVIEWER_LIBRARY_DEBUG Full pathname to a debug build of the QGLViewer library CMake ## ESBTL Library One skin surface example requires the Esbtl library in order to read Pdb files. If Esbtl is not automatically found, setting the ESBTL_INC_DIR environment variable is sufficient. Variable Description Type ESBTL_DIR Directory of ESBTL default installation Environment ESBTL_INC_DIR Directory containing the ESBTL/default.h file Environment ESBTL_INCLUDE_DIR Directory containing the ESBTL/default.h file CMake ## TBB Library If Tbb is not automatically found, the user must set the TBBROOT environment variable. The environment variable TBB_ARCH_PLATFORM=<arch>/<compiler> must be set. <arch> is ia32 or intel64. <compiler> describes the Linux kernel, gcc version or Visual Studio version used. It should be set to what is used in $TBBROOT/lib/<arch>.

For windows users, the folder TBBROOT/bin/<arch>/<compiler> should be added to the PATH variable.

Note that the variables in the table below are being used.

Variable Description Type
TBBROOT Directory of Tbb default installation Environment
TBB_INCLUDE_DIRS Directory containing the tbb/tbb.h file CMake
TBB_LIBRARY_DIRS Directory(ies) containing the compiled TBB libraries CMake
TBB_LIBRARIES Full pathnames of the compiled TBB libraries (both release and debug versions, using "optimized" and "debug" CMake keywords). Note that if the debug versions are not found, the release versions will be used instead for the debug mode. CMake
TBB_RELEASE_LIBRARY Full pathname of the compiled TBB release library CMake
TBB_MALLOC_RELEASE_LIBRARY Full pathname of the compiled TBB release malloc library CMake
TBB_DEBUG_LIBRARY Full pathname of the compiled TBB debug library CMake
TBB_MALLOC_DEBUG_LIBRARY Full pathname of the compiled TBB debug malloc library CMake
TBB_MALLOCPROXY_DEBUG_LIBRARY Full pathname of the compiled TBB debug malloc_proxy library (optional) CMake
TBB_MALLOCPROXY_RELEASE_LIBRARY Full pathname of the compiled TBB release malloc_proxy library (optional) CMake

# Compiler Workarounds

A number of boolean flags are used to workaround compiler bugs and limitations. They all start with the prefix CGAL_CFG. These flags are used to work around compiler bugs and limitations. For example, the flag CGAL_CFG_NO_CPP0X_LONG_LONG denotes that the compiler does not know the type long long.

For each installation a file <CGAL/compiler_config.h> is defined, with the correct settings of all flags. This file is generated automatically by CMake, and it is located in the include directory of where you run CMake. For an in-source configuration this means CGAL-4.12/include.

The test programs used to generate the compiler_config.h file can be found in config/testfiles. Both compiler_config.h and the test programs contain a short description of the problem. In case of trouble with one of the CGAL_CFG flags, it is a good idea to take a look at it.

The file CGAL/compiler_config.h is included from <CGAL/config.h>. which is included by all CGAL header files.

# Compiler Optimizations

By default CMake generates makefiles for Release mode, with optimization flags switched on, and vcproj files for Release and Debug modes.