/*!

\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
<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/or build. Their values can be ON or OFF.


| Variable | %Default Value   |
| :------- | :--------------- |
| `WITH_examples`     | OFF   |
| `WITH_demos`        | OFF   |
| `WITH_CGAL_Core`    | ON    |
| `WITH_CGAL_Qt6`     | 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       | none |
| `CMAKE_INSTALL_PREFIX`| Installation directory path                                           | CMake       | platform-dependent |
| `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       | ON |

\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 |
| `Qt6_DIR`             | Full-path to the Qt cmake directory  |CMake| platform-dependent|


\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

Starting from \boost 1.72, the cmake config mode can be used for configuring the \boost version
to use by setting the environment variable `Boost_DIR` to the path containing the file
`BoostConfig.cmake`. For example if you manually installed \boost 1.77 with `--prefix=<path>`,
then you should set `Boost_DIR=<path>/lib/cmake/Boost-1.77.0`.

By default, when \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 \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 \boost `.dll` to the
`PATH` environment variable.

\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 \gmp and \mpfr so both need to be supported. If either of them is unavailable the
usage of \gmp and of \mpfr will be disabled.


| Variable              | Description                                                           | Type        |
| :-                    | :-                    | :-             |
| `CGAL_DISABLE_GMP`    | Indicates whether to search and use \gmp/\mpfr or not  | CMake |
| `GMP_DIR`  | Directory of \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 \gmp library | CMake |
| `GMP_LIB_DIR` | Idem | Environment |
| `GMP_LIBRARIES` | Full pathname of the compiled \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 \mpfr library | CMake |
| `MPFR_LIB_DIR` | Idem | Environment |
| `MPFR_LIBRARIES`  | Full pathname of the compiled \mpfr library | CMake |



Under Linux, the \gmpxx is also searched for, and you may specify the following variables:


| Variable              | Description                                                           | Type        |
| :-                    | :-                    | :-             |
| `GMPXX_DIR` | Directory of \gmpxx default installation | Environment |
| `GMPXX_INCLUDE_DIR`  | Directory containing the `gmpxx.h` file  | CMake |
| `GMPXX_LIBRARIES`  | Full pathname of the compiled \gmpxx library  | CMake |



\subsection installation_qt6 Qt6 Library

You must set the cmake or environment variable `Qt6_DIR` to point to the path
to the directory containing the file `Qt6Config.cmake` created by your \qt6 installation. If you are
using the open source edition it should be `<path>/qt-everywhere-opensource-src-<version>/qtbase/lib/cmake/Qt6`.

\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 \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 \mpfi. This means that this library must be
configured when compiling an application that uses the above number type.

When \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 \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 \mpfi library | CMake |
| `MPFI_LIB_DIR`       | Idem | Environment |
| `MPFI_LIBRARIES`     | Full pathname of the compiled \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 \gmp 4.2 or later and \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 \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 \rs library | CMake |
| `RS_LIB_DIR` | Idem | Environment |
| `RS_LIBRARIES` | Full pathname of the compiled \rs library | CMake |

Similar variables exist for \rs3.

| Variable             | Description           | Type        |
| :-                   | :-                    | :-
| `RS3_DIR` | Directory of \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 \rs3 library | CMake |
| `RS3_LIB_DIR` | Idem | Environment |
| `RS3_LIBRARIES` | Full pathname of the compiled \rs3 library | CMake |


\subsection installation_ntl NTL Library

Some polynomial computations in \cgal's algebraic kernel
are speed up when \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 \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 \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 \ntl library | CMake |
| `NTL_LIB_DIR` | Idem | Environment |
| `NTL_LIBRARIES` | Full pathname of the compiled \ntl library | CMake |

\subsection installation_eigen Eigen Library

\eigen is a header-only template library.
Only the <I>directory</I> containing the header files of \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 \esbtl library in order to read \pdb files.

If \esbtl is not automatically found, setting the `ESBTL_INC_DIR`
environment variable is sufficient.


| Variable             | Description           | Type        |
| :-                   | :-                    | :-             |
| `ESBTL_DIR` | Directory of \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_metis METIS Library

Some BGL examples require the \metis library in order to partition \metis meshes.

If \metis is not automatically found, setting the `METIS_INCLUDE_DIR` and `METIS_LIBRARY`
cmake variables is necessary.


| Variable             | Description           | Type        |
| :-                   | :-                    | :-             |
| `METIS_INCLUDE_DIR` | Directory of \metis default installation | CMAKE |
| `METIS_LIBRARY` | Directory containing the `libmetis.so or .lib` file | CMAKE |


\subsection installation_tbb TBB Library

If \tbb is not automatically found, the user must set some variables, depending on the used version of TBB.

\subsubsection installation_old_tbb TBB 2020 or before
The `TBB_ROOT` and `TBB_ARCH_PLATFORM=<arch>/<compiler>` environment variables 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 \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 |

\subsubsection installation_new_tbb OneTBB
Since OneAPI \tbb version 2021, Intel provides CMake scripts of their own, and the user only have to set the `TBB_DIR`
CMake variable at configuration time. A typical value for `TBB_DIR` is
`/opt/intel/oneapi/tbb/latest/lib/cmake/tbb` on Unix systems, and `C:/dev/OneAPI/tbb/latest/lib/cmake/tbb` on Windows.
Alternatively, the user can instead source the `setvars` script that can be found at `/opt/intel/oneapi/setvars.sh` on Unix and
`C:/dev/OneAPI/setvars.bat` on Windows. It will setup the PATH and all Intel internal variables to be able to easily use
any library of the OneAPI.

\subsection installation_laslib LASlib library

If LASLIB is not automatically found, the following variables must be set:

| Variable             | Description           | Type        |
| :-                   | :-                    | :-             |
| `LASLIB_INCLUDE_DIR` | Directory containing the file `lasreader.hpp` | CMake |
| `LASZIP_INCLUDE_DIR` | Directory containing the file `mydefs.hpp` | CMake |
| `LASLIB_LIBRARIES` | Full pathname of the compiled LASLIB library | CMake |

\subsection installation_OpenCV OpenCV library

The environment variable `OPENCV_DIR` should be set to the directory
containing the file `OpenCVConfig.cmake` provided by OpenCV.

\subsection installation_SCIP SCIP library

The environment variable `SCIP_DIR` should be set to the directory
containing the file `scip-config.cmake` provided by SCIP.

\subsection installation_GLPK GLPK library

If GLPK is not automatically found, the following variables must be set:

| Variable             | Description           | Type        |
| :-                   | :-                    | :-             |
| `GLPK_INCLUDE_DIR` | Directory containing the file `glpk.h` | CMake |
| `GLPK_LIBRARIES` | Full pathname of the compiled GLPK library | 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 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.

*/
