CGAL 5.6.3 - Manual

Loading...
Searching...
No Matches
Using CGAL on Unix (Linux, macOS, ...)

Since CGAL version 5.0, CGAL is header-only be default, which means that there is no need to build CGAL before it can be used. However, some dependencies of CGAL might still need to be installed.

# Quick Start: Compiling a Program using CGAL

Assuming that you have obtained CGAL through one of the package managers offering CGAL on your platform (see Section Downloading CGAL), you can download CGAL examples ( CGAL-5.6.3-examples.tar.xz) and the compilation of an example is as simple as:

    cd $HOME/CGAL-5.6.3/examples/Triangulation_2 # go to an example directory
    cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples
    make # build the examples

Compiling your own program is similar:

    cd /path/to/your/program
    path/to/cgal/Scripts/scripts/cgal_create_CMakeLists -s your_program
    cmake -DCMAKE_BUILD_TYPE=Release .
    make

The script `cgal_create_CMakeLists` and its options are detailed in Section Creating a CMake Script for a Program Using CGAL.

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

# Prerequisites

Using CGAL requires a few core components to be previously installed:

- a supported compiler (see Section Supported Compilers),
- CMake,
- Boost,
- GNU Multiple Precision Arithmetic (GMP) and GNU Multiple Precision Floating-Point Reliably (MPFR) Libraries.

Optional third-party software might be required to build examples and demos shipped with CGAL, or to build your own project using CGAL, see Section Optional Third Party Libraries.

# Downloading CGAL

CGAL can be obtained through different channels. We recommend using a package manager as this will ensure that all essential third party dependencies are present, and with the correct versions. You may also download the sources of CGAL directly, but it is then your responsibility to independently acquire these dependencies.

The examples and demos of CGAL are not included when you install CGAL with a package manager, and must be downloaded here.

## Using a Package Manager

On most operating systems, package managers offer CGAL and its essential third party dependencies.

On macOS, we recommend using of Homebrew in the following way:

    brew install cgal

On Linux distributions such as `Debian`/`Ubuntu`/`Mint`, use `apt-get` in the following way:

    sudo apt-get install libcgal-dev

For other distributions or package manager, please consult your respective documentation.

## Using CGAL Source Archive

You can also obtain the CGAL library sources directly from https://www.cgal.org/download.html.

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

    tar xf CGAL-5.6.3.tar.xz

The directory `CGAL-5.6.3` will be created. This directory contains the following subdirectories:

Directory | Contents
--- | ---
`auxiliary` (Windows only) | precompiled GMP and MPFR for Windows
`cmake/modules` | modules for finding and using libraries
`demo` | demo programs (most of them need Qt, 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 version 1.7 for dealing with algebraic numbers. Note that 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 within CGAL sources is the present manual. The CGAL manual can also be accessed online at `https://doc.cgal.org` or downloaded separately at `https://github.com/CGAL/cgal/releases`.

# Header-only Usage

CGAL is a header-only library, and as such there is no need to even configure it before using it. Programs using CGAL (examples, tests, demos, etc.) are instead configured using CMake and CGAL will be configured at the same time.

There is one exception to the last paragraph: if you want to install CGAL header files to a standard location (such as `/usr/local/include`):

    cmake .
    make install

For more advanced installations, we refer to Section Configuring CGAL with CMake.

Note that even though CGAL is a header-only library, not all its dependencies are header-only. The libraries GMP and MPFR, for example, are not header-only. As such, these dependencies must be built or installed independently.

# Configuring your Program

Before building anything using 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. 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 your program.

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 `CMAKE_BUILD_TYPE`, whereas 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 most important CMake variable is the variable `CGAL_DIR`, which will serve to configure CGAL as you configure your program.

In a typical installation of dependencies, almost all CMake variables will be set automatically. The variable `CGAL_DIR` is also generally found when CGAL has been obtained via a package manager. In the rare event that it has not, the variable `CGAL_DIR` should be set manually to:

- something like `/usr/local/opt/cgal/lib/cmake/CGAL`, for Brew.
- something like `/usr/lib/x86_64-linux-gnu/cmake/CGAL`, for Linux distributions.

Note that you can also use `CMAKE_PREFIX_PATH` to point to a directory that contains all dependencies, like so:

    cmake -DCMAKE_PREFIX_PATH=/my/custom/brew/installation/dir -DCMAKE_BUILD_TYPE=Release .

If CGAL has been obtained via other means, `CGAL_DIR` must point to the root directory of the CGAL source code (either the root of the unpacked release tarball or the root of the Git working directory).

It is also strongly recommended to set the build type variable to `Release` for performance reasons if no debugging is intended. Users should thus run:

    cd CGAL-5.6.3/examples/Triangulation_2
    cmake -DCGAL_DIR=$HOME/CGAL-5.6.3 -DCMAKE_BUILD_TYPE=Release . # we are here using a release tarball

The package Qt5 on brew is "keg-only", which means it is not "linked" with brew. In order to link against Qt5, you need to run:

    brew link qt@5

After that, you will have to specify the Qt5_DIR by hand to cmake, using something like

    -DQt5_DIR=/usr/local/opt/qt5/lib/cmake/Qt5

where `/usr/local/` is actually your current brew installation directory. Check this directory to be sure where the Qt5 is placed on your machine.

## Specifying Missing Dependencies

The configuration process launched above might fail if CMake fails to find all the required dependencies. This typically happens if you have installed dependencies at non-standard locations. Although the command line tool `cmake` accepts CMake variables as arguments of the form `-D<VAR>:<TYPE>=<VALUE>`, this is only useful if you already know which variables need to be explicitly defined. or this reason, the simplest way to manually set the missing variables is to run the graphical user interface of CMake, `cmake-gui`.

    cd CGAL-5.6.3/examples/Triangulation_2
    cmake-gui .

After the `CMake` window 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. Once these tests are done, you will see many red entries in the upper portion of the application. Just ignore them, and press 'Configure' again. By now, CMake should have found most required libraries and have initialized variables. If red entries are still present, you must provide the necessary information (paths/values). When all entries have been appropriately filled (and automatically filled values have been adjusted, if desired) and lines are gray, you are now ready to press 'Generate', and to exit `cmake-gui` afterwards.

Advanced

You may also decide to solve missing dependencies using the command line tool (which is not recommended). If so, the page Summary of CGAL's Configuration Variables lists variables which can be used to specify the location of third-party software.

If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`.

## Configuring an External Program

Running `cmake` (or `cmake-gui`) 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
    path/to/cgal/Scripts/scripts/cgal_create_CMakeLists -s your_program
    cmake -DCGAL_DIR=$HOME/CGAL-5.6.3 -DCMAKE_BUILD_TYPE=Release .

Note that the script `cgal_create_CMakeLists` creates a very coarse `CMakeLists.txt` file which might not properly encode the third party dependencies of your program. Users are advised to look at the `CMakeLists.txt` files in the example folder(s) of the package that they are using to learn how to specify their dependencies.

## Advanced Configuration Options

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.

# Building your Program

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 most cases they contain several targets, such as all the examples of the Triangulation_2 package.

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-5.6.3/examples/Triangulation_2
    make # build all the examples of the Triangulation_2 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.