\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.8 - Manual

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Installation

Authors
  Eric Berberich, Joachim Reichel, and Fernando Cacciola

# 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.8 # 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.8 . # configure the examples
    make # build the examples

    cd demo/Straight_skeleton_2 # go to a demo directory
    cmake -DCGAL_DIR=$HOME/CGAL-4.8 . # 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
    cmake -DCGAL_DIR=$HOME/CGAL-4.8 .
    make

where the second line creates a `CMakeLists.txt` file (check its options in Section cgal_create_CMakeLists for various details).

Note that, until CGAL 4.6, cgal_create_CMakeLists only recognized source files ending in `.cpp` or `.C`; if the above fails on the `cmake` command or produces an empty Makefile, check whether your source files go by such a name. Recent versions find all source files ending in `.cc`, `.cp`, `.cxx`, `.cpp`, `.CPP`, `.c++`, or `.C`.

In a less ideal world, you probably have to install CMake, a makefile generator, and third party libraries. That is what this manual is about.

# Prerequisites

Installing CGAL requires a few components to be installed ahead: a supported compiler (see Section Supported Compilers, CMake, Boost, and at least Gmp, and Mpfr; see Section Essential Third Party Libraries for more details on essential third party software.

# OS Specific Installation

Some operating systems with package managers offer CGAL and its essential third party software through the manager, for instance, Mac OS X, or some Linux distribution (e.g. Debian). For Windows, an installer is provided.

## CGAL on MAC OS X

For instance, use macports in the following way:

    sudo port install cgal

or if Qt5 are desired

    sudo port install cgal +qt5 +universal +demos

The setup is similar for `homebrew` .

## CGAL on Linux

For instance in debian/Ubuntu, use apt-get in the following way:

    sudo apt-get install libcgal-dev

To get the demos use

    sudo apt-get install libcgal-demo

Check the CGAL-FAQ for source repository of newest releases.

On other distributions, please consult your package manager documentation.

## CGAL on Windows

You can download and run `CGAL-4.8``-Setup.exe` from http://www.cgal.org/download.html. It is a self extracting executable that installs the CGAL source, and that allows you to select and download some precompiled third party libraries. However, you will need to compile the library using your favorite compiler.

A tutorial is provided on how to proceed with Microsoft Visual Studio 2010.

# Downloading CGAL

You can obtain the CGAL library from http://www.cgal.org/download.html and install it yourself.

After you have downloaded the file `CGAL-4.8``.tar.gz` containing the CGAL sources, you have to unpack it. Under a Unix-like shell, use the command:

    tar xzf CGAL-4.8.tar.gz

In both cases the directory `CGAL-4.8` will be created. This directory contains the following subdirectories:

Directory | Contents
--- | ---
`auxiliary` | precompiled Gmp and Mpfr for Windows
`cmake/modules` | modules for finding and using libraries
`config` | configuration files for install script
`demo` | demo programs (most of them need Qt, geomview or other third-party products)
`doc_html` | documentation (HTML)
`examples` | example programs
`include` | header files
`scripts` | some useful scripts (e.g. for creating CMakeLists.txt files)
`src` | source files

The directories `include/CGAL/CORE` and `src/CGALCore` contain a distribution of the Core library`http://www.cs.nyu.edu/exact/` version 1.7 for dealing with algebraic numbers. Core is not part of CGAL and has its own license.

The directory `include/CGAL/OpenNL` contains a distribution of the Open Numerical Library which provides solvers for sparse linear systems, especially designed for the Computer Graphics community. OpenNL is not part of CGAL and has its own license.

The only documentation shipped with CGAL sources is the present installation manual. The CGAL manual must be downloaded separately from `http://www.cgal.org/download.html`.

# Supported Compilers

In order to build the CGAL libraries, you need a C++ compiler. CGAL 4.8 is supported for the following compilers/operating systems:

Compiler | Operating System
--- | ---
Gnu `g++` 4.1 or later`http://gcc.gnu.org/` | Linux / MacOS X
| MS Windows 95/98/2000/XP/NT4
Intel `C++` 15.0`http://software.intel.com/en-us/intel-compilers/` | Linux
MS Visual `C++` 10.0, 11.0, 12.0, 14.0 (Visual Studio 2010, 2012, 2013, and 2015)`http://msdn.microsoft.com/en-us/vstudio/` | MS Windows 95/98/2000/XP/NT4/Vista/7/8
`Clang` `http://clang.llvm.org/` compiler version 3.5 and 3.6.2 | Linux / MacOS X
Apple `Clang` compiler version 6.0 and 4.2 | MacOS X

# Configuring CGAL with CMake

In order to configure, build, and install the CGAL libraries, examples and demos, you need CMake, a cross-platform "makefile generator". If CMake is not installed already you can obtain it from `http://www.cmake.org/`. CMake version 2.8.11 or higher is required. This manual explains only those features of CMake which are needed in order to build CGAL. Please refer to the CMake documentation at `http://www.cmake.org/` for further details.

Before building CGAL you have to choose the compiler/linker, set compiler and linker flags, specify which third-party libraries you want to use and where they can be found, and which CGAL libraries you want to build. Gathering all this information is called configuration. The end of the process is marked by the generation of a makefile or a Visual C++ solution and project file that you can use to build CGAL.

## Configuring CGAL with the CMake GUI

The simplest way to start the configuration is to run the graphical user interface of CMake. We recommend to use `cmake-gui`. You must pass as argument the root directory of CGAL. For example:

    cd CGAL-4.8
    cmake-gui . # Notice the dot to indicate the current directory.

After `cmake-gui` opens, press 'Configure'. A dialog will pop up and you will have to choose what shall gets generated. After you have made your choice and pressed 'Finish', you will see the output of configuration tests in the lower portion of the application. When these tests are done, you will see many red entries in the upper portion of the application. Just ignore them and press 'Configure'. By now CMake should have found many libraries and have initialized variables. If you still find red entries, you have to provide the necessary information. This typically happens if you have installed software at non-standard locations. Providing information and pressing 'Configure' goes on until all entries are grayed. You are now ready to press 'Generate'. Once this is done, you can quit `cmake-gui`.

## Configuring CGAL with the cmake Command-Line Tool

Alternatively, you can run the command-line tool called `cmake`. You pass as argument the root directory of CGAL. For example:

    cd CGAL-4.8
    cmake . # Notice the dot to indicate the current directory.

The very first thing CMake does is to detect the compiler to use. This detection is performed by a special CMake module called a generator. A CMake generator understands the build requirements for a particular compiler/linker and generates the necessary files for that. For example, the UNIX Makefiles generator understands the GNU chain of tools (GCC, ld etc.) and produces makefiles, which can be used to build a target by a simple call to `make`. Likewise, the Visual Studio 2010 generator produces solution and project files and can be manually launched in the VS IDE to build the target.

Each platform has a default generator, so you only need to select one when the default is not what you want. For example, under Windows, it is possible to generate NMakefiles instead of Visual Studio project files in order to build the library with `nmake`. Running `cmake` with no parameters in a command-line prints the list of available generators supported by your platform and CMake version. If the generator you need is not listed there, you can try a newer CMake version, as generators are hardcoded into CMake, and additional generators are added with each release.

Since the choice of the generator determines the type of build files to generate, in some cases you choose a particular generator as a mean to choose a specific compiler (because they use different build files). For example, the following generates solution files for use in Visual C++ 11.0 on a 64bit machine:

    cd CGAL-4.8
    cmake -G"Visual Studio 11 Win64" .

In other cases, however, the generator doesn't directly identify a specific compiler but a chain of tools. For example, the `UNIX Makefiles` generator produces `makefiles` that call some auto-detected command-line compiler, like GCC. If you need the makefiles to use a different compiler, you need to specify the desired compiler in the call to CMake, as in this example:

    cd CGAL-4.8
    cmake -DCMAKE_CXX_COMPILER:FILEPATH=g++-4.7 .

CMake maintains configuration parameters in so-called cmake variables, like the `CMAKE_CXX_COMPILER` in the example above. These variables are not environment variables but CMake variables. Some of the CMake variables represent user choices, such as `WITH_examples` or `CMAKE_BUILD_TYPE=Release`, while others indicate the details of a third-party library, such as `Boost_INCLUDE_DIR` or the compiler flags to use, such as `CMAKE_CXX_FLAGS`.

The command line tool `cmake` accepts CMake variables as arguments of the form `-D<VAR>:<TYPE>=<VALUE>`, as in the example above, but this is only useful if you already know which variables need to be explicitly defined.

Advanced

CMake keeps the variables that a user can manipulate in a so-called CMake cache, a simple text file named `CMakeCache.txt`, whose entries are of the form `VARIABLE:TYPE=VALUE`. Advanced users can manually edit this file, instead of going through the interactive configuration session.

The configuration process not only determines the location of the required dependencies, it also dynamically generates a `compiler_config.h` file, which encodes the properties of your system and a special file named `CGALConfig.cmake`, which is used to build programs using CGAL. The purpose of this file is explained below.

# CGAL Libraries

CGAL is split into five libraries. During configuration, you can select the libraries that you would like to build by setting a CMake variable of the form `WITH_<library>`. By default all are switched `ON`. All activated libraries are build after configuration; see Building CGAL

We next list the libraries and essential 3rd party software (see Essential Third Party Libraries) for each library:

Library | CMake Variable | Functionality | Dependencies
--- | --- | --- | ---
`CGAL` | none | Main library | Gmp, Mpfr, Boost (headers), Boost.Thread and Boost.System (library) for compilers not supporting the keywords `threadlocal` and the class `mutex`
`CGAL_Core` | `WITH_CGAL_Core` | The CORE library for algebraic numbers.CGAL_Core is not part of CGAL, but a custom version of the Core library distributed by CGAL for the user convenience and it has it's own license. | Gmp and Mpfr
`CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | OpenGL, zlib, Vtk(optional)
`CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for Qt5-based demos | Qt5 and OpenGL

## Debug vs. Release

The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the libraries. It accepts the values `Release` or `Debug`. The default is `Release` and should be kept, unless you want to debug your program.

This is not an issue for solution/project files, as there the user selects the build type from within the IDE.

## Static vs. Shared Libraries

Shared libraries, also called dynamic-link libraries, are built by default (`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You can choose to produce static libraries instead by setting the CMake variable `BUILD_SHARED_LIBS` to `FALSE`. If you use `cmake-gui`, a tick box for that variable is available to set it.

These setting affect the variants of third-party libraries (see next section) selected whenever the choice is available.

# Essential Third Party Libraries

The focus of CGAL is on geometry, and we rely on other highly specialized libraries and software for non-geometric issues, for instance, for numeric solvers, or visualization. We first list software that is essential to build (all) libraries of CGAL, that is, this software must be found during the configuration of CGAL for an actived library of CGAL (i.e. `WITH_<library>=ON`); see sec3partysoftwareconfig to specify the location of 3rd party software.

The libraries STL (shipped with any compiler) and Boost are essential to all components (i.e. libCGAL, libCGAL_Core, libCGAL_ImageIO, and libCGAL_Qt5).

## Standard Template Library (STL)

CGAL heavily uses the STL, and in particular adopted many of its design ideas. You can find online documentation for the STL at various web sites, for instance, `http://www.sgi.com/tech/stl/`, `http://www.cplusplus.com/reference/`, or `http://msdn.microsoft.com/en-us/library/1fe2x6kt(VS.100).aspx`.

The STL comes with the compiler, so there is nothing to install.

## Boost

The Boost libraries are a set of portable C++ source libraries. Most of Boost libraries are header-only, but a few of them need to be compiled or installed as binaries.

CGAL requires the Boost libraries. In particular the header files and the threading library (`Boost.Thread` and `Boost.System` binaries). Version 1.48 (or higher) are needed for compilers not supporting the keywords `threadlocal` and the class `mutex` (This is supported for GCC 4.8 and later when using the C++ 11 standard, and for Visual C++ starting with 2015, that is VC14).

On Windows, as auto-linking is used, you also need the binaries of `Boost.Serialization` and `Boost.DateTime`, but the dependency is artificial and used only at link-time: the CGAL libraries do not depend on the DLL's of those two libraries.

In CGAL some demos and examples depend on `Boost.Program_options`.

In case the Boost libraries are not installed on your system already, you can obtain them from `http://www.boost.org/`. For Visual C++ you can download precompiled libraries from `http://sourceforge.net/projects/boost/files/boost-binaries/`. For Visual C++ versions prior to 2015 `Boost.Thread` is required, so make sure to either install the precompiled libraries for your compiler or build `libboost-thread` and `libboost-system`.

As on Windows there is no canonical directory for where to find Boost, we recommend that you define the environment variable `BOOST_ROOT` and set it to where you have installed Boost, e.g., `C:\boost\boost_1_41_0`.

## GMP and MPFR

The components libCGAL, libCGAL_Core, and libCGAL_Qt5 require Gmp and Mpfr which are libraries for multi precision integers and rational numbers, and for multi precision floating point numbers.

CGAL combines floating point arithmetic with exact arithmetic, in order to be efficient and reliable. CGAL has a built-in number type for that, but Gmp and Mpfr provide a faster solution, and we recommend to use them.

Having Gmp version 4.2 or higher and Mpfr version 2.2.1 or higher installed is recommended. These libraries can be obtained from `http://gmplib.org/` and `http://www.mpfr.org/`, respectively.

As Visual C++ is not properly supported by the Gmp and Mpfr projects, we provide precompiled versions of Gmp and Mpfr, which can be downloaded with the installer `CGAL-4.8``-Setup.exe`.

## zlib

zlib is a data compression library, and is essential for the component libCGAL_ImageIO.

In CGAL this library is used in the examples of the 3D Surface Mesh Generation Reference package.

If it is not already on your system, for instance, on Windows, you can download it from `http://www.zlib.net/`.

## OpenGL

OpenGL (Open Graphics Library) provides an API for applications that produce 2D and 3D computer graphics.

In CGAL the library is essential for the component libCGAL_Qt5, as well as libCGAL_ImageIO and for various demos.

Typically, OpenGL is preinstalled on systems; if not, it can be downloaded from `http://www.opengl.org/`.

## Qt5

Qt is a cross-platform application and UI framework.

The component libCGAL_Qt5 requires Qt5 installed on your system. In case Qt is not yet installed on your system, you can download it from `http://qt-project.org/`.

The exhaustive list of Qt5 components used in demos is: `Core`, `Gui`, `Help`, `OpenGL`, `Script`, `ScriptTools`, `Svg`, `Widgets`, `qcollectiongenerator` (with `sqlite` driver plugin) and `Xml`.

Having Qt5 version 5.3.0 is recommended.

# CGAL Examples and Demos

CGAL is distributed with a large collection of examples and demos. By default, these are not configured along with the CGAL libraries, unless you set the variables `WITH_examples=ON` and/or `WITH_demos=ON`.

Nevertheless, even when configured with CGAL, they are not automatically built along with the libraries. You must build the `examples` or `demos` targets (or IDE projects) explicitly.

If you do not plan to compile any demos, you might skip some of the essential libraries (as Qt or OpenGL), as the corresponding CGAL-libraries are not linked. But for your own demos you might need these CGAL-libraries.

# Optional Third Party Libraries

Optional 3rd party software can be used by CGAL for various reasons: Usually certain optional libraries are required to build examples and demos shipped with CGAL or to build your own project using CGAL. Another reason is to speed up basic tasks. In order to support these goals, all optional libraries can be prepared to be used with CGAL while configuring CGAL, just in the same way as essential libraries are configured. Whenever building an example or a demo (or your own executable), these preconfigured libraries are available when using CGAL.

## LEDA

LEDA is a library of efficient data structures and algorithms. Like Core, LEDA offers a real number data type.

In CGAL this library is optional, and its number types can be used as an alternative to Gmp, Mpfr, and Core.

Free and commercial editions of LEDA are available from `http://www.algorithmic-solutions.com/leda/index.html`.

## MPFI

Mpfi provides arbitrary precision interval arithmetic with intervals represented using Mpfr reliable floating-point numbers. It is based on the libraries Gmp and Mpfr. In the setting of CGAL, this library is optional: it is used by some models of the Algebraic Kernel.

Mpfi can be downloaded from `http://mpfi.gforge.inria.fr/`. Version 1.4 or higher is recommended.

## RS and RS3

Rs (Real Solutions) is devoted to the study of the real roots of polynomial systems with a finite number of complex roots (including univariate polynomials). In CGAL, Rs is used by one model of the Algebraic Kernel.

Rs is freely distributable for non-commercial use. You can download it from `http://vegas.loria.fr/rs/`. Actually, the Rs package also includes Rs3, the successor of Rs, which is used in conjunction with it.

The libraries Rs and Rs3 need Mpfi, which can be downloaded from `http://mpfi.gforge.inria.fr/`.

## NTL

Ntl provides data structures and algorithms for signed, arbitrary length integers, and for vectors, matrices, and polynomials over the integers and over finite fields. The optional library Ntl is used by CGAL to speed up operations of the Polynomial package, such as GCDs. It is recommended to install Ntl with support from Gmp.

Ntl can be downloaded from `http://www.shoup.net/ntl/`. Version 5.1 or higher is recommended.

## Eigen

Eigen is a `C++` template library for linear algebra. Eigen supports all matrix sizes, various matrix decomposition methods and sparse linear solvers.

In CGAL, Eigen provides sparse linear solvers in the Poisson Surface Reconstruction Reference and the Triangulated Surface Mesh Parameterization Reference packages.

In addition, Eigen also provides singular value decomposition for the Estimation of Local Differential Properties of Point-Sampled Surfaces Reference and the Approximation of Ridges and Umbilics on Triangulated Surface Meshes Reference packages.

The Eigen web site is `http://eigen.tuxfamily.org`.

## libQGLViewer

libQGLViewer is a 3D widget based on Qt 4's `QGLWidget`. In case of Qt5 used, libQGLViewer needs to be recompiled with the proper Qt5 version.

In CGAL some 3D demos are based on libQGLViewer.

It can be downloaded from `http://www.libqglviewer.com/`.

## ESBTL

The Esbtl (Easy Structural Biology Template Library) is a library that allows the handling of Pdb data.

In CGAL the Esbtl is used in an example of the 3D Skin Surface Meshing Reference package.

It can be downloaded from `http://esbtl.sourceforge.net/`.

## Intel TBB

Tbb (Threading Building Blocks) is a library developed by Intel Corporation for writing software programs that take advantage of multi-core processors.

In CGAL, Tbb is used by the packages that offer parallel code.

The Tbb web site is `http://www.threadingbuildingblocks.org`.

# Building CGAL

The results of a successful configuration are build files that control the build step. The nature of the build files depends on the generator used during configuration, but in all cases they contain several targets, one per library, and a default global target corresponding to all the libraries.

For example, in a Unix-like environment the default generator produces makefiles. You can use the `make` command-line tool for the succeeding build step as follows:

    cd CGAL-4.8

    # build all the selected libraries at once

    make

The resulting libraries are placed in the subdirectory `lib` under `<CMAKE_BINARY_DIR>` (which is `CGAL-4.8` in case you run an in-source-configuration).

With generators other than `UNIX Makefiles` the resulting build files are solution and project files which should be launched in an Ide, such as Visual Studio or KDevelop3. They will contain the targets described above, which you can manually build as with any other solution/project within your Ide.

Alternatively, you can build it with the command line version of the Visual Studio Ide:

    devenv CGAL.sln /Build Debug

The "Debug" argument is needed because CMake creates solution files for all four configurations, and you need to explicitly choose one when building (the other choices are Release, RelWithDebInfo and MinSizeRel).

Advanced

The build files produced by CMake are autoconfigured. That is, if you change any of the dependencies, the build step automatically goes all the way back to the configuration step. This way, once the target has been configured the very first time by invoking cmake, you don't necessarily need to invoke `cmake` again. Rebuilding will call itself `cmake` and re-generate the build file whenever needed. Keep this in mind if you configure CGAL for the Visual Studio IDE since a build could then change the solution/project file in-place and VS will prompt you to reload it.

If you have turned on the configuration of examples (`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional targets named `examples` and `demos`, plus one target for each example and each demo in the build files. None of these targets are included by default, so you need to build them explicitly after the CGAL libraries have been successfully built. The targets `examples` and `demos` include themselves all the targets for examples and demos respectively.

    # build all examples at once
    make examples

    # build all demos at once
    make demos

    # build only the Straight Skeleton demo
    make Straight_skeleton_2_demo

Advanced

When using `UNIX Makefiles` you can find out the exact name of the example or demo target of a particular package by typing `make help | grep <package>`.

# Installing CGAL

On many platforms, library pieces such as headers, docs and binaries are expected to be placed in specific locations. A typical example being `/usr/include` and `/usr/lib` on Unix-like operating systems or `C:/Program Files/` on Windows. The process of placing or copying the library elements into its standard location is sometimes referred to as Installation and it is a postprocessing step after the build step.

CMake carries out the installation by producing a build target named install. The following example shows a typical session from configuration to installation in a Unix-like environment:

    cd CGAL-4.8

    cmake . # configure
    make # compile
    make install # install

If you use a generator that produces IDE files (for Visual Studio for instance) there will be an optional `INSTALL` project, which you will be able to "build" to execute the installation step.

Advanced

The files are copied into a directory tree relative to the installation directory determined by the CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under Unix-like operating systems and `C:\Program Files` under Windows. If you want to install to a different location, you must override that CMake variable explicitly at the configuration time and not when executing the install step.

The file `CGALConfig.cmake` is installed by default in `$CMAKE_INSTALLED_PREFIX/lib/``CGAL-4.8`.

# 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.8``/cmake/platforms/debug` and `CGAL-4.8``/cmake/platforms/release` for two configurations, respectively:

    mkdir CGAL-4.8/cmake/platforms/debug
    cd CGAL-4.8/cmake/platforms/debug
    cmake -DCMAKE_BUILD_TYPE=Debug ../../..

    mkdir CGAL-4.8/cmake/platforms/release
    cd CGAL-4.8/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.8/examples/Straight_skeleton_2
    cmake -DCGAL_DIR=$HOME/CGAL-4.8 .
    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.8 .
    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.8``/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.8
    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-g .
    cd CGAL-4.8/examples/Straight_skeleton_2
    cmake -DCGAL_DIR=CGAL-4.8 -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_ROOT` The 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>`.

The folder `TBBROOT/bin/<arch>/<compiler>` should be added to the `PATH` variable.

Note that the variables in the table below are begin 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.8``/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.