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

Revert "pass on the doc" 

This reverts commit 76cc4a6863.

Actually don't want to remove that information
This commit is contained in:
Mael Rouxel-Labbé 2019-10-25 12:31:53 +02:00
parent 001c74c8df
commit 51fe37f49b
3 changed files with 713 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@ -0,0 +1,357 @@
/*!
\page installation Installation
\cgalAutoToc
<b>Since \cgal version 5.0, \cgal is header-only be default, which means
that there is no need to compile and install anything before it can be used.</b>
However, the dependencies of \cgal might still need to be installed.
This page is a step-by-step description of how to configure, build, and install \cgal
in case you do not wish to use the - now enabled by default - header-only mode of \cgal.
It is also possible to install \cgal using package managers on some operating systems,
see Section \ref secspecificinstall.
\section installation_idealworld Quick Installation
Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as:
cd $HOME/CGAL-\cgalReleaseNumber
cmake -DCMAKE_BUILD_TYPE=Release . # configure CGAL
make # build CGAL
make install # install CGAL
cd examples/Triangulation_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . # configure the examples
make # build the examples
In a less ideal world, you might have to install some required tools and third-party libraries.
This is what this page is about.
\section installation_configwithcmake Configuring CGAL with CMake
Before building \cgal, or anything using \cgal, you have to choose the compiler/linker,
set compiler and linker flags, specify which
third-party libraries you want to use and where they can be found, and
which \cgal libraries you want to build. Gathering
all this information is called <I>configuration</I>.
The end of the process is marked by the generation of a makefile or a
Visual \cpp solution and project file that you can use to build \cgal.
CMake maintains configuration parameters in so-called <I>cmake variables</I>. Some of the CMake
variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others
indicate the details of a third-party library, such as `Boost_INCLUDE_DIR` or which compiler flags to use,
such as `CMAKE_CXX_FLAGS`.
The next sections first present the CMake variables related to \cgal, followed by more generic variables,
and finally the configuration and build processes.
\subsection seclibraries CGAL Libraries
\cgal is split into four libraries. During configuration, you can select the libraries that
you would like to build by setting a CMake variable of the form <TT>WITH_<library></TT>. By default all
are switched `ON`. All activated libraries are to be built after configuration.
Note that some libraries have specific dependencies in addition to the essential ones. See the page
\ref secessential3rdpartysoftware for more information.
| Library | CMake Variable | Functionality | Dependencies |
| :-------- | :------------- | :------------ | :----------- |
| `%CGAL` | none | Main library | \sc{Gmp}, \sc{Mpfr}, \sc{Boost} (headers) |
| `CGAL_Core` | `WITH_CGAL_Core` | The %CORE library for algebraic numbers.\cgalFootnote{CGAL_Core is not part of \cgal, but a custom version of the \sc{Core} library distributed by \cgal for the user convenience and it has it's own license.} | \sc{Gmp} and \sc{Mpfr} |
| `CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | \sc{zlib}, \sc{Vtk} (optional) |
| `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 |
Shared libraries, also called <I>dynamic-link libraries</I>, are built by default
(`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You
can choose to produce static libraries instead, by setting the CMake
variable `BUILD_SHARED_LIBS` to `FALSE`.
\subsection installation_examples CGAL Examples and Demos
\cgal is distributed with a large collection of examples and demos. By default, these are <B>not</B> configured along with
the \cgal libraries, unless you set the variables `WITH_examples=ON` and/or `WITH_demos=ON`.
Additionally, even when configured with \cgal, they are not automatically built along with the libraries.
You must build the `examples` or `demos` targets (or IDE projects) explicitly.
If you do not plan to compile any demos, you may skip some of the dependencies (such as \sc{Qt}),
as the corresponding \cgal-libraries will not be used. Note, however, that your own demos
might need these \cgal-libraries and thus their dependencies. See the page
\ref secessential3rdpartysoftware for more information.
\subsection installation_debugrelease Debug vs. Release
The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the libraries.
It accepts the values `Debug` or `Release`. Note that the default value is `Debug`, since it is
default value in `CMake`. If you do not plan on debugging, it is important to set the variable
to `Release` for performance reasons.
This is however not an issue for solution/project files, since the user selects the build type
from within the IDE in this environment.
\subsection installation_miscvariables Other CMake Variables
There are many more variables that can be used during configuration. The most important ones are:
<ul>
<li> `CMAKE_INSTALL_PREFIX=<dir>` installation directory [/usr/local]</li>
<li>`CMAKE_BUILD_TYPE=<Debug|Release>` build type [Release]</li>
<li>`BUILD_SHARED_LIBS=<TRUE|FALSE>` shared or static libraries [TRUE]</li>
<li>`CMAKE_C_COMPILER=<program>` C compiler [gcc]</li>
<li>`CMAKE_CXX_COMPILER=<program>` C++ compiler [g++]</li>
</ul>
In case you want to add additional compiler and linker flags, you can use
<ul>
<li>`CGAL_CXX_FLAGS` additional compiler flags</li>
<li>`CGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries)</li>
<li>`CGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries)</li>
<li>`CGAL_EXE_LINKER_FLAGS` add. linker flags (executables)</li>
</ul>
Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set
separate values for debug and release builds. In case you do not want to add
additional flags, but to override the default flags, replace "CGAL" by
"CMAKE" in the variable names above.
A comprehensive list of CMake variables can be found on the \ref configurationvariables page.
Note that CMake maintains a cache name `CMakeCache.txt`. If you change options
(or your environment changes), it is best to remove that file to avoid
problems.
\subsection installation_configuring_gui Configuring CGAL with the CMake GUI
The simplest way to start the configuration process is to run the graphical
user interface of CMake, `cmake-gui`. You must pass as
argument the root directory of \cgal. For example:
cd CGAL-\cgalReleaseNumber
cmake-gui . # Notice the dot to indicate the current directory
After `cmake-gui` opens, press 'Configure'.
A dialog will pop up and you will have to choose what shall be generated.
After you have made your choice and pressed 'Finish', you will see
the output of configuration tests in the lower portion of the application.
When these tests are done, you will see many
red entries in the upper portion of the application. Just ignore them and press 'Configure'.
By now CMake should have found many libraries and have initialized variables.
If you still find red entries, you have to provide the necessary information.
This typically happens if you have installed software at non-standard locations.
Providing information and pressing 'Configure' goes on until
all entries are grayed. You are now ready to press 'Generate'. Once this is
done, you can quit `cmake-gui`.
\subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool
Alternatively, you can run the command-line tool called `cmake`.
You pass as argument the root directory of \cgal.
The command line tool `cmake` accepts CMake variables as arguments of the form `-D<VAR>:<TYPE>=<VALUE>`, as
in the example above, but this is only useful if you already know which variables need to be explicitly defined.
For example:
cd CGAL-\cgalReleaseNumber
cmake . # Notice the dot to indicate the current directory
The configuration process not only determines the location of the required dependencies, it also dynamically generates a
`compiler_config.h` file, which encodes the properties of your system and a special file named
`CGALConfig.cmake`, which is used to build programs using \cgal. The
purpose of this file is explained below.
\cgalAdvancedBegin
CMake keeps the variables that a user can manipulate in a
so-called <I>CMake cache</I>, a simple text file named
`CMakeCache.txt`, whose entries are of the form
`VARIABLE:TYPE=VALUE`. Advanced users can manually edit this file,
instead of going through the interactive configuration session.
\cgalAdvancedEnd
\subsection installation_cgalconfig CGALConfig.cmake
During configuration of the \cgal libraries a file named `CGALConfig.cmake` is generated
in \cgal's root directory (in contrast to \cgal's source directory that has been used
for installation). This file contains the definitions of several CMake variables
that summarize the configuration of \cgal and will be essential during the configuration and
building of a program using \cgal, see Section \ref installation_buildprogram.
\section seccmakeoutofsource Multiple Variants of Makefiles (Out-of-Source Builds)
While you can choose between release or debug builds, and shared or static libraries,
it is not possible to generate different variants during a single configuration. You need to run CMake in a
different directory for each variant you are interested in, each with its own selection of configuration parameters.
CMake stores the resulting makefiles and project files, along with several temporary and auxiliary files such
as the variables cache, in the directory where it is executed, called `CMAKE_BINARY_DIR`, but it
takes the source files and configuration scripts from
`CMAKE_SOURCE_DIR`.
The binary and source directories do not need to be the same. Thus, you can configure multiple variants by creating a
distinct directory for each configuration and by running CMake from there. This is known in CMake terminology
as <I>out-of-source configuration</I>, as opposite to an <I>in-source
configuration</I>, as showed in the previous sections.
You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and
`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively:
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug
cd CGAL-\cgalReleaseNumber/cmake/platforms/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../..
mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release
cd CGAL-\cgalReleaseNumber/cmake/platforms/release
cmake -DCMAKE_BUILD_TYPE=Release ../../..
\section secbuilding Building CGAL
The results of a successful configuration are build files that control the build step.
The nature of the build files depends on the generator used during configuration, but in all cases they
contain several <I>targets</I>, one per library, and a default global target corresponding
to all the libraries.
For example, in a \sc{Unix}-like environment the default generator produces
makefiles. You can use the `make` command-line tool for the
succeeding build step as follows:
# build all the selected libraries at once
make
The resulting libraries are placed in the subdirectory `lib` under `<CMAKE_BINARY_DIR>`
(which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration).
With generators other than `UNIX Makefiles`, the resulting build files
are solution and project files which should be launched in an \sc{Ide},
such as Visual Studio or KDevelop3. They will contain the targets described
above, which you can manually build as with any other solution/project within your \sc{Ide}.
Alternatively, you can build it with the command line version of the
\sc{Visual Studio Ide}:
devenv CGAL.sln /Build Debug
The "Debug" argument is needed because CMake creates solution files for
all four configurations, and you need to explicitly choose one when building
(the other choices are `Release`, `RelWithDebInfo`, and `MinSizeRel`).
\cgalAdvancedBegin
The build files produced by CMake are autoconfigured. That
is, if you change any of the dependencies, the build step
automatically goes all the way back to the configuration step. This
way, once the target has been configured the very first time by
invoking cmake, you don't necessarily need to invoke `cmake`
again. Rebuilding will call itself `cmake` and re-generate the
build file whenever needed. Keep this in mind if you configure \cgal
for the Visual Studio IDE since a build could then change the
solution/project file in-place and VS will prompt you to reload it.
\cgalAdvancedEnd
\subsection ssec_installation_build_ex_demos Building Examples and Demos
If you have turned on the configuration of examples
(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional
targets named `examples` and `demos`, plus one target for
each example and each demo in the build files.
None of these targets are included by default, so you need to build them explicitly
<I>after</I> the \cgal libraries have been successfully built.
The targets `examples` and `demos` include themselves all the targets
for examples and demos respectively.
# build all examples at once
make examples
# build all demos at once
make demos
If you are interested in the demos or examples of just a particular module, you can build them in the following way:
make -C demo/Alpha_shapes_2 # equivalent to "cd demo/Alpha_shapes_2; make"
make -C examples/Alpha_shapes_2 # equivalent to "cd examples/Alpha_shapes_2; make"
When using `UNIX Makefiles`, you can find out the exact name of the example or demo target
of a particular package by typing `make help | grep <package>`.
\section secinstalling Installing CGAL
On many platforms, library pieces such as headers, docs and binaries
are expected to be placed in specific locations. A typical example
being `/usr/include` and `/usr/lib` on \sc{Unix}-like
operating systems or `C:/Program Files/` on Windows. The process
of placing or copying the library elements into its standard location
is sometimes referred to as <I>Installation</I> and it is a
postprocessing step after the build step.
CMake carries out the installation by producing a build target named <I>install</I>.
Assuming you have successfully configured and built \cgal as demonstrated in the previous sections,
the installation simply amounts (in a \sc{Unix}-like environment) to:
# install CGAL
make install
If you use a generator that produces IDE files (for Visual Studio for instance), there will be an optional
`INSTALL` project, which you will be able to <I>"build"</I> to execute the installation step.
\cgalAdvancedBegin
The files are copied into a directory tree relative to the <I>installation directory</I> determined by the
CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under \sc{Unix}-like operating systems
and `C:\Program Files` under Windows. If you want to install to a different location, you must override that CMake
variable explicitly <I>at the configuration time</I> and not when executing the install step.
\cgalAdvancedEnd
The file `CGALConfig.cmake` is installed by default in
`$CMAKE_INSTALLED_PREFIX/lib/``CGAL-\cgalReleaseNumber`.
\section installation_buildprogram Building a Program using CGAL
Similarly to \cgal and its libraries, compiling a program using \cgal is done in the usual
two steps of configuration and building.
The configuration process is also done using `cmake` (or `cmake-gui`) and requires a `CMakeLists.txt` file.
This file is automatically provided for all shipped examples and demos of \cgal.
For other programs, CMake can also be used to configure
and build user programs, but one has to provide the corresponding `CMakeLists.txt`.
This script can be generated either manually, or with the help of a shell-script,
see Section \ref devman_create_cgal_CMakeLists. Using this shell-script,
the process of configuring a user's program called `executable.cpp` amounts to:
cd /path/to/your/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=XXXXXX -CMAKE_BUILD_TYPE=Release .
make
In order to configure a program, you need to indicate the location of the configuration file
in the CMake variable `CGAL_DIR` (as indicated in the example above).
If you have installed \cgal, `CGAL_DIR` must afterwards be set to `$CMAKE_INSTALLED_PREFIX/lib/CGAL`.
The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense
if having multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource.
\section secspecificinstall OS Specific Installation
Some operating systems with package managers offer \cgal and its
essential third party software through the manager,
for instance, Mac OS X or some Linux distribution (e.g. Debian).
For Windows, an installer is provided.
\subsection sseccgalmacosxe CGAL on macOS
The \cgal project recommends the use of <a href="https://brew.sh/">Homebrew</a>, in the following way:
brew install cgal
\subsection sseccgaldebian CGAL on Linux
For instance in Debian/Ubuntu, use apt-get in the following way:
sudo apt-get install libcgal-dev
To get the demos, use:
sudo apt-get install libcgal-demo
For other distributions, please consult your respective package manager documentation.
\subsection sseccgalwindows CGAL on Windows
You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html.
It is a self extracting executable that installs the \cgal source, and that allows you
to select and download some precompiled third party libraries. However, you will need to compile
the library using your favorite compiler.
A <a href="https://www.cgal.org/download/windows.html">tutorial</a> is provided on how to proceed with Microsoft Visual Studio.
*/

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

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