|
CGAL 5.0 - Manual
|
|
CGAL 5.0 - Manual
|
Since CGAL version 5.0, CGAL is header-only be default, 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 have a good reason to still use the old way. 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, build, and (optionally) install CGAL in case you do not wish to use the - now enabled by default - header-only mode of CGAL.
It is assumed that you have downloaded a source archive of CGAL, and are using Linux or macOS.
Ideally, compiling and installing CGAL, as well as compiling some examples shipped by CGAL is as simple as:
cd $HOME/CGAL-5.0 mkdir build cd build cmake -DCGAL_HEADER_ONLY=OFF -DCMAKE_BUILD_TYPE=Release .. # configure CGAL make # build 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.
Before building CGAL, or 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, 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 that you can use to build 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 is split into four 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 to be built after configuration.
Note that some libraries have specific dependencies in addition to the essential ones. See the page Essential Third Party Libraries for more information.
| Library | CMake Variable | Functionality | Dependencies |
|---|---|---|---|
CGAL | none | Main library | Gmp, Mpfr, Boost (headers) |
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 | zlib, Vtk (optional) |
CGAL_Qt5 | WITH_CGAL_Qt5 | QGraphicsView support for Qt5-based demos | Qt5 |
Shared libraries, also called dynamic-link libraries, are built by default (.so on Linux, .dylib on macOS). You can choose to produce static libraries instead, by setting the CMake variable BUILD_SHARED_LIBS to FALSE.
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.
The CMake variable CMAKE_BUILD_TYPE indicates how to build the libraries. It accepts the values Debug or Release. Note that the default value is Debug, 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.
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] BUILD_SHARED_LIBS=<TRUE|FALSE> shared or static libraries [TRUE] 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.
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-5.0/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.
Since you intend to build CGAL libraries, you should also ensure that the variable CGAL_HEADER_ONLY has not been set.
If you do not need to debug, you should set the variable CMAKE_BUILD_TYPE to Release.
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-5.0/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.
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.
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.
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, 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-5.0/build/debug and CGAL-5.0/build/release for two configurations, respectively:
mkdir CGAL-5.0/build/debug cd CGAL-5.0/build/debug cmake -DCMAKE_BUILD_TYPE=Debug ../.. mkdir CGAL-5.0/build/release cd CGAL-5.0/build/release cmake -DCMAKE_BUILD_TYPE=Release ../..
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:
# build all the selected libraries at once make
The resulting libraries are placed in the subdirectory lib under <CMAKE_BINARY_DIR> (which is CGAL-5.0 in case you run an in-source-configuration).
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.
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
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>.
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 build step.
CMake carries out the installation by producing a build target named install. Assuming you have successfully configured and built CGAL as demonstrated in the previous sections, the installation simply amounts to:
# install CGAL make install
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/CGAL-5.0.
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/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.
1.8.13