CGAL 5.3.1 - Manual
Using CGAL on Windows (with Visual C++)

CGAL 5.3.1 is supported for the following MS Visual C++ compilers: 14.0, 15.9, 16.0 (Visual Studio 2015, 2017, and 2019).

CGAL is a library that has mandatory dependencies that must be first installed: Boost and GNU Multiple Precision Arithmetic (GMP) and GNU Multiple Precision Floating-Point Reliably (MPFR) Libraries.

You have two options to install CGAL and its dependencies: you can either use the Vcpkg library manager, which will automatically install an appropriate version of these dependencies as you install CGAL, or you can install the dependencies on your own (making sure that you are using a supported version) by following their respective installation instructions.

If you choose to use vcpkg, you might have to bootstrap and download and compile it, but from then on vcpkg will make your life easier. On the other hand, if you need to use a specific version, or have already installed a certain version of a dependency and do not wish to potentially have multiple versions installed, you will want to use the CGAL source archive.

We explain the two approaches in the next two sections.

Installing CGAL with the Vcpkg Library Manager

Installing Vcpkg

The first step is to clone or download vcpkg from https://github.com/microsoft/vcpkg. 

C:\dev> git clone https://github.com/microsoft/vcpkg
C:\dev> cd vcpkg
C:\dev\vcpkg> .\bootstrap-vcpkg.bat

Installing CGAL with Vcpkg

By default vcpkg installs for 32 bit binaries and will use the latest version of Visual C++ installed on your machine. If you develop 64 bit software you must set the Windows environment variable VCPKG_DEFAULT_TRIPLET to x64-windows or add the suffix :x64-windows to the package name you want to install (for example cgal:x64-windows). We refer to the official documentation of vcpkg if you want to compile for an older version of a compiler.

Because of a bug with gmp in vcpkg for windows, you need to install yasm-tool in 32 bits to be able to correctly build gmp 64bits, needed for cgal: 

C:\dev\vcpkg> ./vcpkg.exe install yasm-tool:x86-windows

You are now ready to install CGAL: 

C:\dev\vcpkg> ./vcpkg.exe install cgal

This will take several minutes as it downloads GMP, MPFR, all boost header files, and it will compile GMP and MPFR, as well as several boost libraries. Afterwards, you will find the include files, libraries, and dlls in the subdirectory C:\dev\vcpkg\installed\x64-windows.

Note that CGAL is a header-only library, and there are therefore no lib or dll files for CGAL.

Compiling an Example

In this section we show how to compile a program that uses CGAL. The examples you find in these User Manual pages are not downloaded when you install CGAL with the Vcpkg library manager. You must download them separately from the following download page: CGAL-5.3.1-examples.zip

Assuming you have unzipped this file in your home directory C:\Users\Me, we will next compile an example from the 2D Triangulation package.

Configuring of an Example

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 and we use CMake as configuration tool (see Section CMake for more information on supported versions and where to download it).

The end of the process is marked by the generation of a Visual C++ solution and a project file that you can use to build your program. 

C:\Users\Me\CGAL-5.3.1> cd examples\Triangulation_2
C:\Users\Me\CGAL-5.3.1\examples\Triangulation_2> mkdir build
C:\Users\Me\CGAL-5.3.1\examples\Triangulation_2> cd build
C:\Users\Me\CGAL-5.3.1\examples\Triangulation_2\build> cmake-gui ..

The command cmake-gui launches the graphical interface for cmake. When you hit the Configure button, you must:

  • specify the Generator (e.g., Visual Studio 16 2019),
  • specify the Optional Platform (e.g., x64 in case you want to create 64 bit binaries),
  • select Specify toolchain file for cross compilation (the file vcpkg.cmake within the directory where you have installed vcpkg, e.g. C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake).

toolchain.png
Figure 0.1 The box to check to get to the toolchain option

Once the configuration process is done, tick Advanced and Grouped in cmake-gui. You will see entries for where header files and libraries are taken from.

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

Additional Dependencies

Some CGAL packages also have additional dependencies. For example, during the configuration process above, you may have observed the following message: 

NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled

CGAL is a library of algorithms and data structures and as such does not depend on Qt. However, one of the examples in the Triangulation_2 package does require Qt for visualization purposes. If you already have Qt installed, you can simply fill in the requested CMake variables and paths. Otherwise, you can also install it using vcpkg: 

C:\dev\vcpkg> ./vcpkg.exe install qt5

Remember to specify --triplet or the related environment variable in case you target 64-bit applications.

As Qt5 is modular and as the CGAL examples and demos use only some of these modules you can save download and compilation time by specifying an installation option: 

C:\dev\vcpkg> ./vcpkg.exe install cgal[qt]

In both cases, when you start cmake-gui again and hit the Configure button, the CMake variables and paths concerning Qt should now be filled.

Note that not all optional dependencies are available through the Vcpkg library manager. In this case, you must download and install them independently (see page Essential and Optional Third Party Dependencies for information on support versions and download links) as well as fill the missing information within the CMake interface until configuration is successful (no more red lines indicating missing dependencies).

Advanced

You may also decide to solve missing dependencies using the CMake 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.

Compilation of an Example

Once the configuration process is successful, hit the Generate button, and you will find the file Triangulation_2_examples.sln in the directory C:\Users\Me\CGAL-5.3.1\examples\Triangulation_2\build. Double-click it to open it. There is one project per .cpp file in the directory. Compile them all, or just the one you are interested in.

