mirror of https://github.com/CGAL/cgal
283 lines
15 KiB
Plaintext
283 lines
15 KiB
Plaintext
/*!
|
|
\page windows Using %CGAL on Windows (with Visual C++)
|
|
\cgalAutoToc
|
|
|
|
\cgal \cgalReleaseNumber is supported for the following \ms Visual `C++` compilers:
|
|
15.9, 16.0, 17.0 (\visualstudio 2017, 2019, and 2022).
|
|
|
|
\cgal is a library that has mandatory dependencies that must be first installed:
|
|
\ref thirdpartyBoost and a \ref thirdpartyMP.
|
|
|
|
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.
|
|
|
|
\section sec-installing-with-vcpkg Installing CGAL with the Vcpkg Library Manager
|
|
|
|
\subsection ssec-vcpk-install-vcpk Installing Vcpkg
|
|
|
|
The first step is to clone or download `vcpkg` from
|
|
<a href="https://github.com/microsoft/vcpkg">https://github.com/microsoft/vcpkg</a>.
|
|
|
|
C:\dev> git clone https://github.com/microsoft/vcpkg
|
|
C:\dev> cd vcpkg
|
|
C:\dev\vcpkg> .\bootstrap-vcpkg.bat
|
|
|
|
\subsection ssec-vcpk-install-cgal 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
|
|
<a href="https://github.com/microsoft/vcpkg/blob/master/docs/examples/installing-and-using-packages.md#step-2-use">official documentation</a>
|
|
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.
|
|
|
|
\subsection ssec-vcpkg-compile-example 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:
|
|
<a href="https://github.com/CGAL/cgal/releases/download/v\cgalReleaseNumber/CGAL-\cgalReleaseNumber-examples.zip">CGAL-\cgalReleaseNumber-examples.zip</a>
|
|
|
|
Assuming you have unzipped this file in your home directory `C:\Users\Me`,
|
|
we will next compile an example from the 2D Triangulation package.
|
|
|
|
\subsubsection sssec-vcpkg-configuration-example 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 \ref seccmake for more information on supported versions and where to download it).
|
|
|
|
The end of the process is marked by the generation of a Visual \cpp solution
|
|
and a project file that you can use to build your program.
|
|
|
|
C:\Users\Me\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2
|
|
C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build
|
|
C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build
|
|
C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui ..
|
|
|
|
The command `cmake-gui` launches the graphical interface for `cmake`.
|
|
When you hit the *Configure* button, you must:
|
|
<ul>
|
|
<li>specify the *Generator* (e.g., Visual Studio 16 2019),</li>
|
|
<li>specify the *Optional Platform* (e.g., `x64` in case you want to create 64 bit binaries),</li>
|
|
<li>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`).</li>
|
|
</ul>
|
|
|
|
\cgalFigureBegin{toolchain,toolchain.png}
|
|
The box to check to get to the toolchain option
|
|
\cgalFigureEnd
|
|
|
|
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`.
|
|
|
|
\subsubsection sssect-vcpkg-additional-dependencies 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 qt6
|
|
|
|
Remember to specify `--triplet` or the related environment variable in case you target 64-bit applications.
|
|
|
|
As Qt6 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 \ref thirdparty
|
|
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).
|
|
|
|
\cgalAdvancedBegin
|
|
You may also decide to solve missing dependencies using the `CMake` command line tool (which is not recommended).
|
|
If so, the page \ref configurationvariables lists variables which can be used to specify
|
|
the location of third-party software.
|
|
\cgalAdvancedEnd
|
|
|
|
\subsubsection sssect-vcpkg-compilation 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-\cgalReleaseNumber\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.
|
|
|
|
\subsection subsect-vpckg-my-code 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.
|
|
|
|
\section install-from-source Installing from the Source Archive
|
|
|
|
You can download and extract `CGAL-\cgalReleaseNumber``.zip` from https://www.cgal.org/download/windows.html.
|
|
|
|
\subsection ssect-installer-gmp-mpfr Installing GMP and MPFR
|
|
|
|
Precompiled version of \gmp and \mpfr are provided in the asset <i>GMP and MPFR libraries, for Windows 64bits</i>
|
|
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-\cgalReleaseNumber` 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-\cgalReleaseNumber``\``auxiliary``\``gmp`).
|
|
|
|
|
|
\subsection ssect-installer-boost Installing Boost
|
|
|
|
`Boost` is a mandatory dependency of \cgal. Binary versions of `Boost` are available on
|
|
<a href="https://sourceforge.net/projects/boost/files/boost-binaries/">SourceForge</a>.
|
|
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 \cgalReleaseNumber was released, the latest version of `Boost` was 1.71.
|
|
A typical installation of `Boost` would consist of the following steps:
|
|
|
|
<ul>
|
|
<li>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).</li>
|
|
<li>Extract the files to a new directory, e.g. `c:\dev\libboost_1_71_0`.</li>
|
|
<li>Set the following two environment variables to point respectively to the path of the libraries and the headers
|
|
<ul>
|
|
<li>`BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`</li>
|
|
<li>`BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0`</li>
|
|
</ul>
|
|
as this will help `cmake` to find Boost.</li>
|
|
<li>Add the path to the Boost `dlls` (`C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`) files to the `PATH` environment variable.</li>
|
|
</ul>
|
|
|
|
\subsection ssect-installer-compile-example 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 \ref seccmake 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 \cpp solution
|
|
and a project file that you can use to build your program.
|
|
|
|
C:\dev\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2
|
|
C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build
|
|
C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build
|
|
C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui ..
|
|
|
|
The command `cmake-gui` launches the graphical interface for `cmake`.
|
|
When you hit the *Configure* button, you must:
|
|
<ul>
|
|
<li>Specify the *Generator*, e.g., Visual Studio 16 2019), and</li>
|
|
<li>specify an *Optional Platform* (`x64` in case you want to create 64 bit binaries).</li>
|
|
</ul>
|
|
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`.
|
|
|
|
\subsubsection ssect-installer-additional-dependencies 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:
|
|
|
|
<ul>
|
|
<li>
|
|
Download and install the Qt library for open source development package for your Visual Studio version at
|
|
<a href="https://www.qt.io/download-open-source#source">https://www.qt.io/download-open-source#source</a>.</li>
|
|
<li>Add the environment variable `QTDIR` pointing to the place you installed Qt, e.g., `C:\dev\Qt\Qt6.13.1`,
|
|
as this will help `cmake` to find Qt.</li>
|
|
<li>Add the bin directory of Qt, e.g. add `C:\dev\Qt\Qt6.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.</li>
|
|
</ul>
|
|
|
|
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 \ref thirdparty 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).
|
|
|
|
\cgalAdvancedBegin
|
|
You may also decide to solve missing dependencies using the `CMake` command line tool (which is not recommended).
|
|
If so, the page \ref configurationvariables lists variables which can be used to specify
|
|
the location of third-party software.
|
|
\cgalAdvancedEnd
|
|
|
|
\subsubsection sssect-installer-compilation 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-\cgalReleaseNumber\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.
|
|
|
|
\subsection subsect-installer-my-code 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.
|
|
|
|
\section sec-win-demo 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 \ref packages 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 \ref PkgConvexHull3 package.
|
|
|
|
*/
|