|
CGAL 5.5.4 - Manual
|
|
CGAL 5.5.4 - Manual
|
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.
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.5.4-examples.tar.xz) and the compilation of an example is as simple as:
cd $HOME/CGAL-5.5.4/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.
Using CGAL requires a few core components to be previously installed:
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.
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 responsability 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.
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.
You can also obtain the CGAL library sources directly from https://www.cgal.org/download.html.
Once you have downloaded the file CGAL-5.5.4.tar.xz containing the CGAL sources, you have to unpack it. Under a Unix-like shell, use the command:
tar xf CGAL-5.5.4.tar.xz
The directory CGAL-5.5.4 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.
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.
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:
/usr/local/opt/cgal/lib/cmake/CGAL, for Brew. /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.5.4/examples/Triangulation_2 cmake -DCGAL_DIR=$HOME/CGAL-5.5.4 -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.
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.5.4/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.
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.
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.5.4 -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.
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 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.5.4/examples/Triangulation_2 make # build all the examples of the Triangulation_2 package
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.
1.8.13