"Fossies" - the Fresh Open Source Software Archive

Member "doc_html/Manual/preliminaries.html" (25 Feb 2020, 22466 Bytes) of package /linux/misc/CGAL-4.14.3-doc_html.tar.xz:


Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the CGAL-4.14.3-doc_html.tar.xz project site itself.

\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.14.3 - Manual
Preliminaries

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.

License Issues

CGAL is distributed under a dual license scheme, that is under the Gpl/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.

GPL

The Gpl is an Open Source license that, if you distribute your software based on Gpled CGAL data structures,you are obliged to distribute the source code of your software under the Gpl.

The exact license terms can be found at the Free Software Foundation web site: http://www.gnu.org/copyleft/gpl.html.

LGPL

The 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 Gpl, there is no obligation to make the source code of software you build on top of Lgpled CGAL data structures

The exact license terms can be found at the Free Software Foundation web site: http://www.gnu.org/copyleft/lesser.html.

Rationale of the License Choice

We have chosen the Gpl and the 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 Lgpl, and the higher level packages under the Gpl. The package overview states for each package under which license it is distributed.

Commercial Licenses

Users who cannot comply with 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.

License Checking

Users who have a commercial license for specific packages can check that they do not accidentally use packages for which they do not have a commercial license. The same holds for users who want to be sure that they only use packages of CGAL released under the Lgpl.

To enable checking, users have to define one of the following macros:

Macro Name Effect
CGAL_LICENSE_WARNING get a warning during the compilation
CGAL_LICENSE_ERROR get an error during the compilation

The license checking is not a mean to control users as no information is collected or transmitted.

Marking of Special Functionality

In this manual you will encounter sections marked as follows.

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.

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.

Debugging Support

Such functionality is identified this way in the manual.

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.

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.

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++11 Support

CGAL is based on the C++ standard released in 1998 (and later refined in 2003). A new major version of this standard has been released, and is refered to as C++11. 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 or or -std=c++11 depending on the compiler version) 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

CGAL functors support the result_of 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 CGAL::cpp11::result_of<F(Arg)>::type .

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 Checks of Chapter Chapter_STL_Extensions_for_CGAL.

Identifying the Version of CGAL

<CGAL/config.h>

Every release of CGAL defines the following preprocessor macros:

CGAL_VERSION_STR
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
CGAL_VERSION_NR

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.

CGAL_VERSION_NUMBER(M,m,b)
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.

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

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.