% =============================================================================
% The CGAL Developers' Manual
% Chapter: Portability Issues
% -----------------------------------------------------------------------------
% file   : portability.tex
% authors: Michael Hoffmann <hoffmann@inf.ethz.ch> &
%          Stefan Schirra <stschirr@mpi-sb.mpg.de>
% -----------------------------------------------------------------------------
% $Revision$
% $Date$
% =============================================================================

\chapter{Portability Issues}
\label{chap:portability}
\ccChapterRelease{Chapter Version: 1.0} \\
\ccChapterAuthor{Michael Hoffmann ({\tt hoffmann@inf.ethz.ch}) \&
                 Stefan Schirra ({\tt stschirr@mpi-sb.mpg.de})}
\ccIndexMainItemBegin{portability}

This chapter gives an overview of issues related to the
configuration of \cgal\ that allow you to answer such questions as:
\begin{itemize}
\item Is \leda/\textsc{Gmp}/\textsc{Cln} there? (Section~\ref{sec:leda_gmp_cln_support})
\item What version of \cgal\ am I running? (Section~\ref{sec:which_versions})
\item Which compiler is this? (Section~\ref{sec:which_compiler})
\item Does the compiler support Koenig lookup? (Section~\ref{sec:workaround_flags})
\end{itemize}

Also addressed here are issues related to writing code for 
non-standard-compliant compilers.  Compilers have made a lot of progress toward 
the \CC-standard recently.  But still they do not fully implement it. There 
are a few features you may assume; others you may not assume. The list of 
obsolete workarounds in Section~\ref{sec:obsolete_workarounds} gives some 
indication of what you may assume now.  Especially you may assume that the 
compiler
\begin{itemize}
\item supports namespaces
\item supports member templates
\item support for \texttt{std::iterator\_traits}.
\end{itemize}
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~\ref{sec:workaround_flags} to get an idea of which ``features'' are
still present.  

\ccIndexMainItemBegin{configuration}
\section{Checking for \leda, GMP or CLN support}
\label{sec:leda_gmp_cln_support}
\ccIndexSubsubitem{\leda}{support}{checking for}
%\index{leda support@\leda\ support!checking for}
\index{gmp support@GMP support!checking for}
\index{CLN support@CLN support!checking for}

In the makefiles included for the compilation of every \cgal\ program
(\ie, those to which the environment variable {\tt CGAL\_MAKEFILE} refers),
\ccIndexSubitem{\tt makefile}{\cgal}
\index{CGAL_MAKEFILE variable@{\tt CGAL\_MAKEFILE} variable}
we define command line switches that set the flags 
\begin{verbatim}
CGAL_USE_LEDA, CGAL_USE_GMP, CGAL_USE_CLN
\end{verbatim}
\index{CGAL_USE_LEDA flag@{\tt CGAL\_USE\_LEDA} flag}
\index{flag!for \leda}
\index{CGAL_USE_GMP flag@{\tt CGAL\_USE\_GMP} flag}
\index{flag!for GMP}
\index{CGAL_USE_CLN flag@{\tt CGAL\_USE\_CLN} flag}
\index{flag!for CLN}
iff \cgal\ is configured with \leda, GMP or CLN support, respectively.

\section{Identifying \cgal\ and \leda\ versions}
\label{sec:which_versions}
\ccIndexSubitem{version number}{of \cgal}
\ccIndexSubitem{version number}{of \leda}
\ccIndexSubitem{macros}{for version numbers}

Every release of \cgal\ defines (in \texttt{<CGAL/config.h>}) two
macros:
\begin{description}
\item[\texttt{CGAL\_VERSION}]
     \index{CGAL_VERSION macro@{\tt CGAL\_VERSION} macro}
     -- a textual description of the
     current release (\eg, or 1.2 or 2.2-I-1), and 
\item[\texttt{CGAL\_VERSION\_NR}], 
     \index{CGAL_VERSION_NR macro@{\tt CGAL\_VERSION\_NR} macro}
     --  a numerical description of
     the current release such that more recent releases have higher
     number.

     More precisely, it is defined as \texttt{1vvvmmmiii},
     where \texttt{vvv} is the major release number (currently 002),
     \texttt{mmm} is the minor release number (currently 004), and
     \texttt{iii} is the internal release number (currently 001). For
     public releases, the latter is defined as 100, at least as long as we
     manage to get out something with less than 100 internal releases.
     \texttt{:-)} Examples: for the public release 2.0 this number is 
     1002000100; for internal release 2.2-I-1, it is 1002002001.
\end{description}
 
