songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Misc Installation Documentation Updates

This commit is contained in:
Mael Rouxel-Labbé 2019-10-25 14:05:15 +02:00
parent 8978d919bd
commit e6eb4812eb
5 changed files with 120 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
Documentation/doc/Documentation/Getting_started.txt
View File

@ -1,19 +1,18 @@
/*! /*!
\page general_intro Getting Started with %CGAL \page general_intro Getting Started with %CGAL
- \subpage usage Using \cgal on Unix - \subpage usage
- \subpage windows Using \cgal on Windows - \subpage windows
- \subpage thirdparty lists required and optional third party libraries. - \subpage thirdparty gives information (supported versions, download links) of the required and optional third party libraries.
- \subpage manual gives an idea of where you should look for documentation. - \subpage manual gives an idea of where you should look for documentation.
- \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior. - \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior.
Once you are familiar with building your programs with \cgal and how the documentation is structured, Once you are familiar with building your programs with \cgal and how the documentation is structured,
you can head over to the \ref tutorials for a hand-in-hand introduction to \cgal data structures you can head over to the \ref tutorials for a gentle introduction to \cgal, or directly to the package(s)
and algorithms, or directly to the package(s) that interest you the \ref packages. Each package that interest you the \ref packages. Each package contains simple examples of the various functionalities of the package.
contains simple examples of the various functionalities of the package.
*/ */

18
Documentation/doc/Documentation/Usage.txt
View File

