CGAL 6.1.2 - Manual: Installing CGAL libraries

CGAL 6.1.2 - Manual

Loading...
Searching...
No Matches
Installing CGAL libraries
Advanced

Since CGAL version 5.0, CGAL is header-only, which means that there is no need to compile CGAL or its libraries before it can be used.

This page is for advanced users that either want to install CGAL on their system, or want to build the examples, tests and demos that are shipped in a git branch, for example. If this is not your case, head over back to the page Getting Started with CGAL.

This page is a step-by-step description of how to configure and install CGAL, and (optionally) build examples, tests and demos.

It is assumed that you have downloaded a source archive of CGAL, and are using Linux or macOS.

# Quick Installation

Ideally, installing CGAL, as well as compiling some examples shipped by CGAL is as simple as:

    cd $HOME/CGAL-6.1.2
    mkdir build
    cd build
    cmake ..                                                                          # configure CGAL
    make install                                                                      # install CGAL
    cd examples/Triangulation_2                                                       # go to an example directory
    cmake -DCGAL_DIR=$CMAKE_INSTALLED_PREFIX/lib/CGAL -DCMAKE_BUILD_TYPE=Release .    # configure the examples
    make                                                                              # build the examples

In a less ideal world, you might have to install some required tools and third-party libraries. This is what this page is about.

# Configuring CGAL with CMake

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

CMake maintains configuration parameters in so-called cmake variables. Some of the CMake variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others indicate the details of a third-party library, such as `Boost_INCLUDE_DIR` or which compiler flags to use, such as `CMAKE_CXX_FLAGS`.

The next sections first present the CMake variables related to CGAL, followed by more generic variables, and finally the configuration and build processes.

## CGAL Libraries

CGAL has some optional components. During configuration, you can select the components that you would like to use by setting a CMake variable of the form `WITH_<library>`. By default all are switched `ON`, but some have specific dependencies in addition to the essential ones, so if you don't need those, don't hesitate to switch them `OFF`. See the page Essential Third Party Libraries for more information.

Component | CMake Variable | Functionality | Dependencies
--- | --- | --- | ---
CGAL | none | Main library | GMP, MPFR, Boost (headers)
`CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | zlib, VTK (optional)
`CGAL_Qt6` | `WITH_CGAL_Qt6` | `QGraphicsView` support for Qt6-based demos | Qt6

## 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`. Additionally, 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 may skip some of the dependencies (such as Qt), as the corresponding CGAL-libraries will not be used. Note, however, that your own demos might need these CGAL-libraries and thus their dependencies. See the page Essential Third Party Libraries for more information.

## Debug vs. Release

The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the executables. It accepts the values `Debug` or `Release`. Note that the default value is an empty string, since it is default value in `CMake`. If you do not plan on debugging, it is important to set the variable to `Release` for performance reasons.

This is however not an issue for solution/project files, since the user selects the build type from within the IDE in this environment.

## Other CMake Variables

There are many more variables that can be used during configuration. The most important ones are:

- `CMAKE_INSTALL_PREFIX=<dir>` installation directory [/usr/local]
- `CMAKE_BUILD_TYPE=<Debug|Release>` build type [Release]
- `CMAKE_C_COMPILER=<program>` C compiler [gcc]
- `CMAKE_CXX_COMPILER=<program>` C++ compiler [g++]

In case you want to add additional compiler and linker flags, you can use

- `CGAL_CXX_FLAGS` additional compiler flags
- `CGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries)
- `CGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries)
- `CGAL_EXE_LINKER_FLAGS` add. linker flags (executables)

Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set separate values for debug and release builds. In case you do not want to add additional flags, but to override the default flags, replace "CGAL" by "CMAKE" in the variable names above.

A comprehensive list of CMake variables can be found on the Summary of CGAL's Configuration Variables page.

Note that CMake maintains a cache name `CMakeCache.txt`. If you change options (or your environment changes), it is best to remove that file to avoid problems.

## Configuring CGAL with the CMake GUI

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

    cd CGAL-6.1.2/build
    cmake-gui .. # The two dots indicate the parent directory

After `cmake-gui` opens, press Configure. A dialog will pop up and you will have to choose what shall be 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`.

Without an explicit `CMAKE_BUILD_TYPE`, `CMake` does not add any additional build flags. This will result in a default build without any debug symbols, and without any optimizations. You should set the variable `CMAKE_BUILD_TYPE` to `Debug` to compile with debug symbols, or `Release` to enable optimizations.

## 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. 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. For example:

    cd CGAL-6.1.2/build
    cmake ..

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.

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.

## CGALConfig.cmake

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 variables that summarize the configuration of CGAL and will be essential during the configuration and building of a program using CGAL, see Section Building a Program using CGAL.

# Multiple Builds

While you can choose between release or debug builds, 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, 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-6.1.2/build/debug` and `CGAL-6.1.2/build/release` for two configurations, respectively:

    mkdir CGAL-6.1.2/build/debug
    cd CGAL-6.1.2/build/debug
    cmake -DCMAKE_BUILD_TYPE=Debug ../..

    mkdir CGAL-6.1.2/build/release
    cd CGAL-6.1.2/build/release
    cmake -DCMAKE_BUILD_TYPE=Release ../..

## Building Examples and Demos

Let's assume that you have turned on the configuration of examples (`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`).

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 executable, and a default global target corresponding to all of them (called `examples` and/or `demos`).

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:

    # build all the selected examples at once
    make examples

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

If you are interested in the demos or examples of just a particular module, you can build them in the following way:

    make -C demo/Alpha_shapes_2      # equivalent to "cd demo/Alpha_shapes_2; make"
    make -C examples/Alpha_shapes_2  # equivalent to "cd examples/Alpha_shapes_2; make"

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>`.

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.

# 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`. 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 configuration step.

CMake carries out the installation by producing a build target named install. Assuming you have successfully configured CGAL as demonstrated in the previous sections, the installation simply amounts to:

    # install CGAL
    make install

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. 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/cmake/CGAL`.

# Building a Program using CGAL

Similarly to CGAL and its libraries, compiling a program using CGAL is done in the usual two steps of configuration and building.

The configuration process is also done using `cmake` (or `cmake-gui`) and requires a `CMakeLists.txt` file. This file is automatically provided for all shipped examples and demos of CGAL. For other programs, CMake can also be used to configure and build user programs, but one has to provide the corresponding `CMakeLists.txt`. This script can be generated either manually, or with the help of a shell-script, see Section Creating a CMake Script for a Program Using CGAL. Using this shell-script, the process of configuring a user's program called `your_program.cpp` amounts to:

    cd /path/to/your/program
    cgal_create_CMakeLists -s your_program
    cmake -DCGAL_DIR=XXXXXX -DCMAKE_BUILD_TYPE=Release .
    make

In order to configure a program, you need to indicate the location of the CGAL configuration file in the CMake variable `CGAL_DIR` (as shown in the example above). If you have installed CGAL, `CGAL_DIR` must afterwards be set to `$CMAKE_INSTALLED_PREFIX/lib/cmake/CGAL`.

The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense if you have multiple out-of-source builds of CGAL as in Section Multiple Builds.