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

Re-organize Manual for 5.0 (WIP)

This commit is contained in:
Mael Rouxel-Labbé 2019-07-12 09:04:15 +02:00
parent e89dae2a24
commit cd17a9486e
7 changed files with 999 additions and 1036 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

346
Documentation/doc/Documentation/Configuration_variables.txt Normal file
View File

@ -0,0 +1,346 @@
/*!
\page configurationvariables Summary of CGAL's Configuration Variables
\cgalAutoToc
\author %CGAL Editorial Board
\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
| Variable | Description | Type | %Default Value |
| :- | :- | :- | :- |
| `CMAKE_BUILD_TYPE` | Indicates type of build. Possible values are 'Debug' or 'Release' | CMake | Release |
| `CMAKE_CXX_COMPILER` | Full-path to the executable corresponding to the C++ compiler to use. | CMake | platform-dependent |
| `CXX` | Idem | Environment | Idem |
\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 `TBBROOT`
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 `$TBBROOT/lib/<arch>`.
For windows users, the folder `TBBROOT/bin/<arch>/<compiler>` should be added to the `PATH` variable.
Note that the variables in the table below are being used.
| Variable | Description | Type |
| :- | :- | :- |
| `TBBROOT` | 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.
*/

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

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

@ -1,13 +1,14 @@
/*!
\page general_intro Getting Started
- \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 how to use %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 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 thirdparty lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces.
*/

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

File diff suppressed because it is too large Load Diff

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

@ -63,9 +63,9 @@ 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
\subsection licenseCheck License Checking
Users who have a commercial license for specific packages can check that
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}.
@ -155,7 +155,7 @@ to force its definition on the command line, and it is possible to prevent its d
definition by setting `CGAL_HAS_NO_THREADS` from the command line.
\section Preliminaries_cc0x C++11 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.
@ -182,7 +182,7 @@ 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
@ -208,7 +208,7 @@ public release 3.2.4 this number is 1030241000; for internal release
3.2-I-30.
</DD>
<DT>`CGAL_VERSION_NUMBER(M,m,b)`</DT>
<DD>
<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

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

@ -0,0 +1,259 @@
/*!
\page thirdparty Essential and Optional Third Party Dependencies
\cgalAutoToc
\author %CGAL Editorial Board
\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, that is 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 |
It may work for older versions of the above listed compilers.
\section seccmake CMake
In order to configure and build the \cgal libraries, examples, and demos,
you need CMake, a cross-platform "makefile generator".
If CMake is not already installed you can obtain it from <A HREF="https://cmake.org/">`https://cmake.org/`</A>.
CMake version 3.1 or higher is required.
This manual explains only those features of
CMake which are needed in order to build \cgal. Please refer to the
CMake documentation at <A HREF="https://cmake.org/">`https://cmake.org/`</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 build (all) libraries of \cgal, that is,
this software must be found during the configuration of \cgal for an
actived library of \cgal (i.e.\ <TT>WITH_<library>=ON</TT>);
see the page \ref configurationvariables to specify the location of 3rd
party software.
The libraries \stl (shipped with any compiler) and \sc{Boost} are essential to all components (i.e.\ libCGAL,
libCGAL_Core, libCGAL_ImageIO, and libCGAL_Qt5).
\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, so there is nothing to install.
\subsection thirdpartyBoost Boost
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, 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 on Windows there is no canonical directory for where to find
\sc{Boost}, we recommend that you define the environment variable
`BOOST_ROOT` and set it to where you have installed \sc{Boost}, e.g.,
<A HREF="C:\boost\boost_1_41_0">`C:\boost\boost_1_41_0`</A>.
\subsection thirdpartyMPFR GMP and MPFR
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.
Having \sc{Gmp} version 4.2 or higher and \sc{Mpfr} version 2.2.1 or higher
installed is recommended. 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>, respectively.
As 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
`CGAL-\cgalReleaseNumber``-Setup.exe`.
\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 PkgSurfaceMesher3Ref 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 thirdpartyQt Qt5
Qt is a cross-platform application and UI framework.
The component libCGAL_Qt5 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`.
\sc{Qt} version 5.9.0 or later is required.
\section secoptional3rdpartysoftware Optional Third Party Libraries
Optional 3rd party software can be used by \cgal for various reasons:
Usually certain optional libraries are 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.
\subsection thirdpartyLeda LEDA
\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 MPFI
\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 PkgAlgebraicKernelDRef "Algebraic Kernel".
\sc{Mpfi} can be downloaded from <A HREF="https://mpfi.gforge.inria.fr/">`https://mpfi.gforge.inria.fr/`</A>. Version 1.4 or higher is recommended.
\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 PkgAlgebraicKernelDRef "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
\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>. Version 5.1 or higher is recommended.
\subsection thirdpartyEigen Eigen
\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} provides sparse linear solvers in the \ref PkgPoissonSurfaceReconstruction3Ref
and the \ref PkgSurfaceMeshParameterizationRef packages.
In addition, \sc{Eigen} also provides singular value decomposition for the \ref PkgJetFitting3Ref
and the \ref PkgRidges3Ref packages.
The \sc{Eigen} web site is <A HREF="http://eigen.tuxfamily.org/index.php?title=Main_Page">`http://eigen.tuxfamily.org`</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 PkgSkinSurface3Ref 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 PkgPointSetProcessing3Ref 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 PkgClassificationRef 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
PkgClassificationRef 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
\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>.
*/

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

