CGAL 4.7 - Manual: Portability Issues

\( \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.7 - Manual

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Portability Issues

Author
  Michael Hoffmann (`hoffm.nosp@m.ann@.nosp@m.inf.e.nosp@m.thz..nosp@m.ch`)
  Stefan Schirra
  Sylvain Pion

This chapter gives an overview of issues related to the configuration of CGAL that allow you to answer such questions as:

- Is LEDA / Gmp there? (Section Checking for LEDA or GMP support)
- Which compiler is this? (Section Identifying compilers and architectures )
- Does the compiler support feature X? (Section Workaround flags )

Also addressed here are issues related to writing code for non-standard-compliant compilers. Compilers have made a lot of progress toward the C++-standard recently. But still they do not fully implement it. There are a few features you may assume; others you may not assume. Especially you may assume that the compiler

- supports namespaces
- supports member templates
- support for `std::iterator_traits`.

Still, there are many bugs (sometimes known as "features") left in the compilers. Have a look at the list of (non-obsolete) workarounds in Section Workaround flags to get an idea of which "features" are still present.

# Checking for LEDA or GMP support

In the makefiles included for the compilation of every CGAL program (i.e., those to which the environment variable `CGAL_MAKEFILE` refers),

we define command line switches that set the flags

CGAL_USE_LEDA, CGAL_USE_GMP

iff CGAL is configured with LEDA or GMP support, respectively.

# Using Boost

CGAL code can rely on Boost libraries to some extent.

Boost was shipped with CGAL Release 3.1, and is no longer shipped within CGAL, as it is mainstream, and already distributed with Linux and Cygwin.

Since portability and backward compatibility are a concern in CGAL, we have decided that the list of Boost libraries usable in CGAL will be decided by the CGAL editorial board. The requirements are higher when it appears in the user visible interface than when Boost code is used only internally. Requirements are even lower for code that is not released such as the test-suite. Boost libraries already accepted in the C++ Standard Library Technical Report will be the first easy candidates (these are marked `[TR1]` in the list below).

Finally, the policy is that if a better alternative exists in Boost and is allowed, then CGAL code must use it instead of a CGAL version (which probably must be deprecated and phased out), trying not to break backward compatibility too much.

# Using the version-number and configuration macros and flags

Here is a short example on how these macros can be used. Assume you have some piece of code that depends on whether you have LEDA-4.0 or later.

#ifdef CGAL_USE_LEDA
#include <LEDA/basic.h>
#endif
#if defined(CGAL_USE_LEDA) && __LEDA__ >= 400
... put your code for LEDA 4.0 or later ...
#else
... put your code for the other case ...
#endif

# Identifying compilers and architectures

Every compiler defines some macros that allow you to identify it; see the following table.

GNU 3.2.1 | `__GNUC__` | 3
GNU 3.2.1 | `__GNUC_MINOR__` | 2
GNU 3.2.1 | `__GNUC_PATCHLEVEL__` | 1
Microsoft VC7.1 | `_MSC_VER` | 1310
Microsoft VC8.0 | `_MSC_VER` | 1400
Intel 11.1 | `__INTEL_COMPILER` | 1110
Clang 2.9 | `__clang_major__` | 2
Clang 2.9 | `__clang_minor__` | 9
SUN 5.3 | `__SUNPRO_CC` | 0x530
SUN 5.10 | `__SUNPRO_CC` | 0x5100

There are also flags to identify the architecture.

SGI | `__sgi`
SUN | `__sun`
Linux | `__linux`

# Known problems and workarounds

For (good) reasons that will not be discussed here, it was decided to use C++ for the development of CGAL. An international standard for C++ has been sanctioned in 1998 [3] and the level of compliance varies widely between different compilers, let alone bugs.

## Workaround flags

In order to provide a uniform development environment for CGAL that looks more standard compliant than what the compilers provide, a number of workaround flags and macros have been created. Some of the workaround macros are set in `<CGAL/config.h>`.

using the macros listed in Section Identifying compilers and architectures to identify the compiler. But most of them are set in the platform-specific configuration files

`<CGAL/config/`os-compiler`/CGAL/compiler_config.h>`

where os-compiler refers to a string describing your operating system and compiler that is defined as follows.

\( <\)arch \( >\)`_` \( <\)os \( >\)`-` \( <\)os-version \( >\)`_` \( <\)comp \( >\)`-` \( <\)comp-version \( >\)

\( <\)arch \( >\)
  is the system architecture as defined by `uname -p` or `uname -m`,
\( <\)os \( >\)
  is the operating system as defined by `uname -s`,
\( <\)os-version \( >\)
  is the operating system version as defined by "<TT>uname -r</TT>",
\( <\)comp \( >\)
  is the basename of the compiler executable (if it contains spaces, these are replaced by "-"), and
\( <\)comp-version \( >\)
  is the compiler's version number (which unfortunately can not be derived in a uniform manner, since it is quite compiler specific).

Examples are `mips_IRIX64-6.5_CC-n32-7.30` or `sparc_SunOS-5.6_g++-2.95`. For more information, see the CGAL installation guide .

This platform-specific configuration file is created during

installation by the script `install_cgal`. The flags listed below are set according to the results of test programs that are compiled and run. These test programs reside in the directory

`/config/testfiles`

where `` represents the installation directory for the library. The names of all testfiles, which correspond to the names of the flags,

start with "<TT>CGAL_CFG_</TT>" followed by

- either a description of a bug ending with "<TT>_BUG</TT>"
- or a description of a feature starting with "<TT>NO_</TT>".

For any of these files a corresponding flag is set in the platform-specific configuration file, iff either compilation or execution fails. The reasoning behind this sort of negative scheme is that on standard-compliant platforms there should be no flags at all.

Currently (CGAL-3.4-I-181), we have the following configuration test files (and flags). The short descriptions that are given in the files are included here. In some cases, it is probably necessary to have a look at the actual files to understand what the flag is for. This list is just to give an overview. Be sure to have a look at `Installation/config/testfiles/` to have an up-to-date version of this list.

`CGAL_CFG_LONGNAME_BUG`

  This flag is set if a compiler (or assembler or linker) has problems with long symbol names.

`CGAL_CFG_NET2003_MATCHING_BUG`

  This flag is set, if the compiler does not match a member definition to an existing declaration. This bug shows up on VC 7.1 Beta (`cl1310`).

`CGAL_CFG_NO_LIMITS`

  This flag is set if a compiler does not know the limits.

`CGAL_CFG_NO_LONG_LONG`

  The `long long` built-in integral type is not part of the Iso C++ standard, but many compilers support it nevertheless, since it is part of the Iso C standard. This flag is set if it is supported.

`CGAL_CFG_NO_TMPL_IN_TMPL_PARAM`

      Nested templates in template parameter, such as `template <
      template <class T> class A>` are not supported by any compiler.
      This flag is set if they are not supported.

## Macros connected to workarounds/compilers

Some macros are defined according to certain workaround flags. This is done to avoid some #`ifdef`s in our actual code.

`CGAL_LITTLE_ENDIAN`

  set, iff

  `CGAL_CFG_NO_BIG_ENDIAN` is set.

`CGAL_BIG_ENDIAN`

  set, iff

  `CGAL_CFG_NO_BIG_ENDIAN` is not set.

`CGAL_DEPRECATED`

  used to declare a function as deprecated - just add it before the function declaration. You may also surround deprecated code with `CGAL_NO_DEPRECATED_CODE`, such that it is easy to test if a piece of code uses deprecated code or not:

  #ifndef CGAL_NO_DEPRECATED_CODE
  CGAL_DEPRECATED void foo(int i)
  {
  ...
  }
  #endif // CGAL_NO_DEPRECATED_CODE

## Various other problems and solutions

min and max

  Visual C++ headers (and others) sometimes define `min` and `max` as macros. If you write `max` followed by an opening parenthesis, this can lead to unwanted substitutions. In order to work around it, you should use one of the following tricks:

  max BOOST_PREVENT_MACRO_SUBSTITUTION (a, b);
  (max) (a, b);

Templated member functions

  For SunPRO C++ member function templates with dependent return type must be defined in the body of the class.

Function parameter matching

  The function parameter matching capacities of Visual C++ are rather limited. Failures occur when your function `bar` is like

  bar(std::some_iterator<std::some_container<T>>....) ...
  ...
  bar(std::some_iterator<std::some_other_container<T>>....) ...

  VC++ fails to distinguish that these parameters have different types. A workaround is to add some dummy parameters that are defaulted to certain values, and this affects only the places where the functions are defined, not the places where they are called. This may not be true anymore for recent VC++ versions.

typedefs of derived classes
  Microsoft VC++ does not like the following sorts of typedefs that are standard
  class A : public B::C {
  typedef B::C C;
  };
  It says that the typedef is "redefinition". So such typedefs should be enclosed by
  #ifndef _MSC_VER
  #endif
  This may not be true anymore for recent VC++ versions.

# Requirements and recommendations

Recommendations:

- Workarounds for a compiler bug or a missing feature should not be treated on a per-compiler basis. When you detect a deficiency, you should rather write a short test program that triggers the setting of a flag for this deficiency during configuration.