/*!

\page preliminaries General Information
\cgalAutoToc

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.

These concepts are further developed in the \ref dev_manual.

\section Preliminaries_namespace Namespace CGAL

All names introduced by \cgal, especially those documented in these
manuals, are in a namespace called `CGAL`, which is in global
scope. A user can either qualify names from \cgal by adding
`CGAL::`, e.g., `CGAL::Point_2< CGAL::Exact_predicates_inexact_constructions_kernel >`,
make a single name from \cgal visible in a scope via a `using`
statement, e.g., `using CGAL::Point_2;`, and then use this name
unqualified in this scope, or even make all names from namespace
`CGAL` visible in a scope with `using namespace CGAL;`. The
latter, however, is likely to give raise to name conflicts and is
therefore not recommended.


\section Preliminaries_thread_safety Thread Safety

\cgal is progressively being made thread-safe.  The guidelines which are followed
are:

- it should be possible to use different objects in different threads at the same time (of the same type or not),
- it is not safe to access the same object from different threads at the same time, unless otherwise specified in the class documentation.

If the macro `CGAL_HAS_THREADS` is not defined, then \cgal assumes it can use
any thread-unsafe code (such as static variables).  By default, this macro is not
defined, unless `BOOST_HAS_THREADS` or `_OPENMP` is defined.  It is possible
to force its definition in the compiler options, and it is possible to prevent its
default definition by defining the macro `CGAL_HAS_NO_THREADS`.
If you are using CMake, then you can set the CMake option `CGAL_HAS_NO_THREADS` to
`TRUE`. In addition to defining the preprocessor macro `CGAL_HAS_NO_THREADS`, it will
also avoid CMake to link with the native threads support library on your system.

\section Preliminaries_cc0x C++17 Support

\cgal is based on the version C++17 of the C++ standard.

\section preliminaries_secconmod Concepts and Models

One of the core principles of \cgal is algorithmic <em>genericity</em>, enabling users to call
algorithms with custom data types, and to modify their behavior. To achieve this, and following
the examples of the C++ Standard Template Library (STL) and \boost libraries, \cgal makes heavy
use of C++ templates.

The traditional design pattern used to specify the requirements of these templates is
the <em>concept-model pattern</em>. In this context, a <em>concept</em> is an informal,
abstract set of requirements on a type. A type that satisfies these requirements is said to
<em>model the concept</em>. A concept's requirements are typically syntactic (the set of valid
expressions that a type must support, including member types, member functions, and operators)
and semantic (the expected behavior and invariants of the syntactic requirements) requirements.

For example, the concept `FaceGraph` describes the requirements for a graph data structure that
explicitly maintains faces defined by halfedges. It requires specific accessors, such as a function
to get an incident halfedge from a face, and a function to get an incident face from a halfedge.
Any class that provides these operations with the expected behavior, such as `CGAL::Surface_mesh`
or `CGAL::Polyhedron_3`, can be said to model the `FaceGraph` concept. This allows these different
data structures to be used interchangeably as arguments to many mesh processing algorithms of \cgal.

Concepts can also be <em>refined</em>. A refined concept builds upon an existing one by adding
further requirements. For instance, a `MutableFaceGraph` concept would inherit all the requirements
of `FaceGraph` but add new ones for operations that modify the graph structure, such as adding or
removing faces. Any type that models `MutableFaceGraph` also models `FaceGraph`.

It is important to note that these concepts from the concept-model design pattern should not be
confused with the <a href="https://en.cppreference.com/w/cpp/language/constraints.html">first-class concepts</a> language feature introduced in C++20.
The requirements described by the concept-model pattern are more akin to the pre-existing
<a href="https://en.cppreference.com/w/cpp/named_req.html">C++ Named Requirements</a>
found in the C++ standard, which serve as a formal description of the interface and behavior
required of template arguments. The concept-model pattern provides the philosophical framework
for designing generic libraries like \cgal.

\section preliminaries_secchecks Checks

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 behavior. For details see Section \ref secchecks
of Chapter \ref Chapter_STL_Extensions_for_CGAL.

\section Preliminaries_flags Compile-time Flags to Control Inlining

Making functions inlined can, at times, improve the efficiency of your code.
However this is not always the case and it can differ for a single function
depending on the application in which it is used. Thus \cgal defines a set
of compile-time macros that can be used to control whether certain functions
are designated as inlined functions or not.  The following table lists the
macros and their default values, which are set in one of the \cgal include
files.

| Macro Name                   | Default |
| :---------                   | :------ |
| `CGAL_KERNEL_INLINE`         | inline  |
| `CGAL_KERNEL_MEDIUM_INLINE`  |         |
| `CGAL_KERNEL_LARGE_INLINE`   |         |
| `CGAL_MEDIUM_INLINE`         | inline  |
| `CGAL_LARGE_INLINE`          |         |
| `CGAL_HUGE_INLINE`           |         |

If you wish to change the value of one or more of these macros,
you can simply give it a new value when compiling.  For example, to make
functions that use the macro `CGAL_KERNEL_MEDIUM_INLINE` inline functions,
you should set the value of this macro to `inline` instead of the
default blank.

Note that setting inline manually is very fragile, especially in a template
context.  It is usually better to let the compiler select by himself which
functions should be inlined or not.

\section seccgal_version Identifying the Version of CGAL

Every release of \cgal defines the following preprocessor macros:

<DL>
<DT>`CGAL_VERSION_STR`</DT>
<DD>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</DD>
<DT>`CGAL_VERSION_NR`</DT>
<DD>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.
</DD>
<DT>`CGAL_VERSION_NUMBER(M,m,b)`</DT>
<DD>
a function macro computing the version number macro from the
M.m.b release version. Note that the internal release number is
dropped here. Example: `CGAL_VERSION_NUMBER(3,2,4)` is equal to
1030241000.
</DD>
</DL>

The macro `CGAL_VERSION` is deprecated. It is the same as
`CGAL_VERSION_STR`, but not as a string literal.

*/
