mirror of https://github.com/CGAL/cgal
241 lines
10 KiB
Plaintext
241 lines
10 KiB
Plaintext
/*!
|
|
|
|
\page preliminaries Preliminaries
|
|
\autotoc
|
|
|
|
\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.
|
|
|
|
\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 to 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 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.
|
|
|
|
\advanced Such functionality is identified this way in the manual.
|
|
|
|
\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.
|
|
|
|
\debug Such functionality is identified this way in the manual.
|
|
|
|
\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 # {#Preliminaries_namespace}
|
|
|
|
|
|
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.
|
|
|
|
|
|
# Inclusion Order of Header Files # {#Preliminaries_inclusion}
|
|
|
|
Not all compilers fully support standard header names. \cgal provides
|
|
workarounds for these problems in `CGAL/basic.h`. Consequently, as a
|
|
golden rule, you should always include `CGAL/basic.h` first in your
|
|
programs (or `CGAL/Cartesian.h`, or `CGAL/Homogeneous.h`, since they
|
|
include `CGAL/basic.h` first).
|
|
|
|
|
|
#Thread Safety# {#Preliminaries_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 on the command line, and it is possible to prevent its default
|
|
definition by setting `CGAL_HAS_NO_THREADS` from the command line.
|
|
|
|
|
|
# C++0x Support # {#Preliminaries_cc0x}
|
|
|
|
|
|
\cgal is based on the \CC standard released in 1998 (and later refined in 2003).
|
|
A new major version of this standard is being prepared, and is refered to as C++0x.
|
|
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` 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.
|
|
|
|
#Functor Return Types# {#Preliminaries_functor}
|
|
|
|
\cgal functors support the
|
|
<a href="http://www.boost.org/doc/libs/release/libs/utility/utility.htm#result_of">result_of</a>
|
|
protocol. If a functor `F` has the same return type across all
|
|
overloads of `operator()`, the nested type
|
|
`F::result_type` is defined to be that type. Otherwise the
|
|
return type of calling the functor with an argument of type
|
|
`Arg` can be accessed through
|
|
`boost::result_of<F(Arg)>::type`.
|
|
|
|
\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 Chapter_STL_Extensions_for_CGAL.
|
|
|
|
\section seccgal_version Identifying the Version of CGAL
|
|
|
|
`CGAL/config.h`
|
|
|
|
Every release of \cgal defines the following preprocessor macros:
|
|
|
|
<DL>
|
|
<DT>`CGAL_VERSION`</DT>
|
|
<DD> a textual description of the current release (e.g., or 3.3 or 3.2.1 or 3.2.1-I-15)</DD>
|
|
<DT>`CGAL_VERSION_STR`</DT>
|
|
<DD>same as `CGAL_VERSION` but as a string constant token</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>
|
|
|
|
|
|
#Compile-time Flags to Control Inlining# {#Preliminaries_flags}
|
|
|
|
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.
|
|
|
|
|
|
*/
|