diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt index 84a7d8078b46..16ef913c4086 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/Developer_manual/cmakelist_script.txt b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt new file mode 100644 index 000000000000..47ca6a404c9c --- /dev/null +++ b/Documentation/doc/Documentation/Developer_manual/cmakelist_script.txt @@ -0,0 +1,40 @@ +/*! + +\page devman_create_cgal_CMakeLists Creating a CMake Script for a Program Using %CGAL + +To compile a program that is not shipped with \cgal, it is recommended to also rely on a CMake-supported +configuration using a `CMakeLists.txt`. The Bourne-shell script `cgal_create_CMakeLists.txt` +can be used to create such `CMakeLists.txt` files. +This script resides in the `scripts` directory of \cgal (e.g. `CGAL-\cgalReleaseNumber``/scripts` +directory if you have downloaded a tarball). +Executing `cgal_create_CMakeLists.txt` in an application directory creates a +`CMakeLists.txt` containing rules to build the contained +application(s). Three command line options determine details of the +configuration. + +
+
`-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/Developer_manual/developer_manual.txt b/Documentation/doc/Documentation/Developer_manual/developer_manual.txt index 7d96af6c9e66..b229577bbbc1 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 @@ -19,6 +21,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 d8dcfa659f29..01452b571247 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -1,13 +1,30 @@ /*! -\page general_intro Getting Started +\page general_intro Getting Started with %CGAL -- \subpage installation describes how to install %CGAL, and lists the third party libraries on which %CGAL depends, or for which %CGAL provides interfaces. +The following pages describe how to use \cgal on different environments -- \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 usage -- \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 windows + +- \subpage thirdparty gives information (supported versions, download links) of the required and optional third party libraries. + +The following pages cover advanced installation options + +- \subpage configurationvariables gives information about which CMake variables can be used to help +resolve missing dependencies while using the cmake command line tool. + +- \subpage installation describes the deprecated process of configuring and building \cgal. + +The following pages cover the structure of the manual and general information about \cgal + +- \subpage manual gives an idea of where you should look for documentation. + +- \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking +of pre- and postconditions, and how to alter the failure behavior. + +Once you are familiar with building your programs with \cgal and how the documentation is structured, +you can head over to the \ref tutorials for a gentle introduction to \cgal, or directly to the package(s) +that interest you the \ref packages. Each package contains simple examples of the various functionalities of the package. */ diff --git a/Documentation/doc/Documentation/Installation.txt b/Documentation/doc/Documentation/Installation.txt deleted file mode 100644 index 541befc0636b..000000000000 --- a/Documentation/doc/Documentation/Installation.txt +++ /dev/null @@ -1,1198 +0,0 @@ -/*! -\page installation Installation -\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 -that there is no need to compile and install anything before it can be -used. The dependencies of \cgal still have to be installed. - -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 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. - -\attention Recent versions of CMake are needed for recent versions of MS Visual C++. Please refer to CMake's documentation for further information. - - -\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 -are switched `ON`. All activated libraries are build after -configuration; see \ref secbuilding - -We next list the libraries and essential 3rd party software -(see \ref secessential3rdpartysoftware) for each library: - -| Library | CMake Variable | Functionality | Dependencies | -| :-------- | :------------- | :------------ | :----------- | -| `%CGAL` | none | Main library | \sc{Gmp}, \sc{Mpfr}, \sc{Boost} (headers) | -| `CGAL_Core` | `WITH_CGAL_Core` | The CORE library for algebraic numbers.\cgalFootnote{CGAL_Core is not part of \cgal, but a custom version of the \sc{Core} library distributed by \cgal for the user convenience and it has it's own license.} | \sc{Gmp} and \sc{Mpfr} | -| `CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | \sc{zlib}, \sc{Vtk}(optional) | -| `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 | - -\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 - -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. - -\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 -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. -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}), -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`. - -\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/`. - -\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 -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 
-
-
- -The resulting libraries are placed in the subdirectory `lib` under `` -(which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration). - -With generators other than `UNIX Makefiles` the resulting build files -are solution and project files which -should be launched in an \sc{Ide}, such as Visual Studio or KDevelop3. They will contain the targets described -above, which you can manually build as with any other solution/project within your \sc{Ide}. - -Alternatively, you can build it with the command line version of the -\sc{Visual Studio Ide}: - -
-
-devenv CGAL.sln /Build Debug
-
-
- -The "Debug" argument is needed because CMake creates solution files for -all four configurations, and you need to explicitly choose one when building -(the other choices are Release, RelWithDebInfo and MinSizeRel). - -\cgalAdvancedBegin -The build files produced by CMake are autoconfigured. That -is, if you change any of the dependencies, the build step -automatically goes all the way back to the configuration step. This -way, once the target has been configured the very first time by -invoking cmake, you don't necessarily need to invoke `cmake` -again. Rebuilding will call itself `cmake` and re-generate the -build file whenever needed. Keep this in mind if you configure \cgal -for the Visual Studio IDE since a build could then change the -solution/project file in-place and VS will prompt you to reload it. -\cgalAdvancedEnd - -If you have turned on the configuration of examples -(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional -targets named `examples` and `demos`, plus one target for -each example and each demo in the build files. -None of these targets are included by default, so you need to build them explicitly -after the \cgal libraries have been successfully built. -The targets `examples` and `demos` include themselves all the targets -for examples and demos respectively. - -
-
-# build all examples at once
-make examples 
-
-# build all demos at once
-make demos
-
-
- -\cgalAdvancedBegin -When using `UNIX Makefiles` you can find out the -exact name of the example or demo target of a particular package by -typing `make help | grep `. -\cgalAdvancedEnd - -\section secinstalling Installing CGAL - -On many platforms, library pieces such as headers, docs and binaries -are expected to be placed in specific locations. A typical example -being `/usr/include` and `/usr/lib` on \sc{Unix}-like -operating systems or `C:/Program Files/` on Windows. The process -of placing or copying the library elements into its standard location -is sometimes referred to as Installation and it is a -postprocessing step after the build step. - -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
-
-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 -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. -\cgalAdvancedEnd - -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 installation_configuring_using Configuring and Building Programs Using CGAL - -Ideally, configuring and compiling a demo/example/program amounts to - -
-
-cd CGAL-\cgalReleaseNumber/examples/Triangulation_2
-cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber .
-make
-
-
- -In this ideal world, as for all shipped examples and demos of \cgal, the -required `CMakeLists.txt` is already provided. - -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/License.txt b/Documentation/doc/Documentation/License.txt new file mode 100644 index 000000000000..fddf4a1bd8f5 --- /dev/null +++ b/Documentation/doc/Documentation/License.txt @@ -0,0 +1,104 @@ +/*! +\page license License +\cgalAutoToc + +\cgal is distributed under a dual license scheme, that is under the +\sc{Gpl}/\sc{Lgpl} open source license, as well as under commercial licenses. + +\cgal consists of different parts covered by different open source licenses. +In this section we explain the essence of the different licenses, as well as +the rationale why we have chosen them. + +The fact that \cgal is Open Source software does not mean that users are free +to do whatever they want with the software. Using the software means to accept +the license, which has the status of a contract between the user and the owner +of the \cgal software. + +\section licensesGPL GPL + +The \sc{Gpl} is an Open Source license that, if you distribute your software +based on \sc{Gpl}ed \cgal data structures, obliges you to distribute the +source code of your software under the \sc{Gpl}. + +The exact license terms can be found at the Free Software Foundation +web site: http://www.gnu.org/copyleft/gpl.html. + +\section licensesLGPL LGPL + +The \sc{Lgpl} is an Open Source license that obliges you to distribute +modifications you make on \cgal software accessible to the users. +In contrast to the \sc{Gpl}, there is no obligation to make the source +code of software you build on top of \sc{Lgpl}ed \cgal data structures. + +The exact license terms can be found at the Free Software Foundation web site: +http://www.gnu.org/copyleft/lesser.html. + +\section licensesRationale Rationale of the License Choice + +We have chosen the \sc{Gpl} and the \sc{Lgpl} as they are well-known +and well-understood open source licenses. The former restricts +commercial use, and the latter allows to promote software as de facto standard +so that people can build new higher level data structures on top. + +Therefore, the packages forming a foundation layer are distributed under +the \sc{Lgpl}, and the higher level packages under the \sc{Gpl}. +The package overview states for each package under which license it is distributed. + +\section licensesCommercial Commercial Licenses + +Users who cannot comply with the Open Source license terms can buy individual +data structures under various commercial licenses from GeometryFactory: +http://www.geometryfactory.com/. License fees paid by commercial +customers are reinvested in R\&D performed by the \cgal project partners, +as well as in evolutive maintenance. + +\section licenseCheck License Checking + +Users who have a commercial license for specific packages can check that +they do not accidentally use packages for which they do not have a commercial +license. The same holds for users who want to be sure that they only +use packages of \cgal released under the \sc{Lgpl}. + +To enable checking, users have to define one of the following macros: + +| Macro Name | Effect | +| :--------- | :------ | +| `CGAL_LICENSE_WARNING` | get a warning during the compilation | +| `CGAL_LICENSE_ERROR` | get an error during the compilation | + +The license checking is not a mean to control users as no information +is collected or transmitted. + +\section seccgal_version Identifying the Version of CGAL + +Every release of \cgal defines the following preprocessor macros: + +
+
`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 6d03fb0d21d5..9f23bbda960f 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -1,130 +1,12 @@ /*! -\page preliminaries Preliminaries +\page preliminaries General Information \cgalAutoToc -\author %CGAL Editorial Board -This chapter lists the licenses -under which the \cgal datastructures and algorithms are distributed. -The chapter further explains how to control inlining, thread safety, -code deprecation, checking of pre- and postconditions, -and how to alter the failure behavior. +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 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 -relatively low-level, or requires special care to be properly used. - -\cgalAdvancedBegin -Such functionality is identified this way in the manual. -\cgalAdvancedEnd - -\subsection debugging_support Debugging Support Features - -Usually related to advanced features that for example may not guarantee -class invariants, some functionality is provided that helps debugging, -for example by performing invariants checks on demand. - -\cgalDebugBegin -Such functionality is identified this way in the manual. -\cgalDebugEnd - -\subsection deprecated_code Deprecated Code - -Sometimes, the \cgal project decides that a feature is deprecated. This means -that it still works in the current release, but it will be removed in the next, -or a subsequent release. This can happen when we have found a better way to do -something, and we would like to reduce the maintenance cost of \cgal at some -point in the future. There is a trade-off between maintaining backward -compatibility and implementing new features more easily. - -In order to help users manage the changes to apply to their code, we attempt -to make \cgal code emit warnings when deprecated code is used. This can be -done using some compiler specific features. Those warnings can be disabled -by defining the macro `CGAL_NO_DEPRECATION_WARNINGS`. On top of this, we -also provide a macro, `CGAL_NO_DEPRECATED_CODE`, which, when defined, -disables all deprecated features. This allows users to easily test if their -code relies on deprecated features. - -\deprecated Such functionality is identified this way in the manual. +These concepts are further developed in the \ref dev_manual. \section Preliminaries_namespace Namespace CGAL @@ -154,19 +36,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 @@ -182,43 +55,9 @@ return type of calling the functor with an argument of type Much of the \cgal code contains assert statements for preconditions, and postconditions of functions as well as in the code. These assertions can be switched on and off per package -and the user can change the error behaviour. For details see Section \ref secchecks +and the user can change the error behaviour. For details see Section \ref secchecks of Chapter \ref Chapter_STL_Extensions_for_CGAL. -\section seccgal_version Identifying the Version of CGAL - -`` - -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 new file mode 100644 index 000000000000..e0220b92691c --- /dev/null +++ b/Documentation/doc/Documentation/Third_party.txt @@ -0,0 +1,289 @@ +/*! + +\page thirdparty Essential and Optional Third Party Dependencies +\cgalAutoToc + +\section seccompilers Supported Compilers + +In order to build a program using \cgal, you need a \cpp compiler +supporting C++14 or later. +\cgal \cgalReleaseNumber is supported (continuously tested) for the following compilers/operating systems: + +| Operating System | Compiler | +| :------- | :--------------- | +| Linux | \sc{Gnu} `g++` 6.3 or later\cgalFootnote{`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 | + + + +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". + +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. + +\attention Recent versions of CMake are needed for the most recent versions of MS Visual C++. +Please refer to CMake's documentation for further information, for example +here +for Visual Studio 16 2019. + +\section secessential3rdpartysoftware Essential Third Party Libraries + +The focus of \cgal is on geometry, and we rely on other +highly specialized libraries and software for non-geometric issues, +for instance for numeric solvers or visualization. We first list software +that is essential to most of \cgal, and must therefore be found during the configuration of \cgal. +The page \ref configurationvariables lists CMake and environment variables which can be used to specify +the location of third-party software during configuration. + +\subsection thirdpartystl Standard Template Library (STL) + +\cgal heavily uses the \stl, and in particular adopted many of its design ideas. You can find online +documentation for the \stl at various web sites, for instance, +`https://en.cppreference.com `, +or `https://msdn.microsoft.com`. + +The \stl comes with the compiler, and as such no installation is required. + +\subsection thirdpartyBoost Boost +Version 1.57 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 +installed as binaries. + +\cgal only requires the headers of the \sc{Boost} libraries, but some demos and examples +depend on the binary library `Boost.Program_options`. +As an exception and because of a bug in the \gcc compiler about the \cpp 11 +keyword `thread_local`, the `CGAL_Core` library always requires +the binary library `Boost.Thread` if the \gcc compiler version 9.0 or +earlier is used. + +In case the \sc{Boost} libraries are not installed on your system already, you +can obtain them from `https://www.boost.org/`. +For Visual C++ you can download precompiled libraries +from `https://sourceforge.net/projects/boost/files/boost-binaries/`. + +As there is no canonical directory for where to find \sc{Boost} on Windows, +we recommend that you define the environment variable +`BOOST_ROOT` and set it to where you have installed \sc{Boost}, e.g., `C:\boost\boost_1_69_0`. + +\subsection thirdpartyMPFR GNU Multiple Precision Arithmetic (GMP) and GNU Multiple Precision Floating-Point Reliably (MPFR) Libraries +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 +in order to be efficient and reliable. \cgal has a built-in +number type for that, but \sc{Gmp} and \sc{Mpfr} provide a faster +solution, and we recommend to use them. + +These libraries can be obtained from `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: +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. + +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/`. + +The exhaustive list of \sc{Qt}5 components used in demos is: +`Core`, `Gui`, `Help`, `OpenGL`, `Script`, `ScriptTools`, `Svg`, `Widgets`, +`qcollectiongenerator` (with `sqlite` driver plugin), and `Xml`. + +\subsection thirdpartyEigen Eigen +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. + +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 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 PkgAlgebraicKernelD "Algebraic Kernel". + +\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 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 +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 +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/`. + +\subsection thirdpartyESBTL ESBTL + +The \sc{Esbtl} (Easy Structural Biology Template Library) is a library that allows +the handling of \sc{Pdb} data. + +In \cgal, the \sc{Esbtl} is used in an example of the \ref PkgSkinSurface3 package. + +It can be downloaded from `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 PkgPointSetProcessing3 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 PkgClassification 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 +PkgClassification package for neural network. The C++ API can be +compiled using CMake: it is distributed as part of the official +package and is located in `tensorflow/contrib/cmake`. Be sure to +enable and compile the following targets: + +- `tensorflow_BUILD_ALL_KERNELS` +- `tensorflow_BUILD_PYTHON_BINDINGS` +- `tensorflow_BUILD_SHARED_LIB`. + +The \sc{TensorFlow} web site is `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. + +\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`. + +\subsection thirdpartyzlib zlib + +\sc{zlib} is a data compression library, and is essential for the component libCGAL_ImageIO. + +In \cgal, this library is used in the examples of the \ref PkgSurfaceMesher3 package. + +If it is not already on your system, +for instance, on Windows, you can download it from `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/Tutorials/Tutorial_hello_world.txt b/Documentation/doc/Documentation/Tutorials/Tutorial_hello_world.txt index e90944007da1..f90dbe3d5b5b 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 -Kernel provides what is required by the concept ConvexHullTraits_2". +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/Tutorials/Tutorials.txt b/Documentation/doc/Documentation/Tutorials/Tutorials.txt index ac3dd2c9197a..aab618e954f1 100644 --- a/Documentation/doc/Documentation/Tutorials/Tutorials.txt +++ b/Documentation/doc/Documentation/Tutorials/Tutorials.txt @@ -8,9 +8,7 @@ combined to achieve extensive and complex geometric tasks. The tutorials aim at providing help and ideas on how to use CGAL beyond the simple examples of the User Manual. - - -\section tuto_list List of available tutorials +\section tuto_list List of Available Tutorials - \subpage tutorial_hello_world presents you some short example programs to get a first idea for the look and feel of a program that @@ -19,4 +17,9 @@ User Manual. define what primitives are used by a geometric algorithm, the notions of \em concept and \em model. +\section tuto_examples Package Examples + +Each \cgal package comes with a set of commented examples that illustrate basic features of the package. +See for example Section \ref Triangulation3secexamples of the User Manual of the package \ref PkgTriangulation3. + */ diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt new file mode 100644 index 000000000000..30b3627f683a --- /dev/null +++ b/Documentation/doc/Documentation/Usage.txt @@ -0,0 +1,240 @@ +/*! +\page usage Using %CGAL on Unix (Linux, macOS, ...) +\cgalAutoToc + +Since \cgal version 5.0, \cgal is header-only be default, which means +that there is no need to build \cgal before it can be used. +However, some dependencies of \cgal might still need to be installed. + +\section usage_introduction Quick Start: Compiling a Program using CGAL + +Assuming that you have obtained \cgal through one of the package managers offering \cgal on your platform +(see Section \ref secgettingcgal), you can download \cgal examples ( +CGAL-\cgalReleaseNumber-examples.tar.xz) +and the compilation of an example is as simple as: + + cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory + cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples + make # build the examples + +Compiling your own program is similar: + + cd /path/to/your/program + path/to/cgal/Scripts/scripts/cgal_create_CMakeLists -s your_program + cmake -DCMAKE_BUILD_TYPE=Release . + make + +The script `cgal_create_CMakeLists` and its options are detailed in Section \ref devman_create_cgal_CMakeLists. + +In a less ideal world, you might have to install some required tools and third-party libraries. +This is what this page is about. + +\section secprerequisites Prerequisites + +Using \cgal requires a few core components to be previously installed: +
    +
  • a supported compiler (see Section \ref seccompilers),
    • +
  • \ref seccmake,
    • +
  • \ref thirdpartyBoost,
    • +
  • \ref thirdpartyMPFR.
    • +
+ +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 + +\cgal can be obtained through different channels. We recommend using a package manager as +this will ensure that all essential third party dependencies are present, and with the correct versions. +You may also download the sources of \cgal directly, but it is then your responsability to independently +acquire these dependencies. + +The examples and demos of \cgal are not included when you install \cgal with a package manager, +and must be downloaded +here. + +\subsection secusingpkgman Using a Package Manager + +On most operating systems, package managers offer \cgal and its essential third party dependencies. + +On macOS, we recommend using of Homebrew in the following way: + + brew install cgal + +On Linux distributions such as `Debian`/`Ubuntu`/`Mint`, use `apt-get` in the following way: + + sudo apt-get install libcgal-dev + +For other distributions or package manager, please consult your respective documentation. + +\subsection secusingwebsite Using CGAL Source Archive + +You can also obtain the \cgal library sources directly from +https://www.cgal.org/download.html. + +Once you have downloaded the file `CGAL-\cgalReleaseNumber``.tar.xz` containing the +\cgal sources, you have to unpack it. Under a Unix-like shell, use the +command: + + tar xf CGAL-\cgalReleaseNumber.tar.xz + +The directory `CGAL-\cgalReleaseNumber` will be created. This directory +contains the following subdirectories: + +| Directory | Contents | +| :------------------------- | :----------| +| `auxiliary` (Windows only) | precompiled \sc{Gmp} and \sc{Mpfr} for Windows | +| `cmake/modules` | modules for finding and using libraries | +| `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 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. + +The only documentation shipped within \cgal sources is the present manual. +The \cgal manual can also be accessed online at +`https://doc.cgal.org` +or downloaded separately at +`https://github.com/CGAL/cgal/releases`. + +\section section_headeronly Header-only Usage + +\cgal is a header-only library, and as such +there is no need to even configure it before using it. Programs using \cgal (examples, tests, demos, etc.) +are instead configured using CMake and \cgal will be configured at the same time. + +There is one exception to the last paragraph: if you want to install \cgal header files to +a standard location (such as `/usr/local/include`): + + cmake . + make install + +For more advanced installations, we refer to Section \ref installation_configwithcmake. + +Note that even though \cgal is a header-only library, not all its dependencies +are header-only. The libraries \sc{Gmp} and \sc{Mpfr}, for example, are not +header-only. As such, these dependencies must be built or installed independently. + +\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. + +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`. + +The most important CMake variable is the variable `CGAL_DIR`, which will serve to configure \cgal +as you configure your program. + +In a typical installation of dependencies, almost all CMake variables will be set automatically. +The variable `CGAL_DIR` is also generally found when \cgal has been obtained via a package manager. +In the rare event that it has not, the variable `CGAL_DIR` should be set manually to: + +
    +
  • something like `/usr/local/Cellar/cgal/CGAL-\cgalReleaseNumber/lib/cmake/CGAL`, for Brew.
    • +
  • something like `/usr/lib/x86_64-linux-gnu/cmake/CGAL`, for Linux distributions.
    • +
+ +If \cgal has been obtained via other means, `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). + +It is also strongly recommended to set the build type variable 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 -DCMAKE_BUILD_TYPE=Release . # we are here using a release tarball + +\subsection usage_configuring_cmake_gui Specifying Missing Dependencies + +The configuration process launched above might fail if CMake fails to find +all the required dependencies. This typically happens if you have installed dependencies +at non-standard locations. +Although the command line tool `cmake` accepts CMake variables as arguments of the form +`-D:=`, 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 . + +After the `CMake` window opens, press 'Configure'. A dialog will pop up and you will have to choose +what shall be generated. After you have made your choice and pressed 'Finish', you will see +the output of configuration tests in the lower portion of the application. +Once these tests are done, you will see many red entries in the upper portion of the application. +Just ignore them, and press 'Configure' again. By now, CMake should have found most required +libraries and have initialized variables. +If red entries are still present, you must provide the necessary information (paths/values). +When all entries have been appropriately filled (and automatically filled values have been adjusted, +if desired) and lines are gray, you are now ready to press 'Generate', +and to exit `cmake-gui` afterwards. + +\cgalAdvancedBegin +You may also decide to solve missing dependencies using the command line tool (which is not recommended). +If so, the page \ref configurationvariables lists variables which can be used to specify +the location of third-party software. +\cgalAdvancedEnd + +If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`. + +\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 `your_program.cpp` amounts to: + + cd /path/to/your/program + path/to/cgal/Scripts/scripts/cgal_create_CMakeLists -s your_program + cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . + +Note that the script `cgal_create_CMakeLists` creates a very coarse `CMakeLists.txt` file which +might not properly encode the third party dependencies of your program. Users are advised to look +at the `CMakeLists.txt` files in the example folder(s) of the package that they are using to +learn how to specify their dependencies. + +\subsection usage_configuring_advanced_cmake Advanced Configuration Options + +CMake keeps the variables that a user can manipulate in a so-called CMake cache, a simple text file +named `CMakeCache.txt`, whose entries are of the form `VARIABLE:TYPE=VALUE`. Advanced users can manually +edit this file, instead of going through the interactive configuration session. + +\section usage_building_program Building your Program + +The results of a successful configuration are build files that control the build step. +The nature of the build files depends on the generator used during configuration, but in most cases +they contain several targets, such as all the examples of the Triangulation_2 package. + +In a \sc{Unix}-like environment the default generator produces makefiles. +You can use the `make` command-line tool for the succeeding build step as follows: + + cd CGAL-\cgalReleaseNumber/examples/Triangulation_2 + make # build all the examples of the Triangulation_2 package + +\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/advanced/Configuration_variables.txt b/Documentation/doc/Documentation/advanced/Configuration_variables.txt new file mode 100644 index 000000000000..1bebdc5ddd70 --- /dev/null +++ b/Documentation/doc/Documentation/advanced/Configuration_variables.txt @@ -0,0 +1,353 @@ +/*! + +\page configurationvariables Summary of %CGAL's Configuration Variables +\cgalAutoToc + +\cgalAdvancedBegin +This page lists CMake variables which you can use to help CMake find missing dependencies +while using the command line. We however recommend using the graphical interface (`cmake-gui`). +\cgalAdvancedEnd + +\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 + +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 | | +| `CMAKE_INSTALL_PREFIX`| Installation directory path | CMake | Debug | +| `CMAKE_C_COMPILER` | Full-path to the executable corresponding to the C compiler to use. | CMake | platform-dependent | +| `CMAKE_CXX_COMPILER` | Full-path to the executable corresponding to the C++ compiler to use. | CMake | platform-dependent | +| `CXX` | Idem | Environment | Idem | +| `BUILD_SHARED_LIBS` | Whether to build shared or static libraries. | CMake | TRUE | + +\subsection installation_variables_building Variables Used Only When Building Programs (Such as Demos or Examples) + + +| Variable | Description | Type | %Default Value | +| :- | :- | :- | :- | +| `CGAL_DIR` | Full-path to the binary directory where \cgal was configured |Either CMake or Environment | none | + + +\subsection installation_variables_third_party Variables Providing Information About 3rd-Party Libraries +\anchor sec3partysoftwareconfig + +The following variables provide information about the availability and +location of the 3rd party libraries used by \cgal. CMake automatically +searches for dependencies so you need to specify these variables if +CMake was unable to locate something. This is indicated by a value ending in +`NOTFOUND`. + +Since 3rd-party libraries are system wide, many of the CMake variables listed below can alternatively +be given as similarly-named environment variables instead. Keep in mind that you must provide one or the +other but never both. + +\subsection installation_boost Boost Libraries + +In most cases, if \sc{Boost} is not automatically found, setting the `BOOST_ROOT` +variable is enough. If it is not, you can specify the header and library +directories individually. You can also provide the full pathname to a specific compiled library +if it cannot be found in the library directory or its name is non-standard. + +By default, when \sc{Boost} binary libraries are needed, the shared versions +are used if present. You can set the variable +`CGAL_Boost_USE_STATIC_LIBS` to `ON` if you want to link +with static versions explicitly. + +On Windows, if you link with \sc{Boost} shared libraries, you must ensure that +the `.dll` files are found by the dynamic linker, at run time. +For example, you can add the path to the \sc{Boost} `.dll` to the +`PATH` environment variable. + +| Variable | Description | Type | +| :- | :- | :- | +| `BOOST_ROOT`\cgalFootnote{The environment variable can be spelled either `BOOST_ROOT` or `BOOSTROOT`} | Root directory of your \sc{Boost} installation | Either CMake or Environment | +| `Boost_INCLUDE_DIR` | Directory containing the `boost/version.hpp` file | CMake | +| `BOOST_INCLUDEDIR` | Idem | Environment | +| `Boost_LIBRARY_DIRS` | Directory containing the compiled \sc{Boost} libraries | CMake | +| `BOOST_LIBRARYDIR` | Idem | Environment | +| `Boost_(xyz)_LIBRARY_RELEASE` | Full pathname to a release build of the compiled 'xyz' \sc{Boost} library | CMake | +| `Boost_(xyz)_LIBRARY_DEBUG` | Full pathname to a debug build of the compiled 'xyz' \sc{Boost} library | CMake | + + +\subsection installation_gmp GMP and MPFR Libraries + +Under Windows, auto-linking is used, so only the 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 `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 `$TBB_ROOT/lib/`. + +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 | +| :- | :- | :- | +| `TBB_ROOT` | Directory of \sc{Tbb} default installation | Environment | +| `TBB_INCLUDE_DIRS` | Directory containing the `tbb/tbb.h` file | CMake | +| `TBB_LIBRARY_DIRS` | Directory(ies) containing the compiled TBB libraries | CMake | +| `TBB_LIBRARIES` | Full pathnames of the compiled TBB libraries (both release and debug versions, using "optimized" and "debug" CMake keywords). Note that if the debug versions are not found, the release versions will be used instead for the debug mode. | CMake | +| `TBB_RELEASE_LIBRARY` | Full pathname of the compiled TBB release library | CMake | +| `TBB_MALLOC_RELEASE_LIBRARY` | Full pathname of the compiled TBB release malloc library | CMake | +| `TBB_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug library | CMake | +| `TBB_MALLOC_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug malloc library | CMake | +| `TBB_MALLOCPROXY_DEBUG_LIBRARY` | Full pathname of the compiled TBB debug malloc_proxy library (optional) | CMake | +| `TBB_MALLOCPROXY_RELEASE_LIBRARY` | Full pathname of the compiled TBB release malloc_proxy library (optional) | CMake | + +\section installation_compiler_workarounds Compiler Workarounds + +A number of boolean flags are used to workaround compiler bugs and +limitations. They all start with the prefix `CGAL_CFG`. These +flags are used to work around compiler bugs and limitations. For +example, the flag `CGAL_CFG_NO_CPP0X_LONG_LONG` denotes +that the compiler does not know the type `long long`. + +For each installation a file +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/advanced/Installation.txt b/Documentation/doc/Documentation/advanced/Installation.txt new file mode 100644 index 000000000000..314ead765e1f --- /dev/null +++ b/Documentation/doc/Documentation/advanced/Installation.txt @@ -0,0 +1,313 @@ +/*! +\page installation Building %CGAL libraries (non header-only mode) +\cgalAutoToc + +\cgalAdvancedBegin +Since \cgal version 5.0, \cgal is header-only be default, which means +that there is no need to compile \cgal or its libraries before it can be used. + +This page is for advanced users that have a good reason to still use the old way. +If this is not your case, head over back to the page \ref general_intro. +\cgalAdvancedEnd + +This page is a step-by-step description of how to configure, build, and (optionally) install \cgal +in case you do not wish to use the - now enabled by default - header-only mode of \cgal. + +It is assumed that you have downloaded a source archive of \cgal, and are using Linux or macOS. + +\section installation_idealworld Quick Installation + +Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as: + + cd $HOME/CGAL-\cgalReleaseNumber + mkdir build + cd build + cmake -DCGAL_HEADER_ONLY=OFF -DCMAKE_BUILD_TYPE=Release .. # configure CGAL + make # build CGAL + make install # install CGAL + cd examples/Triangulation_2 # go to an example directory + cmake -DCGAL_DIR=$CMAKE_INSTALLED_PREFIX/lib/CGAL -DCMAKE_BUILD_TYPE=Release . # configure the examples + make # build the examples + +In a less ideal world, you might have to install some required tools and third-party libraries. +This is what this page is about. + +\section installation_configwithcmake Configuring CGAL with CMake + +Before building \cgal, or anything using \cgal, you have to choose the compiler/linker, +set compiler and linker flags, specify which +third-party libraries you want to use and where they can be found, and +which \cgal libraries you want to build. Gathering +all this information is called configuration. +The end of the process is marked by the generation of a makefile that you can use to build \cgal. + +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 which compiler flags to use, +such as `CMAKE_CXX_FLAGS`. + +The next sections first present the CMake variables related to \cgal, followed by more generic variables, +and finally the configuration and build processes. + +\subsection seclibraries CGAL Libraries + +\cgal is split into four libraries. During configuration, you can select the libraries that +you would like to build by setting a CMake variable of the form WITH_. By default all +are switched `ON`. All activated libraries are to be built after configuration. + +Note that some libraries have specific dependencies in addition to the essential ones. See the page +\ref secessential3rdpartysoftware for more information. + +| Library | CMake Variable | Functionality | Dependencies | +| :-------- | :------------- | :------------ | :----------- | +| `%CGAL` | none | Main library | \sc{Gmp}, \sc{Mpfr}, \sc{Boost} (headers) | +| `CGAL_Core` | `WITH_CGAL_Core` | The %CORE library for algebraic numbers.\cgalFootnote{CGAL_Core is not part of \cgal, but a custom version of the \sc{Core} library distributed by \cgal for the user convenience and it has it's own license.} | \sc{Gmp} and \sc{Mpfr} | +| `CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | \sc{zlib}, \sc{Vtk} (optional) | +| `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 | + +Shared libraries, also called dynamic-link libraries, are built by default +(`.so` on Linux, `.dylib` on macOS). You +can choose to produce static libraries instead, by setting the CMake +variable `BUILD_SHARED_LIBS` to `FALSE`. + +\subsection installation_examples CGAL Examples and Demos + +\cgal is distributed with a large collection of examples and demos. By default, these are not configured along with +the \cgal libraries, unless you set the variables `WITH_examples=ON` and/or `WITH_demos=ON`. +Additionally, even when configured with \cgal, they are not automatically built along with the libraries. +You must build the `examples` or `demos` targets (or IDE projects) explicitly. + +If you do not plan to compile any demos, you may skip some of the dependencies (such as \sc{Qt}), +as the corresponding \cgal-libraries will not be used. Note, however, that your own demos +might need these \cgal-libraries and thus their dependencies. See the page +\ref secessential3rdpartysoftware for more information. + +\subsection installation_debugrelease Debug vs. Release + +The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the libraries. +It accepts the values `Debug` or `Release`. Note that the default value is `Debug`, since it is +default value in `CMake`. If you do not plan on debugging, it is important to set the variable +to `Release` for performance reasons. + +This is however not an issue for solution/project files, since the user selects the build type +from within the IDE in this environment. + +\subsection installation_miscvariables Other CMake Variables + +There are many more variables that can be used during configuration. The most important ones are: +
    +
  • `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 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/build + cmake-gui .. # The two dots indicate the parent 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`. + +Since you intend to build CGAL libraries, you should also ensure that the variable +`CGAL_HEADER_ONLY` has not been set. + +If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`. + +\subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool + +Alternatively, you can run the command-line tool called `cmake`. +You pass as argument the root directory of \cgal. +The command line tool `cmake` accepts CMake variables as arguments of the form `-D:=`, 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/build + cmake .. + +The configuration process not only determines the location of the required dependencies, it also dynamically generates a +`compiler_config.h` file, which encodes the properties of your system and a special file named +`CGALConfig.cmake`, which is used to build programs using \cgal. The +purpose of this file is explained below. + +\cgalAdvancedBegin +CMake keeps the variables that a user can manipulate in a +so-called 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 + +\subsection installation_cgalconfig CGALConfig.cmake + +During configuration of the \cgal libraries a file named `CGALConfig.cmake` is generated +in \cgal's root directory (in contrast to \cgal's source directory that has been used +for installation). This file contains the definitions of several CMake variables +that summarize the configuration of \cgal and will be essential during the configuration and +building of a program using \cgal, see Section \ref installation_buildprogram. + +\section seccmakeoutofsource Multiple Builds + +While you can choose between release or debug builds, and shared or static libraries, +it is not possible to generate different variants during a single configuration. You need to run CMake in a +different directory for each variant you are interested in, each with its own selection of configuration parameters. + +CMake stores the resulting makefiles, 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``/build/debug` and +`CGAL-\cgalReleaseNumber``/build/release` for two configurations, respectively: + + mkdir CGAL-\cgalReleaseNumber/build/debug + cd CGAL-\cgalReleaseNumber/build/debug + cmake -DCMAKE_BUILD_TYPE=Debug ../.. + + mkdir CGAL-\cgalReleaseNumber/build/release + cd CGAL-\cgalReleaseNumber/build/release + cmake -DCMAKE_BUILD_TYPE=Release ../.. + +\section secbuilding Building CGAL + +The results of a successful configuration are build files that control the build step. +The nature of the build files depends on the generator used during configuration, but in all cases they +contain several 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: + + # 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). + +\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 + +\subsection ssec_installation_build_ex_demos Building Examples and Demos + +If you have turned on the configuration of examples +(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional +targets named `examples` and `demos`, plus one target for +each example and each demo in the build files. +None of these targets are included by default, so you need to build them explicitly +after the \cgal libraries have been successfully built. +The targets `examples` and `demos` include themselves all the targets +for examples and demos respectively. + + # build all examples at once + make examples + + # build all demos at once + make demos + +If you are interested in the demos or examples of just a particular module, you can build them in the following way: + + make -C demo/Alpha_shapes_2 # equivalent to "cd demo/Alpha_shapes_2; make" + make -C examples/Alpha_shapes_2 # equivalent to "cd examples/Alpha_shapes_2; make" + +When using `UNIX Makefiles`, you can find out the exact name of the example or demo target +of a particular package by typing `make help | grep `. + +\section secinstalling Installing CGAL + +On many platforms, library pieces such as headers, docs and binaries +are expected to be placed in specific locations. A typical example +being `/usr/include` and `/usr/lib`. The process +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. +Assuming you have successfully configured and built \cgal as demonstrated in the previous sections, +the installation simply amounts to: + + # install CGAL + make install + +\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. +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 `your_program.cpp` amounts to: + + cd /path/to/your/program + cgal_create_CMakeLists -s your_program + cmake -DCGAL_DIR=XXXXXX -DCMAKE_BUILD_TYPE=Release . + make + +In order to configure a program, you need to indicate the location of the \cgal configuration file +in the CMake variable `CGAL_DIR` (as shown in the example above). +If you have installed \cgal, `CGAL_DIR` must afterwards be set to `$CMAKE_INSTALLED_PREFIX/lib/CGAL`. + +The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense +if you have multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. + +*/ diff --git a/Documentation/doc/Documentation/main.txt b/Documentation/doc/Documentation/main.txt index 22a8407f82e1..6d9ffe67c1e3 100644 --- a/Documentation/doc/Documentation/main.txt +++ b/Documentation/doc/Documentation/main.txt @@ -2,13 +2,17 @@ \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. +