\noindent \leda\ defines a macro \texttt{\_\_LEDA\_\_}
\index{LEDA macro@{\tt \_\_LEDA\_\_} macro}
in
\texttt{<LEDA/basic.h>} that provides a numerical description of the
current \leda\ version. Examples: for \leda-3.8, it is 380, for
\leda-4.1 it is 410.

\section{Using the version-number and configuration macros and flags}
\label{sec:using_version_macros}
\index{LEDA macro@{\tt \_\_LEDA\_\_} macro!using}
\index{CGAL_USE_LEDA flag@{\tt CGAL\_USE\_LEDA} flag!using}
\index{CGAL_USE_GMP flag@{\tt CGAL\_USE\_GMP} flag!using}
\index{CGAL_USE_CLN flag@{\tt CGAL\_USE\_CLN} flag!using}

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.
\begin{verbatim}
#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 
\end{verbatim}

\section{Identifying compilers and architectures}
\label{sec:which_compiler}
\ccIndexSubitem{compilers}{identifying}
\ccIndexSubitem{macros}{for compiler identification}
\ccIndexSubitem{flag}{for copmiler}

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

\vspace{5mm}\fbox{\begin{tabular}{lll}
Borland 5.4     & \texttt{\_\_BORLANDC\_\_}      & 0x540\\
Borland 5.5     & \texttt{\_\_BORLANDC\_\_}      & 0x550\\
Borland 5.5.1   & \texttt{\_\_BORLANDC\_\_}      & 0x551\\
GNU 2.95        & \texttt{\_\_GNUC\_\_}          & 2\\
GNU 2.95        & \texttt{\_\_GNUC\_MINOR\_\_}   & 95\\
Microsoft VC6.0 & \texttt{\_MSC\_VER}            & 1200\\
Microsoft VC7.0 & \texttt{\_MSC\_VER}            & 1300\\
SGI 7.3         & \texttt{\_COMPILER\_VERSION}   & 730\\
SUN 5.0         & \texttt{\_\_SUNPRO\_CC}        & 0x500\\
\end{tabular}}\vspace{5mm}

\noindent There are also flags to identify the architecture.
\ccIndexSubitem{architecture}{identifying}
\ccIndexSubitem{macros}{for architecture identification}
\ccIndexSubitem{flag}{for architecture}

\vspace{5mm}\fbox{\begin{tabular}{lll}
    SGI   & \texttt{\_\_sgi}\\
    SUN   & \texttt{\_\_sun}\\
    Linux & \texttt{\_\_linux}\\
\end{tabular}}\vspace{5mm}

\section{Known problems and workarounds}
\label{sec:problems_and_workarounds}

For (good) reasons that will not be discussed here, it was decided to
use \CC\ for the development of \cgal. Unfortunately, an international
standard for \CC\ has been sanctioned only recently
\cite{ansi-is14882pl98} and the level of compliance varies widely
between different compilers\index{C++ standard@\CC\ standard}. 
Even basic and vital features such as
partial specialization of class templates and partial ordering of
function templates are still not supported on all compilers.
Especially, though not only, the Microsoft compiler (Visual \CC\ 6.0)
has a broad list of bugs and limitations, and it is not clear whether
or when these are going to be fixed.

