From 9a40d573b95a1acf1f14cc29aa1db69c12648622 Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Mon, 17 Jun 2019 15:07:13 +0200 Subject: [PATCH 1/8] Easy fix --- Documentation/doc/Documentation/Installation.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index f6a6b8e6ee0..bb3a857b869 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -285,7 +285,7 @@ purpose of this file is explained below. \section seclibraries CGAL Libraries -\cgal is split into five libraries. During configuration, you can select the libraries that +\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 WITH_. By default all are switched `ON`. All activated libraries are build after configuration; see \ref secbuilding From c249351ef8022b197e766b1a8fcad80550aa3cfd Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Wed, 19 Jun 2019 15:18:00 +0200 Subject: [PATCH 2/8] First pass on the documentation --- .../doc/Documentation/Installation.txt | 113 +++++++----------- 1 file changed, 44 insertions(+), 69 deletions(-) diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index bb3a857b869..543939cca22 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -4,51 +4,39 @@ \authors Eric Berberich, Joachim Reichel, and Fernando Cacciola \section installation_introduction Introduction - -This document describes how to install \cgal on Windows, Unix-like systems, and MacOS X. -Ideally, setting up \cgal amounts to: +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. The dependencies of \cgal still have to be installed. -
-cd CGAL-\cgalReleaseNumber # go to \cgal directory
-cmake . # configure \cgal
-make # build the \cgal libraries
-
+Ideally, compiling an example or a demo shipped with \cgal is +as simple as: -Compiling an example or a demo shipped with \cgal is similarly simple: - -
-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 
-
+ 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 an own non-shipped program is also close: -
-cd /path/to/program 
-cgal_create_CMakeLists -s executable 
-cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . 
-make
-
+ cd /path/to/program + cgal_create_CMakeLists -s executable + cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . + make where the second line creates a `CMakeLists.txt` file (check its options in Section \ref seccreate_cgal_CMakeLists for various details). -In a less ideal world, you probably have to install CMake, a makefile -generator, and third party libraries. That is what this manual is about. +In a less ideal world, you probably have to install required tools, and third party libraries. That is what this manual is about. \section secprerequisites Prerequisites -Installing \cgal requires a few components to be installed ahead: a -supported compiler (see Section \ref seccompilers, CMake, \sc{Boost}, and at least \sc{Gmp}, and \sc{Mpfr}; see +Using \cgal requires a few components to be installed ahead: a +supported compiler (see Section \ref seccompilers), \sc{Boost}, \sc{Gmp}, and \sc{Mpfr}; see Section \ref secessential3rdpartysoftware for more details on essential third party software. @@ -59,35 +47,21 @@ 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 MAC OS X +\subsection sseccgalmacosxe CGAL on macOS -For instance, use macports in the following way: +The \cgal project recommends the use of Homebrew, in the following way: -
-sudo port install cgal
-
- -or if Qt5 are desired - -
-sudo port install cgal +qt5 +universal +demos
-
- -The setup is similar for homebrew . + brew install cgal \subsection sseccgaldebian CGAL on Linux -For instance in debian/Ubuntu, use apt-get in the following way: +For instance in Debian/Ubuntu, use apt-get in the following way: -
-sudo apt-get install libcgal-dev
-
+ sudo apt-get install libcgal-dev To get the demos use -
-sudo apt-get install libcgal-demo
-
+ sudo apt-get install libcgal-demo Check the \cgal-FAQ for source repository of newest releases. @@ -95,7 +69,7 @@ On other distributions, please consult your package manager documentation. \subsection sseccgalwindows CGAL on Windows -You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download.html. +You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. It is a self extracting executable that 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. @@ -122,17 +96,17 @@ In both cases the directory `CGAL-\cgalReleaseNumber` will be created. This dire contains the following subdirectories: -| Directory | Contents | -| :-----------| :----------| -| `auxiliary` | precompiled \sc{Gmp} and \sc{Mpfr} for Windows | +| 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 | +| `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 @@ -151,17 +125,18 @@ installation manual. The \cgal manual must be downloaded separately from \section seccompilers Supported Compilers -In order to build the \cgal libraries, you need a \cpp compiler. +In order to build a program using \cgal, you need a \cpp compiler +supporting C++14 or later. \cgal \cgalReleaseNumber is supported, that is continuously tested, for the following compilers/operating systems: | Compiler | Operating System | | :------- | :--------------- | -|\sc{Gnu} `g++` 4.1 or later\cgalFootnote{`http://gcc.gnu.org/`} | Linux / MacOS X | +|\sc{Gnu} `g++` 6.3 or later\cgalFootnote{`http://gcc.gnu.org/`} | Linux / MacOS X | | | \sc{MS} Windows | -|\sc{MS} Visual `C++` 12.0, 14.0, 15.9 (\sc{Visual Studio} 2013, 2015, and 2017)\cgalFootnote{`https://visualstudio.microsoft.com/`} | \sc{MS} Windows | -| `Clang` \cgalFootnote{`http://clang.llvm.org/`} compiler version 7.0.1 | Linux | -| Apple `Clang` compiler version 7.0.2 | MacOS X | +|\sc{MS} Visual `C++` 14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019)\cgalFootnote{`https://visualstudio.microsoft.com/`} | \sc{MS} Windows | +| `Clang` \cgalFootnote{`http://clang.llvm.org/`} compiler version 8.0.0 | Linux | +| Apple `Clang` compiler versions 7.0.2 and 10.0.1 | MacOS X | It may work for older versions of the above listed compilers. @@ -176,7 +151,7 @@ This manual explains only those features of CMake which are needed in order to build \cgal. Please refer to the CMake documentation at `https://cmake.org/` for further details. -Before building \cgal you have to choose the compiler/linker, +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 @@ -321,7 +296,7 @@ variable `BUILD_SHARED_LIBS` to `FALSE`. If you use \subsubsection subsection_headeronly_withconfiguration Header-only with CMake Configuration -Since \cgal 4.9, \cgal can be used in header-only mode, i.e. without compiling the \cgal libraries and linking with these libraries when compiling examples, tests and demos. This possibility can be enabled by setting the value of the CMake variable `CGAL_HEADER_ONLY` to `ON`. CMake version 3.0.0 or higher is required to use this option. +Since \cgal 4.9, \cgal can be used in header-only mode, i.e. without compiling the \cgal libraries and linking with these libraries when compiling examples, tests and demos. This possibility can be enabled by setting the value of the CMake variable `CGAL_HEADER_ONLY` to `ON`. One advantage of using \cgal in header-only mode is that you do not need to compile and install \cgal libraries before compiling a given example or demo. Note that even in header-only mode we still need to run CMake on \cgal in order to generate different configuration files. So, setting up \cgal becomes now: From 4342262420652423c596e5d9fbc20ef6a90ff72b Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Wed, 19 Jun 2019 15:28:27 +0200 Subject: [PATCH 3/8] Remove the section "Custom Flags in the Programs Using CGAL" That section is completely outdated. See https://doc.cgal.org/4.14/Manual/installation.html#title46 --- .../doc/Documentation/Installation.txt | 34 ------------------- 1 file changed, 34 deletions(-) diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index 543939cca22..8ee8c146822 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -828,40 +828,6 @@ libCGAL_ImageIO (ImageIO), and libCGAL_Qt5 A user is free to create the `CMakeLists.txt` without calling the script (manual creation). -\subsection installation_custom Custom Flags in the Programs Using CGAL - -Normally, programs linked with \cgal must be compiled with the same flags -used by the compilation of \cgal libraries. For this reason, the very first time -a program is configured, all the flags given by the CMake variables `CMAKE_*_FLAGS` -are locked in the sense that the values recorded in `CGALConfig.cmake` -are used to override any values given by CMake itself or yourself. - -This does not apply to the additional flags that can be given via `CGAL_*_FLAGS`. - -Such inherited values are then recorded in the current CMake cache for the program. -The flags are then unlocked in the sense that at any subsequent configuration you can -provide your own flags and this time they will not be overridden. - -When using the interactive `cmake-gui` the first press on `Configure` unlocks -the flags, so that you can edit them as needed. - -\cgalAdvancedBegin -The locking of flags is controlled by the variable -`CGAL_DONT_OVERRIDE_CMAKE_FLAGS` which starts out FALSE and is -toggled right after the flags have been loaded from -`CGALConfig.cmake`. - -If you use the command line tool you can specify flags directly by setting the -controlling variable right up front: - -
-cd CGAL-\cgalReleaseNumber
-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-g .
-cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
-cmake -DCGAL_DIR=CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS=-O2 -DCGAL_DONT_OVERRIDE_CMAKE_FLAGS=TRUE . 
-
-\cgalAdvancedEnd - \section installation_summary Summary of CGAL's Configuration Variables Most configuration variables are not environment variables but From e89dae2a244a7dc4cb413dff589878c32f86a0c6 Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Wed, 19 Jun 2019 15:31:23 +0200 Subject: [PATCH 4/8] Remove section "Compiler Optimizations" That section has been both wrong (for several releases), and useless. Se https://doc.cgal.org/4.14/Manual/installation.html#title65 --- Documentation/doc/Documentation/Installation.txt | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index 8ee8c146822..156aa7e8d1a 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -1166,10 +1166,5 @@ The file `CGAL/compiler_config.h` is included from ``. which is included by all \cgal header files. -\section seccompileroptimisations Compiler Optimizations - -By default CMake generates makefiles for Release mode, with -optimization flags switched on, and vcproj files for Release -and Debug modes. */ From cd17a9486ebae4d62dd98469cbbf0cdb22797b5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 12 Jul 2019 09:04:15 +0200 Subject: [PATCH 5/8] Re-organize Manual for 5.0 (WIP) --- .../Documentation/Configuration_variables.txt | 346 ++++++ .../Developer_manual/Chapter_portability.txt | 4 +- .../doc/Documentation/Getting_started.txt | 5 +- .../doc/Documentation/Installation.txt | 1073 +---------------- .../doc/Documentation/Preliminaries.txt | 10 +- .../doc/Documentation/Third_party.txt | 259 ++++ Documentation/doc/Documentation/Usage.txt | 338 ++++++ 7 files changed, 999 insertions(+), 1036 deletions(-) create mode 100644 Documentation/doc/Documentation/Configuration_variables.txt create mode 100644 Documentation/doc/Documentation/Third_party.txt create mode 100644 Documentation/doc/Documentation/Usage.txt diff --git a/Documentation/doc/Documentation/Configuration_variables.txt b/Documentation/doc/Documentation/Configuration_variables.txt new file mode 100644 index 00000000000..7403a1ded71 --- /dev/null +++ b/Documentation/doc/Documentation/Configuration_variables.txt @@ -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 +CMake variables. 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 entirely 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 add 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 directory +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 `/qt-everywhere-opensource-src-/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 directory 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=/` must be set. +`` is `ia32` or `intel64`. `` describes the Linux kernel, gcc version or Visual Studio version +used. It should be set to what is used in `$TBBROOT/lib/`. + +For windows users, the folder `TBBROOT/bin//` 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 +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 +``. +which is included by all \cgal header files. + +*/ diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt index 84a7d8078b4..16ef913c408 100644 --- a/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt +++ b/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt @@ -236,8 +236,8 @@ operating system and compiler that is defined as follows. quite compiler specific). -Examples are mips_IRIX64-6.5_CC-n32-7.30 or sparc_SunOS-5.6_g++-2.95. For more information, see the \cgal -\link installation installation guide \endlink. +Examples are mips_IRIX64-6.5_CC-n32-7.30 or sparc_SunOS-5.6_g++-2.95. +For more information, see the \cgal \link usage usage guide \endlink. This platform-specific configuration file is created during diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index d8dcfa659f2..a9ea3882e0b 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -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. + */ diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index 156aa7e8d1a..82899c3489b 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -3,265 +3,14 @@ \cgalAutoToc \authors Eric Berberich, Joachim Reichel, and Fernando Cacciola -\section installation_introduction Introduction - -Since \cgal version 5.0, \cgal is header-only be default, which means +Since \cgal version 5.0, \cgal is header-only be default, which means that there is no need to compile and install anything before it can be -used. The dependencies of \cgal still have to be installed. +used. However, the dependencies of \cgal might still need to be installed. -Ideally, compiling an example or a demo shipped with \cgal is -as simple as: +\section seclibraries CGAL Libraries - 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 an own non-shipped program is also close: - - cd /path/to/program - cgal_create_CMakeLists -s executable - cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . - make - -where the second line creates a `CMakeLists.txt` file (check -its options in Section \ref seccreate_cgal_CMakeLists for various details). - - -In a less ideal world, you probably have to install required tools, and third party libraries. That is what this manual is about. - -\section secprerequisites Prerequisites - -Using \cgal requires a few components to be installed ahead: a -supported compiler (see Section \ref seccompilers), \sc{Boost}, \sc{Gmp}, and \sc{Mpfr}; see -Section \ref secessential3rdpartysoftware for more details on -essential third party software. - -\section secshippedcgal 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 Homebrew, 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 - -Check the \cgal-FAQ for source repository of newest releases. - -On other distributions, please consult your 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 tutorial is provided on how to proceed with Microsoft Visual Studio. - - - -\section secgettingcgal Downloading CGAL - -You can obtain the \cgal library from -https://www.cgal.org/download.html -and install it yourself. - -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{`https://cs.nyu.edu/exact/`} 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 with \cgal sources is the present -installation manual. The \cgal manual must be downloaded separately from -`https://www.cgal.org/download.html`. - -\section seccompilers Supported Compilers - -In order to build a program using \cgal, you need a \cpp compiler -supporting C++14 or later. -\cgal \cgalReleaseNumber is supported, that is continuously tested, for the following compilers/operating systems: - - -| Compiler | Operating System | -| :------- | :--------------- | -|\sc{Gnu} `g++` 6.3 or later\cgalFootnote{`http://gcc.gnu.org/`} | Linux / MacOS X | -| | \sc{MS} Windows | -|\sc{MS} Visual `C++` 14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019)\cgalFootnote{`https://visualstudio.microsoft.com/`} | \sc{MS} Windows | -| `Clang` \cgalFootnote{`http://clang.llvm.org/`} compiler version 8.0.0 | Linux | -| Apple `Clang` compiler versions 7.0.2 and 10.0.1 | MacOS X | - -It may work for older versions of the above listed compilers. - - -\section secconfigwithcmake Configuring CGAL with CMake - -In order to configure, build, and install the \cgal libraries, examples and -demos, you need CMake, a cross-platform "makefile generator". -If CMake is not installed already you can obtain it from `https://cmake.org/`. -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 `https://cmake.org/` for further details. - -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 configuration. -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 - -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 -generator. -A CMake generator understands the build requirements for a -particular compiler/linker and generates the necessary files for that. For -example, the UNIX Makefiles 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 Visual Studio -2010 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 NMakefiles 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 cmake variables, like the `CMAKE_CXX_COMPILER` -in the example above. These variables are not environment variables but CMake variables. 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:=`, 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 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. -\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 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 WITH_. By default all +\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 WITH_. By default all are switched `ON`. All activated libraries are build after configuration; see \ref secbuilding @@ -292,137 +41,6 @@ can choose to produce static libraries instead by setting the CMake variable `BUILD_SHARED_LIBS` to `FALSE`. If you use `cmake-gui`, a tick box for that variable is available to set it. -\subsection subsection_headeronly Header-only Option - -\subsubsection subsection_headeronly_withconfiguration Header-only with CMake Configuration - -Since \cgal 4.9, \cgal can be used in header-only mode, i.e. without compiling the \cgal libraries and linking with these libraries when compiling examples, tests and demos. This possibility can be enabled by setting the value of the CMake variable `CGAL_HEADER_ONLY` to `ON`. - -One advantage of using \cgal in header-only mode is that you do not need to compile and install \cgal libraries before compiling a given example or demo. Note that even in header-only mode we still need to run CMake on \cgal in order to generate different configuration files. So, setting up \cgal becomes now: - -
-cd CGAL-\cgalReleaseNumber # go to \cgal directory
-cmake -DCGAL_HEADER_ONLY=ON . # configure \cgal
-
- -and we do not need to run `make` anymore. - -\subsubsection subsection_headeronly_without_configuration Header-only without CMake Configuration - -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= .
-
- -\subsubsection 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. - -\subsubsection 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 default random, the failure behavior, `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. - -\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.\ WITH_=ON); -see \ref sec3partysoftwareconfig 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, -`http://www.cplusplus.com/reference/`, -or `https://msdn.microsoft.com/en-us/library/1fe2x6kt(v=vs.140).aspx`. - -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 `https://www.boost.org/`. For Visual C++ you can download precompiled libraries -from `https://sourceforge.net/projects/boost/files/boost-binaries/`. - -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., -`C:\boost\boost_1_41_0`. - -\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 -`https://gmplib.org/` and `https://www.mpfr.org/`, 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 `http://www.zlib.net/`. - -\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 `http://www.qt-project.org/`. - - -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 installation_examples CGAL Examples and Demos \cgal is distributed with a large collection of examples and demos. By default, these are not configured along with @@ -431,165 +49,24 @@ the \cgal libraries, unless you set the variables `WITH_examples=ON` and/or `WIT Nevertheless, 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 might skip some of the essential libraries (as \sc{Qt}), +If you do not plan to compile any demos, you might skip some of the essential libraries (such as \sc{Qt}), as the corresponding \cgal-libraries are not linked. But for your own demos you might need these \cgal-libraries. -\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 `https://www.algorithmic-solutions.com`. - -\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 `http://mpfi.gforge.inria.fr/`. 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 `http://vegas.loria.fr/rs/`. 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 -`http://mpfi.gforge.inria.fr/`. - -\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 `http://www.shoup.net/ntl/`. 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 `http://eigen.tuxfamily.org`. - -\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 `http://esbtl.sourceforge.net/`. - -\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 `https://www.threadingbuildingblocks.org`. - -\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 `https://rapidlasso.com/lastools/`. \sc{LASlib} -is usually distributed along with LAStools: for simplicity, \cgal -provides a fork with a -CMake based install procedure. - -\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 `https://opencv.org/`. - -\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 `https://www.tensorflow.org/`. - -\subsection thirdpartyMETIS METIS - -\sc{METIS} is a library developed by the Karypis Lab -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 -Boost Graph Library, -and, by extension, of surface meshes (see Section \ref BGLPartitioning of the package \ref PkgBGL). - -More information is available on the METIS library -at `http://glaros.dtc.umn.edu/gkhome/metis/metis/overview`. - -\section secbuilding Building CGAL +\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 targets, one per library, and a default global target corresponding +The nature of the build files depends on the generator used during configuration, but in all cases they +contain several targets, 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: -
-
-cd CGAL-\cgalReleaseNumber
-
-# build all the selected libraries at once
-
-make 
-
-
+ cd CGAL-\cgalReleaseNumber + # build all the selected libraries at once + make The resulting libraries are placed in the subdirectory `lib` under `` (which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration). @@ -602,11 +79,7 @@ above, which you can manually build as with any other solution/project within yo Alternatively, you can build it with the command line version of the \sc{Visual Studio Ide}: -
-
-devenv CGAL.sln /Build Debug
-
-
+ 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 @@ -633,15 +106,11 @@ None of these targets are included by default, so you need to build them explici The targets `examples` and `demos` include themselves all the targets for examples and demos respectively. -
+    # build all examples at once
+    make examples
 
-# build all examples at once
-make examples 
-
-# build all demos at once
-make demos
-
-
+ # build all demos at once + make demos \cgalAdvancedBegin When using `UNIX Makefiles` you can find out the @@ -649,7 +118,7 @@ exact name of the example or demo target of a particular package by typing `make help | grep `. \cgalAdvancedEnd -\section secinstalling Installing CGAL +\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 @@ -659,25 +128,21 @@ of placing or copying the library elements into its standard location is sometimes referred to as Installation and it is a postprocessing step after the build step. -CMake carries out the installation by producing a build target named install. +CMake carries out the installation by producing a build target named install. The following example shows a typical session from configuration to installation in a \sc{Unix}-like environment: -
+    cd CGAL-\cgalReleaseNumber
 
-cd CGAL-\cgalReleaseNumber
-
-cmake . # configure
-make # compile
-make install # install
-
-
+ cmake . # configure + make # compile + make install # 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 "build" to execute the installation step. \cgalAdvancedBegin -The files are copied into a directory tree relative to the installation directory determined by the +The files are copied into a directory tree relative to the installation directory 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 at the configuration time and not when executing the install step. @@ -686,485 +151,39 @@ variable explicitly at the configuration time and not when executing the The file `CGALConfig.cmake` is installed by default in `$CMAKE_INSTALLED_PREFIX/lib/``CGAL-\cgalReleaseNumber`. -\section seccmakeoutofsource Multiple Variants of Makefiles (out-of-source build) +\section secshippedcgal 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. -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. +\subsection sseccgalmacosxe CGAL on macOS -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 \cgal project recommends the use of Homebrew, in the following way: -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 out-of-source configuration, as opposite to an in-source -configuration, as showed in the previous sections. + brew install cgal -You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and -`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively: +\subsection sseccgaldebian CGAL on Linux -
-mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug
-cd CGAL-\cgalReleaseNumber/cmake/platforms/debug
-cmake -DCMAKE_BUILD_TYPE=Debug ../../..
+For instance in Debian/Ubuntu, use apt-get in the following way:
 
-mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release
-cd CGAL-\cgalReleaseNumber/cmake/platforms/release
-cmake -DCMAKE_BUILD_TYPE=Release ../../..
-
+ sudo apt-get install libcgal-dev -\section installation_configuring_using Configuring and Building Programs Using CGAL +To get the demos use -Ideally, configuring and compiling a demo/example/program amounts to + sudo apt-get install libcgal-demo -
+Check the \cgal-FAQ for source repository of newest releases.
 
-cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
-cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber .
-make
+On other distributions, please consult your package manager documentation.
 
-
+\subsection sseccgalwindows CGAL on Windows -In this ideal world, as for all shipped examples and demos of \cgal, the -required `CMakeLists.txt` is already provided. +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 tutorial is provided on how to proceed with Microsoft Visual Studio. -CMake can also be used to configure and build user programs via such -CMake-scripts. In this less ideal world, 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`, the ideal world looks like this: - -
-cd /path/to/program 
-cgal_create_CMakeLists -s executable
-cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . 
-make
-
- -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 installation_creating 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. - -Use the following Bourne-shell script for programs that are relatively -simple to configure: - -\subsection seccreate_cgal_CMakeLists cgal_create_CMakeLists - -The Bourne-shell script `cgal_create_CMakeLists.txt` resides in the -`CGAL-\cgalReleaseNumber``/scripts` directory. It can be used to create -`CMakeLists.txt` files for compiling \cgal applications. 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. - -
-
`-s source`
If this parameter is given the script will -create a single executable 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 one executable for each given -source file. -
`-c com1:com2:...`
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`. - -
`-b boost1:boost2:...`
Lists components ("boost1", -"boost2") of \sc{Boost} to which the executable(s) should be -linked. Valid options are, for instance, "filesystem" or "program_options". - -
- -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. - -\subsection seccreate_cgal_cmake_script cgal_create_cmake_script - -\deprecated For backward-compatibility we still provide the -Bourne-shell script `cgal_create_cmake_script` that is -contained in the `CGAL-\cgalReleaseNumber``/scripts` directory. It can be used -to create `CMakeLists.txt` files for compiling \cgal -applications. Executing `cgal_create_cmake_script` in an -application directory creates a `CMakeLists.txt` containing -rules for every C++ source file there. The script is deprecated, -as it only works for applications with a single course file that only -need libCGAL and libCGAL_Core. - -Such a shell-script simply creates a CMake script. Processing it -with CMake, searches for \cgal using `find_package`. If found, -the variable `CGAL_USE_FILE` is set to a compilation environment CMake file. Including -this file within a CMake script sets up include paths and libraries to -link with \cgal and essential third party libraries. Beyond, -`find_package` can demand for `COMPONENTS` of \cgal, -that is, all \cgal libraries `libCGAL_Core` (Core), -libCGAL_ImageIO (ImageIO), and libCGAL_Qt5 -(Qt5) or optional 3rd party software such as MPFI, RS3. -A user is free to create the `CMakeLists.txt` -without calling the script (manual creation). - -\section installation_summary Summary of CGAL's Configuration Variables - -Most configuration variables are not environment variables but -CMake variables. 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 entirely 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 add 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 directory -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 `/qt-everywhere-opensource-src-/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 directory 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=/` must be set. -`` is `ia32` or `intel64`. `` describes the Linux kernel, gcc version or Visual Studio version -used. It should be set to what is used in `$TBBROOT/lib/`. - -For windows users, the folder `TBBROOT/bin//` 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 -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 -``. -which is included by all \cgal header files. - - -*/ +*/ diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index 6d03fb0d21d..62ddb9f4c79 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -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.
`CGAL_VERSION_NUMBER(M,m,b)`
-
+
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 diff --git a/Documentation/doc/Documentation/Third_party.txt b/Documentation/doc/Documentation/Third_party.txt new file mode 100644 index 00000000000..46a0522a5b8 --- /dev/null +++ b/Documentation/doc/Documentation/Third_party.txt @@ -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 C++14 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{`http://gcc.gnu.org/`} | +| | `Clang` \cgalFootnote{`http://clang.llvm.org/`} compiler version 8.0.0 | +| \sc{MS} Windows | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{`http://gcc.gnu.org/`} | +| | \sc{MS} Visual `C++` 14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019)\cgalFootnote{`https://visualstudio.microsoft.com/`} | +| MacOS X | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{`http://gcc.gnu.org/`} | +| | 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 `https://cmake.org/`. +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 `https://cmake.org/` 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.\ WITH_=ON); +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, +`https://en.cppreference.com `, +or `https://msdn.microsoft.com`. + +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 `https://www.boost.org/`. For Visual C++ you can download precompiled libraries +from `https://sourceforge.net/projects/boost/files/boost-binaries/`. + +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., +`C:\boost\boost_1_41_0`. + +\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 +`https://gmplib.org/` and `https://www.mpfr.org/`, 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 `https://www.zlib.net/`. + +\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 `https://www.qt-project.org/`. + +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 `https://www.algorithmic-solutions.com`. + +\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 `https://mpfi.gforge.inria.fr/`. 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 `http://vegas.loria.fr/rs/`. 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 +`https://mpfi.gforge.inria.fr/`. + +\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 `https://www.shoup.net/ntl/`. 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 `http://eigen.tuxfamily.org`. + +\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 `http://esbtl.sourceforge.net/`. + +\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 `https://www.threadingbuildingblocks.org`. + +\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 `https://rapidlasso.com/lastools/`. \sc{LASlib} +is usually distributed along with LAStools: for simplicity, \cgal +provides a fork with a +CMake based install procedure. + +\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 `https://opencv.org/`. + +\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 `https://www.tensorflow.org/`. + +\subsection thirdpartyMETIS METIS + +\sc{METIS} is a library developed by the Karypis Lab +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 +Boost Graph Library, +and, by extension, of surface meshes (see Section \ref BGLPartitioning of the package \ref PkgBGL). + +More information is available on the METIS library +at `http://glaros.dtc.umn.edu/gkhome/metis/metis/overview`. + +*/ diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt new file mode 100644 index 00000000000..1e6061471e3 --- /dev/null +++ b/Documentation/doc/Documentation/Usage.txt @@ -0,0 +1,338 @@ +/*! +\page usage Usage +\cgalAutoToc +\authors Eric Berberich, Joachim Reichel, and Fernando Cacciola + +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. + +\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: +
    +
  • a supported compiler (see Section \ref seccompilers),
    • +
  • \ref seccmake
    • +
  • \ref thirdpartyBoost,
    • +
  • \ref thirdpartyMPFR.
    • +
+ +See Section \ref secessential3rdpartysoftware for more details on essential third party software. + +\section secgettingcgal Downloading CGAL + +You can obtain the \cgal library from +https://www.cgal.org/download.html. + +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{`https://cs.nyu.edu/exact/`} 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 +`https://doc.cgal.org` +or downloaded separately from +`https://github.com/CGAL/cgal/releases`. + +\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= . + +\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 default random, +the failure behavior, +`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. + +
+
`-s source`
If this parameter is given the script will +create a single executable 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 one executable for each given +source file. +
`-c com1:com2:...`
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`. + +
`-b boost1:boost2:...`
Lists components ("boost1", +"boost2") of \sc{Boost} to which the executable(s) should be +linked. Valid options are, for instance, "filesystem" or "program_options". + +
+ +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 configuration. +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 +generator. +A CMake generator understands the build requirements for a +particular compiler/linker and generates the necessary files for that. For +example, the UNIX Makefiles 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 Visual Studio +2010 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 NMakefiles 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 cmake variables, like the `CMAKE_CXX_COMPILER` +in the example above. These variables are not environment variables but CMake variables. 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:=`, 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 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. +\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 out-of-source configuration, as opposite to an in-source +configuration, 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 + +*/ From 371f4bbf3f5f37f2a55b1545f9b41979858d4244 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 20 Sep 2019 17:20:15 +0200 Subject: [PATCH 6/8] Progress on Manual improvements --- .../Documentation/Configuration_variables.txt | 12 +- .../doc/Documentation/Installation.txt | 186 +++++++++++-- Documentation/doc/Documentation/License.txt | 72 +++++ .../doc/Documentation/Preliminaries.txt | 77 ------ .../doc/Documentation/Third_party.txt | 88 +++---- Documentation/doc/Documentation/Usage.txt | 247 +++++++----------- .../doc/Documentation/cmakelist_script.txt | 39 +++ Documentation/doc/Documentation/main.txt | 2 +- 8 files changed, 418 insertions(+), 305 deletions(-) create mode 100644 Documentation/doc/Documentation/License.txt create mode 100644 Documentation/doc/Documentation/cmakelist_script.txt diff --git a/Documentation/doc/Documentation/Configuration_variables.txt b/Documentation/doc/Documentation/Configuration_variables.txt index 7403a1ded71..eec18702b94 100644 --- a/Documentation/doc/Documentation/Configuration_variables.txt +++ b/Documentation/doc/Documentation/Configuration_variables.txt @@ -1,9 +1,7 @@ /*! -\page configurationvariables Summary of CGAL's Configuration Variables +\page configurationvariables Summary of %CGAL's Configuration Variables \cgalAutoToc -\author %CGAL Editorial Board - \section installation_summary Summary of CGAL's Configuration Variables @@ -295,18 +293,18 @@ environment variable is sufficient. \subsection installation_tbb TBB Library -If \sc{Tbb} is not automatically found, the user must set the `TBBROOT` +If \sc{Tbb} is not automatically found, the user must set the `TBB_ROOT` environment variable. The environment variable `TBB_ARCH_PLATFORM=/` must be set. `` is `ia32` or `intel64`. `` describes the Linux kernel, gcc version or Visual Studio version -used. It should be set to what is used in `$TBBROOT/lib/`. +used. It should be set to what is used in `$TBB_ROOT/lib/`. -For windows users, the folder `TBBROOT/bin//` should be added to the `PATH` variable. +For windows users, the folder `TBB_ROOT/bin//` 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_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 | diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt index 82899c3489b..344ece43ff5 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/Installation.txt @@ -1,18 +1,32 @@ /*! \page installation Installation \cgalAutoToc -\authors Eric Berberich, Joachim Reichel, and Fernando Cacciola 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. -\section seclibraries CGAL Libraries +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 (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 sseccgalmacosxe. + +\section installation_configwithcmake 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 configuration. +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 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 WITH_. By default all are switched `ON`. All activated libraries are build after -configuration; see \ref secbuilding +configuration; see \ref secbuilding. We next list the libraries and essential 3rd party software (see \ref secessential3rdpartysoftware) for each library: @@ -20,20 +34,11 @@ We next list the libraries and essential 3rd party software | 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_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 | -\subsection installation_debug Debug vs. Release - -The CMake variable `CMAKE_BUILD_TYPE` indicates how to build -the libraries. It accepts the values `Release` or -`Debug`. The default is `Release` and should be kept, unless you want to debug -your program. - -This is not an issue for solution/project files, as there the user selects the build type from within the IDE. - -\subsection installation_static Static vs. Shared Libraries +\subsubsection installation_static Static vs. Shared Libraries Shared libraries, also called dynamic-link libraries, are built by default (`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You @@ -41,17 +46,121 @@ can choose to produce static libraries instead by setting the CMake variable `BUILD_SHARED_LIBS` to `FALSE`. If you use `cmake-gui`, a tick box for that variable is available to set it. -\section installation_examples CGAL Examples and Demos +\subsection installation_examples CGAL Examples and Demos \cgal is distributed with a large collection of examples and demos. By default, these are not configured along with the \cgal libraries, unless you set the variables `WITH_examples=ON` and/or `WITH_demos=ON`. - -Nevertheless, even when configured with \cgal, they are not automatically built along with the libraries. +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 might skip some of the essential libraries (such as \sc{Qt}), -as the corresponding \cgal-libraries are not linked. But for -your own demos you might need these \cgal-libraries. +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. + +\subsection installation_cmakevariables CMake Variables + +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` as it is +default value in `CMake` and if you do not plan on debugging, it is important to set the variable +to `Release` for performance reasons. + +This is not an issue for solution/project files, since the user selects the build type +from within the IDE in this environment. + +\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 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 + +\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 +generator. +A CMake generator understands the build requirements for a +particular compiler/linker and generates the necessary files for that. For +example, the UNIX Makefiles 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 Visual Studio +2010 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 NMakefiles 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++-9.2 . + +CMake maintains configuration parameters in so-called cmake variables, like the `CMAKE_CXX_COMPILER` +in the example above. These variables are not environment variables but CMake variables. 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:=`, 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 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. +\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 secbuilding Building CGAL @@ -83,7 +192,7 @@ Alternatively, you can build it with the command line version of the 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). +(the other choices are `Release`, `RelWithDebInfo`, and `MinSizeRel`). \cgalAdvancedBegin The build files produced by CMake are autoconfigured. That @@ -151,6 +260,33 @@ variable explicitly at the configuration time and not when executing the The file `CGALConfig.cmake` is installed by default in `$CMAKE_INSTALLED_PREFIX/lib/``CGAL-\cgalReleaseNumber`. +\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 out-of-source configuration, as opposite to an in-source +configuration, 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 secshippedcgal OS Specific Installation Some operating systems with package managers offer \cgal and its @@ -170,13 +306,11 @@ For instance in Debian/Ubuntu, use apt-get in the following way: sudo apt-get install libcgal-dev -To get the demos use +To get the demos, use: sudo apt-get install libcgal-demo -Check the \cgal-FAQ for source repository of newest releases. - -On other distributions, please consult your package manager documentation. +For other distributions, please consult your respective package manager documentation. \subsection sseccgalwindows CGAL on Windows diff --git a/Documentation/doc/Documentation/License.txt b/Documentation/doc/Documentation/License.txt new file mode 100644 index 00000000000..e6a966bd6cf --- /dev/null +++ b/Documentation/doc/Documentation/License.txt @@ -0,0 +1,72 @@ +/*! +\page cgallicensepage 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. + +*/ diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index 62ddb9f4c79..c56900ea3eb 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -2,92 +2,15 @@ \page preliminaries Preliminaries \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. -\section licenseIssues License Issues - -\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 diff --git a/Documentation/doc/Documentation/Third_party.txt b/Documentation/doc/Documentation/Third_party.txt index 46a0522a5b8..af75baa2d64 100644 --- a/Documentation/doc/Documentation/Third_party.txt +++ b/Documentation/doc/Documentation/Third_party.txt @@ -2,13 +2,12 @@ \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 C++14 or later. -\cgal \cgalReleaseNumber is supported, that is continuously tested, for the following compilers/operating systems: +\cgal \cgalReleaseNumber is supported (continuously tested) for the following compilers/operating systems: | Operating System | Compiler | | :------- | :--------------- | @@ -19,68 +18,62 @@ supporting C++14 or later. | MacOS X | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{`http://gcc.gnu.org/`} | | | Apple `Clang` compiler versions 7.0.2 and 10.0.1 | -It may work for older versions of the above listed compilers. +Older versions of the above listed compilers might work, but no guarantee is provided. \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 `https://cmake.org/`. +In order to configure and build the \cgal examples, demos, or libraries, +you need CMake, a cross-platform "makefile generator". 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 `https://cmake.org/` for further details. +This manual explains only the features of CMake which are needed in order to build \cgal. +Please refer to the CMake documentation +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.\ WITH_=ON); -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). +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 can be used to learn which variables can be used to specify +the location of third-party software. \subsection thirdpartystl Standard Template Library (STL) -\cgal heavily uses the \stl, and in particular adopted -many of its design ideas. You can find online +\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, `https://en.cppreference.com `, or `https://msdn.microsoft.com`. -The \stl comes with the compiler, so there is nothing to install. +The \stl comes with the compiler, and as such no installation is required. \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 +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`. +\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 +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 `https://www.boost.org/`. For Visual C++ you can download precompiled libraries +can obtain them from `https://www.boost.org/`. +For Visual C++ you can download precompiled libraries from `https://sourceforge.net/projects/boost/files/boost-binaries/`. -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., -`C:\boost\boost_1_41_0`. +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 GMP and MPFR -The components libCGAL, libCGAL_Core, and libCGAL_Qt5 require +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. @@ -96,22 +89,21 @@ installed is recommended. These libraries can be obtained from 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`. +`CGAL-\cgalReleaseNumber``-Setup.exe`. -\subsection thirdpartyzlib zlib +\section secoptional3rdpartysoftware Optional Third Party Libraries -\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 `https://www.zlib.net/`. +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 thirdpartyQt Qt5 Qt is a cross-platform application and UI framework. -The component libCGAL_Qt5 requires \sc{Qt}5 installed on your system. +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 `https://www.qt-project.org/`. @@ -121,13 +113,6 @@ The exhaustive list of \sc{Qt}5 components used in demos is: \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 @@ -256,4 +241,13 @@ and, by extension, of surface meshes (see Section \ref BGLPartitioning of the pa More information is available on the METIS library at `http://glaros.dtc.umn.edu/gkhome/metis/metis/overview`. +\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 `https://www.zlib.net/`. + */ diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt index 1e6061471e3..70d0bdaf26b 100644 --- a/Documentation/doc/Documentation/Usage.txt +++ b/Documentation/doc/Documentation/Usage.txt @@ -1,34 +1,33 @@ /*! \page usage Usage \cgalAutoToc -\authors Eric Berberich, Joachim Reichel, and Fernando Cacciola 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. +used. However, some dependencies of \cgal might still need to be installed. \section usage_introduction Quick Start -Ideally, compiling an example or a demo shipped with \cgal is as simple as: +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 . # configure the examples + cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . # 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 + cd /path/to/your/program cgal_create_CMakeLists -s executable - cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber . + cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . make -where the second line creates a file `CMakeLists.txt` (see Section \ref seccreate_cgal_CMakeLists for more details). +The script `cgal_create_CMakeLists` and its options are detailed in Section \ref manual_create_cgal_CMakeLists. -In a less ideal world, you might have to install required tools, and third party libraries. +\cgalModifBegin +Something about Windows? +\cgalModifEnd + +In a less ideal world, you might have to install the required tools and third party libraries. This is what this page is about. \section secprerequisites Prerequisites @@ -41,14 +40,15 @@ Using \cgal requires a few core components to be previously installed:
  • \ref thirdpartyMPFR.
    • -See Section \ref secessential3rdpartysoftware for more details on essential third party software. +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 https://www.cgal.org/download.html. -After you have downloaded the file `CGAL-\cgalReleaseNumber``.tar.gz` containing the +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: @@ -57,59 +57,51 @@ command: 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 | - +| 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 \sc{Core} library\cgalFootnote{`https://cs.nyu.edu/exact/`} version 1.7 for -dealing with algebraic numbers. \sc{Core} is not part of \cgal and has its +distribution of the \sc{Core} library 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 -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. +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 `https://doc.cgal.org` -or downloaded separately from +or downloaded separately at `https://github.com/CGAL/cgal/releases`. -\section subsection_headeronly Header-only Usage +\section section_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). +Since \cgal 4.12, it has been possible to use \cgal in header-only mode, +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. -So, using \cgal becomes now: - - cd /path/to/your/code # go to the directory of the code source using CGAL - cmake -DCGAL_DIR= . - -\subsection subsection_headeronly_dependencies CGAL Dependencies - -\cgal can be used as a header-only library, though not all its dependencies +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. +header-only. As such, these dependencies must be built or installed independently. -\subsection subsection_headeronly_pbonwindows Possible Problem on Windows +\subsection subsection_headeronly_pbonwindows Potential Issue on Windows -There is one possible problem when using \cgal in header-only mode on a Windows operating system +\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 @@ -119,92 +111,58 @@ the `-b boost1:boost2:...`
    Lists components ("boost1", -"boost2") of \sc{Boost} to which the executable(s) should be -linked. Valid options are, for instance, "filesystem" or "program_options". - - - -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 configuration. -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 +\subsection usage_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 @@ -214,7 +172,7 @@ argument the root directory of \cgal. For example: 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. +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 @@ -226,7 +184,7 @@ 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 +\subsection usage_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 @@ -299,40 +257,35 @@ The configuration process not only determines the location of the required depen `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) +\section usage_building_program Building your Program -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. +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 targets, such as all the examples of the Triangulation_2 package. -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`. +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: -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 out-of-source configuration, as opposite to an in-source -configuration, as showed in the previous sections. + cd CGAL-\cgalReleaseNumber/examples/Triangulation_2 + make # build all the examples of the Triangulation_2 package -You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and -`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively: +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}. - mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug - cd CGAL-\cgalReleaseNumber/cmake/platforms/debug - cmake -DCMAKE_BUILD_TYPE=Debug ../../.. +Alternatively, you can build it with the command line version of the \sc{Visual Studio Ide}: - mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release - cd CGAL-\cgalReleaseNumber/cmake/platforms/release - cmake -DCMAKE_BUILD_TYPE=Release ../../.. + devenv CGAL.sln /Build Release -\section installingcgal Installing CGAL +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`). -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 +\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 */ diff --git a/Documentation/doc/Documentation/cmakelist_script.txt b/Documentation/doc/Documentation/cmakelist_script.txt new file mode 100644 index 00000000000..cfa5a0e52c3 --- /dev/null +++ b/Documentation/doc/Documentation/cmakelist_script.txt @@ -0,0 +1,39 @@ +/*! + +\page manual_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 `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. + +
    +
    `-s source`
    If this parameter is given the script will +create a single executable 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 one executable for each given +source file. +
    `-c com1:com2:...`
    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`. + +
    `-b boost1:boost2:...`
    Lists components ("boost1", +"boost2") of \sc{Boost} to which the executable(s) should be +linked. Valid options are, for instance, "filesystem" or "program_options". + +
    + +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. + +*/ diff --git a/Documentation/doc/Documentation/main.txt b/Documentation/doc/Documentation/main.txt index 22a8407f82e..761b8505a75 100644 --- a/Documentation/doc/Documentation/main.txt +++ b/Documentation/doc/Documentation/main.txt @@ -35,7 +35,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 cgallicensepage "License" page. Manuals for the Previous Releases ================================= From d5301515c718345c2e2f51f081275eb90b45987e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 20 Sep 2019 22:16:08 +0200 Subject: [PATCH 7/8] Some more progress on cleaning the package 'Documentation' --- .../cmakelist_script.txt | 5 +- .../Developer_manual/developer_manual.txt | 2 +- .../doc/Documentation/Getting_started.txt | 12 +- Documentation/doc/Documentation/License.txt | 34 +++- .../doc/Documentation/Preliminaries.txt | 49 +---- .../doc/Documentation/Third_party.txt | 2 +- .../Tutorials/Tutorial_hello_world.txt | 143 ++++++-------- Documentation/doc/Documentation/Usage.txt | 180 ++++++------------ .../Configuration_variables.txt | 0 .../{ => advanced}/Installation.txt | 58 +++--- .../doc/Documentation/advanced/advanced.txt | 8 + Documentation/doc/Documentation/main.txt | 32 ++-- 12 files changed, 225 insertions(+), 300 deletions(-) rename Documentation/doc/Documentation/{ => Developer_manual}/cmakelist_script.txt (88%) rename Documentation/doc/Documentation/{ => advanced}/Configuration_variables.txt (100%) rename Documentation/doc/Documentation/{ => advanced}/Installation.txt (93%) create mode 100644 Documentation/doc/Documentation/advanced/advanced.txt diff --git a/Documentation/doc/Documentation/cmakelist_script.txt b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt similarity index 88% rename from Documentation/doc/Documentation/cmakelist_script.txt rename to Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt index cfa5a0e52c3..47ca6a404c9 100644 --- a/Documentation/doc/Documentation/cmakelist_script.txt +++ b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt @@ -1,11 +1,12 @@ /*! -\page manual_create_cgal_CMakeLists Creating a CMake Script for a Program Using %CGAL +\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 `CGAL-\cgalReleaseNumber``/scripts` directory. +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 diff --git a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt index 7d96af6c9e6..2dbccf670fa 100644 --- a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt +++ b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt @@ -19,6 +19,6 @@ - \subpage devman_testing - \subpage devman_submission - \subpage devman_info +- \subpage devman_create_cgal_CMakeLists - \subpage deprecated - */ diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index a9ea3882e0b..c97361772d6 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -1,14 +1,12 @@ /*! \page general_intro Getting Started -- \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 usage describes how to use %CGAL. - \subpage thirdparty lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces. +- \subpage manual gives an idea 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. + */ diff --git a/Documentation/doc/Documentation/License.txt b/Documentation/doc/Documentation/License.txt index e6a966bd6cf..fddf4a1bd8f 100644 --- a/Documentation/doc/Documentation/License.txt +++ b/Documentation/doc/Documentation/License.txt @@ -1,5 +1,5 @@ /*! -\page cgallicensepage License +\page license License \cgalAutoToc \cgal is distributed under a dual license scheme, that is under the @@ -69,4 +69,36 @@ To enable checking, users have to define one of the following macros: 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: + +
    +
    `CGAL_VERSION_STR`
    +
    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
    +
    `CGAL_VERSION_NR`
    +
    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. +
    +
    `CGAL_VERSION_NUMBER(M,m,b)`
    +
    +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. +
    +
    + +The macro `CGAL_VERSION` is deprecated. It is the same as +`CGAL_VERSION_STR`, but not as a string literal. + */ diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index c56900ea3eb..f464d9314c1 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -77,19 +77,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, C++14. \section Preliminaries_functor Functor Return Types @@ -108,40 +99,6 @@ 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 of Chapter \ref Chapter_STL_Extensions_for_CGAL. -\section seccgal_version Identifying the Version of CGAL - -`` - -Every release of \cgal defines the following preprocessor macros: - -
    -
    `CGAL_VERSION_STR`
    -
    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
    -
    `CGAL_VERSION_NR`
    -
    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. -
    -
    `CGAL_VERSION_NUMBER(M,m,b)`
    -
    -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. -
    -
    - -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. diff --git a/Documentation/doc/Documentation/Third_party.txt b/Documentation/doc/Documentation/Third_party.txt index af75baa2d64..bbc0a312a6f 100644 --- a/Documentation/doc/Documentation/Third_party.txt +++ b/Documentation/doc/Documentation/Third_party.txt @@ -36,7 +36,7 @@ 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 can be used to learn which variables can be used to specify +The page \ref configurationvariables lists variables which can be used to specify the location of third-party software. \subsection thirdpartystl Standard Template Library (STL) diff --git a/Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt b/Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt index e90944007da..a3938229867 100644 --- a/Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt +++ b/Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt @@ -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 inexact +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 -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 +template T& std::min(const T& a, const T& b) { return (a `std::iterator_traits`     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 */ - diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt index 70d0bdaf26b..43794617ca6 100644 --- a/Documentation/doc/Documentation/Usage.txt +++ b/Documentation/doc/Documentation/Usage.txt @@ -21,7 +21,7 @@ Compiling your own program is similar: cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . make -The script `cgal_create_CMakeLists` and its options are detailed in Section \ref manual_create_cgal_CMakeLists. +The script `cgal_create_CMakeLists` and its options are detailed in Section \ref devman_create_cgal_CMakeLists. \cgalModifBegin Something about Windows? @@ -118,144 +118,74 @@ to configure, build, and install \cgal. Head over to \ref installation for more 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_cgal Configuring your Program +\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 configuration. 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. Configuring a program such as a \cgal example amounts to: +to build your program. + +CMake maintains configuration parameters in so-called cmake variables, like the `CMAKE_CXX_COMPILER` +in the example above. These variables are not environment variables but CMake variables. +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 -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release . -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 described in Section \ref manual_create_cgal_CMakeLists. For a user program -`executable.cpp`, this then ideally resumes to: +\subsection usage_configuring_cmake_gui Specifying Missing Dependencies + +This configuration might however fail if CMake fails to find all the required dependencies. +This might typically happen if you have installed dependencies at non-standard locations. +Although the command line tool `cmake` accepts CMake variables as arguments of the form +`-D:=`, 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 lines are gray, you are now ready to press 'Generate', +and to exit `cmake-gui` afterwards. + +\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 -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release . -Note that in both examples we have specified the `CGAL_DIR` variable, 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). +\subsection usage_configuring_advanced_cmake Advanced Configuration Options -\cgalModifBegin -TMP -Note that in both examples we have specified the `CGAL_DIR` variable: 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. -In order to configure a program, you need to indicate the location of this config file -in the CMake variable `CGAL_DIR` (as indicated in the example above). -`CGAL_DIR` can also be an environment variable. +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. -Setting `CGAL_DIR` makes particular sense if having multiple -out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. - -TMP 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. -\cgalModifEnd - -\subsection usage_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 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 usage_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 -generator. -A CMake generator understands the build requirements for a -particular compiler/linker and generates the necessary files for that. For -example, the UNIX Makefiles 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 Visual Studio -2010 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 NMakefiles 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 cmake variables, like the `CMAKE_CXX_COMPILER` -in the example above. These variables are not environment variables but CMake variables. 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:=`, 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 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. -\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. +In addition, the page \ref configurationvariables lists variables which can be used to specify +the location of third-party software while specifying depending in a command line run `cmake`. \section usage_building_program Building your Program diff --git a/Documentation/doc/Documentation/Configuration_variables.txt b/Documentation/doc/Documentation/advanced/Configuration_variables.txt similarity index 100% rename from Documentation/doc/Documentation/Configuration_variables.txt rename to Documentation/doc/Documentation/advanced/Configuration_variables.txt diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/advanced/Installation.txt similarity index 93% rename from Documentation/doc/Documentation/Installation.txt rename to Documentation/doc/Documentation/advanced/Installation.txt index 344ece43ff5..b0615888465 100644 --- a/Documentation/doc/Documentation/Installation.txt +++ b/Documentation/doc/Documentation/advanced/Installation.txt @@ -7,9 +7,9 @@ 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. 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 (enabled by default) header-only mode of \cgal. +in case you do not wish to use the (now enabled by default) header-only mode of \cgal. It is also possible to install \cgal using package managers on some operating systems, -see Section \ref sseccgalmacosxe. +see Section \ref secspecificinstall. \section installation_configwithcmake Configuring CGAL with CMake @@ -21,6 +21,22 @@ all this information is called configuration. 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 cmake variables, like the `CMAKE_CXX_COMPILER` +in the example above. These variables are not environment variables but CMake variables. 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 the compiler flags to use, +such as `CMAKE_CXX_FLAGS`. + +\subsection installation_buildtype Build Type + +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` as it is +default value in `CMake` and if you do not plan on debugging, it is important to set the variable +to `Release` for performance reasons. + +This is not an issue for solution/project files, since the user selects the build type +from within the IDE in this environment. + \subsection seclibraries CGAL Libraries \cgal is split into four libraries. During configuration, you can select the libraries that @@ -57,16 +73,6 @@ If you do not plan to compile any demos, you may skip some of the dependencies ( as the corresponding \cgal-libraries will not be used. Note, however, that your own demos might need these \cgal-libraries and thus their dependencies. -\subsection installation_cmakevariables CMake Variables - -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` as it is -default value in `CMake` and if you do not plan on debugging, it is important to set the variable -to `Release` for performance reasons. - -This is not an issue for solution/project files, since the user selects the build type -from within the IDE in this environment. - \subsection installation_configuring_gui Configuring CGAL with the CMake GUI The simplest way to start the configuration is to run the graphical @@ -91,10 +97,6 @@ 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: @@ -140,12 +142,6 @@ specify the desired compiler in the call to CMake, as in this example: cd CGAL-\cgalReleaseNumber cmake -DCMAKE_CXX_COMPILER:FILEPATH=g++-9.2 . -CMake maintains configuration parameters in so-called cmake variables, like the `CMAKE_CXX_COMPILER` -in the example above. These variables are not environment variables but CMake variables. 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:=`, as in the example above, but this is only useful if you already know which variables need to be explicitly defined. @@ -162,6 +158,22 @@ The configuration process not only determines the location of the required depen `CGALConfig.cmake`, which is used to build programs using \cgal. The purpose of this file is explained below. +\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. +In order to configure a program, you need to indicate the location of this 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`. + \section secbuilding Building CGAL The results of a successful configuration are build files that control the build step. @@ -287,7 +299,7 @@ You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/p cd CGAL-\cgalReleaseNumber/cmake/platforms/release cmake -DCMAKE_BUILD_TYPE=Release ../../.. -\section secshippedcgal OS Specific Installation +\section secspecificinstall OS Specific Installation Some operating systems with package managers offer \cgal and its essential third party software through the manager, diff --git a/Documentation/doc/Documentation/advanced/advanced.txt b/Documentation/doc/Documentation/advanced/advanced.txt new file mode 100644 index 00000000000..f93f7c2b25a --- /dev/null +++ b/Documentation/doc/Documentation/advanced/advanced.txt @@ -0,0 +1,8 @@ +/*! + +\page advanced Advanced + +- \subpage configurationvariables +- \subpage installation + +*/ diff --git a/Documentation/doc/Documentation/main.txt b/Documentation/doc/Documentation/main.txt index 761b8505a75..8b0ec46a568 100644 --- a/Documentation/doc/Documentation/main.txt +++ b/Documentation/doc/Documentation/main.txt @@ -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,15 @@ 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. +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. + +Head over to the page \ref general_intro, which will guide your first steps with \cgal. License ======= @@ -35,7 +38,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 cgallicensepage "License" page. +see the \ref license "License" page. Manuals for the Previous Releases ================================= @@ -52,6 +55,7 @@ For releases X.Y, with 3.1 <= X.Y <= 4.1 visit \endhtmlonly \subpage general_intro +\subpage advanced \subpage tutorials \subpage packages \subpage dev_manual From 3b5de6fe78b253f24090ffa0f7ebd692d2e6b45d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Mon, 23 Sep 2019 12:42:37 +0200 Subject: [PATCH 8/8] More re-organization of /Documentation --- .../Developer_manual/developer_manual.txt | 2 + .../doc/Documentation/Getting_started.txt | 4 +- .../doc/Documentation/Preliminaries.txt | 51 +---- .../doc/Documentation/Third_party.txt | 114 +++++++---- Documentation/doc/Documentation/Usage.txt | 24 +-- .../advanced/Configuration_variables.txt | 8 +- .../Documentation/advanced/Installation.txt | 181 ++++++++++-------- .../doc/Documentation/advanced/advanced.txt | 4 +- Documentation/doc/Documentation/main.txt | 3 +- Documentation/doc/Documentation/manual.txt | 57 +++++- README.md | 15 +- 11 files changed, 260 insertions(+), 203 deletions(-) diff --git a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt index 2dbccf670fa..b229577bbbc 100644 --- a/Documentation/doc/Documentation/Developer_manual/developer_manual.txt +++ b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt @@ -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 diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index c97361772d6..9c31836b258 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -1,7 +1,7 @@ /*! -\page general_intro Getting Started +\page general_intro Getting Started with %CGAL -- \subpage usage describes how to use %CGAL. +- \subpage usage describes the few steps required to build a program using %CGAL. - \subpage thirdparty lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces. diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index f464d9314c1..9f23bbda960 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -1,53 +1,12 @@ /*! -\page preliminaries Preliminaries +\page preliminaries General Information \cgalAutoToc -The chapter further explains how to control inlining, thread safety, -code deprecation, checking of pre- and postconditions, -and how to alter the failure behavior. +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. -\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 @@ -80,7 +39,7 @@ definition by setting `CGAL_HAS_NO_THREADS` from the command line. \section Preliminaries_cc0x C++14 Support 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, C++14. +\cgal is now based on a newer major version of the standard, C++14. \section Preliminaries_functor Functor Return Types diff --git a/Documentation/doc/Documentation/Third_party.txt b/Documentation/doc/Documentation/Third_party.txt index bbc0a312a6f..27a3b4301e9 100644 --- a/Documentation/doc/Documentation/Third_party.txt +++ b/Documentation/doc/Documentation/Third_party.txt @@ -21,10 +21,11 @@ supporting C++14 or later. Older versions of the above listed compilers might work, but no guarantee is provided. \section seccmake CMake +Version 3.1 or later In order to configure and build the \cgal examples, demos, or libraries, you need CMake, a cross-platform "makefile generator". -CMake version 3.1 or higher is required. + This manual explains only the features of CMake which are needed in order to build \cgal. Please refer to the CMake documentation @@ -36,8 +37,8 @@ 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 variables which can be used to specify -the location of third-party software. +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) @@ -49,6 +50,7 @@ or `h The \stl comes with the compiler, and as such no installation is required. \subsection thirdpartyBoost Boost +Version 1.48 or later 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 @@ -56,7 +58,6 @@ 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 @@ -71,34 +72,36 @@ 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 GMP and MPFR +\subsection thirdpartyMPFR GNU Multiple Precision Arithmetic (GMP) and GNU Multiple Precision Floating-Point Reliably (MPFR) Libraries +GMP Version 4.2 or later, MPFR Version 2.2.1 or later 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, +\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 -`https://gmplib.org/` and `https://www.mpfr.org/`, 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 +These libraries can be obtained from `https://gmplib.org/` +and `https://www.mpfr.org/`. +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 `CGAL-\cgalReleaseNumber``-Setup.exe`. \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. +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 +Version 5.9.0 or later Qt is a cross-platform application and UI framework. @@ -109,11 +112,23 @@ it from `https://www.qt-project.org/`. 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`. +`qcollectiongenerator` (with `sqlite` driver plugin), and `Xml`. -\sc{Qt} version 5.9.0 or later is required. +\subsection thirdpartyEigen Eigen +Version 3.1 or later + +\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 +Package Overview page. + +The \sc{Eigen} web site is `http://eigen.tuxfamily.org`. \subsection thirdpartyLeda LEDA +Version 6.2 or later \leda is a library of efficient data structures and algorithms. Like \sc{Core}, \leda offers a real number data type. @@ -123,23 +138,24 @@ be used as an alternative to \sc{Gmp}, \sc{Mpfr}, and \sc{Core}. Free and commercial editions of \leda are available from `https://www.algorithmic-solutions.com`. -\subsection thirdpartyMPFI MPFI +\subsection thirdpartyMPFI Multiple Precision Floating-point Interval (MPFI) +Version 1.4 or later \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". +\ref PkgAlgebraicKernelD "Algebraic Kernel". -\sc{Mpfi} can be downloaded from `https://mpfi.gforge.inria.fr/`. Version 1.4 or higher is recommended. +\sc{Mpfi} can be downloaded from `https://mpfi.gforge.inria.fr/`. \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". +\ref PkgAlgebraicKernelD "Algebraic Kernel". \sc{Rs} is freely distributable for non-commercial use. You can download it from `http://vegas.loria.fr/rs/`. Actually, the \sc{Rs} package also includes \sc{Rs3}, the @@ -149,34 +165,21 @@ The libraries \sc{Rs} and \sc{Rs3} need \sc{Mpfi}, which can be downloaded from `https://mpfi.gforge.inria.fr/`. \subsection thirdpartyNTL NTL +Version 5.1 or later \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 `https://www.shoup.net/ntl/`. 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 `http://eigen.tuxfamily.org`. +\sc{Ntl} can be downloaded from `https://www.shoup.net/ntl/`. \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. +In \cgal the \sc{Esbtl} is used in an example of the \ref PkgSkinSurface3 package. It can be downloaded from `http://esbtl.sourceforge.net/`. @@ -195,7 +198,7 @@ The \sc{Tbb} web site is `http 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 \ref PkgPointSetProcessing3 package. The \sc{LASlib} web site is `https://rapidlasso.com/lastools/`. \sc{LASlib} @@ -208,7 +211,7 @@ CMake based install procedure. \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. +In \cgal, \sc{OpenCV} is used by the \ref PkgClassification package. The \sc{OpenCV} web site is `https://opencv.org/`. @@ -217,7 +220,7 @@ The \sc{OpenCV} web site is `https://opencv.org/`< \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 +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: @@ -229,6 +232,7 @@ enable and compile the following targets: The \sc{TensorFlow} web site is `https://www.tensorflow.org/`. \subsection thirdpartyMETIS METIS +Version 5.1 or later \sc{METIS} is a library developed by the Karypis Lab and designed to partition graphs and produce fill-reducing matrix orderings. @@ -245,9 +249,35 @@ at `http://glaro \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. +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 `https://www.zlib.net/`. +\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 `ceres-solver.org` +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 `https://www.gnu.org/software/glpk/`. + +\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 `http://scip.zib.de/`. + */ diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt index 43794617ca6..7ba365705b4 100644 --- a/Documentation/doc/Documentation/Usage.txt +++ b/Documentation/doc/Documentation/Usage.txt @@ -2,9 +2,9 @@ \page usage Usage \cgalAutoToc -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, some dependencies of \cgal might still need to be installed. +Since \cgal version 5.0, \cgal is header-only be default, which means +that there is no need to build or install \cgal before it can be used. +However, some dependencies of \cgal might still need to be installed. \section usage_introduction Quick Start @@ -12,7 +12,7 @@ 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 + make # build all Triangulation_2 examples Compiling your own program is similar: @@ -27,7 +27,7 @@ The script `cgal_create_CMakeLists` and its options are detailed in Section \ref Something about Windows? \cgalModifEnd -In a less ideal world, you might have to install the required tools and third party libraries. +In a less ideal world, you might have to install some required tools and third-party libraries. This is what this page is about. \section secprerequisites Prerequisites @@ -54,7 +54,7 @@ command: tar xzf CGAL-\cgalReleaseNumber.tar.gz -In both cases the directory `CGAL-\cgalReleaseNumber` will be created. This directory +In both cases, the directory `CGAL-\cgalReleaseNumber` will be created. This directory contains the following subdirectories: | Directory | Contents | @@ -144,8 +144,9 @@ if no debugging is intended. Users should thus run: \subsection usage_configuring_cmake_gui Specifying Missing Dependencies -This configuration might however fail if CMake fails to find all the required dependencies. -This might typically happen if you have installed dependencies at non-standard locations. +The configuration process launched above might however fail if CMake fails to find +all the required dependencies. This might typically happen if you have installed dependencies +at non-standard locations. Although the command line tool `cmake` accepts CMake variables as arguments of the form `-D:=`, 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 @@ -165,6 +166,10 @@ If red entries are still present, you must provide the necessary information (pa When all entries have been appropriately filled and lines are gray, you are now ready to press 'Generate', and to exit `cmake-gui` afterwards. +Note that 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. + \subsection usage_configuring_external Configuring an External Program Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. This file is automatically provided @@ -184,9 +189,6 @@ CMake keeps the variables that a user can manipulate in a so-called CMake cache, 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. -In addition, the page \ref configurationvariables lists variables which can be used to specify -the location of third-party software while specifying depending in a command line run `cmake`. - \section usage_building_program Building your Program The results of a successful configuration are build files that control the build step. diff --git a/Documentation/doc/Documentation/advanced/Configuration_variables.txt b/Documentation/doc/Documentation/advanced/Configuration_variables.txt index eec18702b94..343a513afb2 100644 --- a/Documentation/doc/Documentation/advanced/Configuration_variables.txt +++ b/Documentation/doc/Documentation/advanced/Configuration_variables.txt @@ -62,13 +62,17 @@ defined by cmake. \subsection installation_misc Miscellaneous Variables +Note that the default build type is `Debug`, 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 | Release | +| `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) diff --git a/Documentation/doc/Documentation/advanced/Installation.txt b/Documentation/doc/Documentation/advanced/Installation.txt index b0615888465..e219fb92540 100644 --- a/Documentation/doc/Documentation/advanced/Installation.txt +++ b/Documentation/doc/Documentation/advanced/Installation.txt @@ -6,14 +6,14 @@ 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. -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. +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_configwithcmake Configuring CGAL with CMake -Before building anything using \cgal you have to choose the compiler/linker, +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 @@ -21,31 +21,22 @@ all this information is called configuration. 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 cmake variables, like the `CMAKE_CXX_COMPILER` -in the example above. These variables are not environment variables but CMake variables. Some of the CMake +CMake maintains configuration parameters in so-called cmake variables. 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 the compiler flags to use, +indicate the details of a third-party library, such as `Boost_INCLUDE_DIR` or which compiler flags to use, such as `CMAKE_CXX_FLAGS`. -\subsection installation_buildtype Build Type - -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` as it is -default value in `CMake` and if you do not plan on debugging, it is important to set the variable -to `Release` for performance reasons. - -This is not an issue for solution/project files, since the user selects the build type -from within the IDE in this environment. +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 WITH_. By default all -are switched `ON`. All activated libraries are build after -configuration; see \ref secbuilding. +are switched `ON`. All activated libraries are to be built after configuration. -We next list the libraries and essential 3rd party software -(see \ref secessential3rdpartysoftware) for each library: +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 | | :-------- | :------------- | :------------ | :----------- | @@ -54,13 +45,10 @@ We next list the libraries and essential 3rd party software | `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 | -\subsubsection installation_static Static vs. Shared Libraries - Shared libraries, also called dynamic-link libraries, 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`. If you use -`cmake-gui`, a tick box for that variable is available to set it. +can choose to produce static libraries instead, by setting the CMake +variable `BUILD_SHARED_LIBS` to `FALSE`. \subsection installation_examples CGAL Examples and Demos @@ -71,12 +59,53 @@ 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. +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: +
      +
    • `CMAKE_INSTALL_PREFIX=` installation directory [/usr/local]
      • +
    • `CMAKE_BUILD_TYPE=` build type [Release]
      • +
    • `BUILD_SHARED_LIBS=` shared or static libraries [TRUE]
      • +
    • `CMAKE_C_COMPILER=` C compiler [gcc]
      • +
    • `CMAKE_CXX_COMPILER=` C++ compiler [g++]
      • +
    + +In case you want to add additional compiler and linker flags, you can use +
      +
    • `CGAL_CXX_FLAGS` additional compiler flags
      • +
    • `CGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries)
      • +
    • `CGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries)
      • +
    • `CGAL_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. + +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 is to run the graphical -user interface of CMake. We recommend to use `cmake-gui`. You must pass as +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 @@ -91,60 +120,24 @@ red entries in the upper portion of the application. Just ignore them and press 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. + +If you use `cmake-gui`, a tick box for that variable is available to set it. + 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. For example: +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:=`, 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 very first thing CMake does is to detect the compiler to use. This -detection is performed by a special CMake module called a -generator. -A CMake generator understands the build requirements for a -particular compiler/linker and generates the necessary files for that. For -example, the UNIX Makefiles 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 Visual Studio -2010 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 NMakefiles 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++-9.2 . - -The command line tool `cmake` accepts CMake variables as arguments of the form `-D:=`, 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 CMake cache, a simple text file named @@ -163,16 +156,8 @@ purpose of this file is explained below. 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. -In order to configure a program, you need to indicate the location of this 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`. +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 secbuilding Building CGAL @@ -243,7 +228,7 @@ typing `make help | grep `. 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 +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 Installation and it is a @@ -265,13 +250,41 @@ If you use a generator that produces IDE files (for Visual Studio for instance) \cgalAdvancedBegin The files are copied into a directory tree relative to the installation directory 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 +and `C:\Program Files` under Windows. If you want to install to a different location, you must override that CMake variable explicitly at the configuration time 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 . + +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. + +Once you have successfully configured (either through `cmake` or `cmake-gui`), you are now ready +to build your program. + \section seccmakeoutofsource Multiple Variants of Makefiles (out-of-source build) While you can choose between release or debug builds, and shared or static libraries, @@ -303,7 +316,7 @@ You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/p 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 instance, Mac OS X or some Linux distribution (e.g. Debian). For Windows, an installer is provided. \subsection sseccgalmacosxe CGAL on macOS diff --git a/Documentation/doc/Documentation/advanced/advanced.txt b/Documentation/doc/Documentation/advanced/advanced.txt index f93f7c2b25a..b6136edda22 100644 --- a/Documentation/doc/Documentation/advanced/advanced.txt +++ b/Documentation/doc/Documentation/advanced/advanced.txt @@ -2,7 +2,7 @@ \page advanced Advanced -- \subpage configurationvariables -- \subpage installation +- \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. */ diff --git a/Documentation/doc/Documentation/main.txt b/Documentation/doc/Documentation/main.txt index 8b0ec46a568..7679f65c4f9 100644 --- a/Documentation/doc/Documentation/main.txt +++ b/Documentation/doc/Documentation/main.txt @@ -48,8 +48,6 @@ 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]
    \endhtmlonly @@ -59,6 +57,7 @@ For releases X.Y, with 3.1 <= X.Y <= 4.1 visit \subpage tutorials \subpage packages \subpage dev_manual +\subpage license \htmlonly[block]
    diff --git a/Documentation/doc/Documentation/manual.txt b/Documentation/doc/Documentation/manual.txt index dbada72f28d..33354eecf6d 100644 --- a/Documentation/doc/Documentation/manual.txt +++ b/Documentation/doc/Documentation/manual.txt @@ -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 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. + +*/ diff --git a/README.md b/README.md index 95dffac80e6..024922dc3c4 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,18 @@ 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). + +Header-only +=========== + +Since version 5.0, CGAL is header-only by default, which means +that there is **no need to build or install \cgal before it can be used**. + +Getting started with CGAL +========================= + +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. CGAL Git repository layout ========================== @@ -32,6 +42,7 @@ or `Triangulation_3`); however some packages serve special needs: 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)