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

Some more documentation updates 

+ master merge
This commit is contained in:
Mael Rouxel-Labbé 2019-09-23 15:43:45 +02:00
parent 1c90b1efcd 3b5de6fe78
commit 6c9cd17d0f
18 changed files with 1620 additions and 1719 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt
View File

@ -236,8 +236,8 @@ operating system and compiler that is defined as follows.
quite compiler specific).
</DL>
Examples are <TT>mips_IRIX64-6.5_CC-n32-7.30</TT> or <TT>sparc_SunOS-5.6_g++-2.95</TT>. For more information, see the \cgal
\link installation installation guide \endlink.
Examples are <TT>mips_IRIX64-6.5_CC-n32-7.30</TT> or <TT>sparc_SunOS-5.6_g++-2.95</TT>.
For more information, see the \cgal \link usage usage guide \endlink.
This platform-specific configuration file is created during

40
Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt Normal file
View File

@ -0,0 +1,40 @@
/*!
\page devman_create_cgal_CMakeLists Creating a CMake Script for a Program Using %CGAL
To compile a program that is not shipped with \cgal, it is recommended to also rely on a CMake-supported
configuration using a `CMakeLists.txt`. The Bourne-shell script `cgal_create_CMakeLists.txt`
can be used to create such `CMakeLists.txt` files.
This script resides in the `scripts` directory of \cgal (e.g. `CGAL-\cgalReleaseNumber``/scripts`
directory if you have downloaded a tarball).
Executing `cgal_create_CMakeLists.txt` in an application directory creates a
`CMakeLists.txt` containing rules to build the contained
application(s). Three command line options determine details of the
configuration.
<DL>
<DT><B>`-s source`</B><DD> If this parameter is given the script will
create <B>a single executable</B> for 'source' linked with
compilations of all other source files
(`*.cc`, `*.cp`, `*.cxx`, `*.cpp`, `*.CPP`, `*.c++`, or `*.C`).
This behaviour is usually needed for (graphical) demos.
If the parameter is not given, the script creates <B>one executable for each given
source file</B>.
<DT><B>`-c com1:com2:...`</B><DD> Lists components ("com1",
"com2") of \cgal to which the executable(s) should be linked. Valid components are \cgal's
libraries (i.e.\ "Core", "ImageIO", and "Qt5"). An example is `-c Core`.
<DT><B>`-b boost1:boost2:...`</B><DD> Lists components ("boost1",
"boost2") of \sc{Boost} to which the executable(s) should be
linked. Valid options are, for instance, "filesystem" or "program_options".
</DL>
This options should suffice to create `CMakeLists.txt` script
for most directories containing programs. However, in some special
cases, it might still be required to create the script manually, for
instance, if some source files/executables need a different linking than
other source files.
*/

4
Documentation/doc/Documentation/Developer_manual/developer_manual.txt
View File

@ -2,6 +2,8 @@
\page dev_manual Developer Manual
The developer manual is primarly aimed at \cgal developers, but may also be interesting to any \cgal user.
- \subpage devman_intro
- \subpage devman_code_format
- \subpage devman_kernels
@ -19,6 +21,6 @@
- \subpage devman_testing
- \subpage devman_submission
- \subpage devman_info
- \subpage devman_create_cgal_CMakeLists
- \subpage deprecated
*/

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

@ -1,13 +1,17 @@
/*!
\page general_intro Getting Started
\page general_intro Getting Started with %CGAL
- \subpage installation describes how to install %CGAL, and lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces.
- \subpage usage describes the few steps required to build a program using \cgal.
- \subpage manual gives an idea where you should look for documentation.
The documentation for a class, may be spread over manual pages of
base classes, and reference manual pages of concepts the class is a model of.
- \subpage thirdparty lists the third party libraries on which \cgal depends, or for which \cgal provides interfaces.
- \subpage preliminaries lists the licenses under which the %CGAL datastructures and algorithms are distributed, how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior.
- \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.
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
and algorithms, or directly to the package(s) that interest you the \ref packages. Each package
contains simple examples of the various functionalities of the package.
*/

1196
Documentation/doc/Documentation/Installation.txt
View File

File diff suppressed because it is too large Load Diff

104
Documentation/doc/Documentation/License.txt Normal file
View File

@ -0,0 +1,104 @@
/*!
\page license License
\cgalAutoToc
\cgal is distributed under a dual license scheme, that is under the
\sc{Gpl}/\sc{Lgpl} open source license, as well as under commercial licenses.
\cgal consists of different parts covered by different open source licenses.
In this section we explain the essence of the different licenses, as well as
the rationale why we have chosen them.
The fact that \cgal is Open Source software does not mean that users are free
to do whatever they want with the software. Using the software means to accept
the license, which has the status of a contract between the user and the owner
of the \cgal software.
\section licensesGPL GPL
The \sc{Gpl} is an Open Source license that, if you distribute your software
based on \sc{Gpl}ed \cgal data structures, obliges you to distribute the
source code of your software under the \sc{Gpl}.
The exact license terms can be found at the Free Software Foundation
web site: http://www.gnu.org/copyleft/gpl.html.
\section licensesLGPL LGPL
The \sc{Lgpl} is an Open Source license that obliges you to distribute
modifications you make on \cgal software accessible to the users.
In contrast to the \sc{Gpl}, there is no obligation to make the source
code of software you build on top of \sc{Lgpl}ed \cgal data structures.
The exact license terms can be found at the Free Software Foundation web site:
http://www.gnu.org/copyleft/lesser.html.
\section licensesRationale Rationale of the License Choice
We have chosen the \sc{Gpl} and the \sc{Lgpl} as they are well-known
and well-understood open source licenses. The former restricts
commercial use, and the latter allows to promote software as de facto standard
so that people can build new higher level data structures on top.
Therefore, the packages forming a foundation layer are distributed under
the \sc{Lgpl}, and the higher level packages under the \sc{Gpl}.
The package overview states for each package under which license it is distributed.
\section licensesCommercial Commercial Licenses
Users who cannot comply with the Open Source license terms can buy individual
data structures under various commercial licenses from GeometryFactory:
http://www.geometryfactory.com/. License fees paid by commercial
customers are reinvested in R\&D performed by the \cgal project partners,
as well as in evolutive maintenance.
\section licenseCheck License Checking
Users who have a commercial license for specific packages can check that
they do not accidentally use packages for which they do not have a commercial
license. The same holds for users who want to be sure that they only
use packages of \cgal released under the \sc{Lgpl}.
To enable checking, users have to define one of the following macros:
| Macro Name | Effect |
| :--------- | :------ |
| `CGAL_LICENSE_WARNING` | get a warning during the compilation |
| `CGAL_LICENSE_ERROR` | get an error during the compilation |
The license checking is not a mean to control users as no information
is collected or transmitted.
\section seccgal_version Identifying the Version of CGAL
Every release of \cgal defines the following preprocessor macros:
<DL>
<DT>`CGAL_VERSION_STR`</DT>
<DD>a textual description of the current release (e.g., or 3.3 or 3.2.1 or 3.2.1-I-15) as a string literal</DD>
<DT>`CGAL_VERSION_NR`</DT>
<DD>a numerical description of the current release such that more recent
releases have higher number.
More precisely, it is defined as `1MMmmbiiii`, where `MM` is
the major release number (e.g. 03), `mm` is the minor release
number (e.g. 02), `b` is the bug-fix release number (e.g. 0),
and `iiii` is the internal release number (e.g. 0001). For
public releases, the latter is defined as 1000. Examples: for the
public release 3.2.4 this number is 1030241000; for internal release
3.2-I-1, it is 1030200001. Note that this scheme was modified around
3.2-I-30.
</DD>
<DT>`CGAL_VERSION_NUMBER(M,m,b)`</DT>
<DD>
a function macro computing the version number macro from the
M.m.b release version. Note that the internal release number is
dropped here. Example: `CGAL_VERSION_NUMBER(3,2,4)` is equal to
1030241000.
</DD>
</DL>
The macro `CGAL_VERSION` is deprecated. It is the same as
`CGAL_VERSION_STR`, but not as a string literal.
*/

179
Documentation/doc/Documentation/Preliminaries.txt
View File