@ -0,0 +1,338 @@
/*!
\page usage Usage
\cgalAutoToc
\authors Eric Berberich, Joachim Reichel, and Fernando Cacciola
<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. However, the dependencies of \cgal might still need to be installed.</b>
\section usage_introduction Quick Start
Ideally, compiling an example or a demo shipped with \cgal is as simple as:
cd examples/Triangulation_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . # configure the examples
make # build the examples
cd demo/Triangulation_2 # go to a demo directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . # configure the demos
make # build the demos
Compiling your own program is similar:
cd /path/to/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber .
make
where the second line creates a file `CMakeLists.txt` (see Section \ref seccreate_cgal_CMakeLists for more details).
In a less ideal world, you might have to install 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>
See Section \ref secessential3rdpartysoftware for more details on essential third party software.
\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>.
After 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` | 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 \sc{Core} library\cgalFootnote{<A HREF="https://cs.nyu.edu/exact/">`https://cs.nyu.edu/exact/`</A>} version 1.7 for
dealing with algebraic numbers. \sc{Core} is not part of \cgal and has its
own license.
The directory `include/CGAL/OpenNL` contains a distribution of the
Open Numerical Library 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 from
<A HREF="https://github.com/CGAL/cgal/releases">`https://github.com/CGAL/cgal/releases`</A>.
\section subsection_headeronly Header-only Usage
Since \cgal 4.12, \cgal can be used in header-only mode, without even
configuring \cgal\. Programs using \cgal (examples, tests, demos, etc.)
must be directly configured using CMake. In this case, \cgal will be
configured at the same time. The variable `CGAL_DIR` 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).
So, using \cgal becomes now:
cd /path/to/your/code # go to the directory of the code source using CGAL
cmake -DCGAL_DIR=<CGAL-root> .
\subsection subsection_headeronly_dependencies CGAL Dependencies
\cgal can be used as a header-only library, though not all its dependencies
are header-only. The libraries \sc{Gmp} and \sc{Mpfr}, for example, are not
header-only.
\subsection subsection_headeronly_pbonwindows Possible Problem on Windows
There is one possible problem when using \cgal in header-only mode on a Windows operating system
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.
\cgalModifBegin
EXPLAIN THAT YOU CAN INSTALL IN CASE OF MEETING THIS PROBLEM (?)
\cgalModifEnd
\section installation_configuring_using Configuring and Building Programs Using CGAL
Configuring and compiling a demo/example/program amounts to
cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber .
make
The required `CMakeLists.txt` is already 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 `CMakeLists.txt` script either manually, or with the help of a
shell-script that is introduced below. For a user program `executable.cpp`, this ideally then resumes to:
cd /path/to/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber .
make
The script `cgal_create_CMakeLists` and its options are detailed in Section \ref seccreate_cgal_CMakeLists.
Note that in both examples we specify the `CGAL_DIR`: 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 variable that summarize the
configuration of \cgal. In order to configure a program, you need
to indicate the location of that config file in the CMake variable
`CGAL_DIR` (as indicated in the example above).
`CGAL_DIR` can also be an environment variable. Setting
`CGAL_DIR` makes particular sense if having multiple
out-of-source builds of \cgal as in Section \ref seccmakeoutofsource.
If you have installed \cgal, `CGAL_DIR` must afterwards be set to
`$CMAKE_INSTALLED_PREFIX/lib/CGAL`. Note that \cgal is
recommended to be installed in release mode when using it to build programs.
\subsection seccreate_cgal_CMakeLists Creating a CMake Script for a Program Using CGAL
For compiling a non-shipped program, it is recommended to also rely on a CMake-supported configuration using a
`CMakeLists.txt` used for configuration. The Bourne-shell script `cgal_create_CMakeLists.txt` can
be used to create `CMakeLists.txt` files for compiling \cgal applications
This script resides in the `CGAL-\cgalReleaseNumber``/scripts` directory.
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.
\section secconfigwithcmake Configuring CGAL with CMake
Before building anything using \cgal you have to choose the compiler/linker,
set compiler and linker flags, specify which
third-party libraries you want to use and where they can be found, and
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.
\subsection installation_configuring_gui Configuring CGAL with the CMake GUI
The simplest way to start the configuration is to run the graphical
user interface of CMake. We recommend to use `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 gets 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
\cgalModifBegin
MERGE THAT WITH ABOVE, ADAPT TO FIT EXAMPLE CONFIG RATHER THAN CGAL CONFIG, TRIM IT
\cgalModifEnd
Alternatively, you can run the command-line tool called
`cmake`. You pass as argument the root directory of
\cgal. For example:
cd CGAL-\cgalReleaseNumber
cmake . # Notice the dot to indicate the current directory.
The very first thing CMake does is to detect the compiler to use. This
detection is performed by a special CMake module called a
<I>generator</I>.
A CMake generator understands the build requirements for a
particular compiler/linker and generates the necessary files for that. For
example, the <I>UNIX Makefiles</I> generator understands the GNU chain
of tools (\gcc, ld etc.) and produces makefiles, which can be used to build a
target by a simple call to `make`. Likewise, the <I>Visual Studio
2010</I> generator produces solution and project files and can be manually
launched in the VS IDE to build the target.
Each platform has a default generator, so you only need to select one when
the default is not what you want. For example, under Windows, it is
possible to generate <I>NMakefiles</I> instead of Visual Studio project
files in order to build the library with `nmake`. Running
`cmake` with no parameters in a command-line prints the list of
available generators supported by your platform and CMake version. If the
generator you need is not listed there, you can try a newer
CMake version, as generators are hardcoded into CMake, and additional
generators are added with each release.
Since the choice of the generator determines the type of build files to generate, in some cases
you choose a particular generator as a mean to choose a specific compiler (because they use different
build files). For example, the following generates solution files for
use in Visual \cpp 15.0 on a 64bit machine:
cd CGAL-\cgalReleaseNumber
cmake -G"Visual Studio 15 2017 Win64" .
In other cases, however, the generator doesn't directly identify a
specific compiler but a chain of tools.
For example, the `UNIX Makefiles` generator produces `makefiles` that call some auto-detected
command-line compiler, like \gcc. If you need the makefiles to use a different compiler, you need to
specify the desired compiler in the call to CMake, as in this example:
cd CGAL-\cgalReleaseNumber
cmake -DCMAKE_CXX_COMPILER:FILEPATH=g++-4.7 .
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 `WITH_examples` or `CMAKE_BUILD_TYPE=Release`, while 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`.
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.
\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
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.
\section seccmakeoutofsource Multiple Variants of Makefiles (out-of-source build)
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 installingcgal Installing CGAL
Although header-only makes building \cgal obsolete, it is still possible to configure, build,
and install \cgal. Head to \ref installation for more information.
\cgalModifBegin
+ might still be required to build some cgal libs like cgal-qt?
\cgalModifEnd
*/