CGAL 5.6.3 - Manual

Loading...
Searching...
No Matches
Using CGAL on Windows (with Visual C++)

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

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.6.3-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.6.3> cd examples\Triangulation_2
    C:\Users\Me\CGAL-5.6.3\examples\Triangulation_2> mkdir build
    C:\Users\Me\CGAL-5.6.3\examples\Triangulation_2> cd build
    C:\Users\Me\CGAL-5.6.3\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`).

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 Compilers and 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.6.3\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.6.3``.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.6.3` 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.6.3``\``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.6.3 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.6.3> cd examples\Triangulation_2
    C:\dev\CGAL-5.6.3\examples\Triangulation_2> mkdir build
    C:\dev\CGAL-5.6.3\examples\Triangulation_2> cd build
    C:\dev\CGAL-5.6.3\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 Compilers and 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.6.3\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. A link is provided in the column on the right, to download an archive. It contains the demo executable itself, and a set of dll files that must remain in the same directory as the `.exe` of the demo. See for example the 3D Convex Hulls package.