Package Overview

+ +\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,33 +24,32 @@ 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 -================== +The complete list of packages is available on the page \ref packages. + +

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. +Head over to \ref general_intro to learn how to obtain, install, and use \cgal. + +

License

-License -======= %CGAL is distributed under a dual-license scheme. %CGAL can be used together with Open Source software free of charge. Using %CGAL in other contexts can be done by obtaining a commercial license from [GeometryFactory](http://www.geometryfactory.com). For more details -see the \ref licenseIssues "License" page. +see the \ref license "License" page. + +

Acknowledgement

-Manuals for the Previous Releases -================================= +We provide bibtex entries for each package so that you can cite \cgal correctly in your publications, +see the page \ref how_to_cite_cgal. + +

Manuals for the Previous Releases

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 @@ -55,6 +58,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 dbada72f28dc..33354eecf6d7 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. +\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. + */ -} /* namespace CGAL */ diff --git a/Documentation/doc/Documentation/windows.txt b/Documentation/doc/Documentation/windows.txt new file mode 100644 index 000000000000..a45afc972a57 --- /dev/null +++ b/Documentation/doc/Documentation/windows.txt @@ -0,0 +1,275 @@ +/*! +\page windows Using %CGAL on Windows (with Visual C++) +\cgalAutoToc + +\cgal \cgalReleaseNumber is supported for the following \sc{MS} Visual `C++` compilers: +14.0, 15.9, 16.0 (\sc{Visual Studio} 2015, 2017, and 2019). + +\cgal is a library that has mandatory dependencies that must be first installed: +\ref thirdpartyBoost and \ref thirdpartyMPFR. + +You have two options to install \cgal and its dependencies: you can either use +the *Vcpkg library manager*, which will automatically install an appropriate version of +these dependencies as you install \cgal, or you can install the dependencies on your own +(making sure that you are using a supported version) by following their respective +installation instructions. + +If you choose to use `vcpkg`, you might have to bootstrap and download +and compile it, but from then on `vcpkg` will make your life easier. +On the other hand, if you need to specify a specific version, or have already installed +a certain version of a dependency and do not wish to potentially have multiple versions installed, +you will want to use the \cgal Installer. + +We explain the two approaches in the next two sections. + +\section sec-installing-with-vcpkg Installing CGAL with the Vcpkg Library Manager + +\subsection ssec-vcpk-install-vcpk Installing Vcpkg + +The first step is to clone or download `vcpkg` from +https://github.com/microsoft/vcpkg. + + C:\dev> git clone https://github.com/microsoft/vcpkg + C:\dev> cd vcpkg + C:\dev\vcpkg> .\bootstrap-vcpkg.bat + +\subsection ssec-vcpk-install-cgal Installing CGAL with Vcpkg + +By default `vcpkg` installs for 32 bit binaries and will use the latest version of Visual C++ +installed on your machine. If you develop 64 bit software you must +set the Windows environment variable `VCPKG_DEFAULT_TRIPLE` to `x64-windows` +or pass the option `--triplet x64-windows` whenever you install a package. +We refer to the +official documentation +of `vcpkg` if you want to compile for an older version of a compiler. + +You are now ready to install \cgal: + + C:\dev\vcpkg> ./vcpkg.exe install cgal + +This will take several minutes as it downloads \mpir (a fork of \gmp), +\mpfr, all boost header files, and it will compile \mpir and \mpfr, as well +as several boost libraries. +Afterwards, you will find the include files, libraries, and dlls in the +subdirectory `C:\dev\vcpkg\installed\x64-windows`. + +Note that \cgal is a header-only library, and there are therefore no `lib` or `dll` files for \cgal. + +\subsection ssec-vcpkg-compile-example Compiling an Example + +In this section we show how to compile a program that uses \cgal. +The examples you find in these User Manual pages are not downloaded when you install \cgal +with the Vcpkg library manager. You must download them separately from the following download page: +CGAL-\cgalReleaseNumber-examples.zip + +Assuming you have unzipped this file in your home directory `C:\Users\Me`, +we will next compile an example from the 2D Triangulation package. + +\subsubsection sssec-vcpkg-configuration-example Configuring of an Example + +Before building anything using \cgal, you have to choose the compiler/linker, set compiler +and linker flags, specify which third-party libraries you want to use and where they can be found. +Gathering all this information is called *configuration* and we use *CMake* as configuration tool +(see Section \ref seccmake for more information on supported versions and where to download it). + +The end of the process is marked by the generation of a Visual \cpp solution +and a project file that you can use to build your program. + + C:\Users\Me\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2 + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui .. + +The command `cmake-gui` launches the graphical interface for `cmake`. +When you hit the *Configure* button, you must: +
    +
  • specify the *Generator* (e.g., Visual Studio 16 2019),
    • +
  • specify the *Optional Platform* (e.g., `x64` in case you want to create 64 bit binaries),
    • +
  • select *Specify toolchain file for cross compilation* (the file `vcpkg.cmake` within the directory +where you have installed `vcpkg`, e.g. `C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake`).
    • +
+Once the configuration process is done, tick *Advanced* and *Grouped* in `cmake-gui`. +You will see entries for where header files and libraries are taken from. + +If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`. + +\subsubsection sssect-vcpkg-additional-dependencies Additional Dependencies + +Some \cgal packages also have additional dependencies. For example, during the configuration process +above, you may have observed the following message: + + NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled + +\cgal is a library of algorithms and data structures and as such does +not depend on `Qt`. However, one of the examples in the Triangulation_2 package does require `Qt` +for visualization purposes. If you already have `Qt` installed, you can simply fill in the requested +CMake variables and paths. Otherwise, you can also install it using `vcpkg`: + + C:\dev\vcpkg> ./vcpkg.exe install qt5 + +Remember to specify `--triplet` or the related environment variable in case you target 64-bit applications. + +As Qt5 is modular and as the \cgal examples and demos use only some of these modules +you can save download and compilation time by specifying an *installation option*: + + C:\dev\vcpkg> ./vcpkg.exe install cgal[qt] + +In both cases, when you start `cmake-gui` again and hit the *Configure* button, +the CMake variables and paths concerning Qt should now be filled. + +Note that not all optional dependencies are available through the Vcpkg library manager. +In this case, you must download and install them independently (see page \ref thirdparty +for information on support versions and download links) as well as fill the missing information +within the `CMake` interface until configuration is successful (no more red lines indicating +missing dependencies). + +\cgalAdvancedBegin +You may also decide to solve missing dependencies using the `CMake` command line tool (which is not recommended). +If so, the page \ref configurationvariables lists variables which can be used to specify +the location of third-party software. +\cgalAdvancedEnd + +\subsubsection sssect-vcpkg-compilation Compilation of an Example + +Once the configuration process is successful, hit the *Generate* button, +and you will find the file `Triangulation_2_examples.sln` +in the directory `C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build`. +Double-click it to open it. There is one project per `.cpp` file in the directory. +Compile them all, or just the one you are interested in. + +\subsection subsect-vpckg-my-code Configuring and Compiling Your Code Using CGAL + +Configuring and compiling your own code is practically the same as for \cgal examples +if you use `cmake`. Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. +This file is automatically provided for all examples and demos of \cgal. For your own programs, +you are advised to look at the `CMakeLists.txt` files in the example +folder of the package(s) that you are using to learn how to specify \cgal and additional third party +dependencies. + +\section install-with-installer Installing with the CGAL Installer + +You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. +It is a self-extracting executable that downloads the \cgal header files, and optionally the source code of the +examples and demos. Additionally, it can download precompiled versions of \gmp and \mpfr. + +\subsection ssect-installer-boost Installing Boost + +`Boost` is a mandatory dependency of \cgal. Binary versions of `Boost` are available on +SourceForge. +The `Boost` installers install both `Boost` headers and precompiled libraries. +Please note that the \cgal project is not responsible for the files provided on this website. +When \cgal \cgalReleaseNumber was released, the latest version of `Boost` was 1.71. +A typical installation of `Boost` would consist of the following steps: + +
    +
  • Download and run the file boost_1_71_0-msvc-XX.Y-64.exe (where XX.Y = 14.0 for VC 2015, XX.Y = 14.1 for 2017, XX.Y = 14.2 for VC 2019).
    • +
  • Extract the files to a new directory, e.g. `c:\dev\libboost_1_71_0`.
    • +
  • Set the following two environment variables to point respectively to the path of the libraries and the headers +
      +
    • `BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`
      • +
    • `BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0`
      • +
    +as this will help `cmake` to find Boost.
    • +
  • Add the path to the Boost `dlls` (`C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`) files to the `PATH` environment variable.
    • +
+ +\subsection ssect-installer-install-cgal Installing CGAL Itself + +Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from +https://www.cgal.org/download/windows.html. +It is a self extracting executable that downloads the \cgal header files, and optionally the source code of the +examples and demos. Additionally, it can download the precompiled versions of \gmp and \mpfr. You must +specify if you want the 32 or the 64 bit versions of these two libraries. + +Setting the environment variable `CGAL_DIR` to `C:\dev\CGAL-\cgalReleaseNumber` is a good idea +to help `cmake` to find \cgal during the configuration process, detailed in the next section. + +\subsection ssect-installer-compile-example Compiling an Example + +We assume that you have downloaded the examples with the \cgal Installer. + +Before building anything using \cgal, you have to choose the compiler/linker, set compiler +and linker flags, specify which third-party libraries you want to use and where they can be found. +Gathering all this information is called *configuration* and we use CMake as configuration tool +(see Section \ref seccmake for more information on minimal supported versions and where to +download it). + +The end of the process is marked by the generation of a Visual \cpp solution +and a project file that you can use to build your program. + + C:\dev\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2 + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui .. + +The command `cmake-gui` launches the graphical interface for `cmake`. +When you hit the *Configure* button, you must: +
    +
  • Specify the *Generator*, e.g., Visual Studio 16 2019), and
    • +
  • specify an *Optional Platform* (`x64` in case you want to create 64 bit binaries).
    • +
+Once the configuration is done, tick `Advanced` and `Grouped` in `cmake-gui`. +You will see entries for where header files and libraries are taken from. + +If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`. + +\subsubsection ssect-installer-additional-dependencies Additional Dependencies + +Some \cgal packages also have additional dependencies. For example, during the configuration process +above, you may have observed the following message: + + NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled + +\cgal is a library of algorithms and data structures and as such does +not depend on `Qt`. However, one of the examples does for visualization purposes only. Either you +have Qt installed and you can fill in the requested CMake variables, or you must install it. +A typical `Qt` installation would consist of the following steps: + +
    +
  • +Download and install the Qt library for open source development package for your Visual Studio version at +https://www.qt.io/download/ +(here is the direct link to the offline installers).
    • +
  • Add the environment variable `QTDIR` pointing to the place you installed Qt, e.g., `C:\dev\Qt\Qt5.13.1`, +as this will help `cmake` to find Qt.
    • +
  • Add the bin directory of Qt, e.g. add `C:\dev\Qt\Qt5.13.1\msvcXXXX_YY\bin` to `PATH`, where `XXXX_YY` is something like `vc2017_64`. +To avoid any conflict with another dll with the same name from another folder, add this path as the first in the list.
    • +
+ +Once you have installed `Qt`, the CMake variables concerning `Qt` should now be filled when you +press *Configure* in the \cgal directory. + +You must follow a similar process for other dependencies (see page \ref thirdparty for information +on supported versions of third party libraries as well as download links) and fill the missing information +within the `CMake` interface until configuration is successful (no more red lines indicating +missing dependencies). + +\cgalAdvancedBegin +You may also decide to solve missing dependencies using the `CMake` command line tool (which is not recommended). +If so, the page \ref configurationvariables lists variables which can be used to specify +the location of third-party software. +\cgalAdvancedEnd + +\subsubsection sssect-installer-compilation Compilation of an Example + +Once the configuration process is successful, hit the *Generate* button, +and you will find the file `Triangulation_2_examples.sln` +in the directory `C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build`. +Double-click it in order to open it. You will see one project per `.cpp` file. +Compile them all, or just the one you are interested in. + +\subsection subsect-installer-my-code Configuring and Compiling My Code Using CGAL + +Configuring and compiling your own code is practically the same as for \cgal examples +if you use `cmake`. Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. +This file is automatically provided for all examples and demos of \cgal. For your own programs, +you are advised to look at the `CMakeLists.txt` files in the example +folder of the package(s) that you are using to learn how to specify \cgal and additional third party +dependencies. + +\section install-with-tarball Installing from the Source Archive + +Instead of the installer you can also download release tarballs. The sole difference +is that the installer also downloads precompiled \gmp and \mpfr libraries. + +*/ diff --git a/Documentation/doc/resources/1.8.13/BaseDoxyfile.in b/Documentation/doc/resources/1.8.13/BaseDoxyfile.in index 34d9e359a51f..706be1b14caf 100644 --- a/Documentation/doc/resources/1.8.13/BaseDoxyfile.in +++ b/Documentation/doc/resources/1.8.13/BaseDoxyfile.in @@ -233,6 +233,9 @@ ALIASES = "sc{1}=\1\1\1" ALIASES += "cgal=\sc{%CGAL}" ALIASES += "protocgal=\sc{C++gal}" ALIASES += "plageo=\sc{Plageo}" +ALIASES += "gmp=\sc{GMP}" +ALIASES += "mpir=\sc{MPIR}" +ALIASES += "mpfr=\sc{MPFR}" ALIASES += "stl=\sc{STL}" ALIASES += "leda=\sc{LEDA}" ALIASES += "gcc=\sc{GCC}" diff --git a/INSTALL.md b/INSTALL.md index ca09f887112e..8913be934e01 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,71 +1,55 @@ -Building CGAL Libraries From a Branch -===================================== +NOTICE +====== -Building CGAL using the *branch build* presented here keeps the -build-sources attached to the Git repository. +Since Version 5.0, CGAL is a header-only library it is not needed +to build and install it. Usage of CGAL should thus simply amount to: -Note that we do not document here what are the dependancies and cmake options that -are needed to configure CGAL as they are already documented in the -[installation manual](https://doc.cgal.org/latest/Manual/installation.html). - -Branch Build of CGAL -==================== -The cmake script at the root of the repository is the one to use to -build the CGAL library from a branch. It will collect the list of packages -of the branch and will append their include folder to the include path. -This is main noticeable difference with a build using a regular *flat* release. - -Here is an example of how to build the library in Debug: ``` {.bash} git clone https://github.com/CGAL/cgal.git /path/to/cgal.git -cd /path/to/cgal.git +cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 mkdir -p build/debug cd build/debug -cmake -DCMAKE_BUILD_TYPE=Debug ../.. +cmake -DCMAKE_BUILD_TYPE=Debug -DCGAL_DIR=/path/to/cgal.git make ``` -Here is an example of how to build the library in Release: -``` {.bash} -git clone https://github.com/CGAL/cgal.git /path/to/cgal.git -cd /path/to/cgal.git -mkdir -p build/release -cd build/release -cmake -DCMAKE_BUILD_TYPE=Release ../.. -make -``` -Note that *no installation is required* to use that version of CGAL once it has been compiled. +in the case of the building of an example in debug mode. + +For more information head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html). +Note that this page describes the setting of CGAL as a sources release and, as such, +files are organized in a slightly different way, see the [Layout of the CGAL Git Repository](README.md). + Building a Program Using CGAL ============================= To compile a program using CGAL, simply set `CGAL_DIR` to the location -of where you built the library (environment or cmake variable). +of the directory containing `CGALConfig.cmake` (for example the root +of the extracted source archive or the root of a git checkout). Here is an example of how to build in debug the examples from the 3D Triangulations package: ``` {.bash} - cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_3/examples/Triangulation_3 + cd /path/to/cgal.git/Triangulation_3/examples/Triangulation_3 + mkdir -p build/debug + cd build/debug + cmake -DCGAL_DIR:PATH=/path/to/cgal.git ../.. make ``` -If you're trying to build examples or tests that does not already have a `CMakeLists.txt`, you can trigger its creation by calling the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script) found in `/path/to/cgal.git/Scripts/scripts/` at the root of the example/test directory. Here is an example for the examples of the 2D Triangulation package: +If you are trying to build examples or tests that do not already have a `CMakeLists.txt`, +you can trigger its creation by calling the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script) +found in `/path/to/cgal.git/Scripts/scripts/` at the root of the example/test directory. +Here is an example for the examples of the 2D Triangulation package: ``` {.bash} cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 /path/to/cgal.git/Scripts/scripts/cgal_create_cmake_script - cd - - cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 + cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 + mkdir -p build/debug + cd build/debug + cmake -DCGAL_DIR:PATH=/path/to/cgal.git ../.. make ``` -Note If You Switch Between Branches -=================================== -A build may be outdated after an include/dir has been deleted, -switched or even updated. This might lead to compile problems (link -with outdated version). Thus, it is recommended to build CGAL after -each update, switch, merge of a branch (in particular if directories -have been added/deleted, or cpp files have been added, deleted or -altered). - - +For more information head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html). diff --git a/Installation/CHANGES.md b/Installation/CHANGES.md index 51e45d1c9985..a9d9270524b7 100644 --- a/Installation/CHANGES.md +++ b/Installation/CHANGES.md @@ -4,7 +4,7 @@ Release History [Release 5.0](https://github.com/CGAL/cgal/releases/tag/releases%2FCGAL-5.0) ----------- -Release date: October 2019 +Release date: November 2019 ### General changes @@ -18,6 +18,9 @@ Release date: October 2019 - Since CGAL 4.9, CGAL can be used as a header-only library, with dependencies. Since CGAL 5.0, that is now the default, unless specified differently in the (optional) CMake configuration. +- The section "Getting Started with CGAL" of the documentation has + been updated and reorganized. +- The minimal version of Boost is now 1.57.0. ### [Polygonal Surface Reconstruction](https://doc.cgal.org/5.0/Manual/packages.html#PkgPolygonalSurfaceReconstruction) (new package) diff --git a/Installation/INSTALL.md b/Installation/INSTALL.md index eeefd10cf371..54d011ef4086 100644 --- a/Installation/INSTALL.md +++ b/Installation/INSTALL.md @@ -1,199 +1,15 @@ -INTRODUCTION -============ +NOTICE +====== -This file describes how to install CGAL. The instructions in this file -are for the most common use cases, and cover the command line tools. +Since Version 5.0, CGAL is now header-only by default, meaning that you do not need to build and install CGAL. Usage of CGAL as a header-only library +simply amounts to, for example: -For further information, or in case of problems, please see the -detailed installation instructions, which can be found in this -distribution in the file ./doc_html/index.html or on the CGAL website -https://doc.cgal.org/latest/Manual/installation.html - -The documentation of CGAL is available in PDF and HTML formats. -It is not bundled with the software but can be downloaded separately -at . - -For more information about CGAL, see the . - -In the current file, x.y is an implicit replacement for the current version -of CGAL (3.5.1, 3.6, and so on). - - -PREREQUISITES -============= - -To install CGAL, you need 'cmake' and several third-party libraries. -Some are essential for entire CGAL, some are mandatory for particular -CGAL packages, some are only needed for demos. - - * CMake (>= 3.1), the build system used by CGAL - Required for building CGAL - - * Boost (>= 1.48) - Required for building CGAL and for applications using CGAL - Optional compiled Boost library: Boost.Program_options - http://www.boost.org/ or http://www.boostpro.com/products/free/ - You need the former if you plan to compile the boost libraries yourself, - for example because you target 64 bit applications for XP64 - - * Exact Arithmetic - CGAL combines floating point arithmetic with exact arithmetic, in order - to be fast and reliable. CGAL offers support for GMP and MPFR, for LEDA - exact number types, as well as a built-in exact number type used when - none of the other two is installed. - Required by several examples which have hard coded the number type. - - - GMP (>= 4.1.4) - http://gmplib.org/ - or precompiled version that can be downloaded with CGAL-x.y-Setup.exe - based on http://fp.gladman.plus.com/computing/gmp4win.htm - - - MPFR (>= 2.2.1) - https://www.mpfr.org/ - or precompiled version that can be downloaded with CGAL-x.y-Setup.exe - based on http://fp.gladman.plus.com/computing/gmp4win.htm - - - LEDA (>= 6.2) - http://www.algorithmic-solutions.com/leda/index.htm - - * Visualization - Required for most demos - - - Qt5 (>= 5.9) - http://qt-project.org/ - - - Geomview - http://www.geomview.org/ - Not supported with Visual C++ - - * Numerical Libraries - - EIGEN (>=3.1) - Required by the packages: - * Estimation of Local Differential Properties of Point-Sampled Surfaces - * Approximation of Ridges and Umbilics on Triangulated Surface Meshes - * Planar Parameterization of Triangulated Surface Meshes - * Surface Reconstruction from Point Sets - http://eigen.tuxfamily.org/index.php?title=Main_Page - - - MPFI - Required by the package: - * Algebraic Kernel - https://gforge.inria.fr/projects/mpfi/ - (or shipped with RS http://vegas.loria.fr/rs/) - - - RS (root isolation) - Required by the package: - * Algebraic Kernel - http://vegas.loria.fr/rs/ - - - NTL (Number Type Theory) - Optional for the packages: - * Polynomial - * Algebraic Kernel - http://www.shoup.net/ntl/ - - * Miscellaneous - - - zlib - Optional for the package: - * Surface Mesh Generator can read compressed images directly - http://www.zlib.net/ - - - ESBTL - Optional to read PDB files: - * Import data from a PDB file as CGAL points or weighted points. - An example is given in package Skin_surface (see example skin_surface_pdb_reader.cpp) - http://esbtl.sourceforge.net/ - -CONFIGURATION -============= - -To configure CGAL, type -``` - cmake . -``` -in the directory that contains this INSTALL file. You can add several options -to this command. The most important ones are - -* `-DCMAKE_INSTALL_PREFIX=` installation directory [/usr/local] -* `-DCMAKE_BUILD_TYPE=` build type [Release] -* `-DBUILD_SHARED_LIBS=` shared or static libraries [TRUE] -* `-DCMAKE_C_COMPILER=` C compiler [gcc] -* `-DCMAKE_CXX_COMPILER=` C++ compiler [g++] - -In case you want to add additional compiler and linker flags, you can use - -* `-DCGAL_CXX_FLAGS` additional compiler flags -* `-DCGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries) -* `-DCGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries) -* `-DCGAL_EXE_LINKER_FLAGS` add. linker flags (executables) - -Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set -separate values for debug and release builds. In case you do not want to add -additional flags, but to override the default flags, replace "CGAL" by -"CMAKE" in the variable names above. - -By default demos and examples are not configured. If you want to configure -them at the same time as the CGAL library, you can use - -* `-DWITH_examples=true` -* `-DWITH_demos=true` - -Note that CMake maintains a cache name `CMakeCache.txt`. If you change options -(or your environment changes), it is best to remove that file to avoid -problems. - - -BUILDING -======== - -To build the CGAL libraries, type -``` - make -``` -(or nmake in a Windows command prompt). -If you want, you can install the CGAL header and libraries. To do so, type -``` - make install -``` -You can build all demos or examples by typing -``` - make demos - make examples -``` -If you are interested in the demos or examples of just a particular module, -you can build them in the following way: -``` - make -C demo/Alpha_shapes_2 (or: cd demo/Alpha_shapes_2; make) - make -C examples/Alpha_shapes_2 (or: cd examples/Alpha_shapes_2; make) -``` -A list of all available make targets can be obtained by -``` - make help -``` - -OUT-OF-SOURCE BUILDS -==================== - -The above instructions build the CGAL library in the same directory tree as -the CGAL sources. Sometimes it is advisable to place all the generated files -somewhere else. For example, if you want to build the library in several -configurations (debug and release, different compilers, and so on). Using -different build directories keeps all the generated files separated for each -configuration. - -In the following, `$CGAL_SRC` denotes the directory with the CGAL sources; -`$CGAL_BUILD` is an arbitrary directory where the generated files will be -placed. You can perform an out-of-source build as follows: -``` - mkdir $CGAL_BUILD - cd $CGAL_BUILD - cmake [options] $CGAL_SRC - make - make install (if desired) - make demos (if desired) - make examples (if desired) +``` {.bash} +cd /path/to/cgal/examples/Triangulation_2 +mkdir -p build/debug +cd build/debug +cmake -DCMAKE_BUILD_TYPE=Debug -DCGAL_DIR=/path/to/cgal +make ``` -Basically, the only difference is the last parameter of the `cmake` command: -`$CGAL_SRC` instead of `.` . +For more information head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html). diff --git a/Installation/doc_html/index.html b/Installation/doc_html/index.html index 0c67b663e5ee..1c7c7682d480 100644 --- a/Installation/doc_html/index.html +++ b/Installation/doc_html/index.html @@ -25,13 +25,9 @@

Manuals

- - + @@ -39,7 +35,7 @@

Further Links

diff --git a/README.md b/README.md index 95dffac80e68..0166c3f78aeb 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,30 @@ The Computational Geometry Algorithms Library (CGAL) is a C++ library that aims to provide easy access to efficient and reliable algorithms in computational geometry. -CGAL releases +CGAL Releases ============= The primary vector of distribution of CGAL are sources tarballs, released twice a year, announced on [the web site of CGAL](https://www.cgal.org/). -The sources distributed that way can be built using the -[CGAL installation manual](https://doc.cgal.org/latest/Manual/installation.html). -CGAL Git repository layout +Getting Started with CGAL +========================= + +**Since version 5.0, CGAL is a header-only library, meaning that +it is no longer needed to build CGAL libraries before it can be used.** + +Head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html) +for usage guides and tutorials that will get you started smoothly. + +License +======= +See the file [LICENSE.md](LICENSE.md). + +CGAL Git Repository Layout ========================== The Git repository of CGAL has a different layout from release tarballs. It -contains a `CMakeLists.txt` file that serves as anchor for building, and a -set of subfolders, so called *packages*. Most packages +contains a `CMakeLists.txt` file that serves as anchor for configuring and building programs, +and a set of subfolders, so called *packages*. Most packages implement a data structure or an algorithm for CGAL (e.g., `Convex_hull_2`, or `Triangulation_3`); however some packages serve special needs: @@ -30,24 +41,7 @@ or `Triangulation_3`); however some packages serve special needs: * `Documentation` - infrastructure for CGAL's manual * `STL_Extension` - extensions to the standard template library -Compilation and installation -============================ -The compilation and installation of CGAL from a sources tarball are -described in the -[CGAL installation manual](https://doc.cgal.org/latest/Manual/installation.html) -and in the file [INSTALL.md](Installation/INSTALL.md) that is at the root -of any sources tarball. - -CGAL developers, however, usually compile CGAL directly from a local Git -repository. That kind of compilation is called a *branch build*, and is -described in the file [INSTALL.md](INSTALL.md) that is at the root of the -Git repository. - -License -======= -See the file [LICENSE.md](LICENSE.md). - -More information +More Information ================ * [The CGAL web site](https://www.cgal.org/) * [Latest CGAL release documentation pages](https://doc.cgal.org/) diff --git a/Triangulation_2/examples/Triangulation_2/CMakeLists.txt b/Triangulation_2/examples/Triangulation_2/CMakeLists.txt index 4911f1d98725..fe3f5a7f849f 100644 --- a/Triangulation_2/examples/Triangulation_2/CMakeLists.txt +++ b/Triangulation_2/examples/Triangulation_2/CMakeLists.txt @@ -31,6 +31,8 @@ if ( CGAL_FOUND ) if(CGAL_Qt5_FOUND) target_link_libraries(draw_triangulation_2 PUBLIC CGAL::CGAL_Qt5) + else() + message(STATUS "NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled.") endif() else()