@ -1,130 +1,16 @@
/*!
\page preliminaries Preliminaries
\page preliminaries General Information
\cgalAutoToc
\author %CGAL Editorial Board
This chapter lists the licenses
under which the \cgal datastructures and algorithms are distributed.
The chapter further explains how to control inlining, thread safety,
code deprecation, checking of pre- and postconditions,
and how to alter the failure behavior.
\cgalModifBegin
This page is bad...
\cgalModifEnd
\section licenseIssues License Issues
The chapter explains some basic features of \cgal such as thread safety, code deprecation,
checking of pre- and postconditions and altering the failure behavior, and how to control inlining.
\cgal is distributed under a dual license scheme, that is under the
\sc{Gpl}/\sc{Lgpl} open source license, as well as under commercial licenses.
\cgal consists of different parts covered by different open source licenses.
In this section we explain the essence of the different licenses, as well as
the rationale why we have chosen them.
The fact that \cgal is Open Source software does not mean that users are free
to do whatever they want with the software. Using the software means to accept
the license, which has the status of a contract between the user and the owner
of the \cgal software.
\subsection licensesGPL GPL
The \sc{Gpl} is an Open Source license that, if you distribute your software
based on \sc{Gpl}ed \cgal data structures,you are obliged to distribute the
source code of your software under the \sc{Gpl}.
The exact license terms can be found at the Free Software Foundation
web site: http://www.gnu.org/copyleft/gpl.html.
\subsection licensesLGPL LGPL
The \sc{Lgpl} is an Open Source license that obliges you to distribute
modifications you make on \cgal software accessible to the users.
In contrast to the \sc{Gpl}, there is no obligation to make the source
code of software you build on top of \sc{Lgpl}ed \cgal data structures
The exact license terms can be found at the Free Software Foundation web site:
http://www.gnu.org/copyleft/lesser.html.
\subsection licensesRationale Rationale of the License Choice
We have chosen the \sc{Gpl} and the \sc{Lgpl} as they are well known
and well understood open source licenses. The former restricts
commercial use, and the latter allows to promote software as de facto standard
so that people can build new higher level data structures on top.
Therefore, the packages forming a foundation layer are distributed under
the \sc{Lgpl}, and the higher level packages under the \sc{Gpl}.
The package overview states for each package under which license
it is distributed.
\subsection licensesCommercial Commercial Licenses
Users who cannot comply with the Open Source license terms can buy individual
data structures under various commercial licenses from GeometryFactory:
http://www.geometryfactory.com/. License fees paid by commercial
customers are reinvested in R\&D performed by the \cgal project partners,
as well as in evolutive maintenance.
\subsection licenseCheck License Checking
Users who have a commercial license for specific packages can check that
they do not accidentally use packages for which they do not have a commercial
license. The same holds for users who want to be sure that they only
use packages of \cgal released under the \sc{Lgpl}.
To enable checking, users have to define one of the following macros:
| Macro Name | Effect |
| :--------- | :------ |
| `CGAL_LICENSE_WARNING` | get a warning during the compilation |
| `CGAL_LICENSE_ERROR` | get an error during the compilation |
The license checking is not a mean to control users as no information
is collected or transmitted.
\section markingSpecialFunctionality Marking of Special Functionality
In this manual you will encounter sections marked as follows.
\subsection advanced_features Advanced Features
Some functionality is considered more advanced, for example because it is
relatively low-level, or requires special care to be properly used.
\cgalAdvancedBegin
Such functionality is identified this way in the manual.
\cgalAdvancedEnd
\subsection debugging_support Debugging Support Features
Usually related to advanced features that for example may not guarantee
class invariants, some functionality is provided that helps debugging,
for example by performing invariants checks on demand.
\cgalDebugBegin
Such functionality is identified this way in the manual.
\cgalDebugEnd
\subsection deprecated_code Deprecated Code
Sometimes, the \cgal project decides that a feature is deprecated. This means
that it still works in the current release, but it will be removed in the next,
or a subsequent release. This can happen when we have found a better way to do
something, and we would like to reduce the maintenance cost of \cgal at some
point in the future. There is a trade-off between maintaining backward
compatibility and implementing new features more easily.
In order to help users manage the changes to apply to their code, we attempt
to make \cgal code emit warnings when deprecated code is used. This can be
done using some compiler specific features. Those warnings can be disabled
by defining the macro `CGAL_NO_DEPRECATION_WARNINGS`. On top of this, we
also provide a macro, `CGAL_NO_DEPRECATED_CODE`, which, when defined,
disables all deprecated features. This allows users to easily test if their
code relies on deprecated features.
\deprecated Such functionality is identified this way in the manual.
These concepts are further developed in the \ref dev_manual.
\section Preliminaries_namespace Namespace CGAL
@ -154,19 +40,10 @@ defined, unless `BOOST_HAS_THREADS` or `_OPENMP` is defined. It is possible
to force its definition on the command line, and it is possible to prevent its default
definition by setting `CGAL_HAS_NO_THREADS` from the command line.
\section Preliminaries_cc0x C++14 Support
\section Preliminaries_cc0x C++11 Support
\cgal is based on the \CC standard released in 1998 (and later refined in 2003).
A new major version of this standard has been released, and is refered to as \cpp11.
Some compilers and standard library implementations already provide some of the
functionality of this new standard, as a preview. For example, \gcc provides
a command-line switch (`-std=c++0x` or or `-std=c++11` depending on the compiler version)
which enables some of those features.
\cgal attempts to support this mode progressively, and already makes use of
some of these features if they are available, although no extensive support has
been implemented yet.
After being based on the \CC standard released in 1998 (and later refined in 2003) for a long time,
\cgal is now based on a newer major version of the standard, <a href="https://isocpp.org/wiki/faq/cpp14">C++14</a>.
\section Preliminaries_functor Functor Return Types
@ -182,43 +59,9 @@ return type of calling the functor with an argument of type
Much of the \cgal code contains assert statements for preconditions, and postconditions of functions
as well as in the code. These assertions can be switched on and off per package
and the user can change the error behaviour. For details see Section \ref secchecks
and the user can change the error behaviour. For details see Section \ref secchecks
of Chapter \ref Chapter_STL_Extensions_for_CGAL.
\section seccgal_version Identifying the Version of CGAL
`<CGAL/config.h>`
Every release of \cgal defines the following preprocessor macros:
<DL>
<DT>`CGAL_VERSION_STR`</DT>
<DD>a textual description of the current release (e.g., or 3.3 or 3.2.1 or 3.2.1-I-15) as a string literal</DD>
<DT>`CGAL_VERSION_NR`</DT>
<DD>a numerical description of the current release such that more recent
releases have higher number.
More precisely, it is defined as `1MMmmbiiii`, where `MM` is
the major release number (e.g. 03), `mm` is the minor release
number (e.g. 02), `b` is the bug-fix release number (e.g. 0),
and `iiii` is the internal release number (e.g. 0001). For
public releases, the latter is defined as 1000. Examples: for the
public release 3.2.4 this number is 1030241000; for internal release
3.2-I-1, it is 1030200001. Note that this scheme was modified around
3.2-I-30.
</DD>
<DT>`CGAL_VERSION_NUMBER(M,m,b)`</DT>
<DD>
a function macro computing the version number macro from the
M.m.b release version. Note that the internal release number is
dropped here. Example: `CGAL_VERSION_NUMBER(3,2,4)` is equal to
1030241000.
</DD>
</DL>
The macro `CGAL_VERSION` is deprecated. It is the same as
`CGAL_VERSION_STR`, but not as a string literal.
\section Preliminaries_flags Compile-time Flags to Control Inlining
Making functions inlined can, at times, improve the efficiency of your code.

283
Documentation/doc/Documentation/Third_party.txt Normal file
View File

@ -0,0 +1,283 @@
/*!
\page thirdparty Essential and Optional Third Party Dependencies
\cgalAutoToc
\section seccompilers Supported Compilers
In order to build a program using \cgal, you need a \cpp compiler
supporting <a href="https://isocpp.org/wiki/faq/cpp14">C++14</a> or later.
\cgal \cgalReleaseNumber is supported (continuously tested) for the following compilers/operating systems:
| Operating System | Compiler |
| :------- | :--------------- |
| Linux | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{<A HREF="http://gcc.gnu.org/">`http://gcc.gnu.org/`</A>} |
| | `Clang` \cgalFootnote{<A HREF="http://clang.llvm.org/">`http://clang.llvm.org/`</A>} compiler version 8.0.0 |
| \sc{MS} Windows | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{<A HREF="http://gcc.gnu.org/">`http://gcc.gnu.org/`</A>} |
| | \sc{MS} Visual `C++` 14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019)\cgalFootnote{<A HREF="https://visualstudio.microsoft.com/">`https://visualstudio.microsoft.com/`</A>} |
| MacOS X | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{<A HREF="http://gcc.gnu.org/">`http://gcc.gnu.org/`</A>} |
| | Apple `Clang` compiler versions 7.0.2 and 10.0.1 |
Older versions of the above listed compilers might work, but no guarantee is provided.
\section seccmake CMake
<b>Version 3.1 or later</b>
In order to configure and build the \cgal examples, demos, or libraries,
you need <a href="https://cmake.org/">CMake</a>, a cross-platform "makefile generator".
This manual explains only the features of CMake which are needed in order to build \cgal.
Please refer to the <a href="https://cmake.org/documentation/">CMake documentation</a>
for further details.
\section secessential3rdpartysoftware Essential Third Party Libraries
The focus of \cgal is on geometry, and we rely on other
highly specialized libraries and software for non-geometric issues,
for instance for numeric solvers or visualization. We first list software
that is essential to most of \cgal, and must therefore be found during the configuration of \cgal.
The page \ref configurationvariables lists CMake and environment variables which can be used to specify
the location of third-party software during configuration.
\subsection thirdpartystl Standard Template Library (STL)
\cgal heavily uses the \stl, and in particular adopted many of its design ideas. You can find online
documentation for the \stl at various web sites, for instance,
<A HREF="https://en.cppreference.com/w/">`https://en.cppreference.com `</A>,
or <A HREF="https://msdn.microsoft.com/en-us/library/1fe2x6kt(v=vs.140).aspx">`https://msdn.microsoft.com`</A>.
The \stl comes with the compiler, and as such no installation is required.
\subsection thirdpartyBoost Boost
<b>Version 1.48 or later</b>
The \sc{Boost} libraries are a set of portable C++ source libraries.
Most of \sc{Boost} libraries are header-only, but a few of them need to be compiled or
installed as binaries.
\cgal only requires the headers of the \sc{Boost} libraries, but some demos and examples
depend on the binary library `Boost.Program_options`.
As an exception and because of a bug in the \gcc compiler about the \cpp 11
keyword `thread_local`, the `CGAL_Core` library always requires
the binary library `Boost.Thread` if the \gcc compiler version 9.0 or
earlier is used.
In case the \sc{Boost} libraries are not installed on your system already, you
can obtain them from <A HREF="https://www.boost.org">`https://www.boost.org/`</A>.
For Visual C++ you can download precompiled libraries
from <A HREF="https://sourceforge.net/projects/boost/files/boost-binaries/">`https://sourceforge.net/projects/boost/files/boost-binaries/`</A>.
As there is no canonical directory for where to find \sc{Boost} on Windows,
we recommend that you define the environment variable
`BOOST_ROOT` and set it to where you have installed \sc{Boost}, e.g., `C:\boost\boost_1_69_0`.
\subsection thirdpartyMPFR GNU Multiple Precision Arithmetic (GMP) and GNU Multiple Precision Floating-Point Reliably (MPFR) Libraries
<b>GMP Version 4.2 or later, MPFR Version 2.2.1 or later</b>
The components `libCGAL`, `libCGAL_Core`, and `libCGAL_Qt5` require
\sc{Gmp} and \sc{Mpfr} which are libraries for multi precision integers and rational numbers,
and for multi precision floating point numbers.
\cgal combines floating point arithmetic with exact arithmetic
in order to be efficient and reliable. \cgal has a built-in
number type for that, but \sc{Gmp} and \sc{Mpfr} provide a faster
solution, and we recommend to use them.
These libraries can be obtained from <A HREF="https://gmplib.org/">`https://gmplib.org/`</A>
and <A HREF="https://www.mpfr.org/">`https://www.mpfr.org/`</A>.
Since Visual \cpp is not properly supported by the \sc{Gmp} and \sc{Mpfr} projects,
we provide precompiled versions of \sc{Gmp} and \sc{Mpfr}, which can be downloaded with the installer
<a href="https://github.com/CGAL/cgal/releases">`CGAL-\cgalReleaseNumber``-Setup.exe`</a>.
\section secoptional3rdpartysoftware Optional Third Party Libraries
Optional 3rd party software can be used by \cgal for various reasons:
certain optional libraries might be required to build examples and
demos shipped with \cgal or to build your own project using \cgal;
another reason is to speed up basic tasks where specialized libraries can be faster than the default
version shipped with \cgal.
The page \ref configurationvariables lists CMake and environment variables which can be used to specify
the location of third-party software during configuration.
\subsection thirdpartyQt Qt5
<b>Version 5.9.0 or later</b>
Qt is a cross-platform application and UI framework.
The component libCGAL_Qt5 is essential to run the \cgal demos and basic viewers.
It requires \sc{Qt}5 installed on your system.
In case \sc{Qt} is not yet installed on your system, you can download
it from <A HREF="https://www.qt-project.org/">`https://www.qt-project.org/`</A>.
The exhaustive list of \sc{Qt}5 components used in demos is:
`Core`, `Gui`, `Help`, `OpenGL`, `Script`, `ScriptTools`, `Svg`, `Widgets`,
`qcollectiongenerator` (with `sqlite` driver plugin), and `Xml`.
\subsection thirdpartyEigen Eigen
<b>Version 3.1 or later</b>
\sc{Eigen} is a `C++` template library for linear algebra. \sc{Eigen} supports all
matrix sizes, various matrix decomposition methods and sparse linear solvers.
In \cgal, \sc{Eigen} is used in many packages such as \ref PkgPoissonSurfaceReconstruction3
or \ref PkgJetFitting3, providing sparse linear solvers and singular value decompositions.
A package dependency over \sc{Eigen} is marked on the
<a href="https://doc.cgal.org/latest/Manual/packages.html">Package Overview</a> page.
The \sc{Eigen} web site is <A HREF="http://eigen.tuxfamily.org/index.php?title=Main_Page">`http://eigen.tuxfamily.org`</A>.
\subsection thirdpartyLeda LEDA
<b>Version 6.2 or later</b>
\leda is a library of efficient data structures and
algorithms. Like \sc{Core}, \leda offers a real number data type.
In \cgal this library is optional, and its number types can
be used as an alternative to \sc{Gmp}, \sc{Mpfr}, and \sc{Core}.
Free and commercial editions of \leda are available from <A HREF="https://www.algorithmic-solutions.com">`https://www.algorithmic-solutions.com`</A>.
\subsection thirdpartyMPFI Multiple Precision Floating-point Interval (MPFI)
<b>Version 1.4 or later</b>
\sc{Mpfi} provides arbitrary precision interval arithmetic with intervals
represented using \sc{Mpfr} reliable floating-point numbers.
It is based on the libraries \sc{Gmp} and \sc{Mpfr}.
In the setting of \cgal, this library is
optional: it is used by some models of the
\ref PkgAlgebraicKernelD "Algebraic Kernel".
\sc{Mpfi} can be downloaded from <A HREF="https://mpfi.gforge.inria.fr/">`https://mpfi.gforge.inria.fr/`</A>.
\subsection thirdpartyRS3 RS and RS3
\sc{Rs} (Real Solutions) is devoted to the study of the real roots of
polynomial systems with a finite number of complex roots (including
univariate polynomials). In \cgal, \sc{Rs} is used by one model of the
\ref PkgAlgebraicKernelD "Algebraic Kernel".
\sc{Rs} is freely distributable for non-commercial use. You can download it
from <a href="http://vegas.loria.fr/rs/">`http://vegas.loria.fr/rs/`</a>. Actually, the \sc{Rs} package also includes \sc{Rs3}, the
successor of \sc{Rs}, which is used in conjunction with it.
The libraries \sc{Rs} and \sc{Rs3} need \sc{Mpfi}, which can be downloaded from
<A HREF="https://mpfi.gforge.inria.fr/">`https://mpfi.gforge.inria.fr/`</A>.
\subsection thirdpartyNTL NTL
<b>Version 5.1 or later</b>
\sc{Ntl} provides data structures and algorithms for signed, arbitrary
length integers, and for vectors, matrices, and polynomials over the
integers and over finite fields. The optional library \sc{Ntl} is used by \cgal
to speed up operations of the Polynomial package, such as GCDs. It is recommended to install \sc{Ntl} with support from \sc{Gmp}.
\sc{Ntl} can be downloaded from <A HREF="https://www.shoup.net/ntl/">`https://www.shoup.net/ntl/`</A>.
\subsection thirdpartyESBTL ESBTL
The \sc{Esbtl} (Easy Structural Biology Template Library) is a library that allows
the handling of \sc{Pdb} data.
In \cgal, the \sc{Esbtl} is used in an example of the \ref PkgSkinSurface3 package.
It can be downloaded from <A HREF="http://esbtl.sourceforge.net/">`http://esbtl.sourceforge.net/`</A>.
\subsection thirdpartyTBB Intel TBB
\sc{Tbb} (Threading Building Blocks) is a library developed by Intel Corporation for writing software
programs that take advantage of multi-core processors.
In \cgal, \sc{Tbb} is used by the packages that offer parallel code.
The \sc{Tbb} web site is <A HREF="https://www.threadingbuildingblocks.org">`https://www.threadingbuildingblocks.org`</A>.
\subsection thirdpartyLASlib LASlib
\sc{LASlib} is a `C++` library for handling LIDAR data sets stored in
the LAS format (or the compressed LAZ format).
In \cgal, \sc{LASlib} is used to provide input and output functions in
the \ref PkgPointSetProcessing3 package.
The \sc{LASlib} web site is <a
href="https://rapidlasso.com/lastools/">`https://rapidlasso.com/lastools/`</a>. \sc{LASlib}
is usually distributed along with LAStools: for simplicity, \cgal
provides <a href="https://github.com/CGAL/LAStools">a fork with a
CMake based install procedure</a>.
\subsection thirdpartyOpenCV OpenCV
\sc{OpenCV} (Open Computer Vision) is a library designed for computer
vision, computer graphics and machine learning.
In \cgal, \sc{OpenCV} is used by the \ref PkgClassification package.
The \sc{OpenCV} web site is <A HREF="https://opencv.org/">`https://opencv.org/`</A>.
\subsection thirdpartyTensorFlow TensorFlow
\sc{TensorFlow} is a library designed for machine learning and deep learning.
In \cgal, the C++ API of \sc{TensorFlow} is used by the \ref
PkgClassification package for neural network. The C++ API can be
compiled using CMake: it is distributed as part of the official
package and is located in `tensorflow/contrib/cmake`. Be sure to
enable and compile the following targets:
- `tensorflow_BUILD_ALL_KERNELS`
- `tensorflow_BUILD_PYTHON_BINDINGS`
- `tensorflow_BUILD_SHARED_LIB`.
The \sc{TensorFlow} web site is <A HREF="https://www.tensorflow.org/">`https://www.tensorflow.org/`</A>.
\subsection thirdpartyMETIS METIS
<b>Version 5.1 or later</b>
\sc{METIS} is a library developed by the <A HREF="http://glaros.dtc.umn.edu/gkhome/">Karypis Lab</A>
and designed to partition graphs and produce fill-reducing matrix orderings.
\cgal offers wrappers around some of the methods of the \sc{METIS} library
to allow the partitioning of graphs that are models of the concepts of the
<A HREF="https://www.boost.org/libs/graph/doc/index.html">Boost Graph Library</A>,
and, by extension, of surface meshes (see Section \ref BGLPartitioning of the package \ref PkgBGL).
More information is available on the METIS library
at <A HREF="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview">`http://glaros.dtc.umn.edu/gkhome/metis/metis/overview`</A>.
\subsection thirdpartyzlib zlib
\sc{zlib} is a data compression library, and is essential for the component libCGAL_ImageIO.
In \cgal, this library is used in the examples of the \ref PkgSurfaceMesher3 package.
If it is not already on your system,
for instance, on Windows, you can download it from <A HREF="https://www.zlib.net/">`https://www.zlib.net/`</A>.
\subsection thirdpartyCeres Ceres Solver
\sc{Ceres} is an open source C++ library for modeling and solving large, complicated optimization problems.
In \cgal, \sc{Ceres} is used by the \ref PkgPolygonMeshProcessingRef package for mesh smoothing, which
requires solving complex non-linear least squares problems.
Visit the official website of the library at <A HREF="http://ceres-solver.org/index.html">`ceres-solver.org`</A>
for more information.
\subsection thirdpartyGLPK GLPK
\sc{GLPK} (GNU Linear Programming Kit) is a library for solving linear programming (LP), mixed integer programming (MIP), and other related problems.
In \cgal, \sc{GLPK} provides an optional linear integer program solver in the \ref PkgPolygonalSurfaceReconstruction package.
The \sc{GLPK} web site is <A HREF="https://www.gnu.org/software/glpk/">`https://www.gnu.org/software/glpk/`</A>.
\subsection thirdpartySCIP SCIP
\sc{SCIP} (Solving Constraint Integer Programs) is currently one of the fastest open source solvers for mixed integer programming (MIP) and mixed integer nonlinear programming (MINLP).
In \cgal, \sc{SCIP} provides an optional linear integer program solver in the \ref PkgPolygonalSurfaceReconstruction package.
The \sc{SCIP} web site is <A HREF="http://scip.zib.de/">`http://scip.zib.de/`</A>.
*/