@ -1,5 +1,5 @@
/*! /*!
\page usage Using %CGAL on UNIX \page usage Using %CGAL on Linux and macOS
\cgalAutoToc \cgalAutoToc
Since \cgal version 5.0, \cgal is header-only be default, which means Since \cgal version 5.0, \cgal is header-only be default, which means
@ -9,8 +9,8 @@ However, some dependencies of \cgal might still need to be installed.
\section usage_introduction Quick Start: Compiling a Program using CGAL \section usage_introduction Quick Start: Compiling a Program using CGAL
Assuming that you have obtained \cgal through one of the package managers offering \cgal on your platform Assuming that you have obtained \cgal through one of the package managers offering \cgal on your platform
(see Section \ref secgettingcgal), compiling <a href="TODO">\cgal examples</a> (see Section \ref secgettingcgal), you can download \cgal examples <a href="TODO">here</a>
is as simple as: and the compilation of an example is as simple as:
cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory
cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples
@ -19,7 +19,7 @@ is as simple as:
Compiling your own program is similar: Compiling your own program is similar:
cd /path/to/your/program cd /path/to/your/program
cgal_create_CMakeLists -s executable cgal_create_CMakeLists -s your_program
cmake -DCMAKE_BUILD_TYPE=Release . cmake -DCMAKE_BUILD_TYPE=Release .
make make
@ -55,7 +55,7 @@ and must be downloaded <a href="TODO">here</a>.
On most operating systems, package managers offer \cgal and its essential third party dependencies. On most operating systems, package managers offer \cgal and its essential third party dependencies.
On `macOS`, we recommend using of <a href="https://brew.sh/">Homebrew</a> in the following way: On macOS, we recommend using of <a href="https://brew.sh/">Homebrew</a> in the following way:
brew install cgal brew install cgal
@ -101,8 +101,8 @@ The directory `include/CGAL/OpenNL` contains a distribution of the
which provides solvers for sparse linear systems, especially designed for the Computer Graphics community. which provides solvers for sparse linear systems, especially designed for the Computer Graphics community.
\sc{OpenNL} is not part of \cgal and has its own license. \sc{OpenNL} is not part of \cgal and has its own license.
The only documentation shipped within \cgal sources is the present The only documentation shipped within \cgal sources is the present manual.
installation manual. The \cgal manual can be accessed online at The \cgal manual can also be accessed online at
<a href="https://doc.cgal.org/latest/Manual/index.html">`https://doc.cgal.org`</a> <a href="https://doc.cgal.org/latest/Manual/index.html">`https://doc.cgal.org`</a>
or downloaded separately at or downloaded separately at
<a href="https://github.com/CGAL/cgal/releases">`https://github.com/CGAL/cgal/releases`</a>. <a href="https://github.com/CGAL/cgal/releases">`https://github.com/CGAL/cgal/releases`</a>.
@ -190,10 +190,10 @@ for all shipped examples and demos of \cgal. For other programs, CMake can also
and build user programs, but one has to provide the corresponding `CMakeLists.txt`. 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, This script can be generated either manually, or with the help of a shell-script,
see Section \ref devman_create_cgal_CMakeLists. Using this shell-script, see Section \ref devman_create_cgal_CMakeLists. Using this shell-script,
the process of configuring a user's program called `executable.cpp` amounts to: the process of configuring a user's program called `your_program.cpp` amounts to:
cd /path/to/your/program cd /path/to/your/program
cgal_create_CMakeLists -s executable cgal_create_CMakeLists -s your_program
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release . cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release .
Note that the script `cgal_create_CMakeLists` creates a very coarse `CMakeLists.txt` file which Note that the script `cgal_create_CMakeLists` creates a very coarse `CMakeLists.txt` file which

149
Documentation/doc/Documentation/advanced/Installation.txt
View File

@ -1,27 +1,31 @@
/*! /*!
\page installation Installation \page installation Building %CGAL libraries (non header-only mode)
\cgalAutoToc \cgalAutoToc
<b>Since \cgal version 5.0, \cgal is header-only be default, which means <b>Since \cgal version 5.0, \cgal is header-only be default, which means
that there is no need to compile and install anything before it can be used.</b> that there is no need to compile \cgal or its libraries before it can be used.
However, the dependencies of \cgal might still need to be installed.
This page is a step-by-step description of how to configure, build, and install \cgal 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 \ref general_intro.</b>
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. in case you do not wish to use the - now enabled by default - header-only mode of \cgal.
It is also possible to install \cgal using package managers on some operating systems,
see Section \ref secspecificinstall. It is assumed that you have downloaded a source archive of \cgal, and are using Linux or macOS.
\section installation_idealworld Quick Installation \section installation_idealworld Quick Installation
Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as: Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as:
cd $HOME/CGAL-\cgalReleaseNumber cd $HOME/CGAL-\cgalReleaseNumber
cmake -DCMAKE_BUILD_TYPE=Release . # configure CGAL mkdir build
make # build CGAL cd build
make install # install CGAL cmake -DCMAKE_BUILD_TYPE=Release .. # configure CGAL
cd examples/Triangulation_2 # go to an example directory make # build CGAL
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . # configure the examples make install # install CGAL
make # build the examples cd examples/Triangulation_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber/build -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. In a less ideal world, you might have to install some required tools and third-party libraries.
This is what this page is about. This is what this page is about.
@ -33,8 +37,7 @@ set compiler and linker flags, specify which
third-party libraries you want to use and where they can be found, and third-party libraries you want to use and where they can be found, and
which \cgal libraries you want to build. Gathering which \cgal libraries you want to build. Gathering
all this information is called <I>configuration</I>. all this information is called <I>configuration</I>.
The end of the process is marked by the generation of a makefile or a The end of the process is marked by the generation of a makefile that you can use to build \cgal.
Visual \cpp solution and project file that you can use to build \cgal.
CMake maintains configuration parameters in so-called <I>cmake variables</I>. Some of the CMake CMake maintains configuration parameters in so-called <I>cmake variables</I>. Some of the CMake
variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others
@ -61,7 +64,7 @@ Note that some libraries have specific dependencies in addition to the essential
| `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 | | `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 |
Shared libraries, also called <I>dynamic-link libraries</I>, are built by default Shared libraries, also called <I>dynamic-link libraries</I>, are built by default
(`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You (`.so` on Linux, `.dylib` on macOS). You
can choose to produce static libraries instead, by setting the CMake can choose to produce static libraries instead, by setting the CMake
variable `BUILD_SHARED_LIBS` to `FALSE`. variable `BUILD_SHARED_LIBS` to `FALSE`.
@ -123,21 +126,21 @@ The simplest way to start the configuration process is to run the graphical
user interface of CMake, `cmake-gui`. You must pass as user interface of CMake, `cmake-gui`. You must pass as
argument the root directory of \cgal. For example: argument the root directory of \cgal. For example:
cd CGAL-\cgalReleaseNumber cd CGAL-\cgalReleaseNumber/build
cmake-gui . # Notice the dot to indicate the current directory cmake-gui .. # The two dots indicate the parent directory
After `cmake-gui` opens, press 'Configure'. After `cmake-gui` opens, press *Configure*.
A dialog will pop up and you will have to choose what shall be generated. 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 After you have made your choice and pressed *Finish*, you will see
the output of configuration tests in the lower portion of the application. the output of configuration tests in the lower portion of the application.
When these tests are done, you will see many When these tests are done, you will see many
red entries in the upper portion of the application. Just ignore them and press 'Configure'. 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. 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. 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. This typically happens if you have installed software at non-standard locations.
Providing information and pressing 'Configure' goes on until Providing information and pressing *Configure* goes on until
all entries are grayed. You are now ready to press 'Generate'. Once this is all entries are grayed. You are now ready to press *Generate*. Once this is
done, you can quit `cmake-gui`. done, you can quit `cmake-gui`.
\subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool \subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool
@ -148,8 +151,8 @@ The command line tool `cmake` accepts CMake variables as arguments of the form `
in the example above, but this is only useful if you already know which variables need to be explicitly defined. in the example above, but this is only useful if you already know which variables need to be explicitly defined.
For example: For example:
cd CGAL-\cgalReleaseNumber cd CGAL-\cgalReleaseNumber/build
cmake . # Notice the dot to indicate the current directory cmake ..
The configuration process not only determines the location of the required dependencies, it also dynamically generates a 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 `compiler_config.h` file, which encodes the properties of your system and a special file named
@ -172,13 +175,13 @@ 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 that summarize the configuration of \cgal and will be essential during the configuration and
building of a program using \cgal, see Section \ref installation_buildprogram. building of a program using \cgal, see Section \ref installation_buildprogram.
\section seccmakeoutofsource Multiple Variants of Makefiles (Out-of-Source Builds) \section seccmakeoutofsource Multiple Builds
While you can choose between release or debug builds, and shared or static libraries, 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 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. different directory for each variant you are interested in, each with its own selection of configuration parameters.
CMake stores the resulting makefiles and project files, along with several temporary and auxiliary files such 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 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 takes the source files and configuration scripts from
`CMAKE_SOURCE_DIR`. `CMAKE_SOURCE_DIR`.
@ -187,16 +190,16 @@ The binary and source directories do not need to be the same. Thus, you can conf
distinct directory for each configuration and by running CMake from there. This is known in CMake terminology distinct directory for each configuration and by running CMake from there. This is known in CMake terminology
as <I>out-of-source configuration</I>, as opposite to an <I>in-source as <I>out-of-source configuration</I>, as opposite to an <I>in-source
configuration</I>, as showed in the previous sections. configuration</I>, as showed in the previous sections.
You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/build/debug` and
`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively: `CGAL-\cgalReleaseNumber``/build/release` for two configurations, respectively:
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug mkdir CGAL-\cgalReleaseNumber/build/debug
cd CGAL-\cgalReleaseNumber/cmake/platforms/debug cd CGAL-\cgalReleaseNumber/build/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../.. cmake -DCMAKE_BUILD_TYPE=Debug ../..
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release mkdir CGAL-\cgalReleaseNumber/build/release
cd CGAL-\cgalReleaseNumber/cmake/platforms/release cd CGAL-\cgalReleaseNumber/build/release
cmake -DCMAKE_BUILD_TYPE=Release ../../.. cmake -DCMAKE_BUILD_TYPE=Release ../..
\section secbuilding Building CGAL \section secbuilding Building CGAL
@ -205,9 +208,8 @@ The nature of the build files depends on the generator used during configuration
contain several <I>targets</I>, one per library, and a default global target corresponding contain several <I>targets</I>, one per library, and a default global target corresponding
to all the libraries. to all the libraries.
For example, in a \sc{Unix}-like environment the default generator produces For example, in a \sc{Unix}-like environment the default generator produces makefiles.
makefiles. You can use the `make` command-line tool for the You can use the `make` command-line tool for the succeeding build step as follows:
succeeding build step as follows:
# build all the selected libraries at once # build all the selected libraries at once
make make
@ -215,20 +217,6 @@ succeeding build step as follows:
The resulting libraries are placed in the subdirectory `lib` under `<CMAKE_BINARY_DIR>` The resulting libraries are placed in the subdirectory `lib` under `<CMAKE_BINARY_DIR>`
(which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration). (which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration).
With generators other than `UNIX Makefiles`, the resulting build files
are solution and project files which should be launched in an \sc{Ide},
such as Visual Studio or KDevelop3. They will contain the targets described
above, which you can manually build as with any other solution/project within your \sc{Ide}.
Alternatively, you can build it with the command line version of the
\sc{Visual Studio Ide}:
devenv CGAL.sln /Build Debug
The "Debug" argument is needed because CMake creates solution files for
all four configurations, and you need to explicitly choose one when building
(the other choices are `Release`, `RelWithDebInfo`, and `MinSizeRel`).
\cgalAdvancedBegin \cgalAdvancedBegin
The build files produced by CMake are autoconfigured. That The build files produced by CMake are autoconfigured. That
is, if you change any of the dependencies, the build step is, if you change any of the dependencies, the build step
@ -236,9 +224,7 @@ automatically goes all the way back to the configuration step. This
way, once the target has been configured the very first time by way, once the target has been configured the very first time by
invoking cmake, you don't necessarily need to invoke `cmake` invoking cmake, you don't necessarily need to invoke `cmake`
again. Rebuilding will call itself `cmake` and re-generate the again. Rebuilding will call itself `cmake` and re-generate the
build file whenever needed. Keep this in mind if you configure \cgal build file whenever needed.
for the Visual Studio IDE since a build could then change the
solution/project file in-place and VS will prompt you to reload it.
\cgalAdvancedEnd \cgalAdvancedEnd
\subsection ssec_installation_build_ex_demos Building Examples and Demos \subsection ssec_installation_build_ex_demos Building Examples and Demos
@ -270,26 +256,22 @@ of a particular package by typing `make help | grep <package>`.
On many platforms, library pieces such as headers, docs and binaries On many platforms, library pieces such as headers, docs and binaries
are expected to be placed in specific locations. A typical example are expected to be placed in specific locations. A typical example
being `/usr/include` and `/usr/lib` on \sc{Unix}-like being `/usr/include` and `/usr/lib`. The process
operating systems or `C:/Program Files/` on Windows. The process
of placing or copying the library elements into its standard location of placing or copying the library elements into its standard location
is sometimes referred to as <I>Installation</I> and it is a is sometimes referred to as <I>Installation</I> and it is a
postprocessing step after the build step. postprocessing step after the build step.
CMake carries out the installation by producing a build target named <I>install</I>. CMake carries out the installation by producing a build target named <I>install</I>.
Assuming you have successfully configured and built \cgal as demonstrated in the previous sections, Assuming you have successfully configured and built \cgal as demonstrated in the previous sections,
the installation simply amounts (in a \sc{Unix}-like environment) to: the installation simply amounts to:
# install CGAL # install CGAL
make install make install
If you use a generator that produces IDE files (for Visual Studio for instance), there will be an optional
`INSTALL` project, which you will be able to <I>"build"</I> to execute the installation step.
\cgalAdvancedBegin \cgalAdvancedBegin
The files are copied into a directory tree relative to the <I>installation directory</I> determined by the The files are copied into a directory tree relative to the <I>installation directory</I> determined by the
CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under \sc{Unix}-like operating systems CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under \sc{Unix}-like operating systems.
and `C:\Program Files` under Windows. If you want to install to a different location, you must override that CMake If you want to install to a different location, you must override that CMake
variable explicitly <I>at the configuration time</I> and not when executing the install step. variable explicitly <I>at the configuration time</I> and not when executing the install step.
\cgalAdvancedEnd \cgalAdvancedEnd
@ -307,51 +289,18 @@ For other programs, CMake can also be used to configure
and build user programs, but one has to provide the corresponding `CMakeLists.txt`. 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, This script can be generated either manually, or with the help of a shell-script,
see Section \ref devman_create_cgal_CMakeLists. Using this shell-script, see Section \ref devman_create_cgal_CMakeLists. Using this shell-script,
the process of configuring a user's program called `executable.cpp` amounts to: the process of configuring a user's program called `your_program.cpp` amounts to:
cd /path/to/your/program cd /path/to/your/program
cgal_create_CMakeLists -s executable cgal_create_CMakeLists -s your_program
cmake -DCGAL_DIR=XXXXXX -CMAKE_BUILD_TYPE=Release . cmake -DCGAL_DIR=XXXXXX -CMAKE_BUILD_TYPE=Release .
make make
In order to configure a program, you need to indicate the location of the configuration file In order to configure a program, you need to indicate the location of the \cgal configuration file
in the CMake variable `CGAL_DIR` (as indicated in the example above). 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`. 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 The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense
if having multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. if you have multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource.
\section secspecificinstall OS Specific Installation
Some operating systems with package managers offer \cgal and its
essential third party software through the manager,
for instance, Mac OS X or some Linux distribution (e.g. Debian).
For Windows, an installer is provided.
\subsection sseccgalmacosxe CGAL on macOS
The \cgal project recommends the use of <a href="https://brew.sh/">Homebrew</a>, in the following way:
brew install cgal
\subsection sseccgaldebian CGAL on Linux
For instance in Debian/Ubuntu, use apt-get in the following way:
sudo apt-get install libcgal-dev
To get the demos, use:
sudo apt-get install libcgal-demo
For other distributions, please consult your respective package manager documentation.
\subsection sseccgalwindows CGAL on Windows
You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html.
It is a self extracting executable that installs the \cgal source, and that allows you
to select and download some precompiled third party libraries. However, you will need to compile
the library using your favorite compiler.
A <a href="https://www.cgal.org/download/windows.html">tutorial</a> is provided on how to proceed with Microsoft Visual Studio.
*/ */

