|
CGAL 5.2.1 - Manual
|
|
CGAL 5.2.1 - Manual
|
CGAL 5.2.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.
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
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.
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.2.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.
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.2.1> cd examples\Triangulation_2 C:\Users\Me\CGAL-5.2.1\examples\Triangulation_2> mkdir build C:\Users\Me\CGAL-5.2.1\examples\Triangulation_2> cd build C:\Users\Me\CGAL-5.2.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:
x64 in case you want to create 64 bit binaries), vcpkg.cmake within the directory where you have installed vcpkg, e.g. C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake). 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.
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).
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.
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.2.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 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.
You can download and extract CGAL-5.2.1.zip from https://www.cgal.org/download/windows.html.
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.2.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.2.1\auxiliary\gmp).
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.2.1 was released, the latest version of Boost was 1.71. A typical installation of Boost would consist of the following steps:
c:\dev\libboost_1_71_0. BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0 cmake to find Boost. dlls (C:\dev\libboost_1_71_0\lib64-msvc-XX.Y) files to the PATH environment variable. Download and run CGAL-5.2.1-Setup.exe from https://www.cgal.org/download/windows.html. It is a self extracting executable that downloads the CGAL header files, and optionally the source code of the examples and demos. Additionally, it can download the precompiled versions of GMP and MPFR. You must specify if you want the 32 or the 64 bit versions of these two libraries.
Setting the environment variable CGAL_DIR to C:\dev\CGAL-5.2.1 is a good idea to help cmake to find CGAL during the configuration process, detailed in the next section.
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.2.1> cd examples\Triangulation_2 C:\dev\CGAL-5.2.1\examples\Triangulation_2> mkdir build C:\dev\CGAL-5.2.1\examples\Triangulation_2> cd build C:\dev\CGAL-5.2.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:
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.
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:
QTDIR pointing to the place you installed Qt, e.g., C:\dev\Qt\Qt5.13.1, as this will help cmake to find Qt. 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).
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.
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.2.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 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.
1.8.13