143
Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt
View File

@ -15,24 +15,23 @@ namespace CGAL {
\cgalAutoToc
\author %CGAL Editorial Board
This tutorial is for the %CGAL newbie, who knows C++ and has
This tutorial is for the %CGAL newbie, who knows \CC and has
a basic knowledge of geometric algorithms. The first section
shows how to define a point and segment class, and how to
apply geometric predicates on them. The section further raises
the awareness that that there are serious issues when using
floating point numbers for coordinates. In the second section
you see how the 2D convex hull function gets its input
and where it puts the result. The third section shows what
we mean with a \em Traits class, and the fourth section explains
the notion of \em concept and \em model.
floating point numbers for coordinates. In the second section,
you will meet a typical \cgal function, which computes a 2D convex hull.
The third section shows what we mean with a \em Traits class,
and the fourth section explains the notion of \em concept and \em model.
\section intro_Three Three Points and One Segment
In this first example we see how to construct some points
and a segment, and we perform some basic operations on them.
All \cgal header files are in the subdirectory `include/CGAL`. All \cgal
classes and functions are in the namespace `CGAL`.
In this first example, we demonstrate how to construct some points
and a segment, and perform some basic operations on them.
All \cgal header files are in the subdirectory `include/CGAL`. All \cgal
classes and functions are in the namespace `CGAL`.
Classes start with a capital letter, global
function with a lowercase letter, and constants are all uppercase.
The dimension of an object is expressed with a suffix.
@ -42,24 +41,20 @@ The kernel we have chosen for this first example uses `double`
precision floating point numbers for the %Cartesian coordinates of the point.
Besides the types we see \em predicates like the orientation test for
three points, and \em constructions like the distance and midpoint
three points, and \em constructions like the distance and midpoint
computation. A predicate has a discrete set of possible results,
whereas a construction produces either a number, or another
geometric entity.
\cgalExample{Kernel_23/points_and_segment.cpp}
To do geometry with floating point numbers can be surprising
as the next example shows.
\cgalExample{Kernel_23/surprising.cpp}
When reading the code, we would assume that it prints three times "collinear".
However we obtain:
Reading the code, we could assume that it would print three times "collinear".
However the actual output is the following:
\verbatim
not collinear
@ -67,19 +62,18 @@ not collinear
collinear
\endverbatim
As the fractions are not representable as double precision number
the collinearity test will internally compute a determinant of a 3x3 matrix
This is because these fractions are not representable as double-precision numbers,
and the collinearity test will internally compute a determinant of a 3x3 matrix
which is close but not equal to zero, and hence the non collinearity for the
first two tests.
first two tests.
Something similar can happen with points that perform a left turn,
but due to rounding errors during the determinant computation, it
seems that the points are collinear, or perform a right turn.
If you need that the numbers get interpreted at their full precision
you can use a \cgal kernel that performs exact predicates and
extract constructions.
If you must ensure that your numbers get interpreted at their full precision
you can use a \cgal kernel that performs exact predicates and
extract constructions.
\cgalExample{Kernel_23/exact.cpp}
@ -95,7 +89,7 @@ In the first block the points are still not collinear,
for the simple reason that the coordinates you see as text
get turned into floating point numbers. When they are then
turned into arbitrary precision rationals, they exactly
represent the floating point number, but not the text.
represent the floating point number, but not the text!
This is different in the second block, which corresponds
to reading numbers from a file. The arbitrary precision
@ -106,67 +100,63 @@ In the third block you see that constructions as
midpoint constructions are exact, just as the name
of the kernel type suggests.
In many cases you will have floating point numbers that are "exact",
In many cases, you will have floating point numbers that are "exact",
in the sense that they were computed by some application or obtained
from a sensor. They are not the string "0.1" or computed on the
from a sensor. They are not the string "0.1" or computed on the
fly as "1.0/10.0", but a full precision floating point number.
If they are input to an algorithm that makes no constructions
you can use a kernel that provides exact predicates, but inexact
constructions. An example for that is the convex hull algorithm
If they are input to an algorithm that makes no constructions,
you can use a kernel that provides exact predicates but <em>inexact</em>
constructions. One such example is the convex hull algorithm
which we will see in the next section.
The output is a subset of the input, and the algorithm
only compares coordinates and performs orientation tests.
The output is a subset of the input, and the algorithm
only compares coordinates and performs orientation tests.
At a first glance the kernel doing exact predicates and constructions
seems to be the perfect choice, but performance requirements
or limited memory resources make that it is not. Also for many
or limited memory resources make that it is not. Furthermore, for many
algorithms it is irrelevant to do exact constructions. For example
a surface mesh simplification algorithm that iteratively contracts
an edge, by collapsing it to the midpoint of the edge.
Most \cgal packages explain what kind of kernel they need or support.
an edge by collapsing it to the midpoint of the edge.
Most \cgal packages explain which kind of kernel they should use or support.
\section intro_convex_hull The Convex Hull of a Sequence of Points
All examples in this section compute the 2D convex hull of a set of points.
We show that algorithms get their input as a begin/end iterator pair
denoting a range of points, and that they write the result, in the
example the points on the convex hull, into an output iterator.
We show that algorithms get their input as a begin/end iterator pair
denoting a range of points, and that they write the result (in the
example the points on the convex hull) into an output iterator.
\subsection intro_array The Convex Hull of Points in a Built-in Array
In the first example we have as input an array of five points.
As the convex hull of these points is a subset of the input
In the first example, we have as input an array of five points.
As the convex hull of these points is a subset of the input,
it is safe to provide an array for storing the result which
has the same size.
\cgalExample{Convex_hull_2/array_convex_hull_2.cpp}
We saw in the previous section that \cgal comes
with several kernels. As the convex hull algorithm only makes
We have seen in the previous section that \cgal comes
with several kernels. Since the convex hull algorithm only makes
comparisons of coordinates and orientation tests of input points,
we can choose a kernel that provides exact predicates, but no
we can choose a kernel that provides exact predicates, but no
exact geometric constructions.
The convex hull function takes three arguments, the start
and past-the-end pointer for the input, and the start pointer of the
and past-the-end pointer for the input, and the start pointer of the
array for the result. The function returns the pointer
into the result array just behind the last convex hull
point written, so the pointer difference tells us how
many points are on the convex hull.
many points are on the convex hull.
\subsection intro_vector The Convex Hull of Points in a Vector
In the second example we replace the built-in array
by a `std::vector` of the Standard Template Library.
In the second example, we replace the built-in array
by an `std::vector` of the Standard Template Library.
\cgalExample{Convex_hull_2/vector_convex_hull_2.cpp}
We put some points in the vector calling the `push_back()`
We put some points in the vector, calling the `push_back()`
method of the `std::vector` class.
We then call the convex hull function. The first two arguments,
@ -175,8 +165,8 @@ generalization of pointers: they can be dereferenced and
incremented. The convex hull function is *generic* in the sense
that it takes as input whatever can be dereferenced and incremented.
The third argument is where the result gets written to. In the
previous example we provided a pointer to allocated memory. The
The third argument is where the result gets written to. In the
previous example we provided a pointer to allocated memory. The
generalization of such a pointer is the *output iterator*, which
allows to increment and assign a value to the dereferenced iterator.
In this example we start with an empty vector which grows as needed.
@ -185,34 +175,32 @@ iterator generated by the helper function
`std::back_inserter(result)`. This output iterator does nothing when
incremented, and calls `result.push_back(..)` on the assignment.
If you know the \stl, the Standard Template Library, the above makes
perfect sense, as this is the way the \stl decouples algorithms from
containers. If you don't know the \stl, you maybe better first
familiarize yourself with its basic ideas.
\section intro_traits About Kernels and Traits Classes
In this section we show how we express the requirements that must
In this section, we show how we express the requirements that must
be fulfilled in order that a function like `convex_hull_2()`
can be used with an arbitrary point type.
If you look at the manual page of the function `convex_hull_2()`
and the other 2D convex hull algorithms, you see that they come in two
versions. In the examples we have seen so far the function that takes two
versions. In the examples we have seen so far, the function that takes two
iterators for the range of input points and an output iterator for
writing the result to. The second version has an additional template
parameter `Traits`, and an additional parameter of this type.
\code{.cpp}
template<class InputIterator , class OutputIterator , class Traits >
OutputIterator
OutputIterator
convex_hull_2(InputIterator first,
InputIterator beyond,
OutputIterator result,
const Traits & ch_traits)
\endcode
\endcode
What are the geometric primitives a typical convex hull algorithm
uses? Of course, this depends on the algorithm, so let us consider
@ -238,10 +226,8 @@ test, while `Less_xy_2` is used for sorting the points. The requirements these
types have to satisfy are documented in full with the concept
`ConvexHullTraits_2`.
The types are regrouped for a simple reason. The alternative would
have been a rather lengthy function template, and an even longer
have been a rather lengthy function template, and an even longer
function call.
\code{.cpp}
@ -258,7 +244,7 @@ this template parameter? And why do we have template parameters at all?
To answer the first question, any model of the %CGAL concept `Kernel` provides
what is required by the concept `ConvexHullTraits_2`.
As for the second question, think about an application where we want to
As for the second question, think about an application where we want to
compute the convex hull of 3D points projected into the `yz` plane. Using
the class `Projection_traits_yz_3` this is a small modification
of the previous example.
@ -277,15 +263,14 @@ traits object to store state, for example if the projection plane was
given by a direction, which is hardwired in the class
`Projection_traits_yz_3`.
\section intro_concept Concepts and Models
In the previous section we wrote that "Any model of the CGAL concept
In the previous section, we wrote that "Any model of the CGAL concept
Kernel provides what is required by the concept ConvexHullTraits_2".
A \em concept is a set of requirements on a type, namely that it has
certain nested types, certain member functions, or comes with certain
free functions that take the type as it. A \em model of a concept
free functions that take the type as it. A \em model of a concept
is a class that fulfills the requirements of the concept.
Let's have a look at the following function.
@ -299,30 +284,30 @@ duplicate(T t)
}
\endcode
If you want to instantiate this function with a class `C` this
class must at least provide a copy constructor, and we
say that class `C` must be a model of `CopyConstructible`.
If you want to instantiate this function with a class `C`, this
class must at least provide a copy constructor, and we
say that class `C` must be a model of `CopyConstructible`.
A singleton class does not fulfill this requirment.
Another example is the function
Another example is the function:
\code{.cpp}
template <typename T>
template <typename T>
T& std::min(const T& a, const T& b)
{
return (a<b)?a:b;
}
}
\endcode
This function only compiles if the `operator<(..)` is defined for the type used as `T`,
and we say that the type must be a model of `LessThanComparable`.
An example for a concept with required free functions is the `HalfedgeListGraph` in the
\cgal package \ref PkgBGL. In order to be a model of `HalfedgeListGraph` a class `G`
\cgal package \ref PkgBGL. In order to be a model of `HalfedgeListGraph` a class `G`
there must be a global function `halfedges(const G&)`, etc.
An example for a concept with a required traits class is `InputIterator`.
For a model of an `InputIterator` a specialization of the class
For a model of an `InputIterator` a specialization of the class
<a href="http://en.cppreference.com/w/cpp/iterator/iterator_traits"> `std::iterator_traits`</a>
must exist (or the generic template must be applicable).
@ -333,11 +318,9 @@ Tutorial and Reference" by Nicolai M. Josuttis from Addison-Wesley, or
"Generic Programming and the STL" by Matthew H. Austern for the \stl
and its notion of *concepts* and *models*.
Other resources for \cgal are the rest of the \ref tutorials "tutorials"
and the user support page at
https://www.cgal.org/.
Other resources for \cgal are the rest of the \ref tutorials "tutorials"
and the user support page at https://www.cgal.org/.
*/
} /* namespace CGAL */