\subsection{Workaround flags}
\label{sec:workaround_flags}
\ccIndexMainItemBegin{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 \ccAnchor{http://www.cgal.org/Manual/include/CGAL/config.h}{\texttt{<CGAL/config.h>}}
\ccIndexMainItem{\tt config.h}
using the macros 
listed in Section~\ref{sec:which_compiler} to identify the compiler. 
But most of them are set in the platform-specific configuration files
\ccIndexSubitem{configuration}{file}
\begin{center}
\texttt{<CGAL/config/}{\em os-compiler}\texttt{/CGAL/compiler\_config.h>}
\end{center}
where \textit{os-compiler} refers to a string describing your
operating system and compiler that is defined as follows.
\ccIndexSubitemBegin{flag}{for OS \& compiler}

\begin{center}
  \textit{$<$arch$>$\texttt{\_}$<$os$>$\texttt{-}$<$os-version$>$\texttt{\_}$<$comp$>${\tt
      -}$<$comp-version$>$}
\end{center}

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

\noindent Examples are \texttt{mips\_IRIX64-6.5\_CC-n32-7.30} or {\tt
  sparc\_SunOS-5.6\_g++-2.95}. For more information, see the \cgal\ 
\ccAnchor{http://www.cgal.org/Manual/doc_html/installation/contents.html}{installation guide}.
\ccIndexSubitemEnd{flag}{for OS \& compiler}

This platform-specific configuration file is created during
\ccIndexSubsubitem{configuration}{file}{creation}
\ccIndexMainItem{installation}
installation by the script \texttt{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
\begin{center}
\verb|$(CGAL_ROOT)/config/testfiles|
\end{center}
where \verb|$(CGAL_ROOT)| represents the installation directory for the library.
The names of all testfiles, which correspond to the names of the flags, 
\ccIndexSubitem{workaround flags}{names}
start with ``\texttt{CGAL\_CFG\_}'' followed by
\begin{itemize}
\item \textit{either} a description of a bug ending with
  ``\texttt{\_BUG}''
\item \textit{or} a description of a feature starting with
  ``\texttt{NO\_}''.
\end{itemize}
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.

\InternalOnly{
Which compilers passed which tests can be determined by looking at the 
\ccAnchor{http://www.cs.uu.nl/CGAL/Members/Develop/testsuite/results.html}%
{test suite results page}\lcTex{ ( 
\nonlinkedpath|http://www.cs.uu.nl/CGAL/Members/Develop/testsuite/results.html|)}
for the package \texttt{Configuration}.
}

\noindent Currently (CGAL-2.4-I-8), 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.  See the section on
\ccAnchor{http://www.cgal.org/Manual/doc_html/installation/Chapter_installation.html#Section_17}{troubleshooting} in the installation guide
for more explanation of some of these problems and known workarounds. 

\begin{description}
\item[{\tt CGAL\_CFG\_CCTYPE\_MACRO\_BUG}]~\\
 \index{cctype functions@{\tt cctype} functions!as macros}
 This flag is set if a compiler defines the
 standard C library functions in {\tt cctype} ({\tt isdigit} \etc) as macros.
 According to the standard they have to be functions.

\item[{\tt CGAL\_CFG\_ENUM\_BUG}]~\\
 \ccIndexMainItem{enumeratrion bug}
 This flag is set, if the compiler does not promote enumeration types
 (which depend on a template parameter) correctly when they are used
 as int template arguments (\eg, Borland 5.5).

\item[{\tt CGAL\_CFG\_MATCHING\_BUG\_2}]~\\
 \ccIndexSubitem{matching}{function template}
 This flag is set if the compiler does not match the most
 specialized instance of a function template correctly,
 but complains about multiple matches
 (\eg, SGI 7.2).

\item[{\tt CGAL\_CFG\_MATCHING\_BUG\_3}]~\\
 \ccIndexSubitem{matching}{pointer type arguments}
  This flag is set, if the compiler does not match function arguments 
  of pointer type correctly, when the return type depends on 
  the parameter's type (\eg, sun C++ 5.3).

\item[{\tt CGAL\_CFG\_NO\_AUTOMATIC\_TEMPLATE\_INCLUSION}]~\\
 \ccIndexSubitem{source files}{template implementation files}
 When template implementation files are not included in the source files,
 a compiler may attempt to find the unincluded template bodies
 automatically. For example, suppose that the following conditions are
 all true:
 \begin{itemize}
 \item template entity {\tt ABC::f} is declared in file {\tt xyz.h}
 \item an instantiation of {\tt ABC::f} is required in a compilation
 \item no definition of {\tt ABC::f} appears in the source code processed by
       the compilation
 \end{itemize}
 In this case, the compiler may look to see if the source file {\tt xyz.n}
 exists, where {\tt n} is {\tt .c}, {\tt .C}, {\tt .cpp}, {\tt .CPP}, 
 {\tt .cxx}, {\tt .CXX}, or {\tt .cc}. The flag
 is set if this feature is missing.
 

\item[{\tt CGAL\_CFG\_NO\_BIG\_ENDIAN}]~\\
  \ccIndexMainItem{big-endian}
  \ccIndexMainItem{little-endian}
  The byte order of a machine architecture distinguishes into
  big-endian and little-endian machines.  This flag is
  set if it is a little-endian machine.
 
\item[{\tt CGAL\_CFG\_NO\_ITERATOR\_TRAITS}]~\\
  \ccIndexMainItem{iterator traits}
  The class \texttt{std::iterator\_traits} is part of the \texttt{std} library.
  It is used to access certain properties of iterators, such as their value
  type or iterator category (forward, bidirectional, \etc).
  This flag is set if \texttt{std::iterator\_traits} is not fully supported 
  including their use in a template class, as a default template
  argument, and as a return type of global function.

\item[{\tt CGAL\_CFG\_NO\_KOENIG\_LOOKUP}]~\\
  \ccIndexMainItem{Koenig lookup}
 This flag is set if the compiler does not support the operator Koenig
 lookup. That is, it does not search in the namespace of the arguments for
 the function.

\item[{\tt CGAL\_CFG\_NO\_LOCALE}]~\\
 \ccIndexMainItem{locale}
 This flag is set if a compiler does not know the locale classic. 

\item[{\tt CGAL\_CFG\_NO\_LONGNAME\_PROBLEM}]~\\
 \ccIndexMainItem{long-name problem}
 This flag is set if a compiler (or assembler or linker) has problems 
 with long names. 

\item[{\tt CGAL\_CFG\_NO\_PARTIAL\_CLASS\_TEMPLATE\_SPECIALISATION}]~\\
 \ccIndexMainItem{partial specialization}
 This flag is set if a compiler doesn't support partial specialization 
 of class templates.

\item[{\tt CGAL\_CFG\_NO\_SCOPE\_MEMBER\_FUNCTION\_PARAMETERS}]~\\
 \ccIndexSubitem{scope operator}{with parameters}
 \ccIndexSubitem{inlining}{member function}
 The parameter types of member functions might contain a scope
 operator. This works as long as the member function is implemented
 inline in the class. If the member function is implemented external
 not all compilers are able to parse the scope operators correctly.
 This flag is set if the compiler fails parsing.
 
\item[{\tt CGAL\_CFG\_NO\_STANDARD\_HEADERS}]~\\ 
  \ccIndexSubitem{header files}{standard}
  This flag is
  set if a compiler does not support the new standard headers (\ie,
  without the {\tt .h} suffix).
 
\item[{\tt CGAL\_CFG\_NO\_STDC\_NAMESPACE}]~\\ 
  \index{C standard library!and namespace std@and namespace \ccStyle{std}} 
  \ccIndexSubitem{namespace}{\ccFont std}
  This flag is
  set if a compiler does not put the parts of the standard library
  inherited from the standard C library in namespace {\ccFont std} (only tests
  for the symbols used in \cgal).
 
\item[{\tt CGAL\_CFG\_NO\_TEMPLATE\_FRIEND\_DISTINCTION}]~\\ 
  \ccIndexSubsubitem{template}{function}{friend declaration}
  \ccIndexSubitem{friend declaration}{function template}
  Checks whether the compiler wants to have a \texttt{<>} in friend
  declarations of template functions.

\item[{\tt CGAL\_CFG\_NO\_TMPL\_IN\_TMPL\_DEPENDING\_FUNCTION\_PARAM}]~\\ 
  \ccIndexSubitem{template}{template parameter}
  This flag is set of a compiler does not support member functions that have
  parameter types that are dependent on the template parameter list of the
  class and are implemented outside of the class body (\eg, g++ 2.95.2).
  
\item[{\tt CGAL\_CFG\_NO\_TMPL\_IN\_TMPL\_PARAM}]~\\ 
  \ccIndexSubitem{template}{template parameter}
  Nested
  templates in template parameter, such as ``\texttt{template <
    template <class T> class A>}'' are not supported by any compiler.
  This flag is set if they are not supported.

\item[{\tt CGAL\_CFG\_TYPENAME\_BUG}]~\\
 \ccIndexSubitem{\tt typename}{and template parameter}
 \index{template!argument!with typename@with \texttt{typename}}
 This flag is set if a compiler complains about {\tt typename}, 
 when passing a dependent type as template argument.

\item[{\tt CGAL\_CFG\_USING\_USING\_BUG}]~\\
 \ccIndexSubitem{\tt using}{nested}
 This flag is set if a compiler does not accept a \texttt{using}
 decrlataion referring to a symbol that is again declared by a 
 using declaration.

\end{description}
\ccIndexMainItemEnd{workaround flags}

\subsection{Macros connected to workarounds/compilers}
\label{sec:workaround_macros}
\ccIndexSubitemBegin{macros}{for workarounds}

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

\begin{description}
\item[\texttt{CGAL\_TYPENAME\_MSVC\_NULL}] set to \texttt{typename},
 \index{cgal_typename_msvc_null macro@\texttt{CGAL\_TYPENAME\_MSVC\_NULL} macro}
 \ccIndexSubitem{\tt typename}{and template parameter}
  if {\texttt{CGAL\_CFG\_TYPENAME\_BUG}} is not set and
  empty, otherwise.
\item[\texttt{CGAL\_NULL\_TMPL\_ARGS}] set to \texttt{<>}, if
 \index{cgal_null_tmpl_args macro@\texttt{CGAL\_NULL\_TMPL\_ARGS} macro}
  \ccIndexSubsubitem{template}{function}{friend declaration}
  \ccIndexSubitem{friend declaration}{function template}
  {\texttt{CGAL\_CFG\_NO\_TEMPLATE\_FRIEND\_DISTINCTION}}
  is not set and empty, otherwise.
\item[\texttt{CGAL\_CLIB\_STD}] 
 \index{cgal_clib_std macro@{\tt CGAL\_CLIB\_STD} macro}
  \index{C standard library!and namespace std@and namespace \ccStyle{std}} 
  \ccIndexSubitem{namespace}{\ccFont std}
  set to \texttt{std}, if
  {\texttt{CGAL\_CFG\_NO\_STDC\_NAMESPACE}} is not set and
  empty, otherwise.
\item[\texttt{CGAL\_SCOPE}] 
 \index{cgal_scope macro@{\tt CGAL\_SCOPE} macro}
  \ccIndexSubitem{scope operator}{for VC++}
  empty for the Microsoft compiler and set
  to \texttt{CGAL::}, otherwise.
\item[\texttt{CGAL\_LITTLE\_ENDIAN}] set, iff
 \index{cgal_little_endian macro@\texttt{CGAL\_LITTLE\_ENDIAN} macro}
  \ccIndexMainItem{little-endian}
  {\texttt{CGAL\_CFG\_NO\_BIG\_ENDIAN}} is set.
\item[\texttt{CGAL\_BIG\_ENDIAN}] set, iff
 \index{cgal_big_endian macro@\texttt{CGAL\_BIG\_ENDIAN} macro}
  \ccIndexMainItem{big-endian}
  {\texttt{CGAL\_CFG\_NO\_BIG\_ENDIAN}} is not set.
\end{description}
\ccIndexSubitemEnd{macros}{for workarounds}


\subsection{Various other problems and solutions}
\label{sec:various_problems}

%\subsection{The Long-name Problem}
%\label{sec:long_name_problem}
%
%Because of the decisions to avoid using abbreviations in identifiers
%and to write generic code using template parameters, the names of things
%in \cgal\ can become a little long.  No, make that very long.
%While one can argue that 
%the genericty and readability of the code are good reasons to have such
%long names, some assemblers and compilers are not so easily convinced; 
%they have problems 
%with names that are beyond a certain length. In particular, the Solaris 
%assembler limit names to about ??? and VC++ truncates names used in
%debugging to about 250 bytes and, in general, to about 2000 bytes.  
%For Solaris, the solution is to install the GNU assemblers ({\tt gas}).
%However, since this is not always possible (and is not a solution for
%VC++), one should also define a file of abbreviations for those classes
%where the problems appear.  See the file 
%\ccAnchor{http://www.cgal.org/Manual/include/CGAL/Triangulation_short_names_2.h}{\texttt{<CGAL/Triangulation\_short\_names\_2.h>}}
%for an example of such a file.
%

%\subsection{Partial specialization}
%
%A new feature introduced by the \CC-standard is partial specialization.
%It plays a crucial role in the design of some parts of \cgal. Unfortunately
%the Microsoft compiler does not (yet?) support it. This puts some burden
%on the \cgal\ user, see the section on iterators.

\begin{description}
\item[\textbf{Template Parameters}]
\ 
\begin{itemize}
\item
With Borland, if a class is declared with a template parameter T, say, then
the same name of the template parameter must be used elsewhere in all
the other definitions and declarations for this class.

\item
Borland does not like things like
\begin{center}
\verb|template <class T> class foo { ... T(blah) ... }|
\end{center}

the workaround is
\begin{center}
\verb|template <class T0> class foo { typedef T0 T; ... T(blah) ... }|
\end{center}

\item
For V\CC\ 6.0, the matching of template instances is broken 
\begin{verbatim}
       template < class T >void foo( T, int){}
       template < class T, class R >void foo( T, R){}
\end{verbatim}
would lead to ``multiple matches'' error. 

\item
The V\CC\ 6.0 compiler does not like more than one non-type template
argument.  We had a case with two int parameters where it compiled and
linked seamlessless, but it generated no code.

\end{itemize}


\item[\textbf{{\tt for} loop variables}]

The Visual \CC complier places variables that are declared inside
a \ccc{for} loop header into the surrounding scope, which can often
cause ``multiple declaration'' errors.  The obvious solution is not
to declare variables in the \ccc{for} loop header (or always use
different names for your counters).


\item[\textbf{Templated member functions}]

For Visual \CC\, all the templated member functions must be inline. 

\item[\textbf{namespace qualifier}]

Sometimes one must remove the namespace qualifier from a function
parameter in order to get the correct behavior with Visual \CC.

\item[\textbf{{\tt typename} problem}]
For Visual \CC, the keyword \ccc{typename} must be omitted, when
a type dependent on a template parameter is passed as a template parameter. 
You should use the macro \texttt{CGAL\_TYPENAME\_MSVC\_NULL} 
(Section~\ref{sec:workaround_macros}) in place of the word \texttt{typename} 
in this case.

\item[\textbf{Friend operators}]

For Borland, one must delcare a friend operator before defining it.
This means that often one has to declare the class,
then declare the operator that is meant to be a friend
(since friend declaration of an operator (depending on a template) only 
works for already-declared operators),
then define the class and declare the friend operator there,
and only then define the operator.

\item[\textbf{Function parameter matching}]

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


%\item[\textbf{{\tt using} declaration}]
%
%Then, "using" is a bit broken. For instance, trying to import C-library
%functions into the namespace std leads to rather strange error
%messages. (VC++)
\item[\textbf{default constructors}]
%%
%% see message from Geert-Jan Giezeman to cgal-develop on 6 July 2000
%%

Borland seems to have some problem with default contructors at times;
adding the default constructors explicitly instead of relying on the
compiler to deal with them seems to solve the problem.

\item[\textbf{typedefs of derived classes}]
Microsoft VC++ does not like the following sorts of typedefs that are 
standard
\begin{verbatim}
class A : public B::C {
        typedef B::C C;
};
\end{verbatim}
It says that the typedef is "redefinition".  So such typedefs should be 
enclosed by
\begin{verbatim}
#ifndef _MSC_VER

#endif
\end{verbatim}

\item[\textbf{{\tt std::stack} iterator traits}]
The class \texttt{std::stack} is just a wrapper around a container.
Is has a 2nd template parameter that defaults to \texttt{std::deque},
which is semi-broken under VC++ 6.0 because it has naked pointers as 
iterators, just as \texttt{std::vector} usually does.  You can avoid
problems that arise by explicitly setting the second template parameter
to something that has proper iterator (\eg, \texttt{std::list}).

\item[\textbf{{\tt std::list} iterator inside item class}]

The following program, which attempts to use an iterator over a list of
items inside the item class, does not compile on the Borland compiler:

\begin{verbatim}
#include <vector>

struct E {
 typedef std::list<E>::iterator T2; // compiles not
 typedef std::list<E> T3; // compiles
 typedef std::vector<E>::iterator T1; // compiles
};

int main() {
 E e;
 return 0;
}
\end{verbatim}

This problem was reported to the Borland mailing list and the answer received
indicates that they do not consider this a bug.  Their suggested solution
is to store a list of \texttt{E*} instead of \texttt{E}. Alternatively, one
can use \texttt{std::vector} instead of \texttt{std::list} (since their
implementation of the STL uses pointers for vector iterators) or use 
\texttt{CGAL::In\_place\_list}.

\item[\textbf{parse error in constructions}]
\ccIndexSubitem{parse error}{construction}
The following program will produce a parse error with g++ 3.1.

\begin{verbatim}
#include <CGAL/Segment_circle_2.h> 

typedef CGAL::Segment_circle_2<double> Curve; 
typedef Curve::Segment                 Segment; 
typedef Curve::Point                   Point; 

int main()
{
  Segment s1(Point(0,0), Point(1,1));
  Curve curve(Segment(Point(0,0), Point(1,1))); // parse error
  
  // ...
  return 0;
}
\end{verbatim}

This is a well-known bug in the Gnu compiler 
(see \path|http://gcc.gnu.org/bugs.html#parsing|).
The workaround is to split :

\verb|   Curve curve(Segment(Point(0,0), Point(1,1)));| 

into, {\textit e.g.,} :
\begin{verbatim}
   Segment s (Point(0,0), Point(1,1));
   Curve rude_curve(s);
\end{verbatim}

\item[\textbf{\texttt{std::strcpy} and \texttt{-O2} flag}]
\ccIndexSubitem{optimization flag}{errors when using}

Borland's compiler cannot compile this program when the optimization flag
\texttt{-O2} is used during compilation:
\begin{verbatim}
#include <cstring>

int main() {
  char from[10], to[10];
  std::strcpy(to, from);
  return 0;
}
\end{verbatim}
The following error is produced:
\begin{verbatim}
bcc32.exe -O2 -P bug.C
Borland C++ 5.5.1 for Win32 Copyright (c) 1993, 2000 Borland
bug.C:
Error E2316 bug.C 7: '__strcpy__' is not a member of 'std' in function main()
*** 1 errors in Compile ***
\end{verbatim}

It is believed that this comes from the compiler attempting to produce an
inline version of \texttt{strcpy()} when the optimization is turned on.
Putting \texttt{\#undef strcpy} before the \texttt{strcpy()} fixes it.

\end{description}
\ccIndexMainItemEnd{configuration}

\subsection{Obsolete workarounds}
\label{sec:obsolete_workarounds}
\ccIndexSubitemBegin{workaround flags}{obsolete}

\noindent 
There are also a number of former testfiles that were removed 
after all supported compilers passed them. At the developers' meeting
in 4/1999 in Z\"urich it was decided that the features / bugs corresponding
to removed workaround flags need not to be handled anymore. That is, we
can assume these presence of the features and absence of these bugs in our
code. Developers may remove the workarounds from existing code, though
they are not forced to.

\begin{description}
\item[{\tt CGAL\_CFG\_DYNAMIC\_CAST\_BUG}]~\\
 When a dynamic cast involves a pointer to a not-yet-instantiated 
 template class, some compilers give an error.

\item[{\tt CGAL\_CFG\_INCOMPLETE\_TYPE\_BUG\_1}]~\\
  When a class (\ccc{Cls_P} / \ccc{Cls_Pl}) refers to a not-yet-defined class
  (\ccc{Cls_At}), some compilers give an ``incomplete type error''.  This
  program is used to detect a special case of this problem where
  templates are involved.

\item[{\tt CGAL\_CFG\_INCOMPLETE\_TYPE\_BUG\_3}]~\\
  When a class (\ccc{A}) refers to a not-yet-defined class (\ccc{B}), some
  compilers give an ``incomplete type error''.  This program is used
  to detect a special case of this problem where virtual functions and
  templates are involved.

\item[{\tt CGAL\_CFG\_INCOMPLETE\_TYPE\_BUG\_4}]~\\
  When a class (\ccc{A}) refers to a not-yet-defined class (\ccc{B}), some
  compilers give an ``incomplete type error''.  This program is used
  to detect a special case of this problem where typedefs are
  involved.

\item[{\tt CGAL\_CFG\_INCOMPLETE\_TYPE\_BUG\_5}]~\\
  Some compilers issue an ``incomplete type error'' with some \stl\
  versions if a template type, which has not been instantiated yet, is
  put into an \stl\ vector (\eg, SunPro 4.2 with STLport-3.01). This
  program is used to detect this bug.

\item[{\tt CGAL\_CFG\_MATCHING\_BUG\_1}]~\\
 This flag is set if the compiler does not match a function
 argument of type {\tt typename T::A} correctly.
 (\eg, SGI 7.2)

\item[{\tt CGAL\_CFG\_NO\_ARROW\_OPERATOR}]~\\
  The arrow operator \ccc{operator->()} could not be overloaded by
  some compilers within a class template (SunPro CC 4.2 complains if
  the return value is not a struct). This flag is set
  if it cannot be overloaded. Note that the arrow operator is
  mandatory for iterators according to the Dec. 1996 \CC\ Standard
  draft.

\item[{\tt CGAL\_CFG\_NO\_BUILTIN\_BOOL}]~\\
  This flag is set if a compiler does not know the keyword {\tt bool}.

\item[{\tt CGAL\_CFG\_NO\_CONSTANTS\_IN\_FUNCTION\_TEMPLATES}]~\\
  This flag is set if constants are not accepted in a template
  argument list for template functions.

\item[{\tt CGAL\_CFG\_NO\_CONST\_CAST}]~\\
  This flag is set if the compiler does not support the operator
  \ccc{const_cast}.

\item[{\tt CGAL\_CFG\_NO\_CONST\_REFERENCE\_OVERLOADING}]~\\
  The Gnu g++ 2.7.2.1 compiler is not able to distinguish cleanly between
  overloading with a reference and a const reference parameter if it
  looks for a match with a derived class and reports an ambigious
  overloading resolution. One workaround could be to remove the const
  reference declaration. {\tt g++} will warn of a conversion from \ccc{const
    X\&} to \ccc{X\&} but compiles. Another workaround would be the
  explicit cast to the base class (if known).  This flag 
  is set if the compiler fails to distinguish those functions.

\item[{\tt CGAL\_CFG\_NO\_DEFAULT\_PREVIOUS\_TEMPLATE\_ARGUMENTS}]~\\
  Default template arguments that are dependant on previous template
  arguments like in \ccc{template< class A, class C = vector<A> >}
  are not supported by any compiler. The following definition is set
  if they are not supported. Note that if {\tt
    CGAL\_CFG\_NO\_DEFAULT\_TEMPLATE\_ARGUMENTS} is set, this
  definition must also be set.

\item[{\tt CGAL\_CFG\_NO\_DEFAULT\_TEMPLATE\_ARGUMENTS}]~\\
  This flag is set if a compiler does not support default template
  arguments like \ccc{template< class A = int >}.
 
\item[{\tt CGAL\_CFG\_NO\_DYNAMIC\_CAST}]~\\ 
  This flag is set
  if the compiler does not support the operator \texttt{dynamic\_cast}.

\item[{\tt CGAL\_CFG\_NO\_EXPLICIT}]~\\
  This flag is set if a compiler does not know the keyword
  \ccc{explicit}.

\item[{\tt CGAL\_CFG\_NO\_EXPLICIT\_CLASS\_TEMPLATE\_SPECIALISATION}]~\\
  This flag is set if a compiler does not support full specialization
  of class templates.

\item[{\tt CGAL\_CFG\_NO\_EXPLICIT\_TEMPLATE\_FUNCTION\_ARGUMENT\_SPECIFICATION}]~\\
  This flag is set if a compiler does not like explicit specification
  of template arguments in template function calls.

\item[{\tt CGAL\_CFG\_NO\_LAZY\_INSTANTIATION}]~\\
  Implicit instantiation of a class template does only instantiate
  member functions when needed (Dec. 1996 C++ Standard draft, 14.7.1).
  This implies that member functions that are not instantiated in a
  certain context are allowed to use functionality from the template
  arguments that are not provided by the actual argument. For example,
  the Gnu g++ 2.7.2 does not comply with this. The following definition
  is set if the implicit instantiation does not work in this lazy
  fashion.

\item[{\tt CGAL\_CFG\_NO\_MEMBER\_TEMPLATES}]~\\
  This flag is set if a compiler does not support member function
  templates.

\item[{\tt CGAL\_CFG\_NO\_MUTABLE}]~\\
  This flag is set if a compiler does not know the keyword
  \ccc{mutable}.

\item[{\tt CGAL\_CFG\_NO\_NAMESPACE}]~\\
 This flag is set if a compiler does not know namespaces.

\item[{\tt CGAL\_CFG\_NO\_PARTIAL\_TEMPLATE\_FUNCTION\_ARGUMENT\_SPECIFICATION}]~\\
 This flag is set if a compiler doesn't like explicit partial 
 specification of template arguments in template function calls.

\item[{\tt CGAL\_CFG\_NO\_REINTERPRET\_CAST}]~\\
  This flag is set if the compiler does not support the operator
  \ccc{reinterpret_cast}.

\item[{\tt CGAL\_CFG\_NO\_STATIC\_CAST}]~\\
  This flag is set if the compiler does not support the operator
  \ccc{static_cast}.

\item[{\tt CGAL\_CFG\_NO\_STATIC\_MEMBERS\_IN\_CLASS\_TEMPLATES}]~\\
  The following flag is set if a compiler does not accept static
  members in a template class.
 
\item[{\tt CGAL\_CFG\_NO\_STDIO\_NAMESPACE}]~\\ 
  \index{IO library@I/O library!and namespace std@and namespace \ccStyle{std}}
  \ccIndexSubitem{namespace}{\ccFont std}
  This flag is
  set if a compiler does not put the IO standard library in namespace
  {\ccFont std}.
 
\item[{\tt CGAL\_CFG\_NO\_STD\_NAMESPACE}]~\\ 
  \ccIndexSubitem{namespace}{\ccFont std}
  This flag is
  set if a compiler does not know the namespace \ccStyle{std}.  Some
  compilers know namespace \ccStyle{std} but do not implement namespaces in
  general.

\item[{\tt CGAL\_CFG\_NO\_TEMPLATE\_FUNCTION\_MATCHING}]~\\
  Some compilers (like g++ 2.7.2) follow the old rules for argument
  matching stated in the ARM: template functions have to match
  exactly. In particular, derived classes do not match to base class
  parameters in a template function. The following flag is set if this
  is the case.

\item[{\tt CGAL\_CFG\_NO\_TYPENAME}]~\\
  This flag is set if a compiler does not know the keyword
  \ccc{typename}.

\item[{\tt CGAL\_CFG\_RETURN\_TYPE\_BUG\_1}]~\\
  The following flag is set, if a compiler does not allow the return
  type \ccc{T::A} of a function or a class method.

\item[{\tt CGAL\_CFG\_RETURN\_TYPE\_BUG\_2}]~\\
  The following flag is set, if a compiler does not allow the return
  type \ccc{A<T>::B} of a function or class method.
\end{description}
\ccIndexSubitemEnd{workaround flags}{obsolete}


\InternalOnly{
\section{Requirements and recommendations}
\label{sec:portability_req_and_rec}
}
\InternalOnly{
\noindent
Recommendations:
\begin{itemize}
\item 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.
\item Avoid classes having friend functions and member functions with
      the same name. \texttt{g++ 2.95.*} does not like that. This holds also for
      operators, especially \ccc{operator-()}.
\item Don't use variable declarations in a \texttt{for}-clause. It is a
      feature of the Microsoft compiler not to support this feature of
      the \CC-Standard.
\end{itemize}
}

\ccIndexMainItemEnd{portability}