mirror of https://github.com/CGAL/cgal
115 lines
4.9 KiB
Plaintext
115 lines
4.9 KiB
Plaintext
/*!
|
|
|
|
\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_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 behaviour. 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.
|
|
|
|
*/
|