225
Documentation/doc/Documentation/Usage.txt Normal file
View File

@ -0,0 +1,225 @@
/*!
\page usage Usage
\cgalAutoToc
Since \cgal version 5.0, \cgal is header-only be default, which means
that there is <b>no need to build or install \cgal before it can be used</b>.
However, some dependencies of \cgal might still need to be installed.
\section usage_introduction Quick Start
Ideally, compiling an example shipped with \cgal is as simple as:
cd examples/Triangulation_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . # configure the examples
make # build the examples
Compiling your own program is similar:
cd /path/to/your/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release .
make
The script `cgal_create_CMakeLists` and its options are detailed in Section \ref devman_create_cgal_CMakeLists.
\cgalModifBegin
Something about Windows?
\cgalModifEnd
In a less ideal world, you might have to install some required tools and third-party libraries.
This is what this page is about.
\section secprerequisites Prerequisites
Using \cgal requires a few core components to be previously installed:
<ul>
<li> a supported compiler (see Section \ref seccompilers), </li>
<li> \ref seccmake </li>
<li> \ref thirdpartyBoost, </li>
<li> \ref thirdpartyMPFR. </li>
</ul>
Optional third-party software might be required to build examples and demos shipped with \cgal,
or to build your own project using \cgal, see Section \ref secoptional3rdpartysoftware.
\section secgettingcgal Downloading CGAL
You can obtain the \cgal library from
<A HREF="https://www.cgal.org/download.html">https://www.cgal.org/download.html</A>.
Once you have downloaded the file `CGAL-\cgalReleaseNumber``.tar.gz` containing the
\cgal sources, you have to unpack it. Under a Unix-like shell, use the
command:
tar xzf CGAL-\cgalReleaseNumber.tar.gz
In both cases, the directory `CGAL-\cgalReleaseNumber` will be created. This directory
contains the following subdirectories:
| Directory | Contents |
| :------------------------- | :----------|
| `auxiliary` (Windows only) | precompiled \sc{Gmp} and \sc{Mpfr} for Windows |
| `cmake/modules` | modules for finding and using libraries |
| `config` | configuration files for install script |
| `demo` | demo programs (most of them need \sc{Qt}, geomview or other third-party products) |
| `doc_html` | documentation (HTML) |
| `examples` | example programs |
| `include` | header files |
| `scripts` | some useful scripts (e.g. for creating CMakeLists.txt files) |
| `src` | source files |
The directories `include/CGAL/CORE` and `src/CGALCore` contain a
distribution of the <a href="https://cs.nyu.edu/exact/">\sc{Core} library</a> version 1.7 for
dealing with algebraic numbers. Note that \sc{Core} is not part of \cgal and has its
own license.
The directory `include/CGAL/OpenNL` contains a distribution of the
<a href="http://alice.loria.fr/index.php/software/4-library/23-opennl.html">Open Numerical Library</a>,
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.
The only documentation shipped within \cgal sources is the present
installation manual. The \cgal manual can be accessed online at
<A HREF="https://doc.cgal.org/latest/Manual/index.html">`https://doc.cgal.org`</A>
or downloaded separately at
<A HREF="https://github.com/CGAL/cgal/releases">`https://github.com/CGAL/cgal/releases`</A>.
\section section_headeronly Header-only Usage
Since \cgal 4.12, it has been possible to use \cgal in <a href="https://en.wikipedia.org/wiki/Header-only">header-only mode</a>,
without even configuring \cgal\. Programs using \cgal (examples, tests, demos, etc.)
are instead configured using CMake and \cgal will be configured at the same time.
Note that even though \cgal can be used as a header-only library, not all its dependencies
are header-only. The libraries \sc{Gmp} and \sc{Mpfr}, for example, are not
header-only. As such, these dependencies must be built or installed independently.
\subsection subsection_headeronly_pbonwindows Potential Issue on Windows
\cgalModifBegin
(RE)MOVE THAT?
\cgalModifEnd
A potential issue when using \cgal in header-only mode on a Windows operating system can arise
when compiling a program using several modules (executable programs or dynamic-link libraries DLL).
If two different modules use the same static variable, this variable is defined independently
in each of these modules. If one module modifies the value of this variable, it will not be modified
in the other module, which could induce an unexpected behavior. In \cgal, this concerns only
a few specific variables: the <A HREF="https://doc.cgal.org/latest/Generator/classCGAL_1_1Random.html">default random</A>,
the <A HREF="https://doc.cgal.org/latest/STL_Extension/group__PkgSTLExtensionAssertions.html">failure behavior</A>,
`CGAL::IO::Mode`. One example is the following: if you change the default random in one DLL, then
if you use the default random in another DLL, you will not obtain the modified default random but the original one.
\subsection usage_installingcgal Building and Installing CGAL
Although using the header-only mode makes building and installing \cgal obsolete, it is still possible
to configure, build, and install \cgal. Head over to \ref installation for more information. It is
however advised by the \cgal project to use the much simpler header-only mode, and the present page
assumes that this configuration is being used.
\section usage_configuring Configuring your Program
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 <I>configuration</I>. The end of the process is marked
by the generation of a makefile or a Visual \cpp solution and project file that you can use
to build your program.
CMake maintains configuration parameters in so-called <I>cmake variables</I>, like the `CMAKE_CXX_COMPILER`
in the example above. These variables <I>are not environment variables</I> but <I>CMake variables</I>.
Some of the CMake variables represent user choices, such as `CMAKE_BUILD_TYPE`,
whereas others indicate the details of a third-party library, such as `Boost_INCLUDE_DIR`
or the compiler flags to use, such as `CMAKE_CXX_FLAGS`.
In a typical installation of dependencies, almost all CMake variables will be set automatically;
users need only to provide the variable `CGAL_DIR`, which must point to the root directory
of the \cgal source code (either the root of the unpacked release tarball or the root
of the Git working directory).
It is also strongly recommended to set the build type to `Release` for performance reasons
if no debugging is intended. Users should thus run:
cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release .
\subsection usage_configuring_cmake_gui Specifying Missing Dependencies
The configuration process launched above might however fail if CMake fails to find
all the required dependencies. This typically happens if you have installed dependencies
at non-standard locations.
Although the command line tool `cmake` accepts CMake variables as arguments of the form
`-D<VAR>:<TYPE>=<VALUE>`, this is only useful if you already know which variables
need to be explicitly defined. or this reason, the simplest way to manually set the missing variables
is to run the graphical user interface of CMake, `cmake-gui`.
cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
cmake-gui -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release .
After the `CMake` window opens, press 'Configure'. 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
the output of configuration tests in the lower portion of the application.
Once these tests are done, you will see many red entries in the upper portion of the application.
Just ignore them, and press 'Configure' again. By now, CMake should have found most required
libraries and have initialized variables.
If red entries are still present, you must provide the necessary information (paths/values).
When all entries have been appropriately filled (and automatically filled values have been adjusted,
if desired) and lines are gray, you are now ready to press 'Generate',
and to exit `cmake-gui` afterwards.
\cgalAdvancedBegin
If you decide to solve missing dependencies using the command line tool (not the recommended way),
the page \ref configurationvariables lists variables which can be used to specify
the location of third-party software.
\cgalAdvancedEnd
\subsection usage_configuring_external Configuring an External Program
Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. This file is automatically provided
for all shipped examples and demos of \cgal. For other programs, CMake can also be used to configure
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,
see Section \ref devman_create_cgal_CMakeLists. Using this shell-script,
the process of configuring a user's program called `executable.cpp` amounts to:
cd /path/to/your/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release .
\subsection usage_configuring_advanced_cmake Advanced Configuration Options
CMake keeps the variables that a user can manipulate in a so-called CMake cache, a simple text file
named `CMakeCache.txt`, whose entries are of the form `VARIABLE:TYPE=VALUE`. Advanced users can manually
edit this file, instead of going through the interactive configuration session.
\section usage_building_program Building your Program
The results of a successful configuration are build files that control the build step.
The nature of the build files depends on the generator used during configuration, but in most cases
they contain several <I>targets</I>, such as all the examples of the Triangulation_2 package.
In a \sc{Unix}-like environment the default generator produces makefiles.
You can use the `make` command-line tool for the succeeding build step as follows:
cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
make # build all the examples of the Triangulation_2 package
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 Release
The "Release" 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 `Debug`, `RelWithDebInfo`, and `MinSizeRel`).
\cgalAdvancedBegin
The build files produced by CMake are autoconfigured. That is, if you change any of the dependencies,
the build step automatically goes all the way back to the configuration step. This way, once the target
has been configured the very first time by invoking cmake, you don't necessarily need to invoke `cmake`
again. Rebuilding will call itself `cmake` and re-generate the build file whenever needed.
\cgalAdvancedEnd
*/

