/*!

\page devman_portability Portability Issues

\author Michael Hoffmann (<TT>hoffmann@inf.ethz.ch</TT>)
\author Stefan Schirra
\author Sylvain Pion

This chapter gives an overview of issues related to the
configuration of \cgal that allow you to answer such questions as:
<UL>
<LI>Is \em LEDA / \gmp there? (Section  \ref secleda_gmp_support)
<LI>Which compiler is this? (Section  \ref secwhich_compiler )
</UL>

Also addressed here are issues related to writing code for
non-standard-compliant compilers.  Compilers have made a lot of progress toward
the \cpp-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
<UL>
<LI>supports namespaces
<LI>supports member templates
<LI>support for <TT>std::iterator_traits</TT>.
</UL>

\section secleda_gmp_support Checking for LEDA or GMP support

In the makefiles included for the compilation of every \cgal program
(<I>i.e.</I>, those to which the environment variable <TT>CGAL_MAKEFILE</TT> refers),

we define command line switches that set the flags
\code{.cpp}
CGAL_USE_LEDA, CGAL_USE_GMP
\endcode

iff \cgal is configured with \leda or GMP support, respectively.

\section secboost_support 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 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 <TT>[TR1]</TT> in the list below). However,
wrapping the use within \cgal is generally advised (like what is done
in the `cpp11` namespace).
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.

A list of reasonable Boost libraries to use in the \cgal API is
Graph, Parameter (for packages already using it),
Property Map, Smart Pointers (for packages already using it),
Variant.

Before using a Boost libraries internally, first check whether it is already
used, and if not indicate it while submitting your changes (feature, small-feature
or pull request), or even by sending an email to cgal-develop during the development.


\section secusing_version_macros 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.
\code{.cpp}
#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
\endcode

\section secwhich_compiler Identifying compilers and architectures

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

<TABLE BORDER=2><TR><TD>
  <TABLE CELLSPACING=5 >
  <TR>
    <TD ALIGN=LEFT NOWRAP>
GNU 3.2.1
    <TD ALIGN=LEFT NOWRAP>
`__GNUC__`
    <TD ALIGN=LEFT NOWRAP>
3
  <TR>
    <TD ALIGN=LEFT NOWRAP>
GNU 3.2.1
    <TD ALIGN=LEFT NOWRAP>
`__GNUC_MINOR__`
    <TD ALIGN=LEFT NOWRAP>
2
  <TR>
    <TD ALIGN=LEFT NOWRAP>
GNU 3.2.1
    <TD ALIGN=LEFT NOWRAP>
`__GNUC_PATCHLEVEL__`
    <TD ALIGN=LEFT NOWRAP>
1
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Microsoft VC7.1
    <TD ALIGN=LEFT NOWRAP>
`_MSC_VER`
    <TD ALIGN=LEFT NOWRAP>
1310
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Microsoft VC8.0
    <TD ALIGN=LEFT NOWRAP>
`_MSC_VER`
    <TD ALIGN=LEFT NOWRAP>
1400
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Intel 11.1
    <TD ALIGN=LEFT NOWRAP>
`__INTEL_COMPILER`
    <TD ALIGN=LEFT NOWRAP>
1110
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Clang 2.9
    <TD ALIGN=LEFT NOWRAP>
`__clang_major__`
    <TD ALIGN=LEFT NOWRAP>
2
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Clang 2.9
    <TD ALIGN=LEFT NOWRAP>
`__clang_minor__`
    <TD ALIGN=LEFT NOWRAP>
9
  <TR>
    <TD ALIGN=LEFT NOWRAP>
SUN 5.3
    <TD ALIGN=LEFT NOWRAP>
`__SUNPRO_CC`
    <TD ALIGN=LEFT NOWRAP>
0x530
  <TR>
    <TD ALIGN=LEFT NOWRAP>
SUN 5.10
    <TD ALIGN=LEFT NOWRAP>
`__SUNPRO_CC`
    <TD ALIGN=LEFT NOWRAP>
0x5100
</TABLE>
</TABLE>

There are also flags to identify the architecture.

<TABLE BORDER=2><TR><TD>
  <TABLE CELLSPACING=5 >
  <TR>
    <TD ALIGN=LEFT NOWRAP>
SGI
    <TD ALIGN=LEFT NOWRAP>
`__sgi`
  <TR>
    <TD ALIGN=LEFT NOWRAP>
SUN
    <TD ALIGN=LEFT NOWRAP>
`__sun`
  <TR>
    <TD ALIGN=LEFT NOWRAP>
Linux
    <TD ALIGN=LEFT NOWRAP>
`__linux`
</TABLE>
</TABLE>

\section secproblems_and_workarounds Known problems and workarounds

\subsection secworkaround_macros Macros connected to workarounds/compilers

Some macros are defined according to the detected compiler. This is
done to avoid some `ifdef`s in our actual code.

<DL>
<DT><B><TT>CGAL_LITTLE_ENDIAN</TT></B><DD> set, iff


  <TT>CGAL_CFG_NO_BIG_ENDIAN</TT> is set.
<DT><B><TT>CGAL_BIG_ENDIAN</TT></B><DD> set, iff


  <TT>CGAL_CFG_NO_BIG_ENDIAN</TT> is not set.

<DT><B><TT>CGAL_DEPRECATED</TT></B><DD>


  used to declare a function as deprecated  -  just add it before the
  function declaration.  You may also surround deprecated code with
  <TT>CGAL_NO_DEPRECATED_CODE</TT>, such that it is easy to test
  if a piece of code uses deprecated code or not:
\code{.cpp}
#ifndef CGAL_NO_DEPRECATED_CODE
CGAL_DEPRECATED void foo(int i)
{
 ...
}
#endif // CGAL_NO_DEPRECATED_CODE
\endcode
</DL>

\subsection secvarious_problems Various other problems and solutions

<DL>
<DT><B><B>min and max</B></B><DD>
Visual \cpp 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:
\code{.cpp}
  max BOOST_PREVENT_MACRO_SUBSTITUTION (a, b);
  (max) (a, b);
\endcode

<DT><B><B>Templated member functions</B></B><DD>

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

<DT><B><B>Function parameter matching</B></B><DD>

The function parameter matching capacities of Visual \cpp are rather limited.
Failures occur when your function `bar` is like
\code{.cpp}
  bar(std::some_iterator<std::some_container<T>>....) ...
  ...
  bar(std::some_iterator<std::some_other_container<T>>....) ...
\endcode
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.

<DT><B><B>typedefs of derived classes</B></B><DD>
Microsoft VC++ does not like the following sorts of typedefs that are
standard
\code{.cpp}
class A : public B::C {
        typedef B::C C;
};
\endcode
It says that the typedef is "redefinition".  So such typedefs should be
enclosed by
\code{.cpp}
#ifndef _MSC_VER

#endif
\endcode
This may not be true anymore for recent VC++ versions.
</DL>

*/
