songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

cleanup

This commit is contained in:
Andreas Fabri 2008-12-02 11:32:30 +00:00
parent 731e50518a
commit dd33ad3cfc
3 changed files with 75 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Installation/INSTALL
View File

@ -16,7 +16,8 @@ To install CGAL, you should:
---------------------------
* install CMake, the build system used by CGAL
Required Rel 2.4-patch-7, Recommended Rel 2.6 supporting a crossplatform cmake-gui
Required Rel 2.4-patch-7,
Recommended Rel 2.6 supporting a crossplatform cmake-gui
Download from: http://www.cmake.org/
* install the Boost libraries (http://www.boost.org/ or http://www.boostpro.com/products/free)
@ -31,9 +32,8 @@ To install CGAL, you should:
o Used for exact arithmetic
- gmp (http://gmplib.org/)
- mpfr (http://www.mpfr.org/)
- leda (http://www.algorithmic-solutions.com/leda/index.htm) (commercial)
- gmp (http://gmplib.org/) and mpfr (http://www.mpfr.org/)
- leda as alternative to gmp+mpfr (http://www.algorithmic-solutions.com/leda/index.htm)
o Miscellaneous
@ -301,7 +301,7 @@ To install CGAL, you should:
between static or shared libraries (respectively).
If this is not specified, it defaults to static (FALSE) under Windows and
shared (TRUE) under Linux.
Note that Windows does not support shared libraries.
Note that we do not support shared libraries for CGAL under Windows.
Note that CMake uses the term "Module" to refer to static libraries
(this is relevant in the following section about linker flags).

156
Installation/doc_tex/Installation/appendix.tex
View File

@ -8,12 +8,6 @@
%% $Id$
%%
\section{Using CGAL and LEDA\label{sec:leda}}
\index{LEDA@\leda!support in \cgal}
\cgal\ provides support functions for the \leda\ number types
\texttt{big\_float}, \texttt{integer}, \texttt{rational} and
\texttt{real} (see the files \texttt{<CGAL/leda\_*>}).
\section{Compiler Workarounds}
\index{compilers!workarounds}\index{workaround flags}
@ -26,14 +20,10 @@ know the type \texttt{long long}.
For each compiler a file \texttt{<CGAL/compiler\_config.h>}
\index{files!\texttt{compiler\_config.h}} is defined, with the correct
settings of all flags. This file is generated automatically by the
\texttt{install\_cgal} script, and it is located in the compiler
specific include directory. This directory can be found below
\texttt{include/CGAL/config/};
\index{directories!include/CGAL/config@\texttt{include/CGAL/config}}
\index{directories!compiler specific}\index{compiler specific include
directory} it is named according to the compiler's \cgal-OS
description (cf. Section~\ref{sec:os-compiler-id}).
settings of all flags. This file is generated automatically by
\cmake, and it is located in the \texttt{include} directory of
where you run \cmake. For an in-source configuration this means
\texttt{CGAL-3.4/include}.
The test programs used to generate the \texttt{compiler\_config.h}
file can be found in \texttt{config/testfiles}.
@ -43,9 +33,8 @@ description of the problem. In case of trouble with one of the
\texttt{CGAL\_CFG} flags, it is a good idea to take a look at it.
The file \texttt{CGAL/compiler\_config.h} is included from
\texttt{<CGAL/basic.h>}.\index{files!\texttt{basic.h}} As discussed in
Section~\ref{sec:appl}, \texttt{<CGAL/basic.h>} should always be the
first file included in any application using \cgal.
\texttt{<CGAL/config.h>}.\index{files!\texttt{config.h}}
which is included by all \cgal\ header files.
\subsection{Standard Header Replacements}
\index{compilers!missing standard header files} %
@ -68,26 +57,9 @@ the additions to namespace \ccc{std} by defining the macro
\index{compilers!optimization}
\index{optimization compiler flags}
You may have noticed that we do not set optimizer flags as \texttt{-O}
by default in the include makefiles(see section~\ref{sec:makefiles} for
a description of the makefile structure in \cgal). The main reason
for not doing this is that compilers run much more stable without. On
the other hand, most if not all \cgal\ programs will run considerably
faster when compiled with optimizations! So if you are going for
performance, you should/have to add \texttt{-O}, \texttt{-O3} or maybe
more specific optimizer flags (please refer to the compiler
documentation for that) to the \texttt{CXXFLAGS} variable in your
application makefile:
\begin{alltt}
#---------------------------------------------------------------------#
# compiler flags
#---------------------------------------------------------------------#
# The flag CGAL_CXXFLAGS contains the path to the compiler and is defined
# in the file CGAL_MAKEFILE. You may add your own compiler flags to CXXFLAGS.
CXXFLAGS = $(CGAL_CXXFLAGS) -O
\end{alltt}
%$
By default \cmake\ generates makefiles for Release mode, with
optimization flags switched on, and vcproj files for Release
and Debug mode.
\section{Troubleshooting\label{sec:troubleshooting}}
\index{troubleshooting}
@ -98,13 +70,11 @@ a look at the bug reporting instructions from the \cgal\ homepage:
\begin{alltt}
\cgalhomepage
\end{alltt}
In case of problems or questions related to installation, please
include a copy of the \texttt{install.log} file for reference.
\subsection{Compiler Version Test Execution Failed\label{sec:compvertestfails}}
\index{Compiler version test}\index{compilers!version test}
Possibly already during the startup of the install script, the
Possibly already during the startup of the configuration, the
execution of the compiler version test might fail with the following
(or similar) error message.
\begin{verbatim}
@ -133,28 +103,6 @@ Alternatively, you can build the runtime linker path into the
executables by setting corresponding custom linker flags (cf.
Section~\ref{sec:compiler-menu}).
%% \subsection{Defect in the G++ 3.2 ABI}
%% \label{sec:gcc32abi}
%% \index{gcc@\texttt{g++} 3.2 ABI}\index{compilers!gcc@\texttt{g++} 3.2 ABI}
%% Some versions of \texttt{gcc}, for example \Gcc{3.3.0}, have problems
%% in their \CC-ABI, that surface in error messages similar to the
%% following.
%% %
%% \begin{verbatim}
%% error: due to a defect in the G++ 3.2 ABI, G++ has assigned
%% the same mangled name to two different types.
%% \end{verbatim}
%% %
%% If this occurs to you, please seriously consider upgrading your
%% compiler. This issue is fixed starting from \Gcc{3.3.1}.
%% Alternatively, you can add \texttt{-fabi-version=0} to your custom
%% compiler flags.
%% In interactive mode, this is done via the Compiler Menu,
%% as described in Section~\ref{sec:compiler-menu}. Afterwards rebuild
%% the libraries. But note that changing the \textsc{Abi} might have side
%% effects. Hence, a compiler upgrade is the recommended fix here.
\subsection{The ``Long-Name-Problem'' on Solaris\label{sec:longnamesolaris}}
\index{problems with long names}\index{long name problem}
@ -222,91 +170,19 @@ and \stl\ may give some problems. In order to avoid them, it is highly
recommended to use the latest \leda\ release, since this is what we
test \cgal\ with.
\index{LEDA@\leda!on \bcc}\index{LEDA@\leda!on \msvc}
With \msvc\ or \bcc, \leda\ has to be compiled and used with the
\texttt{LEDA\_STD\_HEADERS} flag set. \cgal\ uses \CC\ standard
conforming headers\footnote{the ones that do not have \texttt{.h}
suffix}, while \leda\ can also work with the old-style header files;
but mixing the styles is strictly forbidden. Before compiling \leda\,
edit the file \texttt{\$(LEDAROOT)/incl/LEDA/system.h} and uncomment
the \texttt{\#define} in the following fragment there.
\begin{alltt}
// use c++ std headers
//#define LEDA_STD_HEADERS
\end{alltt}
\paragraph{\msvc\ Specifics.}
If a binary release of \leda{} is used, make sure that it is one of
them that uses new-style headers. Namely, among the self-extracting
executables, choose one of these that have the name ending with
\texttt{-std.exe}.
%% \subsection{\msvc{}-Specific Problems}
%% \index{msvc@\msvc{}!specific problems}
%% \subsubsection{\msvc{6.0}}
%% This compiler version is no longer supported starting with \cgal\ 3.0.
%% \subsubsection{\msvc{7.0} (\textsc{.NET})}
%% This compiler version is no longer supported starting with \cgal\ 3.1.
%% \medskip
%% \textbf{Other problems.}
%% Here goes an incomplete list of problems encountered, and
%% \cgal-specific workarounds, if available. Compiler error messages are
%% meant to be hints only, and do not pretend to be complete, as well.
%% \begin{enumerate}
%% %
%% \item Internal compiler errors can sometimes be avoided by increasing
%% the amount of memory available to the compiler. Use \texttt{-Zm<number>}
%% option. In \cgal\ makefiles it is set to \texttt{-Zm900}, meaning
%% ``using 900\% out of the usual memory limit''. \label{msvc::Zm}
%% %
%% \item \texttt{[...]/VC98/INCLUDE/xlocnum(268) :
%% error C2587: '\_U' :\\
%% illegal use of local variable as default parameter} can
%% occur\footnote{For instance, in \cgal\ \texttt{Min\_circle}
%% package}. The only workaround we know is to redefine the macro
%% \texttt{\_VIRTUAL} in \texttt{<xlocnum>}\footnote{Yes, in the \msvc\
%% header! You need not edit the actual file though. Copy it to
%% a directory that is searched ahead of the other directories.
%% DISCLAIMER:
%% {\em We do not know if the actions described in this footnote are
%% legal in your country. You are on your own here.}}
%% to be empty. Search for\\
%% \texttt{\#define~\_VIRTUAL~virtual} there and replace it by
%% \texttt{\#define~\_VIRTUAL~}. \label{msvc::VIRTUAL}
%% %
%% \end{enumerate}
\section{Scripts}
\subsection{\texttt{cgal\_create\_makefile\label{sec:create_cgal_makefile}}}
\TTindex{cgal\_create\_makefile}\index{scripts!\texttt{cgal\_create\_makefile}}
\subsection{\texttt{cgal\_create\_cmake_script\label{sec:create_cgal_cmake_script}}}
\TTindex{cgal\_create\_cmake\_script}\index{scripts!\texttt{cgal\_create\_cmake\_script}}
The Bourne-shell script \texttt{cgal\_create\_makefile} is contained in the
The Bourne-shell script \texttt{cgal\_create\_cmake\_script} is contained in the
\cgaldir\texttt{/scripts} directory. It can be used to create
makefiles for compiling \cgal\ applications. Executing
\texttt{cgal\_create\_makefile} in an application directory creates a
\texttt{makefile} containing rules for every \texttt{*.cpp} file there.
\texttt{CmakeLists.txt} files for compiling \cgal\ applications. Executing
\texttt{cgal\_create\_cmake\_script} in an application directory creates a
\texttt{CMakeLists.txt} containing rules for every \texttt{*.cpp} file there.
In order to use this makefile, you have to specify the \cgal\ include
makefile (see section~\ref{sec:makefiles}) to be used. This can be
done be either setting the environment variable
\texttt{CGAL\_MAKEFILE} or by editing the line
\begin{alltt}
# CGAL_MAKEFILE = ENTER_YOUR_INCLUDE_MAKEFILE_HERE
\end{alltt}
of the created makefile. First remove the ``\texttt{\#}'' at the
beginning of the line and then replace the text after ``\texttt{=}''
by the location of the include makefile.
Finally type \texttt{make} to compile the application programs.
%%
%% EOF

96
Installation/doc_tex/Installation/installation.tex
View File

@ -203,7 +203,7 @@ robust numerical and geometric computation. \core\ is not part of
Before building \cgal\ you have to choose the compiler/linker,
set compiler and linker flags, specify which
third-party libraries you want to use and where they can be found,
which \cgal\ components you want to build. Gathering
which \cgal\ libraries you want to build. Gathering
all this information is called {\em configuration}.
For CGAL-3.4, the configuration is generated with \cmake, a
@ -327,7 +327,7 @@ functionality out of the main library. During configuration, you can selected th
shall be built by setting the cmake variable of the form {\tt WITH\_<library>}. By default all
are switched \texttt{ON}.
\begin{center}\index{cgal!components}\index{cgal components}
\begin{center}\index{cgal!libraries}\index{cgal libraries}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|} \hline
@ -352,12 +352,12 @@ are switched \texttt{ON}.
\end{tabular}
\end{center}
If you turn off the configuration of a component you can still configure it manually from the component source directory:
If you turn off the configuration of a library you can still configure it manually from the source directory:
{\ccTexHtml{\scriptsize}{}
\begin{verbatim}
cd ~/CGAL-3.4/src/CGALQt4
cmake . # configures only the CGAL_Qt4 component
cmake . # configures only the CGAL_Qt4 library
\end{verbatim}
}
@ -378,17 +378,16 @@ This is not an issue for solution/project files, as there the user selects the b
\subsection{Static vs.\ Dynamic Libraries }
In windows, the \cgal\ libraries are necessarily static
({\tt .lib}), but on the other platforms, including \texttt{cygwin}, they are by default shared libraries ({\tt .so}).
Under Windows we only support the static versions of the \cgal\ libraries, but on the other platforms
they are by default shared libraries ({\tt .so}).
You can choose to produce static libraries instead by setting the cmake variable {\tt CMAKE\_SHARED\_LIBS=FALSE}
These setting affect the variants of third-party libraries selected whenever the choice is available.
\subsection{Multiple Variants}\label{sec:cmake-out-of-source}
\subsection{Multiple Variants of makefiles}\label{sec:cmake-out-of-source}
While you can choose between release/debug builds, shared/static libraries
(except on Windows), etc...
it is not possible to have both variants on a single configuration. To do that you need to run cmake in a
While you can choose between release/debug builds, shared/static libraries,
it is not possible to generate different variants during a single configuration. To do that you need to run cmake in a
different directory for each variant, each with its own selection of configuration parameters.
\cmake\ stores the resulting makefiles/projectfiles, along with several temporary and auxiliary files such
@ -397,12 +396,12 @@ takes the source files and configuration scripts from whatever directory is indi
\texttt{CMAKE\_SOURCE\_DIR}
The binary and source directory need not be the same, thus, you can configure multiple variants by creating a
distinct directory for each one and running cmake from there. This is known in \cmake\ as
{\em out-of-source configuration}, as opposite to an {\em in-source configuration} as the one shown in the
distinct directory for each configuration and by running cmake from there. This is known in \cmake\ terminology
as {\em out-of-source configuration}, as opposite to an {\em in-source configuration} as showed in the
previous sections.
The \cgal\ directory tree contains directories \cgaldir{}\texttt{/cmake/platforms} and you can create your
variant subdirectory in there:
You can for example generate subdirectories \cgaldir{}\texttt{/cmake/platforms/debug} and
\cgaldir{}\texttt{/cmake/platforms/release} for two configurations:
{\ccTexHtml{\scriptsize}{}
\begin{verbatim}
@ -416,6 +415,8 @@ cmake -DCMAKE_BUILD_TYPE=Release ../../..
\end{verbatim}
}
\subsection{Compiler and Linker Flags}
\cmake\ determines the set of compiler and linker flags to use based on the target compiler and automatically defines
@ -471,8 +472,8 @@ variables but starting with \texttt{CGAL} instead of \texttt{CMAKE}:
If configuration succeeded there will be certain {\em build files} ready to build the libraries.
The nature of the build files depend on the generator used during configuration, but in all cases they
will contain several {\em targets}, one per component, and a default global target corresponding
to all the library components at once.
will contain several {\em targets}, one per library, and a default global target corresponding
to all the libraries at once.
For example, in a UNIX-like environment the default generator produces makefiles and you would
use the \texttt{make} command-line tool as follow:
@ -482,21 +483,50 @@ use the \texttt{make} command-line tool as follow:
cd ~/CGAL-3.4
# build all the selected components at once
# build all the selected library at once
make
# build each selected component independently,
# continuing with the next component in case of error
# due to the '-k' switch.
make -k CGAL CGAL_Core CGAL_PDB CGAL_ImageIO CGAL_Qt3 CGAL_Qt4
# build just the libraries needed for the Surface mesher demo
make CGAL CGAL_ImageIO CGAL_Qt4
\end{verbatim}
}
Notice that according to the rules of 'make', an error in the default target will abort compilation/linking of
all the \cgal\ components (which are part of the same single default target) even if {\tt -k}
is specified, so you need to list the components explicitly to prevent that.
The libraries will all be located in a subdirectory {\tt /lib} under {\tt <CMAKE\_BINARY\_DIR>}
which is \cgaldir\ in case you run an in-source-configuration.
With generators other than {\tt UNIX Makefiles} the resulting build files are solution/project files which
should be launched in an {\sc Ide}, such as Visual Studio or KDevelop3. They will contain the targets described
above which you can manually build as any other solution/project within your {\sc Ide}.
Alternatively, you can build it with the command line version of the {\sc Ide}:
{\ccTexHtml{\scriptsize}{}
\begin{verbatim}
devenv CGAL.sln /Build Debug
\end{verbatim}
}
The "Debug" argument is needed because CMake creates solution files with
all four configurations and you need to explicitly choose one when building
(the other choices are Release, RelWithDebInfo and MinSizeRel).
\begin{ccAdvanced}
The build files produced by cmake are autoconfigured. That is, if you change any
of the dependencies, the build step automatically goes all the way back to the configure step
during the building. This way, once the target has been configured the very first time by
invoking cmake, you don't necessarily need to invoke \texttt{cmake} again. Rebuilding will call
itself \texttt{cmake} and re-generate the build file whenever needed. Keep this in mind if you
configure \cgal\ for the Visual Studio IDE since a build could then change the solution/project
file in-place and VS will prompt you to reload it.
\end{ccAdvanced}
If you have not turned off configuration of examples and/or demos, there will be additional
targets named \texttt{examples} and \texttt{demo}, plus one target for each example and each demo.
@ -517,24 +547,6 @@ make Straight_skeleton_2_demo
\end{verbatim}
}
The libraries will all be located in a subdirectory {\tt /lib} under {\tt <CMAKE\_BINARY\_DIR>}
\footnote{Which need not be the \cgal\ root directory as explained in Section ~\ref{sec:cmake-out-of-source}}
With generators other than {\tt UNIX Makefiles} the resulting build files are solution/project files which
should be launched in an {\sc Ide}, such as Visual Studio or KDevelop3. They will contain the targets described
above which you can manually build as any other solution/project within your {\sc Ide}.
\begin{ccAdvanced}
The build files produced by cmake are autoconfigured. That is, if you change any
of the dependencies, the build step automatically goes all the way back to the configure step
during the building. This way, once the target has been configured the very first time by
invoking cmake, you don't necessarily need to invoke \texttt{cmake} again. Rebuilding will call
itself \texttt{cmake} and re-generate the build file whenever needed. Keep this in mind if you
configure \cgal\ for the Visual Studio IDE since a build could then change the solution/project
file in-place and VS will prompt you to reload it.
\end{ccAdvanced}
\section{Installing \cgal\ Libraries}
On many platforms, library pieces such as headers, docs and binaries