348
Documentation/doc/Documentation/advanced/Configuration_variables.txt Normal file
View File

@ -0,0 +1,348 @@
/*!
\page configurationvariables Summary of %CGAL's Configuration Variables
\cgalAutoToc
\section installation_summary Summary of CGAL's Configuration Variables
Most configuration variables are not environment variables but
<I>CMake variables</I>. They are given in the command line to CMake
via the `-D` option, or passed from the interactive interface
of `cmake-gui`. Unless indicated differently, all the variables
summarized below are CMake variables.
\subsection installation_component_selection Component Selection
The following boolean variables indicate which \cgal components to
configure and build. Their values can be ON or OFF.
| Variable | %Default Value |
| :------- | :--------------- |
| `WITH_examples` | OFF |
| `WITH_demos` | OFF |
| `WITH_CGAL_Core` | ON |
| `WITH_CGAL_Qt5` | ON |
| `WITH_CGAL_ImageIO` | ON |
\subsection installation_flags Compiler and Linker Flags
The following variables specify compiler and linker flags. Each variable holds a
space-separated list of command-line switches for the compiler and linker and
their default values are automatically defined by CMake based on the target platform.
Have in mind that these variables specify a list of flags, not just one
single flag. If you provide your own definition for a variable, you will <I>entirely</I> override
the list of flags chosen by CMake for that particular variable.
The variables that correspond to both debug and release builds are always
used in conjunction with those for the specific build type.
| Program | Both Debug and Release | Release Only | Debug Only |
| :------ | :---------------------- | :------------- | :----------- |
| C++ Compiler | `CMAKE_CXX_FLAGS` | `CMAKE_CXX_FLAGS_RELEASE` | `CMAKE_CXX_FLAGS_DEBUG` |
| Linker (shared libs) | `CMAKE_SHARED_LINKER_FLAGS` | `CMAKE_SHARED_LINKER_FLAGS_RELEASE` | `CMAKE_SHARED_LINKER_FLAGS_DEBUG` |
| Linker (static libs) | `CMAKE_MODULE_LINKER_FLAGS` | `CMAKE_MODULE_LINKER_FLAGS_RELEASE` | `CMAKE_MODULE_LINKER_FLAGS_DEBUG` |
| Linker (programs) | `CMAKE_EXE_LINKER_FLAGS` | `CMAKE_EXE_LINKER_FLAGS_RELEASE` | `CMAKE_EXE_LINKER_FLAGS_DEBUG`|
\subsection installation_additional_flags Additional Compiler and Linker Flags
The following variables can be used to <I>add</I> flags without overriding the ones
defined by cmake.
| Program | Both Debug and Release | Release Only | Debug Only |
| :------ | :---------------------- | :------------- | :----------- |
| C++ Compiler | `CGAL_CXX_FLAGS` | `CGAL_CXX_FLAGS_RELEASE` | `CGAL_CXX_FLAGS_DEBUG` |
| Linker (shared libs) | `CGAL_SHARED_LINKER_FLAGS` | `CGAL_SHARED_LINKER_FLAGS_RELEASE` | `CGAL_SHARED_LINKER_FLAGS_DEBUG` |
| Linker (static libs) | `CGAL_MODULE_LINKER_FLAGS` | `CGAL_MODULE_LINKER_FLAGS_RELEASE` | `CGAL_MODULE_LINKER_FLAGS_DEBUG` |
| Linker (programs) | `CGAL_EXE_LINKER_FLAGS` | `CGAL_EXE_LINKER_FLAGS_RELEASE` | `CGAL_EXE_LINKER_FLAGS_DEBUG` |
\subsection installation_misc Miscellaneous Variables
Note that the default build type is <b>`Debug`</b>, which should only be used to debug
and will serverly limit performances.
| Variable | Description | Type | %Default Value |
| :- | :- | :- | :- |
| `CMAKE_BUILD_TYPE` | Indicates type of build. Possible values are 'Debug' or 'Release' | CMake | |
| `CMAKE_INSTALL_PREFIX`| Installation directory path | CMake | Debug |
| `CMAKE_C_COMPILER` | Full-path to the executable corresponding to the C compiler to use. | CMake | platform-dependent |
| `CMAKE_CXX_COMPILER` | Full-path to the executable corresponding to the C++ compiler to use. | CMake | platform-dependent |
| `CXX` | Idem | Environment | Idem |
| `BUILD_SHARED_LIBS` | Whether to build shared or static libraries. | CMake | TRUE |
\subsection installation_variables_building Variables Used Only When Building Programs (Such as Demos or Examples)
| Variable | Description | Type | %Default Value |
| :- | :- | :- | :- |
| `CGAL_DIR` | Full-path to the binary directory where \cgal was configured |Either CMake or Environment | none |
\subsection installation_variables_third_party Variables Providing Information About 3rd-Party Libraries
\anchor sec3partysoftwareconfig
The following variables provide information about the availability and
location of the 3rd party libraries used by \cgal. CMake automatically
searches for dependencies so you need to specify these variables if
CMake was unable to locate something. This is indicated by a value ending in
`NOTFOUND`.
Since 3rd-party libraries are system wide, many of the CMake variables listed below can alternatively
be given as similarly-named environment variables instead. Keep in mind that you must provide one or the
other but never both.
\subsection installation_boost Boost Libraries
In most cases, if \sc{Boost} is not automatically found, setting the `BOOST_ROOT`
variable is enough. If it is not, you can specify the header and library
directories individually. You can also provide the full pathname to a specific compiled library
if it cannot be found in the library directory or its name is non-standard.
By default, when \sc{Boost} binary libraries are needed, the shared versions
are used if present. You can set the variable
`CGAL_Boost_USE_STATIC_LIBS` to `ON` if you want to link
with static versions explicitly.
On Windows, if you link with \sc{Boost} shared libraries, you must ensure that
the `.dll` files are found by the dynamic linker, at run time.
For example, you can add the path to the \sc{Boost} `.dll` to the
`PATH` environment variable.
| Variable | Description | Type |
| :- | :- | :- |
| `BOOST_ROOT`\cgalFootnote{The environment variable can be spelled either `BOOST_ROOT` or `BOOSTROOT`} | Root directory of your \sc{Boost} installation | Either CMake or Environment |
| `Boost_INCLUDE_DIR` | Directory containing the `boost/version.hpp` file | CMake |
| `BOOST_INCLUDEDIR` | Idem | Environment |
| `Boost_LIBRARY_DIRS` | Directory containing the compiled \sc{Boost} libraries | CMake |
| `BOOST_LIBRARYDIR` | Idem | Environment |
| `Boost_(xyz)_LIBRARY_RELEASE` | Full pathname to a release build of the compiled 'xyz' \sc{Boost} library | CMake |
| `Boost_(xyz)_LIBRARY_DEBUG` | Full pathname to a debug build of the compiled 'xyz' \sc{Boost} library | CMake |
\subsection installation_gmp GMP and MPFR Libraries
Under Windows, auto-linking is used, so only the <I>directory</I>
containing the libraries is needed and you would specify `GMP|MPFR_LIBRARY_DIR` rather than
`GMP|MPFR_LIBRARIES`. On the other hand, under Linux the actual library filename is needed.
Thus you would specify `GMP|MPFR_LIBRARIES`. In no case you need to specify both.
\cgal uses both \sc{Gmp} and \sc{Mpfr} so both need to be supported. If either of them is unavailable the
usage of \sc{Gmp} and of \sc{Mpfr} will be disabled.
| Variable | Description | Type |
| :- | :- | :- |
| `CGAL_DISABLE_GMP` | Indicates whether to search and use \sc{Gmp}/\sc{Mpfr} or not | CMake |
| `GMP_DIR` | Directory of \sc{Gmp} default installation | Environment |
| `GMP_INCLUDE_DIR` | Directory containing the `gmp.h` file | CMake |
| `GMP_INC_DIR` | Idem | Environment |
| `GMP_LIBRARIES_DIR` | Directory containing the compiled \sc{Gmp} library | CMake |
| `GMP_LIB_DIR` | Idem | Environment |
| `GMP_LIBRARIES` | Full pathname of the compiled \sc{Gmp} library | CMake |
| `MPFR_INCLUDE_DIR` | Directory containing the `mpfr.h` file | CMake |
| `MPFR_INC_DIR` | Idem | Environment |
| `MPFR_LIBRARIES_DIR` | Directory containing the compiled \sc{Mpfr} library | CMake |
| `MPFR_LIB_DIR` | Idem | Environment |
| `MPFR_LIBRARIES` | Full pathname of the compiled \sc{Mpfr} library | CMake |
Under Linux, the \sc{Gmpxx} is also searched for, and you may specify the following variables:
| Variable | Description | Type |
| :- | :- | :- |
| `GMPXX_DIR` | Directory of \sc{gmpxx} default installation | Environment |
| `GMPXX_INCLUDE_DIR` | Directory containing the `gmpxx.h` file | CMake |
| `GMPXX_LIBRARIES` | Full pathname of the compiled \sc{Gmpxx} library | CMake |
\subsection installation_qt5 Qt5 Library
You must set the cmake or environment variable `Qt5_DIR` to point to the path
to the directory containing the file `Qt5Config.cmake` created by your \sc{Qt}5 installation. If you are
using the open source edition it should be `<path>/qt-everywhere-opensource-src-<version>/qtbase/lib/cmake/Qt5`.
\subsection installation_leda LEDA Library
When the \leda libraries are not automatically found, yet they are installed on the system
with base names 'leda' and 'ledaD' (for the release and debug versions resp.), it might
be sufficient to just indicate the library directory via the `LEDA_LIBRARY_DIRS` variable.
If that doesn't work because, for example, the names are different, you can provide the full pathnames of each variant
via `LEDA_LIBRARY_RELEASE` and `LEDA_LIBRARY_DEBUG`.
The variables specifying definitions and flags can be left undefined if they are not needed by LEDA.
| Variable | Description | Type |
| :- | :- | :- |
| `WITH_LEDA` | Indicates whether to search and use \leda or not | CMake |
| `LEDA_DIR` | Directory of \sc{LEDA} default installation | Environment |
| `LEDA_INCLUDE_DIR` | Directory containing the file `LEDA/system/basic.h` | CMake |
| `LEDA_LIBRARIES` | Directory containing the compiled \leda libraries | CMake |
| `LEDA_INC_DIR` | Directory containing the file `LEDA/system/basic.h` | Environment |
| `LEDA_LIB_DIR` | Directory containing the compiled \leda libraries | Environment |
| `LEDA_LIBRARY_RELEASE` | Full pathname to a release build of the \leda library | CMake |
| `LEDA_LIBRARY_DEBUG` | Full pathname to a debug build of the \leda library | CMake |
| `LEDA_DEFINITIONS` | Preprocessor definitions | CMake |
| `LEDA_CXX_FLAGS` | Compiler flags | CMake |
| `LEDA_LINKER_FLAGS` | Linker flags | CMake |
\subsection installation_mpfi MPFI Library
\cgal provides a number type based on this library, but the \cgal library
itself does not depend on \sc{Mpfi}. This means that this library must be
configured when compiling an application that uses the above number type.
When \sc{Mpfi} files are not on the standard path, the locations of the headers
and library files must be specified by using environment variables.
| Variable | Description | Type |
| :- | :- | :- |
| `MPFI_DIR` |Directory of \sc{MPFI} default installation | Environment |
| `MPFI_INCLUDE_DIR` | Directory containing the `mpfi.h` file | CMake |
| `MPFI_INC_DIR` | Idem | Environment |
| `MPFI_LIBRARIES_DIR` | Directory containing the compiled \sc{Mpfi} library | CMake |
| `MPFI_LIB_DIR` | Idem | Environment |
| `MPFI_LIBRARIES` | Full pathname of the compiled \sc{Mpfi} library | CMake |
\subsection installation_rs RS and RS3 Library
As said before, only the \cgal univariate algebraic kernel depends on the
library Rs. As the algebraic kernel is not compiled as a part of the \cgal
library, this library is not detected nor configured at installation time.
CMake will try to find Rs in the standard header and library
directories. When it is not automatically detected, the locations of the
headers and library files must be specified using environment variables.
Rs needs \sc{Gmp} 4.2 or later and \sc{Mpfi} 1.3.4 or later. The variables
related to the latter library may also need to be defined.
| Variable | Description | Type |
| :- | :- | :- |
| `RS_DIR` | Directory of \sc{Rs} default installation | Environment |
| `RS_INCLUDE_DIR` | Directory containing the `rs_exports.h` file | CMake |
| `RS_INC_DIR` | Idem | Environment |
| `RS_LIBRARIES_DIR` | Directory containing the compiled \sc{Rs} library | CMake |
| `RS_LIB_DIR` | Idem | Environment |
| `RS_LIBRARIES` | Full pathname of the compiled \sc{Rs} library | CMake |
Similar variables exist for \sc{Rs3}.
| Variable | Description | Type |
| :- | :- | :-
| `RS3_DIR` | Directory of \sc{Rs3} default installation | Environment |
| `RS3_INCLUDE_DIR` | Directory containing the file `rs3_fncts.h` file | CMake |
| `RS3_INC_DIR` | Idem | Environment |
| `RS3_LIBRARIES_DIR` | Directory containing the compiled \sc{Rs3} library | CMake |
| `RS3_LIB_DIR` | Idem | Environment |
| `RS3_LIBRARIES` | Full pathname of the compiled \sc{Rs3} library | CMake |
\subsection installation_ntl NTL Library
Some polynomial computations in \cgal's algebraic kernel
are speed up when \sc{Ntl} is available.
As the algebraic kernel is not compiled as a part of the \cgal
library, this library is not detected nor configured at installation time.
CMake will try to find \sc{Ntl} in the standard header and library
directories. When it is not automatically detected, the locations of the
headers and library files must be specified using environment variables.
| Variable | Description | Type |
| :- | :- | :- |
| `NTL_DIR` | Directory of \sc{NTL} default installation | Environment |
| `NTL_INCLUDE_DIR` | Directory containing the `NTL/ZZX.h` file | CMake |
| `NTL_INC_DIR` | Idem | Environment |
| `NTL_LIBRARIES_DIR` | Directory containing the compiled \sc{Ntl} library | CMake |
| `NTL_LIB_DIR` | Idem | Environment |
| `NTL_LIBRARIES` | Full pathname of the compiled \sc{Ntl} library | CMake |
\subsection installation_eigen Eigen Library
\sc{Eigen} is a header-only template library.
Only the <I>directory</I> containing the header files of \sc{Eigen} 3.1 (or greater) is needed.
| Variable | Description | Type |
| :- | :- | :- |
| `EIGEN3_INCLUDE_DIR` | Directory containing the file `signature_of_eigen3_matrix_library` | CMake |
| `EIGEN3_INC_DIR` | Idem | Environment |
\subsection installation_esbtl ESBTL Library
One skin surface example requires the \sc{Esbtl} library in order to read \sc{Pdb} files.
If \sc{Esbtl} is not automatically found, setting the `ESBTL_INC_DIR`
environment variable is sufficient.
| Variable | Description | Type |
| :- | :- | :- |
| `ESBTL_DIR` | Directory of \sc{ESBTL} default installation | Environment |
| `ESBTL_INC_DIR` | Directory containing the `ESBTL/default.h` file | Environment |
| `ESBTL_INCLUDE_DIR` | Directory containing the `ESBTL/default.h` file | CMake |
\subsection installation_tbb TBB Library
If \sc{Tbb} is not automatically found, the user must set the `TBB_ROOT`
environment variable. The environment variable `TBB_ARCH_PLATFORM=<arch>/<compiler>` must be set.
`<arch>` is `ia32` or `intel64`. `<compiler>` describes the Linux kernel, gcc version or Visual Studio version
used. It should be set to what is used in `$TBB_ROOT/lib/<arch>`.
For windows users, the folder `TBB_ROOT/bin/<arch>/<compiler>` should be added to the `PATH` variable.
Note that the variables in the table below are being used.
| Variable | Description | Type |
| :- | :- | :- |
| `TBB_ROOT` | Directory of \sc{Tbb} default installation | Environment |
| `TBB_INCLUDE_DIRS` | Directory containing the `tbb/tbb.h` file | CMake |
| `TBB_LIBRARY_DIRS` | Directory(ies) containing the compiled TBB libraries | CMake |
| `TBB_LIBRARIES` | Full pathnames of the compiled TBB libraries (both release and debug versions, using "optimized" and "debug" CMake keywords). Note that if the debug versions are not found, the release versions will be used instead for the debug mode. | CMake |
| `TBB_RELEASE_LIBRARY` | Full pathname of the compiled TBB release library | CMake |
| `TBB_MALLOC_RELEASE_LIBRARY` | Full pathname of the compiled TBB release malloc library | CMake |
| `TBB_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug library | CMake |
| `TBB_MALLOC_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug malloc library | CMake |
| `TBB_MALLOCPROXY_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug malloc_proxy library (optional) | CMake |
| `TBB_MALLOCPROXY_RELEASE_LIBRARY` | Full pathname of the compiled TBB release malloc_proxy library (optional) | CMake |
\section installation_compiler_workarounds Compiler Workarounds
A number of boolean flags are used to workaround compiler bugs and
limitations. They all start with the prefix `CGAL_CFG`. These
flags are used to work around compiler bugs and limitations. For
example, the flag `CGAL_CFG_NO_CPP0X_LONG_LONG` denotes
that the compiler does not know the type `long long`.
For each installation a file <TT><CGAL/compiler_config.h></TT>
is defined, with the correct
settings of all flags. This file is generated automatically by CMake,
and it is located in the `include` directory of where you run
CMake. For an in-source configuration this means
`CGAL-\cgalReleaseNumber``/include`.
The test programs used to generate the `compiler_config.h`
file can be found in `config/testfiles`.
Both
`compiler_config.h` and the test programs contain a short
description of the problem. In case of trouble with one of the
`CGAL_CFG` flags, it is a good idea to take a look at it.
The file `CGAL/compiler_config.h` is included from
`<CGAL/config.h>`.
which is included by all \cgal header files.
*/