125
Documentation/doc/Documentation/windows.txt
View File

@ -1,5 +1,5 @@
/*! /*!
\page windows Installing %CGAL for Visual C++ on Windows \page windows Using %CGAL on Windows (with Visual C++)
\cgalAutoToc \cgalAutoToc
\cgal is a library that has mandatory dependencies that must be first installed: \cgal is a library that has mandatory dependencies that must be first installed:
@ -19,20 +19,18 @@ you will want to use the \cgal Installer.
We explain the two approaches in the next two sections. We explain the two approaches in the next two sections.
\section sec-installing-with-vcpkg Installing CGAL with the Vcpkg library manager \section sec-installing-with-vcpkg Installing CGAL with the Vcpkg Library Manager
\subsection ssec-vcpk-install-vcpk Installing Vcpkg \subsection ssec-vcpk-install-vcpk Installing Vcpkg
The first step is to clone or download `vcpkg` from The first step is to clone or download `vcpkg` from
<a href="https://github.com/microsoft/vcpkg">https://github.com/microsoft/vcpkg</a>. <a href="https://github.com/microsoft/vcpkg">https://github.com/microsoft/vcpkg</a>.
\code{.sh} C:\dev> git clone https://github.com/microsoft/vcpkg
C:\dev> git clone https://github.com/microsoft/vcpkg C:\dev> cd vcpkg
C:\dev> cd vcpkg C:\dev\vcpkg> .\bootstrap-vcpkg.bat
C:\dev\vcpkg> .\bootstrap-vcpkg.bat
\endcode
\subsection ssec-vcpk-install-cgal Installing with Vcpkg \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++ 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 installed on your machine. If you develop 64 bit software you must
@ -44,9 +42,7 @@ of `vcpkg` if you want to compile for an older version of a compiler.
You are now ready to install \cgal: You are now ready to install \cgal:
\code{.sh} C:\dev\vcpkg> ./vcpkg.exe install cgal
C:\dev\vcpkg> ./vcpkg.exe install cgal
\endcode
This will take several minutes as it downloads \mpir (a fork of \gmp), This will take several minutes as it downloads \mpir (a fork of \gmp),
\mpfr, all boost header files, and it will compile \mpir and \mpfr, as well \mpfr, all boost header files, and it will compile \mpir and \mpfr, as well
@ -56,7 +52,6 @@ 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. 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 \subsection ssec-vcpkg-compile-example Compiling an Example
In this section we show how to compile a program that uses \cgal. In this section we show how to compile a program that uses \cgal.
@ -77,13 +72,12 @@ Gathering all this information is called *configuration* and we use *CMake* as c
The end of the process is marked by the generation of a Visual \cpp solution 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. and a project file that you can use to build your program.
\code{.sh} C:\Users\Me\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2
C:\Users\Me\CGAL-5.0> cd examples\Triangulation_2 C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build
C:\Users\Me\CGAL-5.0\examples\Triangulation_2> mkdir build C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build
C:\Users\Me\CGAL-5.0\examples\Triangulation_2> cd build C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui ..
C:\Users\Me\CGAL-5.0\examples\Triangulation_2\build> cmake-gui .. # cmake-gui is the graphical interface for cmake, which we recommend to use
\endcode
The command `cmake-gui` launches the graphical interface for `cmake`.
When you hit the *Configure* button, you must: When you hit the *Configure* button, you must:
<ul> <ul>
<li>specify the *Generator* (e.g., Visual Studio 16 2019),</li> <li>specify the *Generator* (e.g., Visual Studio 16 2019),</li>
@ -96,31 +90,24 @@ You will see entries for where header files and libraries are taken from.
\subsubsection sssect-vcpkg-additional-dependencies Additional Dependencies \subsubsection sssect-vcpkg-additional-dependencies Additional Dependencies
Some \cgal packages also have additional dependencies. During the configuration Some \cgal packages also have additional dependencies. For example, during the configuration process
of the above examples, you may have observed the following message: above, you may have observed the following message:
\code{.sh} NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled
NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled
\endcode
\cgal is a library of algorithms and data structures and as such does \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` 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 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`: CMake variables and paths. Otherwise, you can also install it using `vcpkg`:
\code{.sh} C:\dev\vcpkg> ./vcpkg.exe install qt5
C:\dev\vcpkg> .\vcpkg.exe install qt5
\endcode
Remember to specify `--triplet` or the related environment variable in case you target 64-bit applications. 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 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*: you can save download and compilation time by specifying an *installation option*:
\code{.sh} C:\dev\vcpkg> ./vcpkg.exe install cgal [qt]
C:\dev\vcpkg> ./vcpkg.exe install cgal [qt]
\endcode
In both cases, when you start `cmake-gui` again and hit the *Configure* button, 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. the CMake variables and paths concerning Qt should now be filled.
@ -139,44 +126,44 @@ the location of third-party software.
\subsubsection sssect-vcpkg-compilation Compilation of an Example \subsubsection sssect-vcpkg-compilation Compilation of an Example
Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` Once the configuration process is successful, hit the *Generate* button,
in the directory `C:\Users\Me\CGAL-5.0\examples\Triangulation_2\build`. 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. 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. Compile them all, or just the one you are interested in.
\subsection subsect-vpckg-my-code Configuring and Compiling My Code Using CGAL \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 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. 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, 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 you are advised to look at the `CMakeLists.txt` files in the example
folder of the package that you are using to learn how to specify \cgal and additional third party folder of the package(s) that you are using to learn how to specify \cgal and additional third party
dependencies. dependencies.
\section install-with-installer Installing with the CGAL Installer \section install-with-installer Installing with the CGAL Installer
You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. You can download and run `CGAL-\cgalReleaseNumber``-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 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 precompiled versions of \gmp and \mpfr. examples and demos. Additionally, it can download precompiled versions of \gmp and \mpfr.
\subsection ssect-installer-boost Installing Boost \subsection ssect-installer-boost Installing Boost
Binary versions of `Boost` are available on SourceForge. `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. 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. 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. 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> <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>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>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 <li>Set the following two environment variables to point respectively to the path of the libraries and the headers
<ul>
\code{.sh} <li>`BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`</li>
BOOST_LIBRARYDIR=C:\dev\libboost_1_71_0\lib64-msvc-XX.Y <li>`BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0`</li>
BOOST_INCLUDEDIR=C:\dev\libboost_1_71_0 </ul>
\endcode
as this will help `cmake` to find Boost.</li> 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> <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> </ul>
@ -186,15 +173,15 @@ as this will help `cmake` to find Boost.</li>
Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from
<a href="https://www.cgal.org/download/windows.html">https://www.cgal.org/download/windows.html</a>. <a href="https://www.cgal.org/download/windows.html">https://www.cgal.org/download/windows.html</a>.
It is a self extracting executable that downloads the \cgal header files, and optionally the source code of the 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 examples and demos. Additionally, it can download the precompiled versions of \gmp and \mpfr. You must
specify if yoy want the 32 or the 64 bit versions of these two libraries. specify if you want the 32 or the 64 bit versions of these two libraries.
\cgal being a header-only library, there is no need to compile it. Set the environment variable `CGAL_DIR` to `C:\dev\CGAL-5.0`, Setting the environment variable `CGAL_DIR` to `C:\dev\CGAL-\cgalReleaseNumber` is a good idea
as this will help `cmake` to find \cgal. to help `cmake` to find \cgal during the configuration process, detailed in the next section.
\subsection ssect-installer-compile-example Compiling an Example \subsection ssect-installer-compile-example Compiling an Example
We assume you have downloaded the examples with the \cgal Installer. 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 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. and linker flags, specify which third-party libraries you want to use and where they can be found.
@ -205,14 +192,13 @@ download it).
The end of the process is marked by the generation of a Visual \cpp solution 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. and a project file that you can use to build your program.
\code{.sh} C:\dev\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2
C:\dev\CGAL-5.0> cd examples\Triangulation_2 C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build
C:\dev\CGAL-5.0\examples\Triangulation_2> mkdir build C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build
C:\dev\CGAL-5.0\examples\Triangulation_2> cd build C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui ..
C:\dev\CGAL-5.0\examples\Triangulation_2\build> cmake-gui .. # cmake-gui is the graphical interface for cmake, which we recommend to use
\endcode
When you hit the *Configure* button you must: The command `cmake-gui` launches the graphical interface for `cmake`.
When you hit the *Configure* button, you must:
<ul> <ul>
<li>Specify the *Generator*, e.g., Visual Studio 16 2019), and</li> <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> <li>specify an *Optional Platform* (`x64` in case you want to create 64 bit binaries).</li>
@ -222,16 +208,15 @@ You will see entries for where header files and libraries are taken from.
\subsubsection ssect-installer-additional-dependencies Additional Dependencies \subsubsection ssect-installer-additional-dependencies Additional Dependencies
Individual \cgal packages may also have additional dependencies. During the configuration Some \cgal packages also have additional dependencies. For example, during the configuration process
of the above examples, you may have observed the following message: above, you may have observed the following message:
\code{.sh} NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled
NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled
\endcode
\cgal is a library of algorithms and data structures and as such does \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 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 we install it now. 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> <ul>
<li> <li>
@ -242,10 +227,11 @@ Download and install the Qt library for open source development package for your
as this will help `cmake` to find Qt.</li> as this will help `cmake` to find Qt.</li>
<li>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`. <li>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.</li> To avoid any conflict with another dll with the same name from another folder, add this path as the first in the list.</li>
<li>When you start `cmake-gui` again and hit the *Configure* button,
the CMake variables concerning Qt should now be filled.</li>
</ul> </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 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 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 within the `CMake` interface until configuration is successful (no more red lines indicating
@ -259,10 +245,11 @@ the location of third-party software.
\subsubsection sssect-installer-compilation Compilation of an Example \subsubsection sssect-installer-compilation Compilation of an Example
Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` Once the configuration process is successful, hit the *Generate* button,
in the directory `C:\dev\CGAL-5.0\examples\Triangulation_2\build`. and you will find the file `Triangulation_2_examples.sln`
Double click in order to open it. You will see one project per `.cpp` file. in the directory `C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build`.
Compile them all or just the one you are interested in. 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 \subsection subsect-installer-my-code Configuring and Compiling My Code Using CGAL
@ -270,7 +257,7 @@ Configuring and compiling your own code is practically the same as for \cgal exa
if you use `cmake`. Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. 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, 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 you are advised to look at the `CMakeLists.txt` files in the example
folder of the package that you are using to learn how to specify \cgal and additional third party folder of the package(s) that you are using to learn how to specify \cgal and additional third party
dependencies. dependencies.
\section install-with-tarball Installing from the Source Archive \section install-with-tarball Installing from the Source Archive

2
README.md
View File

@ -15,7 +15,7 @@ Getting Started with CGAL
========================= =========================
**Since version 5.0, CGAL is a header-only library, meaning that **Since version 5.0, CGAL is a header-only library, meaning that
it is no longer needed to build or install CGAL before it can be used.** it is no longer needed to build CGAL libraries before it can be used.**
Head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html) Head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html)
for usage guides and tutorials that will get you started smoothly. for usage guides and tutorials that will get you started smoothly.