Configuring and Compiling Your Code Using CGAL

Configuring and compiling your own code is practically the same as for CGAL examples if you use cmake. Running cmake (or cmake-gui) requires a CMakeLists.txt file. This file is automatically provided for all examples and demos of CGAL. For your own programs, you are advised to look at the CMakeLists.txt files in the example folder of the package(s) that you are using to learn how to specify CGAL and additional third party dependencies.

Installing from the Source Archive

You can download and extract CGAL-5.3.1.zip from https://www.cgal.org/download/windows.html.

Installing GMP and MPFR

Precompiled version of GMP and MPFR are provided in the asset GMP and MPFR libraries, for Windows 64bits from https://github.com/CGAL/cgal/releases. If you only install those libraries to use CGAL, then you should extract this archive inside the directory CGAL-5.3.1 created when extracting the CGAL zip source archive. That way those dependencies will be automatically detected by cmake (you should then get the directory CGAL-5.3.1\auxiliary\gmp).

Installing Boost

Boost is a mandatory dependency of CGAL. Binary versions of Boost are available on SourceForge. The Boost installers install both Boost headers and precompiled libraries. Please note that the CGAL project is not responsible for the files provided on this website. When CGAL 5.3.1 was released, the latest version of Boost was 1.71. A typical installation of Boost would consist of the following steps:

  • Download and run the file boost_1_71_0-msvc-XX.Y-64.exe (where XX.Y = 14.0 for VC 2015, XX.Y = 14.1 for 2017, XX.Y = 14.2 for VC 2019).
  • Extract the files to a new directory, e.g. c:\dev\libboost_1_71_0.
  • Set the following two environment variables to point respectively to the path of the libraries and the headers
    • BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y
    • BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0
    as this will help cmake to find Boost.
  • Add the path to the Boost dlls (C:\dev\libboost_1_71_0\lib64-msvc-XX.Y) files to the PATH environment variable.

Compiling an Example

We assume that you have downloaded the examples with the CGAL Installer.

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 and we use CMake as configuration tool (see Section CMake for more information on minimal supported versions and where to download it).

The end of the process is marked by the generation of a Visual C++ solution and a project file that you can use to build your program. 

C:\dev\CGAL-5.3.1> cd examples\Triangulation_2
C:\dev\CGAL-5.3.1\examples\Triangulation_2> mkdir build
C:\dev\CGAL-5.3.1\examples\Triangulation_2> cd build
C:\dev\CGAL-5.3.1\examples\Triangulation_2\build> cmake-gui ..

The command cmake-gui launches the graphical interface for cmake. When you hit the Configure button, you must:

  • Specify the Generator, e.g., Visual Studio 16 2019), and
  • specify an Optional Platform (x64 in case you want to create 64 bit binaries).

Once the configuration is done, tick Advanced and Grouped in cmake-gui. You will see entries for where header files and libraries are taken from.

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

Additional Dependencies

Some CGAL packages also have additional dependencies. For example, during the configuration process above, you may have observed the following message: 

NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled

CGAL is a library of algorithms and data structures and as such does not depend on Qt. However, one of the examples does for visualization purposes only. Either you have Qt installed and you can fill in the requested CMake variables, or you must install it. A typical Qt installation would consist of the following steps:

  • Download and install the Qt library for open source development package for your Visual Studio version at https://www.qt.io/download (here is the direct link to the offline installers).
  • Add the environment variable QTDIR pointing to the place you installed Qt, e.g., C:\dev\Qt\Qt5.13.1, as this will help cmake to find Qt.
  • Add the bin directory of Qt, e.g. add C:\dev\Qt\Qt5.13.1\msvcXXXX_YY\bin to PATH, where XXXX_YY is something like vc2017_64. To avoid any conflict with another dll with the same name from another folder, add this path as the first in the list.

Once you have installed Qt, the CMake variables concerning Qt should now be filled when you press Configure in the CGAL directory.

You must follow a similar process for other dependencies (see page Essential and Optional Third Party Dependencies for information on supported versions of third party libraries as well as download links) and fill the missing information within the CMake interface until configuration is successful (no more red lines indicating missing dependencies).

Advanced

You may also decide to solve missing dependencies using the CMake 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.

Compilation of an Example

Once the configuration process is successful, hit the Generate button, and you will find the file Triangulation_2_examples.sln in the directory C:\dev\CGAL-5.3.1\examples\Triangulation_2\build. Double-click it in order to open it. You will see one project per .cpp file. Compile them all, or just the one you are interested in.

Configuring and Compiling My Code Using CGAL

Configuring and compiling your own code is practically the same as for CGAL examples if you use cmake. Running cmake (or cmake-gui) requires a CMakeLists.txt file. This file is automatically provided for all examples and demos of CGAL. For your own programs, you are advised to look at the CMakeLists.txt files in the example folder of the package(s) that you are using to learn how to specify CGAL and additional third party dependencies.

Trying CGAL algorithms using a Precompiled Demo

CGAL provides a few demos offering a graphical user interface for some CGAL algorithms. All precompiled demos are available for download on the Package Overview page. Two links are provided in the column on the right: the demo itself (under Windows Demo) and a set of dlls (under Common Demo Dlls) that contains dlls files that must be placed in the same directory as the .exe of the demo. See for example the 3D Convex Hulls package.