357
Documentation/doc/Documentation/advanced/Installation.txt Normal file
View File

@ -0,0 +1,357 @@
/*!
\page installation Installation
\cgalAutoToc
<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>
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
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.
\section installation_idealworld Quick Installation
Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as:
cd $HOME/CGAL-\cgalReleaseNumber
cmake -DCMAKE_BUILD_TYPE=Release . # configure CGAL
make # build CGAL
make install # install CGAL
cd examples/Triangulation_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -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.
This is what this page is about.
\section installation_configwithcmake Configuring CGAL with CMake
Before building \cgal, or 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
which \cgal libraries you want to build. Gathering
all this information is called <I>configuration</I>.
The end of the process is marked by the generation of a makefile or a
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
variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others
indicate the details of a third-party library, such as `Boost_INCLUDE_DIR` or which compiler flags to use,
such as `CMAKE_CXX_FLAGS`.
The next sections first present the CMake variables related to \cgal, followed by more generic variables,
and finally the configuration and build processes.
\subsection seclibraries CGAL Libraries
\cgal is split into four libraries. During configuration, you can select the libraries that
you would like to build by setting a CMake variable of the form <TT>WITH_<library></TT>. By default all
are switched `ON`. All activated libraries are to be built after configuration.
Note that some libraries have specific dependencies in addition to the essential ones. See the page
\ref secessential3rdpartysoftware for more information.
| Library | CMake Variable | Functionality | Dependencies |
| :-------- | :------------- | :------------ | :----------- |
| `%CGAL` | none | Main library | \sc{Gmp}, \sc{Mpfr}, \sc{Boost} (headers) |
| `CGAL_Core` | `WITH_CGAL_Core` | The %CORE library for algebraic numbers.\cgalFootnote{CGAL_Core is not part of \cgal, but a custom version of the \sc{Core} library distributed by \cgal for the user convenience and it has it's own license.} | \sc{Gmp} and \sc{Mpfr} |
| `CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | \sc{zlib}, \sc{Vtk} (optional) |
| `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
(`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You
can choose to produce static libraries instead, by setting the CMake
variable `BUILD_SHARED_LIBS` to `FALSE`.
\subsection installation_examples CGAL Examples and Demos
\cgal is distributed with a large collection of examples and demos. By default, these are <B>not</B> configured along with
the \cgal libraries, unless you set the variables `WITH_examples=ON` and/or `WITH_demos=ON`.
Additionally, even when configured with \cgal, they are not automatically built along with the libraries.
You must build the `examples` or `demos` targets (or IDE projects) explicitly.
If you do not plan to compile any demos, you may skip some of the dependencies (such as \sc{Qt}),
as the corresponding \cgal-libraries will not be used. Note, however, that your own demos
might need these \cgal-libraries and thus their dependencies. See the page
\ref secessential3rdpartysoftware for more information.
\subsection installation_debugrelease Debug vs. Release
The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the libraries.
It accepts the values `Debug` or `Release`. Note that the default value is `Debug`, since it is
default value in `CMake`. If you do not plan on debugging, it is important to set the variable
to `Release` for performance reasons.
This is however not an issue for solution/project files, since the user selects the build type
from within the IDE in this environment.
\subsection installation_miscvariables Other CMake Variables
There are many more variables that can be used during configuration. The most important ones are:
<ul>
<li> `CMAKE_INSTALL_PREFIX=<dir>` installation directory [/usr/local]</li>
<li>`CMAKE_BUILD_TYPE=<Debug|Release>` build type [Release]</li>
<li>`BUILD_SHARED_LIBS=<TRUE|FALSE>` shared or static libraries [TRUE]</li>
<li>`CMAKE_C_COMPILER=<program>` C compiler [gcc]</li>
<li>`CMAKE_CXX_COMPILER=<program>` C++ compiler [g++]</li>
</ul>
In case you want to add additional compiler and linker flags, you can use
<ul>
<li>`CGAL_CXX_FLAGS` additional compiler flags</li>
<li>`CGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries)</li>
<li>`CGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries)</li>
<li>`CGAL_EXE_LINKER_FLAGS` add. linker flags (executables)</li>
</ul>
Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set
separate values for debug and release builds. In case you do not want to add
additional flags, but to override the default flags, replace "CGAL" by
"CMAKE" in the variable names above.
A comprehensive list of CMake variables can be found on the \ref configurationvariables page.
Note that CMake maintains a cache name `CMakeCache.txt`. If you change options
(or your environment changes), it is best to remove that file to avoid
problems.
\subsection installation_configuring_gui Configuring CGAL with the CMake GUI
The simplest way to start the configuration process is to run the graphical
user interface of CMake, `cmake-gui`. You must pass as
argument the root directory of \cgal. For example:
cd CGAL-\cgalReleaseNumber
cmake-gui . # Notice the dot to indicate the current directory
After `cmake-gui` opens, press 'Configure'.
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
the output of configuration tests in the lower portion of the application.
When these tests are done, you will see many
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.
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.
Providing information and pressing 'Configure' goes on until
all entries are grayed. You are now ready to press 'Generate'. Once this is
done, you can quit `cmake-gui`.
\subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool
Alternatively, you can run the command-line tool called `cmake`.
You pass as argument the root directory of \cgal.
The command line tool `cmake` accepts CMake variables as arguments of the form `-D<VAR>:<TYPE>=<VALUE>`, as
in the example above, but this is only useful if you already know which variables need to be explicitly defined.
For example:
cd CGAL-\cgalReleaseNumber
cmake . # Notice the dot to indicate the current directory
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
`CGALConfig.cmake`, which is used to build programs using \cgal. The
purpose of this file is explained below.
\cgalAdvancedBegin
CMake keeps the variables that a user can manipulate in a
so-called <I>CMake cache</I>, a simple text file named
`CMakeCache.txt`, whose entries are of the form
`VARIABLE:TYPE=VALUE`. Advanced users can manually edit this file,
instead of going through the interactive configuration session.
\cgalAdvancedEnd
\subsection installation_cgalconfig CGALConfig.cmake
During configuration of the \cgal libraries a file named `CGALConfig.cmake` is generated
in \cgal's root directory (in contrast to \cgal's source directory that has been used
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
building of a program using \cgal, see Section \ref installation_buildprogram.
\section seccmakeoutofsource Multiple Variants of Makefiles (Out-of-Source Builds)
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
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
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
`CMAKE_SOURCE_DIR`.
The binary and source directories do not need to be the same. Thus, you can configure multiple variants by creating a
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
configuration</I>, as showed in the previous sections.
You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and
`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively:
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug
cd CGAL-\cgalReleaseNumber/cmake/platforms/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../..
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release
cd CGAL-\cgalReleaseNumber/cmake/platforms/release
cmake -DCMAKE_BUILD_TYPE=Release ../../..
\section secbuilding Building CGAL
The results of a successful configuration are build files that control the build step.
The nature of the build files depends on the generator used during configuration, but in all cases they
contain several <I>targets</I>, one per library, and a default global target corresponding
to all the libraries.
For example, in a \sc{Unix}-like environment the default generator produces
makefiles. You can use the `make` command-line tool for the
succeeding build step as follows:
# build all the selected libraries at once
make
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).
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
The build files produced by CMake are autoconfigured. That
is, if you change any of the dependencies, the build step
automatically goes all the way back to the configuration step. This
way, once the target has been configured the very first time by
invoking cmake, you don't necessarily need to invoke `cmake`
again. Rebuilding will call itself `cmake` and re-generate the
build file whenever needed. Keep this in mind if you configure \cgal
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
\subsection ssec_installation_build_ex_demos Building Examples and Demos
If you have turned on the configuration of examples
(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional
targets named `examples` and `demos`, plus one target for
each example and each demo in the build files.
None of these targets are included by default, so you need to build them explicitly
<I>after</I> the \cgal libraries have been successfully built.
The targets `examples` and `demos` include themselves all the targets
for examples and demos respectively.
# build all examples at once
make examples
# build all demos at once
make demos
If you are interested in the demos or examples of just a particular module, you can build them in the following way:
make -C demo/Alpha_shapes_2 # equivalent to "cd demo/Alpha_shapes_2; make"
make -C examples/Alpha_shapes_2 # equivalent to "cd examples/Alpha_shapes_2; make"
When using `UNIX Makefiles`, you can find out the exact name of the example or demo target
of a particular package by typing `make help | grep <package>`.
\section secinstalling Installing CGAL
On many platforms, library pieces such as headers, docs and binaries
are expected to be placed in specific locations. A typical example
being `/usr/include` and `/usr/lib` on \sc{Unix}-like
operating systems or `C:/Program Files/` on Windows. The process
of placing or copying the library elements into its standard location
is sometimes referred to as <I>Installation</I> and it is a
postprocessing step after the build step.
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,
the installation simply amounts (in a \sc{Unix}-like environment) to:
# install CGAL
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
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
and `C:\Program Files` under Windows. 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.
\cgalAdvancedEnd
The file `CGALConfig.cmake` is installed by default in
`$CMAKE_INSTALLED_PREFIX/lib/``CGAL-\cgalReleaseNumber`.
\section installation_buildprogram Building a Program using CGAL
Similarly to \cgal and its libraries, compiling a program using \cgal is done in the usual
two steps of configuration and building.
The configuration process is also done using `cmake` (or `cmake-gui`) and requires a `CMakeLists.txt` file.
This file is automatically provided for all shipped examples and demos of \cgal.
For other programs, CMake can also be used to configure
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,
see Section \ref devman_create_cgal_CMakeLists. Using this shell-script,
the process of configuring a user's program called `executable.cpp` amounts to:
cd /path/to/your/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=XXXXXX -CMAKE_BUILD_TYPE=Release .
make
In order to configure a program, you need to indicate the location of the configuration file
in the CMake variable `CGAL_DIR` (as indicated in the example above).
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
if having 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.
*/

8
Documentation/doc/Documentation/advanced/advanced.txt Normal file
View File

@ -0,0 +1,8 @@
/*!
\page advanced Advanced
- \subpage configurationvariables lists the various CMake variables that can be used to help find third-party dependencies.
- \subpage installation describes the (optional) process of building and installing %CGAL itself.
*/

38
Documentation/doc/Documentation/main.txt
View File

@ -2,13 +2,15 @@
\mainpage
The goal of the \cgal Open Source Project is to provide easy access to
efficient and reliable geometric algorithms in the form of a C++
library.
The Computational Geometry Algorithms Library (\cgal) is a software project
that provides easy access to efficient and reliable geometric algorithms
in the form of a C++ library.
The Computational Geometry Algorithms Library offers data structures
and algorithms like \ref PartTriangulationsAndDelaunayTriangulations "triangulations", \ref PartVoronoiDiagrams "Voronoi diagrams", \ref PartPolygons, \ref PartPolyhedra, \ref PartArrangements "arrangements of curves", \ref PartMeshing "mesh generation", \ref PartGeometryProcessing "geometry processing", \ref PartConvexHullAlgorithms "convex hull algorithms", to name just
a few.
\cgal offers data structures and algorithms like \ref PartTriangulationsAndDelaunayTriangulations "triangulations",
\ref PartVoronoiDiagrams "Voronoi diagrams", \ref PartPolygons, \ref PartPolyhedra,
\ref PartArrangements "arrangements of curves", \ref PartMeshing "mesh generation",
\ref PartGeometryProcessing "geometry processing", \ref PartConvexHullAlgorithms "convex hull algorithms",
to name just a few.
All these data structures and algorithms operate on geometric objects
like points and segments, and perform geometric tests on them. These
@ -20,14 +22,18 @@ solver for linear and quadratic programs. It further offers interfaces
to third party software such as the GUI libraries Qt, Geomview, and
the Boost Graph Library.
Demos and Examples
==================
Getting Started
===============
In the distribution of the library you find the two directories *demo*
and *examples*. They contain subdirectories for the \cgal packages.
The demos use third party libraries for the graphical user interface. The
examples don't have this dependency and most examples are refered to in the
user manual.
\cgalModifBegin
remove?
In the distribution of the library, you will find the directories *demo* and *examples*.
They contain subdirectories for the \cgal packages.
The demos use third-party libraries for the graphical user interface.
The examples do not have this dependency and most examples are referred to in the user manual.
\cgalModifEnd
Head over to the page \ref general_intro, which will guide your first steps with \cgal.
License
=======
@ -35,7 +41,7 @@ License
together with Open Source software free of charge. Using %CGAL in
other contexts can be done by obtaining a commercial license from
[GeometryFactory](http://www.geometryfactory.com). For more details
see the \ref licenseIssues "License" page.
see the \ref license "License" page.
Manuals for the Previous Releases
=================================
@ -45,16 +51,16 @@ For releases >= 4.2, visit [https://doc.cgal.org/X.Y](https://doc.cgal.org/4.2)
For releases X.Y, with 3.1 <= X.Y <= 4.1 visit
[https://doc.cgal.org/Manual/X.Y/doc_html/cgal_manual/packages.html](https://doc.cgal.org/Manual/3.1/doc_html/cgal_manual/packages.html)
\htmlonly[block]
<div style="display:none">
\endhtmlonly
\subpage general_intro
\subpage advanced
\subpage tutorials
\subpage packages
\subpage dev_manual
\subpage license
\htmlonly[block]
</div>

57
Documentation/doc/Documentation/manual.txt
View File

@ -1,17 +1,14 @@
namespace CGAL {
/*!
\page manual Organization of the Manual
\cgalAutoToc
\author %CGAL Editorial Board
Organization of the Manual
==========================
\section secorganization Organization of the Manual
This manual is organized in several parts covering the many domains
of computational geometry. Each part consists of several chapters,
of computational geometry.
Each part consists of several chapters,
and each chapter is split into a *User Manual* and a *Reference
Manual*. The User Manual gives the general idea and comes with examples.
The Reference Manual presents the \sc{Api} of the various classes
@ -28,8 +25,7 @@ The scope of the search box is the package you currently look at and the
packages it depends on, or it is the whole manual when you are in
a top level page such as the package overview.
Organization of the Reference Manual
====================================
\section secorganizationref Organization of the Reference Manual
The \cgal library is a library of class templates. Consequently, we express
the requirements on template arguments by specifying \em concepts
@ -70,6 +66,47 @@ As pointed out in Section \ref intro_concept "Concepts and Models"
the notion of a \em concept is about requirements,
and it can be a required global function or a required traits class.
*/
} /* namespace CGAL */
\section markingSpecialFunctionality Marking of Special Functionality
In this manual, you will encounter sections marked as follows.
\subsection advanced_features Advanced Features
Some functionality is considered more advanced, for example because it is
relatively low-level, or requires special care to be properly used.
\cgalAdvancedBegin
Such functionality is identified this way in the manual.
\cgalAdvancedEnd
\subsection debugging_support Debugging Support Features
Usually related to advanced features that for example may not guarantee
class invariants, some functionality is provided that helps debugging,
for example by performing invariants checks on demand.
\cgalDebugBegin
Such functionality is identified this way in the manual.
\cgalDebugEnd
\subsection deprecated_code Deprecated Code
Sometimes, the \cgal project decides that a feature is <em>deprecated</em>. This means
that it still works in the current release, but it will be removed in the next,
or a subsequent release. This can happen when we have found a better way to do
something, and we would like to reduce the maintenance cost of \cgal at some
point in the future. There is a trade-off between maintaining backward
compatibility and implementing new features more easily.
In order to help users manage the changes to apply to their code, we attempt
to make \cgal code emit warnings when deprecated code is used. This can be
done using some compiler specific features. Those warnings can be disabled
by defining the macro `CGAL_NO_DEPRECATION_WARNINGS`. On top of this, we
also provide a macro, `CGAL_NO_DEPRECATED_CODE`, which, when defined,
disables all deprecated features. This allows users to easily test if their
code relies on deprecated features.
\deprecated Such functionality is identified this way in the manual.
*/

67
INSTALL.md
View File

@ -1,30 +1,36 @@
Building CGAL Libraries From a Branch
=====================================
NOTICE
======
Building CGAL using the *branch build* presented here keeps the
build-sources attached to the Git repository.
Since Version 5.0, CGAL is now header-only by default, meaning that it is no longer mandatory
to build (and install) CGAL and its libraries. Usage of CGAL as a header-only library should
thus simply amount to:
Note that we do not document here what are the dependancies and cmake options that
are needed to configure CGAL as they are already documented in the
[installation manual](https://doc.cgal.org/latest/Manual/installation.html).
``` {.bash}
git clone https://github.com/CGAL/cgal.git /path/to/cgal.git
cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2
mkdir -p build/debug
cd build/debug
cmake -DCMAKE_BUILD_TYPE=Debug -DCGAL_DIR=/path/to/cgal.git
make
```
Branch Build of CGAL
in the case of the building of an example in debug mode.
More information on dependencies, configuration flags, and useful scripts to build programs that are not shipped
with CGAL can be found on header-only usage at https://doc.cgal.org/latest/Manual/general_intro.html,
noting that this page describes the setting of CGAL as a sources release and, as such,
files are organized in a slightly different way, see the [Layout of the CGAL Git Repository](README.md).
BRANCH BUILD OF CGAL
====================
Although not recommended, it is still possible to build (and install) CGAL.
The cmake script at the root of the repository is the one to use to
build the CGAL library from a branch. It will collect the list of packages
of the branch and will append their include folder to the include path.
This is main noticeable difference with a build using a regular *flat* release.
Here is an example of how to build the library in Debug:
``` {.bash}
git clone https://github.com/CGAL/cgal.git /path/to/cgal.git
cd /path/to/cgal.git
mkdir -p build/debug
cd build/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../..
make
```
Here is an example of how to build the library in Release:
``` {.bash}
git clone https://github.com/CGAL/cgal.git /path/to/cgal.git
@ -34,33 +40,48 @@ cd build/release
cmake -DCMAKE_BUILD_TYPE=Release ../..
make
```
Note that *no installation is required* to use that version of CGAL once it has been compiled.
Building a Program Using CGAL
=============================
To compile a program using CGAL, simply set `CGAL_DIR` to the location
of where you built the library (environment or cmake variable).
of where you have built the library (environment or cmake variable).
Here is an example of how to build in debug the examples from the 3D Triangulations package:
``` {.bash}
cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_3/examples/Triangulation_3
cd /path/to/cgal.git/Triangulation_3/examples/Triangulation_3
mkdir -p build/debug
cd build/debug
cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug ../..
make
```
If you're trying to build examples or tests that does not already have a `CMakeLists.txt`, you can trigger its creation by calling the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script) found in `/path/to/cgal.git/Scripts/scripts/` at the root of the example/test directory. Here is an example for the examples of the 2D Triangulation package:
If you are trying to build examples or tests that do not already have a `CMakeLists.txt`,
you can trigger its creation by calling the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script)
found in `/path/to/cgal.git/Scripts/scripts/` at the root of the example/test directory.
Here is an example for the examples of the 2D Triangulation package:
``` {.bash}
cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2
/path/to/cgal.git/Scripts/scripts/cgal_create_cmake_script
cd -
cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_2/examples/Triangulation_2
cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2
mkdir -p build/debug
cd build/debug
cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug ../..
make
```
More information on building and installing CGAL is available in the CGAL manual,
at https://doc.cgal.org/latest/Manual/installation.html, noting that this page describes the setting
of CGAL as a sources release and, as such, files are organized in a slightly different way,
see the [Layout of the CGAL Git Repository](README.md).
Note If You Switch Between Branches
===================================
A build may be outdated after an include/dir has been deleted,
switched or even updated. This might lead to compile problems (link
with outdated version). Thus, it is recommended to build CGAL after

211
Installation/INSTALL.md
View File

@ -1,199 +1,26 @@
INTRODUCTION
============
NOTICE
======
This file describes how to install CGAL. The instructions in this file
are for the most common use cases, and cover the command line tools.
Since Version 5.0, CGAL is now header-only by default, meaning that it is no longer mandatory
to build (and install) CGAL and its libraries. Usage of CGAL as a header-only library
simply amounts to, for example:
For further information, or in case of problems, please see the
detailed installation instructions, which can be found in this
distribution in the file ./doc_html/index.html or on the CGAL website
https://doc.cgal.org/latest/Manual/installation.html
The documentation of CGAL is available in PDF and HTML formats.
It is not bundled with the software but can be downloaded separately
at <https://www.cgal.org/Manual>.
For more information about CGAL, see the <https://www.cgal.org/>.
In the current file, x.y is an implicit replacement for the current version
of CGAL (3.5.1, 3.6, and so on).
PREREQUISITES
=============
To install CGAL, you need 'cmake' and several third-party libraries.
Some are essential for entire CGAL, some are mandatory for particular
CGAL packages, some are only needed for demos.
* CMake (>= 3.1), the build system used by CGAL
Required for building CGAL
* Boost (>= 1.48)
Required for building CGAL and for applications using CGAL
Optional compiled Boost library: Boost.Program_options
http://www.boost.org/ or http://www.boostpro.com/products/free/
You need the former if you plan to compile the boost libraries yourself,
for example because you target 64 bit applications for XP64
* Exact Arithmetic
CGAL combines floating point arithmetic with exact arithmetic, in order
to be fast and reliable. CGAL offers support for GMP and MPFR, for LEDA
exact number types, as well as a built-in exact number type used when
none of the other two is installed.
Required by several examples which have hard coded the number type.
- GMP (>= 4.1.4)
http://gmplib.org/
or precompiled version that can be downloaded with CGAL-x.y-Setup.exe
based on http://fp.gladman.plus.com/computing/gmp4win.htm
- MPFR (>= 2.2.1)
https://www.mpfr.org/
or precompiled version that can be downloaded with CGAL-x.y-Setup.exe
based on http://fp.gladman.plus.com/computing/gmp4win.htm
- LEDA (>= 6.2)
http://www.algorithmic-solutions.com/leda/index.htm
* Visualization
Required for most demos
- Qt5 (>= 5.9)
http://qt-project.org/
- Geomview
http://www.geomview.org/
Not supported with Visual C++
* Numerical Libraries
- EIGEN (>=3.1)
Required by the packages:
* Estimation of Local Differential Properties of Point-Sampled Surfaces
* Approximation of Ridges and Umbilics on Triangulated Surface Meshes
* Planar Parameterization of Triangulated Surface Meshes
* Surface Reconstruction from Point Sets
http://eigen.tuxfamily.org/index.php?title=Main_Page
- MPFI
Required by the package:
* Algebraic Kernel
https://gforge.inria.fr/projects/mpfi/
(or shipped with RS http://vegas.loria.fr/rs/)
- RS (root isolation)
Required by the package:
* Algebraic Kernel
http://vegas.loria.fr/rs/
- NTL (Number Type Theory)
Optional for the packages:
* Polynomial
* Algebraic Kernel
http://www.shoup.net/ntl/
* Miscellaneous
- zlib
Optional for the package:
* Surface Mesh Generator can read compressed images directly
http://www.zlib.net/
- ESBTL
Optional to read PDB files:
* Import data from a PDB file as CGAL points or weighted points.
An example is given in package Skin_surface (see example skin_surface_pdb_reader.cpp)
http://esbtl.sourceforge.net/
CONFIGURATION
=============
To configure CGAL, type
```
cmake .
```
in the directory that contains this INSTALL file. You can add several options
to this command. The most important ones are
* `-DCMAKE_INSTALL_PREFIX=<dir>` installation directory [/usr/local]
* `-DCMAKE_BUILD_TYPE=<Debug|Release>` build type [Release]
* `-DBUILD_SHARED_LIBS=<TRUE|FALSE>` shared or static libraries [TRUE]
* `-DCMAKE_C_COMPILER=<program>` C compiler [gcc]
* `-DCMAKE_CXX_COMPILER=<program>` C++ compiler [g++]
In case you want to add additional compiler and linker flags, you can use
* `-DCGAL_CXX_FLAGS` additional compiler flags
* `-DCGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries)
* `-DCGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries)
* `-DCGAL_EXE_LINKER_FLAGS` add. linker flags (executables)
Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set
separate values for debug and release builds. In case you do not want to add
additional flags, but to override the default flags, replace "CGAL" by
"CMAKE" in the variable names above.
By default demos and examples are not configured. If you want to configure
them at the same time as the CGAL library, you can use
* `-DWITH_examples=true`
* `-DWITH_demos=true`
Note that CMake maintains a cache name `CMakeCache.txt`. If you change options
(or your environment changes), it is best to remove that file to avoid
problems.
BUILDING
========
To build the CGAL libraries, type
```
make
```
(or nmake in a Windows command prompt).
If you want, you can install the CGAL header and libraries. To do so, type
```
make install
```
You can build all demos or examples by typing
```
make demos
make examples
```
If you are interested in the demos or examples of just a particular module,
you can build them in the following way:
```
make -C demo/Alpha_shapes_2 (or: cd demo/Alpha_shapes_2; make)
make -C examples/Alpha_shapes_2 (or: cd examples/Alpha_shapes_2; make)
```
A list of all available make targets can be obtained by
```
make help
``` {.bash}
cd /path/to/cgal/examples/Triangulation_2
mkdir -p build/debug
cd build/debug
cmake -DCMAKE_BUILD_TYPE=Debug -DCGAL_DIR=/path/to/cgal
make
```
OUT-OF-SOURCE BUILDS
====================
More information on header-only dependencies, configuration flags, and useful scripts to build programs
that are not shipped with CGAL is available in this distribution in the file ./doc_html/index.html
("Getting Started with CGAL"), or on the CGAL website at https://doc.cgal.org/latest/Manual/general_intro.html
The above instructions build the CGAL library in the same directory tree as
the CGAL sources. Sometimes it is advisable to place all the generated files
somewhere else. For example, if you want to build the library in several
configurations (debug and release, different compilers, and so on). Using
different build directories keeps all the generated files separated for each
configuration.
BUILDING AND INSTALLING CGAL
============================
In the following, `$CGAL_SRC` denotes the directory with the CGAL sources;
`$CGAL_BUILD` is an arbitrary directory where the generated files will be
placed. You can perform an out-of-source build as follows:
```
mkdir $CGAL_BUILD
cd $CGAL_BUILD
cmake [options] $CGAL_SRC
make
make install (if desired)
make demos (if desired)
make examples (if desired)
```
Basically, the only difference is the last parameter of the `cmake` command:
`$CGAL_SRC` instead of `.` .
Although not recommended, it is still possible to build and install CGAL. More information on
building and installing CGAL is available in this distribution in the file ./doc_html/index.html
("Advanced" > "Installation"), or on the CGAL website at https://doc.cgal.org/latest/Manual/installation.html

57
README.md
View File

@ -6,19 +6,45 @@ The Computational Geometry Algorithms Library (CGAL) is a C++ library that
aims to provide easy access to efficient and reliable algorithms in
computational geometry.
CGAL releases
CGAL Releases
=============
The primary vector of distribution of CGAL are sources tarballs, released
twice a year, announced on [the web site of CGAL](https://www.cgal.org/).
The sources distributed that way can be built using the
[CGAL installation manual](https://doc.cgal.org/latest/Manual/installation.html).
CGAL Git repository layout
Getting Started with CGAL
=========================
**Since version 5.0, CGAL is header-only by default, meaning that
it is no longer necessary to build or install CGAL before it can be used.**
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.
Compilation and Installation
============================
If you do not wish to use the header-only mode of CGAL, it is still possible to build CGAL itself.
The compilation and installation of CGAL from a sources tarball are
described in the [CGAL installation manual](https://doc.cgal.org/latest/Manual/installation.html)
and in the file [INSTALL.md](Installation/INSTALL.md) that is at the root
of any sources tarball.
You can also clone this repository and compile from your local Git repository.
This kind of compilation is called a *branch build*, and is
described in the file [INSTALL.md](INSTALL.md) that is at the root of the
Git repository.
License
=======
See the file [LICENSE.md](LICENSE.md).
CGAL Git Repository Layout
==========================
The Git repository of CGAL has a different layout from release tarballs. It
contains a `CMakeLists.txt` file that serves as anchor for building, and a
set of subfolders, so called *packages*. Most packages
contains a `CMakeLists.txt` file that serves as anchor for configuring and building programs,
and a set of subfolders, so called *packages*. Most packages
implement a data structure or an algorithm for CGAL (e.g., `Convex_hull_2`,
or `Triangulation_3`); however some packages serve special needs:
@ -30,24 +56,7 @@ or `Triangulation_3`); however some packages serve special needs:
* `Documentation` - infrastructure for CGAL's manual
* `STL_Extension` - extensions to the standard template library
Compilation and installation
============================
The compilation and installation of CGAL from a sources tarball are
described in the
[CGAL installation manual](https://doc.cgal.org/latest/Manual/installation.html)
and in the file [INSTALL.md](Installation/INSTALL.md) that is at the root
of any sources tarball.
CGAL developers, however, usually compile CGAL directly from a local Git
repository. That kind of compilation is called a *branch build*, and is
described in the file [INSTALL.md](INSTALL.md) that is at the root of the
Git repository.
License
=======
See the file [LICENSE.md](LICENSE.md).
More information
More Information
================
* [The CGAL web site](https://www.cgal.org/)
* [Latest CGAL release documentation pages](https://doc.cgal.org/)