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

1414 lines
67 KiB
TeX
Raw Blame History

%
%% *** CGAL Installation Guide ***
%%
%% file: installation.tex
%%
%% authors: Eric Berberich, Michael Hoffmann, Dima Pasechnik and Wieger Wesselink
%%
%% $Id$
%%
\newcommand{\cmake}{CMake}
\newcommand{\cpack}{CPack}
\newcommand{\nsis}{NullSoft Scriptable Installer}
%% macro for Windows-specific installation
\newcommand{\MSInst}{Windows-specific Installation}
%% macro for g++
\newcommand{\Gcc}[1]{\gnu~\texttt{g++}~{\rm #1}}
\newcommand{\gccurl}{\path'http://gcc.gnu.org/'}
%% macro for SUNPRO CC
\newcommand{\sunprocc}[1]{\textsc{Sunpro}~\texttt{CC}~{\rm #1}}
\newcommand{\sunproccurl}{\path'http://developers.sun.com/sunstudio/'}
%% macro for Borland C++
\newcommand{\bcc}[1]{\textsc{Borland}~\texttt{C++}~{\rm #1}}
\newcommand{\bccurl}{\path'http://www.inprise.com/bcppbuilder/'}
%% macro for Microsoft Visual C++
\newcommand{\msvc}[1]{\textsc{MS}~Visual~\texttt{C++}~{\rm #1}}
\newcommand{\msvcurl}{\path'http://msdn.microsoft.com/en-us/vstudio/'}
%% macro for Intel C++ Compiler
\newcommand{\icl}[1]{\textsc{Intel}~\texttt{C++}~{\rm #1}}
\newcommand{\iclurl}{\path'http://software.intel.com/en-us/intel-compilers/'}
%% macro for Microsoft Windows
\newcommand{\mswin}{\textsc{MS}~Windows}
%% macro for CGAL directory
\newcommand{\cgalrel}{\texttt{CGAL-\cgalversionnumber}}
%% macros for WWW pages
% Now in cgal_manual.sty -- Laurent Rineau, 2010/02/20
%% write index in typewriter type. (c) Susan :-)
\newcommand{\TTindex}[1]{\index{#1@{\tt #1}}}
\newcommand{\TTsubindex}[2]{\index{#1@{\tt #1}!{#2}}}
\newcommand{\TTsubindextwo}[2]{\index{#1!#2@{\tt #2} }}
\section{Introduction}
This document describes how to install \cgal\ on Windows, Unix-like systems, and MacOS X.
Ideally, setting up \cgal\ amounts to:
\begin{alltt}
cd \cgalrel # go to \cgal\ directory
cmake . # configure \cgal
make # build the \cgal\ libraries
\end{alltt}
%% $ This dollar is there to trick syntax highlighting in emacs
Compiling an example shipped with \cgal\ is similar simple:
\begin{alltt}
cd examples/Straight_skeleton_2 # go to an example directory
cmake -DCGAL_DIR=$HOME/\cgalrel . # configure the examples
make # build the examples
\end{alltt}
%% $ This dollar is there to trick syntax highlighting in emacs
Compiling an own non-shipped program is also close:
\begin{alltt}
cd /path/to/program
cgal_create_CMakeLists -s executable
cmake -DCGAL_DIR=$HOME/\cgalrel .
make
\end{alltt}
%% $ This dollar is there to trick syntax highlighting in emacs
where the second line creates a \texttt{CMakeLists.txt} file (check
its options in Section~\ref{sec:create_cgal_CMakeLists} for various details).
In a less ideal world, you probably have to install \cmake, a makefile
generator, and third party libraries. That is what this manual is about.
\section{Prerequisites\label{sec:prerequisites}}
Installing \cgal\ requires a few components to be installed ahead: a
supported compiler (see Section~\ref{sec:compilers}, \cmake, \boost, and at least \gmp, and \mpfr; see
Section~\ref{sec:essential3rdpartysoftware} for more details on
essential third party software.
\section{OS-shipped \cgal\ \label{sec:shippedcgal}}
Some operating systems with package managers offer \cgal\ and its
essential third party software through the manager,
for instance, Mac OS X, or some Linux distribution (e.g.~Debian).
\subsection{\cgal\ on MAC OS X\label{ssec:cgalmacosx}}
For instance, use macports in the following way:
\begin{alltt}
sudo port install cgal
\end{alltt}
or if Qt4 demos are desired
\begin{alltt}
sudo port install cgal +qt4 +universal +demos
\end{alltt}
The setup is similar for homebrew.
\subsection{\cgal\ on Linux\label{ssec:cgaldebian}}
For instance in debian/Ubuntu, use apt-get in the following way:
\begin{alltt}
sudo apt-get install libcgal-dev
\end{alltt}
To get the demos use
\begin{alltt}
sudo apt-get install libcgal-demo
\end{alltt}
Check the \cgal-FAQ for source repository of newest releases.
On other distributions, please consult your package manager documentation.
\section{Downloading \cgal\label{sec:gettingcgal}}
\index{CGAL@\cgal!getting}\index{getting \cgal}
You can obtain the \cgal\ library from \cgaldownloadpage\ and
install it yourself.
After you have downloaded the file \texttt{\cgalrel.tar.gz} containing the
\cgal\ sources, you have to unpack it. Under a Unix-like shell, use the
command:
\begin{alltt}
tar xzf \cgalrel.tar.gz
\end{alltt}
When you are on Windows you may download and run \texttt{\cgalrel-Setup.exe}. It
is a self extracting executable that installs the \cgal\ source, and that allows
you to select and download some precompiled third party libraries.
In both cases the directory \cgalrel\ will be created. This directory
contains the following subdirectories:\index{directories!structure}
\begin{center}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|} \hline
\textbf{directory} & \textbf{contents}\\\hline\hline
\texttt{auxiliary} & precompiled \gmp and \mpfr\ for Windows\\\hline
\texttt{cmake/modules} & modules for finding and using libraries\\\hline
\texttt{config} & configuration files for install script\\\hline
\texttt{demo} & demo programs (most of them need \qt, geomview or other third-party products)\\\hline
\texttt{doc\_html} & documentation (HTML)\\\hline
% \texttt{doc\_pdf} & documentation (PDF)\\\hline
\texttt{examples} & example programs\\\hline
\texttt{include} & header files\\\hline
\texttt{scripts} & some useful scripts (e.g.~for creating CMakeLists.txt files)\\\hline
\texttt{src} & source files\\\hline
\end{tabular}
\end{center}
The directories \texttt{include/CGAL/CORE} and \texttt{src/CGAL\_Core} contain a
distribution of the \core\ library\footnote{\corepage} version~1.7 for
dealing with algebraic numbers. \core\ is not part of \cgal\ and has its
own license.
The directory \texttt{include/CGAL/OpenNL} contains a distribution of the
Open Numerical Library which provides solvers for sparse linear systems,
especially designed for the Computer Graphics community. \opennl\ is not part
of \cgal\ and has its own license.
The only documentation shipped with \cgal{} sources is the present
installation manual. The \cgal{} manual must be downloaded separately from
\cgaldownloadpage.
\section{Supported Compilers\label{sec:compilers}}
In order to build the \cgal\ libraries, you need a \CC\ compiler.
\cgal~\cgalversionnumber\ is supported for the following compilers/operating systems:
\begin{center}\index{compilers!supported}\index{supported compilers}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|} \hline
\textbf{compiler} & \textbf{operating system}\\\hline\hline
\Gcc{3.4 or later}\footnotemark[1]
& Linux / MacOS X
\\ & \mswin\ 95/98/2000/XP/NT4\\\hline
\icl{11.0 or later}\footnotemark[2] & Linux \\\hline
\msvc{9.0, 10.0} (\textsc{Visual Studio 2008 and 2010})\footnotemark[3]
& \mswin\ 95/98/2000/XP/NT4/Vista/7\\\hline
\end{tabular}
\end{center}
\footnotetext[1]{\gccurl}\addtocounter{footnote}{1}
\footnotetext[2]{\iclurl}\addtocounter{footnote}{1}
\footnotetext[3]{\msvcurl}\addtocounter{footnote}{1}
\section{Configuring \cgal\ with CMake\label{sec:configwithcmake}}
In order to configure, build, and install the \cgal\ libraries, examples and
demos, you need \cmake, a cross-platform ``makefile generator''.
If \cmake\ is not installed already you can obtain it from \cmakepage.
\cmake\ version~2.6.2 or higher is required. On Windows, \cmake{}
version~2.8.6 or higher is required, for a proper support of DLL's
generation.
This manual explains only those features of
\cmake\ which are needed in order to build \cgal. Please refer to the
\cmake\ documentation at \cmakepage\ for further details.
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, and
which \cgal\ libraries you want to build. Gathering
all this information is called \emph{configuration}.
The end of the process is marked by the generation of a makefile or a
Visual \CC\ solution and project file that you can use to build \cgal.
\subsection{Configuring \cgal{} with the \cmake{} \textsc{Gui} }
The simplest way to start the configuration is to run the graphical
user interface of \cmake. We recommend to use \texttt{cmake-gui}. It
is available on many platforms as of \cmake\ version~2.6. You must pass as
argument the root directory of \cgal. For example:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
cmake-gui . # Notice the dot to indicate the current directory.
\end{alltt}
}
After \texttt{cmake-gui} opens, press 'Configure'.
A dialog will pop up and you will have to choose what shall gets generated.
After you have made your choice and pressed 'Finish', you will see
the output of configuration tests in the lower portion of the application.
When these tests are done, you will see many
red entries in the upper portion of the application. Just ignore them and press 'Configure'.
By now \cmake\ should have found many libraries and have initialized variables.
If you still find red entries, you have to provide the necessary information.
This typically happens if you have installed software at non-standard locations.
Providing information and pressing 'Configure' goes on until
all entries are grayed. You are now ready to press 'Generate'. Once this is
done, you can quit \texttt{cmake-gui}.
\subsection{Configuring \cgal{} with the cmake command-line tool }
Alternatively, you can run the command-line tool called
\texttt{cmake}. You pass as argument the root directory of
\cgal. For example:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
cmake . # Notice the dot to indicate the current directory.
\end{alltt}
}
The very first thing \cmake\ does is to detect the compiler to use. This
detection is performed by a special \cmake\ module called a
\emph{generator}.
A \cmake\ generator understands the build requirements for a
particular compiler/linker and generates the necessary files for that. For
example, the \emph{UNIX Makefiles} generator understands the GNU chain
of tools (\gcc, ld etc.) and produces makefiles, which can be used to build a
target by a simple call to \texttt{make}. Likewise, the \emph{Visual Studio
2010} generator produces solution and project files and can be manually
launched in the VS IDE to build the target.
Each platform has a default generator, so you only need to select one when
the default is not what you want. For example, under Windows, it is
possible to generate \emph{NMakefiles} instead of Visual Studio project
files in order to build the library with \texttt{nmake}. Running
\texttt{cmake} with no parameters in a command-line prints the list of
available generators supported by your platform and \cmake\ version. If the
generator you need is not listed there, you can try a newer
\cmake\ version, as generators are hardcoded into \cmake, and additional
generators are added with each release.
Since the choice of the generator determines the type of build files to generate, in some cases
you choose a particular generator as a mean to choose a specific compiler (because they use different
build files). For example, the following generates solution files for
use in Visual \CC\ 11.0 on a 64bit machine:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
cmake -G"Visual Studio 11 Win64" .
\end{alltt}
}
In other cases, however, the generator doesn't directly identify a
specific compiler but a chain of tools.
For example, the \texttt{UNIX Makefiles} generator produces \texttt{makefiles} that call some auto-detected
command-line compiler, like \gcc. If you need the makefiles to use a different compiler, you need to
specify the desired compiler in the call to \cmake{}, as in this example:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
cmake -DCMAKE_CXX_COMPILER:FILEPATH=g++-4.7 .
\end{alltt}
}
\cmake\ maintains configuration parameters in so-called \emph{cmake variables}, like the \texttt{CMAKE\_CXX\_COMPILER}
in the example above. These variables \emph{are not environment variables} but \emph{\cmake\ variables}. Some of the \cmake{}
variables represent user choices, such as \texttt{WITH\_examples} or \texttt{CMAKE\_BUILD\_TYPE=Release}, while others
indicate the details of a third-party library, such as \texttt{Boost\_INCLUDE\_DIR} or the compiler flags to use,
such as \texttt{CMAKE\_CXX\_FLAGS}.
The command line tool \texttt{cmake} accepts \cmake\ variables as arguments of the form \texttt{-D<VAR>:<TYPE>=<VALUE>}, as
in the example above, but this is only useful if you already know which variables need to be explicitly defined.
\begin{ccAdvanced}
\cmake\ keeps the variables that a user can manipulate in a so-called \emph{\cmake\ cache}, a simple text file
named \texttt{CMakeCache.txt}, whose entries are of the form VARIABLE:TYPE=VALUE. Advanced users can manually edit this
file, instead of going through the interactive configuration session.
\end{ccAdvanced}
The configuration process not only determines the location of the required dependencies, it also dynamically generates a
\texttt{compiler\_config.h} file, which encodes the properties of your system and a special file named
\texttt{CGALConfig.cmake}, which is used to build programs using \cgal. The
purpose of this file is explained below.
\section{\cgal\ Libraries\label{sec:libraries}}
\cgal\ is split into five libraries. During configuration, you can select the libraries that
you would like to build by setting a \cmake\ variable of the form \texttt{WITH\_<library>}. By default all
are switched \texttt{ON}. All activated libraries are build after
configuration; see~\ref{sec:building}
We next list the libraries and essential 3rd party software
(see~\ref{sec:essential3rdpartysoftware}) for each library:
\begin{center}\index{cgal!libraries}\index{cgal libraries}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|} \hline
\textbf{library} & \textbf{\cmake\ variable} & \textbf{functionality} & \textbf{dependencies}\\\hline\hline
\texttt{CGAL} & \emph{none} & Main library & \gmp, \mpfr, \boost\ (headers)\\
& & & and Boost.Thread (library)\\\hline
\texttt{CGAL\_Core} & \texttt{WITH\_CGAL\_Core} & The CORE library for algebraic numbers.\footnotemark[15] & \gmp\ and \mpfr\\\hline
\texttt{CGAL\_ImageIO} & \texttt{WITH\_CGAL\_ImageIO} & Utilities to read and write image files & \opengl, \zlib, \vtk (optional)\\\hline
\texttt{CGAL\_Qt3} & \texttt{WITH\_CGAL\_Qt3} & \ccc{CGAL::Qt_widget} used by \qt3-based demos & \qt3 and \opengl\\\hline
\texttt{CGAL\_Qt4} & \texttt{WITH\_CGAL\_Qt4} & \ccc{QGraphicsView} support for \qt4-based demos & \qt4 and \opengl\\\hline
\end{tabular}
\end{center}
\footnotetext[15]{CGAL\_Core is not part of \cgal, it is a custom version the \core\ library distributed
by \cgal\ for the user convenience and it has it's own license.}\addtocounter{footnote}{1}
% Remark EBEB: Removed the following. Just reconfigure while CGAL if a library
% was missing
%If you turn off the configuration of a library, you can still configure it manually from the source directory:
%{\ccTexHtml{}{}
%\begin{alltt}
% cd \cgalrel/src/CGALQt4
% cmake . # configures only the CGAL_Qt4 library
%\end{alltt}
%}
\subsection{Debug vs.\ Release}
The \cmake\ variable \texttt{CMAKE\_BUILD\_TYPE} indicates how to build
the libraries. It accepts the values \texttt{Release} or
\texttt{Debug}. The default is \texttt{Release} and should be kept, unless you want to debug
your program.
This is not an issue for solution/project files, as there the user selects the build type from within the IDE.
\subsection{Static vs.\ Shared Libraries }
Shared libraries, also called \emph{dynamic-link libraries}, are built by default
(\texttt{.dll} on Windows, \texttt{.so} on Linux, \texttt{.dylib} on MacOS). You
can choose to produce static libraries instead by setting the \cmake{}
variable \texttt{BUILD\_SHARED\_LIBS} to \texttt{FALSE}. If you use
\texttt{cmake-gui}, a tick box for that variable is available to set it.
These setting affect the variants of third-party libraries (see next
section) selected whenever the choice is available.
\section{Essential Third Party Libraries\label{sec:essential3rdpartysoftware}}
The focus of \cgal\ is on geometry, and we rely on other
highly specialized libraries and software for non-geometric issues,
for instance, for numeric solvers, or visualization. We first list software
that is essential to build (all) libraries of \cgal, that is,
this software must be found during the configuration of \cgal\ for an
actived library of \cgal\ (i.e.~\texttt{WITH\_<library>=ON});
see \ref{sec:3partysoftwareconfig} to specify the location of 3rd
party software.
The libraries \stl\ (shipped with any compiler) and \boost\ are essential to all components (i.e.~libCGAL,
libCGAL\_Core, libCGAL\_ImageIO, libCGAL\_Qt3 and libCGAL\_Qt4).
\subsection{Standard Template Library (\stl) \label{thirdparty:stl}}
\cgal\ heavily uses the \stl, and in particular adopted
many of its design ideas. You can find online
documentation for the \stl\ at various web sites, for instance,
\path+http://www.sgi.com/tech/stl/+, \path+http://www.cplusplus.com/reference/+,
or \path+http://msdn.microsoft.com/en-us/library/1fe2x6kt(VS.100).aspx+.
The \stl\ comes with the compiler, so there is nothing to install.
\subsection{\boost \label{thirdparty:Boost}}
The \boost\ libraries are a set of portable C++ source libraries. Most of
\boost\ libraries are header-only, but a few of them need to be compiled or
installed as binaries.
\cgal\ requires the \boost\ libraries. In particular the header files
and the threading library (\texttt{Boost.Thread} and
\texttt{Boost.System} binaries). Version 1.39 (or higher) are needed.
On Windows, as auto-linking is used, you also need the binaries of
\texttt{Boost.Serialization} and \texttt{Boost.DateTime}, but the
dependency is artificial and used only at link-time: the CGAL libraries do
not depend on the DLL's of those two libraries.
In \cgal\ some demos and examples depend on \texttt{Boost.Program\_options}.
In case the \boost\ libraries are not installed on your system already, you
can obtain them from \boostpage. For Windows you can download an
installer from \boostprodownloadpage.
Since \texttt{Boost.Thread} is required, make sure to either install the precompiled
libraries for your compiler or build \texttt{libboost-thread} and \texttt{libboost-system}.
As on Windows there is no canonical directory for where to find \boost, we recommend that you define the environment variable \ccc{BOOST_ROOT} and set it
to where you have installed \boost, e.g., \path|C:\boost\boost_1_41_0|.
\subsection{\gmp\ and \mpfr\ \label{thirdparty:GMP} \label{thirdparty:MPFR}}
The components libCGAL, libCGAL\_Core, libCGAL\_Qt3 and libCGAL\_Qt4 require
\gmp\ and \mpfr\ which are libraries for multi precision integers and rational numbers,
and for multi precision floating point numbers.
\cgal\ combines floating point arithmetic with exact arithmetic,
in order to be efficient and reliable. \cgal\ has a built-in
number type for that, but \gmp\ and \mpfr\ provide a faster
solution, and we recommend to use them.
Having \gmp\ version 4.2 or higher and \mpfr\ version 2.2.1 or higher
installed is recommended. These libraries can be obtained from
\gmppage\ and \mpfrpage, respectively.
As Visual \CC\ is not properly
supported by the \gmp\ and \mpfr\ projects, we provide precompiled versions
of \gmp\ and \mpfr, which can be downloaded with the installer
\texttt{\cgalrel-Setup.exe}.
\subsection{\zlib \label{thirdparty:zlib}}
\zlib\ is a data compression library, and is essential for the component libCGAL\_ImageIO.
In \cgal\ this library is used in the examples of the \ccRef[Surface Mesh Generation]{Pkg:SurfaceMesher3} package.
If it is not already on your system,
for instance, on Windows, you can download it from \zlibpage.
\subsection{\opengl \label{thirdparty:OpenGL}}
\opengl\ (Open Graphics Library) provides an API for applications that
produce 2D and 3D computer graphics.
In \cgal\ the library is essential for the components libCGAL\_Qt3 and
libCGAL\_Qt4, as well as libCGAL\_ImageIO and for various demos.
Typically, \opengl\ is preinstalled on systems; if not, it can be
downloaded from \openglpage.
\subsection{\qt3\ and \qt4\label{thirdparty:Qt3}\label{thirdparty:Qt4}\label{thirdparty:Qt}}
Qt is a cross-platform application and UI framework.
The component libCGAL\_Qt3 requires \qt3\ installed on your system, while
the component libCGAL\_Qt4 requires \qt4\ installed on your system.
In case \qt\ is not yet installed on your system, you can download
it from \qtpage.
Older demos of \cgal use libCGAL\_Qt3 and \qt3, while newer and newly
developed demos require libCGAL\_Qt4 and \qt4.
Having \qt4\ version 4.3.0 or higher is recommended.
\section{\cgal\ Examples and Demos}
\cgal\ is distributed with a large collection of examples and demos. By default, these are \textbf{not} configured along with
the \cgal\ libraries, unless you set the variables \texttt{WITH\_examples=ON} and/or \texttt{WITH\_demos=ON}.
Nevertheless, even when configured with \cgal, they are not automatically built along with the libraries.
You must build the \texttt{examples} or \texttt{demos} targets (or IDE projects) explicitly.
If you do not plan to compile any demos, you might skip some of the essential libraries (as \qt\ or
\opengl), as the corresponding \cgal-libraries are not linked. But for
your own demos you might need these \cgal-libraries.
\section{Optional Third Party Libraries\label{sec:optional3rdpartysoftware}}
Optional 3rd party software can be used by \cgal\ for various reasons:
Usually certain optional libraries are required to build examples and
demos shipped with \cgal\ or to build your own project using \cgal.
Another reason is to speed up basic tasks.
In order to support these goals, all optional libraries can be \emph{prepared to be
used with \cgal} while configuring \cgal, just in the same way as
essential libraries are configured. Whenever building an example or a
demo (or your own executable), these \emph{preconfigured} libraries
are available when using \cgal.
% EBEB: I removed CORE. We actually do not encourage at this point to
% use non-shipped CORE. This might change with CORE v2.0
%\subsection{CORE \label{thirdparty:Core}}
%
%\core\ is a library that provides a number type for computing with real
%numbers; that is, it allows to represent expressions with square roots
%involved. This package is useful when dealing with curved objecs.
%
%\core\ is needed by the \cgal\ kernel that deals with algebraic
%numbers.
%
%\core\ can be downloaded from \corepage',
%but we recommend to use the version of \core\ that is distributed
%with \cgal.
\subsection{\leda\ \label{thirdparty:Leda}}
\leda\ is a library of efficient data structures and
algorithms. Like \core, \leda\ offers a real number data type.
In \cgal\ this library is optional, and its number types can
be used as an alternative to \gmp, \mpfr, and \core.
Free and commercial editions of \leda\ are available from \ledapage.
\subsection{\mpfi\ \label{thirdparty:MPFI}}
\mpfi\ provides arbitrary precision interval arithmetic with intervals
represented using \mpfr\ reliable floating-point numbers. It is based on
the libraries \gmp\ and \mpfr. In the setting of \cgal, this library is
optional: it is used by some models of the
\ccRef[Algebraic Kernel]{Pkg:AlgebraicKerneld}.
\mpfi\ can be downloaded from \mpfipage. Version 1.4 or higher is
recommended.
\subsection{\rs\ and \rs3\label{thirdparty:RS}\label{thirdparty:RS3}}
\rs{} (Real Solutions) is devoted to the study of the real roots of
polynomial systems with a finite number of complex roots (including
univariate polynomials). In \cgal, \rs{} is used by one model of the
\ccRef[Algebraic Kernel]{Pkg:AlgebraicKerneld}.
\rs{} is freely distributable for non-commercial use. You can download it
from \rspage{}. Actually, the \rs\ package also includes \rs3, the
successor of \rs, which is used in conjunction with it.
The libraries \rs\ and \rs3\ need \mpfi, which can be downloaded from
\mpfipage.
\subsection{\ntl \label{thirdparty:NTL}}
\ntl\ provides data structures and algorithms for signed, arbitrary
length integers, and for vectors, matrices, and polynomials over the
integers and over finite fields. The optional library \ntl\ is used by
\cgal\ to speed up operations of the Polynomial package, such as GCDs.
It is recommended to install \ntl\ with support from \gmp.
\ntl\ can be downloaded from \ntlpage. Version 5.1 or higher is recommended.
% \subsection{\opennl \label{thirdparty:OpenNL}}
% SL: As for Core, OpenNL is distributed by CGAL and the online version is not compatible.
% \opennl\ (Open Numerical Library) is a library used to easily construct and solve
% sparse linear systems.
%
% In \cgal\ it is the default solver for the
% \ccRef[Surface Mesh Parameterization]{Pkg:SurfaceParameterization} package.
%
% The \opennl's main website is \opennlpage.
% \cgal\ includes a version of OpenNL in C++ made especially for \cgal\ by Bruno L\'evy.
\subsection{\eigen \label{thirdparty:Eigen}}
\eigen\ is a \texttt{C++} template library for linear algebra. \eigen\ supports all
matrix sizes, various matrix decomposition methods and sparse linear solvers.
In \cgal, \eigen\ provides sparse linear solvers in the \ccRef[Surface Reconstruction from Point Sets]{Pkg:SurfaceReconstructionFromPointSets}
and the \ccRef[Planar Parameterization of Triangulated Surface Meshes]{Pkg:SurfaceParameterization} packages.
In addition, \eigen\ also provides singular value decomposition for the \ccRef[Estimation of Local Differential Properties]{Pkg:Jet_fitting_3}
and the \ccRef[Approximation of Ridges and Umbilics]{Pkg:Ridges_3} packages.
The \eigen\ web site is \eigenpage.
% \subsection{\taucs \label{thirdparty:Taucs}}
% \taucs\ is a library of sparse linear solvers.
% In \cgal, \taucs\ can be used by the
% \ccRef[Surface Reconstruction from Point Sets]{Pkg:SurfaceReconstructionFromPointSets}
% package, and by the \ccRef[Planar Parameterization of Triangulated Surface Meshes]{Pkg:SurfaceParameterization}
% package. Note that since \cgal\ 4.0, \eigen\ is recommended over \taucs.
% The \taucs\ website is \taucspage.\\
% The latest official version is \taucs\ version 2.2, September 4, 2003.
% Copyright (c) 2001, 2002, 2003 by Sivan Toledo, Tel-Aviv University,
% stoledo@tau.ac.il. All Rights Reserved.\\
% See \taucspage{} for the license and the availability note.\\
% Used by permission of Sivan Toledo.
% The \cgal\ project provides a modified version of \taucs\ in the download
% section of \cgalhomepage. This version fixes some bugs,
% supports 64-bit platforms, and allows a simplified installation process.
% It also contains a complete \lapack\ implementation.
% As Visual~\CC\ is not properly
% supported by the \taucs\ project, we provide a precompiled version of
% \taucs, which can be downloaded with the installer
% \texttt{\cgalrel-Setup.exe}.
% \emph{CAUTION:} Since version 3.3.1, \cgal\ is no longer compatible with the official
% release of \taucs\ (currently 2.2). Make sure to use the modified
% version provided in the download section.
% \subsection{\blas \label{thirdparty:Blas}}
% \blas\ (Basic Linear Algebra Subprograms) is a library of
% basic vector and matrix operations.
% In \cgal, \blas\ can be used by the packages
% \ccRef[Estimation of Local Differential Properties]{Pkg:Jet_fitting_3}
% and \ccRef[Approximation of Ridges and Umbilics]{Pkg:Ridges_3} only.
% Note that if \eigen\ is available on the system, \blas\ is not
% required anymore.
% You can download the official release from \blaspage.
% Alternatively, installing \taucs\ customized for \cgal\ provides \blas.
% \subsection{\lapack \label{thirdparty:Lapack}}
% \lapack\ provides routines for solving systems of simultaneous linear equations,
% least-squares solutions of linear systems of equations, eigenvalue problems,
% and singular value problems.
% In \cgal, \lapack\ can be used by the packages
% \ccRef[Estimation of Local Differential Properties]{Pkg:Jet_fitting_3}
% and \ccRef[Approximation of Ridges and Umbilics]{Pkg:Ridges_3} only.
% Note that if \eigen\ is available on the system, \lapack\ is not
% required anymore.
% You can download the official release from \lapackpage.
% Alternatively, installing \taucs\ customized for \cgal\ provides \lapack.
\subsection{libQGLViewer \label{thirdparty:libQGLViewer}}
libQGLViewer is a 3D widget based on \qt~4's \ccc{QGLWidget}.
In \cgal\ some 3D demos are based on libQGLViewer.
It can be downloaded from \libqglviewerpage.
\subsection{\coin \label{thirdparty:Coin3D}}
\coin\ is an implementation of Open Inventor.
In \cgal, \coin\ is used in the demo
of the \ccRef[Kinetic Data Structures]{Pkg:Kds} package.
You can download it from \coinpage.
\subsection{\esbtl \label{thirdparty:ESBTL}}
The \esbtl\ (Easy Structural Biology Template Library) is a library that allows
the handling of \textsc{Pdb} data.
In \cgal\ the \esbtl\ is used in an example of the
\ccRef[3D Skin Surface Meshing]{Pkg:SkinSurface3} package.
It can be downloaded from \esbtlpage.
\section{Building \cgal \label{sec:building}}
The results of a successful configuration are build files that control the build step.
The nature of the build files depends on the generator used during configuration, but in all cases they
contain several \emph{targets}, one per library, and a default global target corresponding
to all the libraries.
For example, in a \textsc{Unix}-like environment the default generator produces
makefiles. You can use the \texttt{make} command-line tool for the
succeeding build step as follows:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
# build all the selected libraries at once
make
\end{alltt}
}
The resulting libraries are placed in the subdirectory \texttt{lib} under \texttt{<CMAKE\_BINARY\_DIR>}
(which is \cgalrel\ in case you run an in-source-configuration).
With generators other than \texttt{UNIX Makefiles} the resulting build files
are solution and project files which
should be launched in an \textsc{Ide}, such as Visual Studio or KDevelop3. They will contain the targets described
above, which you can manually build as with any other solution/project within your \textsc{Ide}.
Alternatively, you can build it with the command line version of the
\textsc{Visual Studio Ide}:
{\ccTexHtml{}{}
\begin{alltt}
devenv CGAL.sln /Build Debug
\end{alltt}
}
The "Debug" argument is needed because \cmake\ creates solution files for
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 configuration step. 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 turned on the configuration of examples
(\texttt{-DWITH\_examples=ON}) and/or demos (\texttt{-DWITH\_demos=ON}), there will be additional
targets named \texttt{examples} and \texttt{demos}, plus one target for
each example and each demo in the build files.
None of these targets are included by default, so you need to build them explicitly
\emph{after} the \cgal\ libraries have been successfully built.
The targets \texttt{examples} and \texttt{demos} include themselves all the targets
for examples and demos respectively.
{
\ccTexHtml{}{}
\begin{alltt}
# build all examples at once
make examples
# build all demos at once
make demos
# build only the Straight Skeleton demo
make Straight_skeleton_2_demo
\end{alltt}
}
\begin{ccAdvanced}
When using \texttt{UNIX Makefiles} you can find out the exact name of the example or demo target
of a particular package by typing \texttt{make help | grep <package>}.
\end{ccAdvanced}
\section{Installing \cgal \label{sec:installing}}
% prevent links to /usr/include and /usr/lib (\path commands)
\ccHtmlLinksOff%
On many platforms, library pieces such as headers, docs and binaries
are expected to be placed in specific locations. A~typical example
being \path'/usr/include' and \path'/usr/lib' on \textsc{Unix}-like
operating systems or \path'C:/Program Files/' on Windows. The process
of placing or copying the library elements into its standard location
is sometimes referred to as \emph{Installation} and it is a
postprocessing step after the build step.
\ccHtmlLinksOn%
\cmake\ carries out the installation by producing a build target named \emph{install}.
The following example shows a typical session from configuration to
installation in a \textsc{Unix}-like environment:
{\ccTexHtml{}{}
\begin{alltt}
cd \cgalrel
cmake . # configure
make # compile
make install # install
\end{alltt}
}
If you use a generator that produces IDE files (for Visual Studio for instance) there will be an optional
\texttt{INSTALL} project, which you will be able to \emph{``build''} to execute the installation step.
\begin{ccAdvanced}
The files are copied into a directory tree relative to the \emph{installation directory} determined by the
\cmake\ variable \texttt{CMAKE\_INSTALL\_PREFIX}. This variable defaults to \texttt{/usr/local} under \textsc{Unix}-like operating systems
and \path'C:\Program Files' under Windows. If you want to install to a different location, you must override that \cmake{}
variable explicitly \emph{at the configuration time} and not when executing the install step.
\end{ccAdvanced}
The file \texttt{CGALConfig.cmake} is installed by default in
\texttt{\$CMAKE\_INSTALLED\_PREFIX/lib/\cgalrel}.
\section{Example Configuration}
Below is an example output on a linux machine with g++4.4 installed, using \cmake\ 2.8.5,
and the following command-line call to \texttt{cmake}:
{\ccTexHtml{}{}
\begin{alltt}
cmake -DWITH_examples=OFF -DWITH_demos=OFF -DCMAKE_BUILD_TYPE=Release
/path/to/unpacked/CGAL-tarball/
\end{alltt}
}
{\ccTexHtml{}{}
\begin{alltt}
\input{Installation/cmakerun.txt}
\end{alltt}
}
%$ % <- added to close non-correct "math" enviroment ("HOME"), DO NOT DELETE
\section{Multiple Variants of makefiles (out-of-source build)}\label{sec:cmake-out-of-source}
While you can choose between release or debug builds, and shared or static libraries,
it is not possible to generate different variants during a single configuration. You need to run \cmake\ in a
different directory for each variant you are interested in, each with its own selection of configuration parameters.
\cmake\ stores the resulting makefiles and project files, along with several temporary and auxiliary files such
as the variables cache, in the directory where it is executed, called \texttt{CMAKE\_BINARY\_DIR}, but it
takes the source files and configuration scripts from
\texttt{CMAKE\_SOURCE\_DIR}.
The binary and source directories do not need to be the same. Thus, you can configure multiple variants by creating a
distinct directory for each configuration and by running \cmake\ from there. This is known in \cmake\ terminology
as \emph{out-of-source configuration}, as opposite to an \emph{in-source
configuration}, as showed in the previous sections.
You can, for example, generate subdirectories \cgalrel{}\texttt{/cmake/platforms/debug} and
\cgalrel{}\texttt{/cmake/platforms/release} for two configurations, respectively:
{\ccTexHtml{}{}
\begin{alltt}
mkdir \cgalrel/cmake/platforms/debug
cd \cgalrel/cmake/platforms/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../..
mkdir \cgalrel/cmake/platforms/release
cd \cgalrel/cmake/platforms/release
cmake -DCMAKE_BUILD_TYPE=Release ../../..
\end{alltt}
}
\input{Installation/usage}
\section{Summary of \cgal's Configuration Variables}
Most configuration variables are not environment variables but \emph{\cmake\ variables}. They are given in the command line to \cmake\ via the \texttt{-D} option,
or passed from the interactive interface of \texttt{cmake-gui}. Unless
indicated differently, all the variables summarized below are \cmake\ variables.
\index{cgal!cmake-vars-components}\index{cgal configuration variables - components }
\subsection{Component selection}
The following boolean variables indicate which \cgal\ components to configure and build. Their values can be ON or OFF.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|} \hline
\textbf{Variable} & \textbf{Default value}\\\hline\hline
\texttt{WITH\_examples} & OFF\\\hline
\texttt{WITH\_demos} & OFF\\\hline
\texttt{WITH\_CGAL\_Core} & ON\\\hline
\texttt{WITH\_CGAL\_Qt3} & ON\\\hline
\texttt{WITH\_CGAL\_Qt4} & ON\\\hline
\texttt{WITH\_CGAL\_ImageIO} & ON\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-flags}\index{cgal configuration cmake variables - flags}
\subsection{Compiler and Linker Flags}
The following variables specify compiler and linker flags. Each variable holds a
space-separated list of command-line switches for the compiler and linker and
their default values are automatically defined by \cmake\ based on the target platform.
Have in mind that these variables specify a list of flags, not just one
single flag. If you provide your own definition for a variable, you will \emph{entirely} override
the list of flags chosen by \cmake\ for that particular variable.
The variables that correspond to both debug and release builds are always
used in conjunction with those for the specific build type.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|} \hline
\textbf{Program} & \textbf{Both Debug and Release} & \textbf{Release only} & \textbf{Debug Only}\\\hline\hline
C++ Compiler & \texttt{CMAKE\_CXX\_FLAGS} & \texttt{CMAKE\_CXX\_FLAGS\_RELEASE} & \texttt{CMAKE\_CXX\_FLAGS\_DEBUG}\\\hline
Linker (shared libs) & \texttt{CMAKE\_SHARED\_LINKER\_FLAGS} & \texttt{CMAKE\_SHARED\_LINKER\_FLAGS\_RELEASE} & \texttt{CMAKE\_SHARED\_LINKER\_FLAGS\_DEBUG}\\\hline
Linker (static libs) & \texttt{CMAKE\_MODULE\_LINKER\_FLAGS} & \texttt{CMAKE\_MODULE\_LINKER\_FLAGS\_RELEASE} & \texttt{CMAKE\_MODULE\_LINKER\_FLAGS\_DEBUG}\\\hline
Linker (programs) & \texttt{CMAKE\_EXE\_LINKER\_FLAGS} & \texttt{CMAKE\_EXE\_LINKER\_FLAGS\_RELEASE} & \texttt{CMAKE\_EXE\_LINKER\_FLAGS\_DEBUG}\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-extra-flags}\index{cgal configuration cmake variables - additional flags}
\subsubsection{Additional Compiler and Linker Flags}
The following variables can be used to \emph{add} flags without overriding the ones
defined by cmake.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|}\hline
\textbf{Program} & \textbf{Both Debug and Release} & \textbf{Release only} & \textbf{Debug Only}\\\hline\hline
C++ Compiler & \texttt{CGAL\_CXX\_FLAGS} & \texttt{CGAL\_CXX\_FLAGS\_RELEASE} & \texttt{CGAL\_CXX\_FLAGS\_DEBUG}\\\hline
Linker (shared libs) & \texttt{CGAL\_SHARED\_LINKER\_FLAGS} & \texttt{CGAL\_SHARED\_LINKER\_FLAGS\_RELEASE} & \texttt{CGAL\_SHARED\_LINKER\_FLAGS\_DEBUG}\\\hline
Linker (static libs) & \texttt{CGAL\_MODULE\_LINKER\_FLAGS} & \texttt{CGAL\_MODULE\_LINKER\_FLAGS\_RELEASE} & \texttt{CGAL\_MODULE\_LINKER\_FLAGS\_DEBUG}\\\hline
Linker (programs) & \texttt{CGAL\_EXE\_LINKER\_FLAGS} & \texttt{CGAL\_EXE\_LINKER\_FLAGS\_RELEASE} & \texttt{CGAL\_EXE\_LINKER\_FLAGS\_DEBUG}\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-misc}\index{cgal configuration cmake variables - miscellaneous}
\subsection{Miscellaneous Variables}
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type} & \textbf{Default value}\\\hline\hline
\texttt{CMAKE\_BUILD\_TYPE} & Indicates type of build. Possible values are 'Debug' or 'Release' & CMake & Release\\\hline
\texttt{CMAKE\_CXX\_COMPILER} & Full-path to the executable corresponding to the C++ compiler to use. & CMake & platform-dependent\\\hline
\texttt{CXX} & Idem & Environment & Idem\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-exe}\index{cgal configuration cmake variables - for programs only}
\subsubsection{Variables used only when building programs (such as demos or examples)}
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type} & \textbf{Default value}\\\hline\hline
\texttt{CGAL\_DIR} & Full-path to the binary directory where \cgal\ was configured & Either CMake or Environment & \emph{none}\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep}\index{cgal configuration cmake variables - dependencies}
\subsection{Variables providing information about 3rd-party libraries}\label{sec:3partysoftwareconfig}
The following variables provide information about the availability and
location of the 3rd party libraries used by \cgal. \cmake\ automatically
searches for dependencies so you need to specify these variables if
\cmake\ was unable to locate something. This is indicated by a value ending in
\texttt{NOTFOUND}.
Since 3rd-party libraries are system wide, many of the \cmake\ variables listed below can alternatively
be given as similarly-named environment variables instead. Keep in mind that you must provide one or the
other but never both.
\index{cgal!general-config-cmake-vars-dep-boost}\index{cgal configuration cmake variables - dependencies - boost}
\subsubsection{\boost\ libraries}
In most cases, if \boost\ is not automatically found, setting the \texttt{BOOST\_ROOT}
variable is enough. If it is not, you can specify the header and library
directories individually. You can also provide the full pathname to a specific compiled library
if it cannot be found in the library directory or its name is non-standard.
By default, when \boost\ binary libraries are needed, the shared versions
are used if present. You can set the variable
\texttt{CGAL\_Boost\_USE\_STATIC\_LIBS} to \texttt{ON} if you want to link
with static versions explicitly.
On Windows, if you link with \boost\ shared libraries, you must ensure that
the \texttt{.dll} files are found by the dynamic linker, at run time.
For example, you can add the path to the \boost\ \texttt{.dll} to the
\texttt{PATH} environment variable.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{BOOST\_ROOT}\footnotemark[16] & Root directory of your \boost\ installation & Either CMake or Environment\\\hline
\texttt{Boost\_INCLUDE\_DIR} & Directory containing the \texttt{boost/version.hpp} file & CMake\\\hline
\texttt{BOOST\_INCLUDEDIR} & Idem & Environment\\\hline
\texttt{Boost\_LIBRARY\_DIRS} & Directory containing the compiled \boost\ libraries & CMake\\\hline
\texttt{BOOST\_LIBRARYDIR} & Idem & Environment\\\hline
\texttt{Boost\_\emph{(xyz)}\_LIBRARY\_RELEASE} & Full pathname to a release build of the compiled 'xyz' \boost\ library & CMake\\\hline
\texttt{Boost\_\emph{(xyz)}\_LIBRARY\_DEBUG} & Full pathname to a debug build of the compiled 'xyz' \boost\ library & CMake\\\hline
\end{tabular}
}
\footnotetext[16]{The environment variable can be spelled either \texttt{BOOST\_ROOT} or \texttt{BOOSTROOT}}\addtocounter{footnote}{1}
\index{cgal!general-config-cmake-vars-dep-gmp-mpfr}\index{cgal configuration cmake variables - dependencies - gmp, mpfr}
\subsubsection{\gmp\ and \mpfr\ libraries}
Under Windows, auto-linking is used, so only the \emph{directory}
containing the libraries is needed and you would specify \texttt{GMP|MPFR\_LIBRARY\_DIR} rather than
\texttt{GMP|MPFR\_LIBRARIES}. On the other hand, under Linux the actual library filename is needed.
Thus you would specify \texttt{GMP|MPFR\_LIBRARIES}. In no case you need to specify both.
\cgal\ uses both \gmp\ and \mpfr\, so both need to be supported. If either of them is unavailable the
usage of \gmp\ and of \mpfr\ will be disabled.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{WITH\_GMP} & Indicates whether to search and use \gmp\/\mpfr\ or not & CMake\\\hline
\texttt{GMP\_DIR} & Directory of \gmp\ default installation & Environment\\\hline
\texttt{GMP\_INCLUDE\_DIR} & Directory containing the \texttt{gmp.h} file & CMake\\\hline
\texttt{GMP\_INC\_DIR} & Idem & Environment\\\hline
\texttt{GMP\_LIBRARIES\_DIR} & Directory containing the compiled \gmp\ library & CMake\\\hline
\texttt{GMP\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{GMP\_LIBRARIES} & Full pathname of the compiled \gmp\ library & CMake\\\hline
\texttt{MPFR\_INCLUDE\_DIR} & Directory containing the \texttt{mpfr.h} file & CMake\\\hline
\texttt{MPFR\_INC\_DIR} & Idem & Environment\\\hline
\texttt{MPFR\_LIBRARIES\_DIR} & Directory containing the compiled \mpfr\ library & CMake\\\hline
\texttt{MPFR\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{MPFR\_LIBRARIES} & Full pathname of the compiled \mpfr\ library & CMake\\\hline
\end{tabular}
}
Under Linux, the \gmpxx\ is also searched for, and you may specify the following variables:
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{GMPXX\_DIR} & Directory of \gmpxx\ default installation & Environment\\\hline
\texttt{GMPXX\_INCLUDE\_DIR} & Directory containing the \texttt{gmpxx.h} file & CMake\\\hline
\texttt{GMPXX\_LIBRARIES} & Full pathname of the compiled \gmpxx\ library & CMake\\\hline
\end{tabular}
}
% TODO EBEB zlib, OpenGL?
\index{cgal!general-config-cmake-vars-dep-qt3}\index{cgal configuration cmake variables - dependencies - qt3}
\subsubsection{\qt3\ library}
In most cases, if \qt3\ is not automatically found, setting the \texttt{QTDIR}
environment variable is sufficient. If it is not, you can specify the directory containing
the header files and the full pathnames of the \qt3\ libraries.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{QTDIR} & Root directory of the \qt3\ library & Environment\\\hline
\texttt{QT3\_INCLUDE\_DIR} & Directory containing the \texttt{qt.h} file & CMake\\\hline
\texttt{QT3\_QT\_LIBRARY} & Full pathname to the qt library of \qt3\ & CMake\\\hline
\texttt{QT3\_QTMAIN\_LIBRARY} & Full pathname to the qtmain library of \qt3\ & CMake\\\hline
\texttt{QT3\_QASSISTANTCLIENT\_LIBRARY} & Full pathname to the qassistantclient library of \qt3\ & CMake\\\hline
\texttt{QT3\_MOC\_EXECUTABLE} & Full pathname to the moc executable of \qt3\ & CMake\\\hline
\texttt{QT3\_UIC\_EXECUTABLE} & Full pathname to the uic executable of \qt3\ & CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-qt4}\index{cgal configuration cmake variables - dependencies - qt4}
\subsubsection{\qt4\ library}
The \cmake\ scripts that search for \qt4\ can use the introspection feature
of the tool \texttt{qmake} included in \qt4\ distributions. If \qt4\ is not
automatically found, it is sufficient to set the \texttt{PATH}
environment variable, so that \qt4\ \texttt{qmake} tool is in the path, and
before \qt3\ \texttt{qmake} if that one exists. One can alternatively set the
\cmake\ variable \texttt{QT\_QMAKE\_EXECUTABLE}. The following variables
should be then assigned automatically by \cmake{}.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{QT\_INCLUDE\_DIR} & Directory containing the \texttt{QtCore/qglobal.h} file & CMake\\\hline
\texttt{QT\_LIBRARY\_DIR} & Directory containing the compiled \qt4\ libraries & CMake\\\hline
\texttt{QT\_\emph{(xyz)}\_LIBRARY} & Full pathname to the compiled 'xyz' \qt4\ library\footnotemark[17] & CMake\\\hline
\texttt{QT\_QMAKE\_EXECUTABLE} & Full pathname to the qmake executable of \qt4\ & CMake\\\hline
\texttt{QT\_MOC\_EXECUTABLE} & Full pathname to the moc executable of \qt4\ & CMake\\\hline
\texttt{QT\_UIC\_EXECUTABLE} & Full pathname to the uic executable of \qt4\ & CMake\\\hline
\end{tabular}
}
\footnotetext[17]{If both release and debug versions are available, this variable contains a list
of the following form: '\texttt{optimized;<fullpath-to-release-lib>;debug;<fullpath-to-debug-lib>}', where
the '\texttt{optimized}' and '\texttt{debug}' tags should appear verbatim.}\addtocounter{footnote}{1}
\index{cgal!general-config-cmake-vars-dep-leda}\index{cgal configuration cmake variables - dependencies - leda}
\subsubsection{\leda\ library}
When the \leda\ libraries are not automatically found, yet they are installed on the system
with base names 'leda' and 'ledaD' (for the release and debug versions resp.), it might
be sufficient to just indicate the library directory via the \texttt{LEDA\_LIBRARY\_DIRS} variable.
If that doesn't work because, for example, the names are different, you can provide the full pathnames of each variant
via \texttt{LEDA\_LIBRARY\_RELEASE} and \texttt{LEDA\_LIBRARY\_DEBUG}.
The variables specifying definitions and flags can be left undefined if they are not needed by \leda.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{WITH\_LEDA} & Indicates whether to search and use \leda\ or not & CMake\\\hline
\texttt{LEDA\_DIR} & Directory of \leda\ default installation & Environment\\\hline
\texttt{LEDA\_INCLUDE\_DIR} & Directory containing the file \texttt{LEDA/system/basic.h} & CMake\\\hline
\texttt{LEDA\_LIBRARIES} & Directory containing the compiled \leda\ libraries & CMake\\\hline
\texttt{LEDA\_INC\_DIR} & Directory containing the file \texttt{LEDA/system/basic.h} & Environment\\\hline
\texttt{LEDA\_LIB\_DIR} & Directory containing the compiled \leda\ libraries & Environment\\\hline
\texttt{LEDA\_LIBRARY\_RELEASE} & Full pathname to a release build of the \leda\ library & Either CMake\\\hline
\texttt{LEDA\_LIBRARY\_DEBUG} & Full pathname to a debug build of the \leda\ library & Either CMake\\\hline
\texttt{LEDA\_DEFINITIONS} & Preprocessor definitions & Either CMake\\\hline
\texttt{LEDA\_CXX\_FLAGS} & Compiler flags & Either CMake\\\hline
\texttt{LEDA\_LINKER\_FLAGS} & Linker flags & Either CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-mpfi}\index{cgal configuration cmake variables - dependencies - mpfi}
\subsubsection{\mpfi\ library}
\cgal\ provides a number type based on this library, but the \cgal\ library
itself does not depend on \mpfi. This means that this library must be
configured when compiling an application that uses the above number type.
When \mpfi\ files are not on the standard path, the locations of the headers
and library files must be specified by using environment variables.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{MPFI\_DIR} & Directory of \mpfi\ default installation & Environment\\\hline
\texttt{MPFI\_INCLUDE\_DIR} & Directory containing the \texttt{mpfi.h} file & CMake\\\hline
\texttt{MPFI\_INC\_DIR} & Idem & Environment\\\hline
\texttt{MPFI\_LIBRARIES\_DIR} & Directory containing the compiled \mpfi\ library & CMake\\\hline
\texttt{MPFI\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{MPFI\_LIBRARIES} & Full pathname of the compiled \mpfi\ library & CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-rs}\index{cgal configuration cmake variables - dependencies - rs}
\subsubsection{\rs\ and \rs3\ library}
As said before, only the \cgal{} univariate algebraic kernel depends on the
library \rs. As the algebraic kernel is not compiled as a part of the \cgal{}
library, this library is not detected nor configured at installation time.
\cmake{} will try to find \rs{} in the standard header and library
directories. When it is not automatically detected, the locations of the
headers and library files must be specified using environment variables.
\rs{} needs \gmp~4.2 or later and \mpfi~1.3.4 or later. The variables
related to the latter library may also need to be defined.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{RS\_DIR} & Directory of \rs\ default installation & Environment\\\hline
\texttt{RS\_INCLUDE\_DIR} & Directory containing the \texttt{rs\_exports.h} file & CMake\\\hline
\texttt{RS\_INC\_DIR} & Idem & Environment\\\hline
\texttt{RS\_LIBRARIES\_DIR} & Directory containing the compiled \rs\ library & CMake\\\hline
\texttt{RS\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{RS\_LIBRARIES} & Full pathname of the compiled \rs\ library & CMake\\\hline
\end{tabular}
}
Similar variables exist for \rs3.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{RS3\_DIR} & Directory of \rs3 default installation & Environment\\\hline
\texttt{RS3\_INCLUDE\_DIR} & Directory containing the \texttt{rs3\_fncts.h} file & CMake\\\hline
\texttt{RS3\_INC\_DIR} & Idem & Environment\\\hline
\texttt{RS3\_LIBRARIES\_DIR} & Directory containing the compiled \rs3\ library & CMake\\\hline
\texttt{RS3\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{RS3\_LIBRARIES} & Full pathname of the compiled \rs3\ library & CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-ntl}\index{cgal configuration cmake variables - dependencies - ntl}
\subsubsection{\ntl\ library}
Some polynomial computations in \cgal's algebraic kernel
are speed up when \ntl\ is available.
As the algebraic kernel is not compiled as a part of the \cgal{}
library, this library is not detected nor configured at installation time.
\cmake{} will try to find \ntl{} in the standard header and library
directories. When it is not automatically detected, the locations of the
headers and library files must be specified using environment variables.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{NTL\_DIR} & Directory of \ntl\ default installation & Environment\\\hline
\texttt{NTL\_INCLUDE\_DIR} & Directory containing the \texttt{NTL/ZZX.h} file & CMake\\\hline
\texttt{NTL\_INC\_DIR} & Idem & Environment\\\hline
\texttt{NTL\_LIBRARIES\_DIR} & Directory containing the compiled \ntl\ library & CMake\\\hline
\texttt{NTL\_LIB\_DIR} & Idem & Environment\\\hline
\texttt{NTL\_LIBRARIES} & Full pathname of the compiled \ntl\ library & CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-eigen}\index{cgal configuration cmake variables - dependencies - eigen}
\subsubsection{\eigen{} library}
\eigen\ is a header-only template library.
Only the {\em directory} containing the header files of \eigen\ 3.1 (or greater) is needed.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{EIGEN3\_DIR} & Directory of \eigen\ default installation & Environment\\\hline
\texttt{EIGEN3\_INCLUDE\_DIR} & Directory containing the file \texttt{signature\_of\_eigen3\_matrix\_library} & CMake\\\hline
\texttt{EIGEN3\_INC\_DIR} & Idem & Environment\\\hline
\end{tabular}
}
% \index{cgal!general-config-cmake-vars-dep-taucs}\index{cgal configuration cmake variables - dependencies - taucs}
% \subsubsection{\taucs\ and METIS libraries}
% Some demos require the \taucs\ and METIS libraries. If any of the two is not
% found, the \taucs\ support is disabled.
% Under Windows, auto-linking is used, so only the \emph{directory}
% containing the libraries is needed, and you would specify \texttt{TAUCS\_LIBRARY\_DIR} rather than
% \texttt{TAUCS\_LIBRARIES}. On the other hand, under Linux the actual library filename is needed.
% Thus you would specify \texttt{TAUCS\_LIBRARIES}. In no case you need to specify both.
% \cgal\ uses both \taucs\ and METIS so both need to be supported. If either of them is unavailable the
% usage of \taucs-METIS will be disabled.
% {\ccTexHtml{\small}{}
% \renewcommand{\arraystretch}{1.3}
% \gdef\lcTabularBorder{2}
% \begin{tabular}{|l|l|l|} \hline
% \textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
% \texttt{TAUCS\_INCLUDE\_DIR} & Directory containing the \texttt{taucs.h} file & CMake\\\hline
% \texttt{TAUCS\_INC\_DIR} & Idem & Environment\\\hline
% \texttt{TAUCS\_LIBRARIES\_DIR} & Directory containing the compiled \taucs\ library & CMake\\\hline
% \texttt{TAUCS\_LIB\_DIR} & Idem & Environment\\\hline
% \texttt{TAUCS\_LIBRARY} & Full pathname of the compiled \taucs\ library & CMake\\\hline
% \texttt{METIS\_LIBRARY} & Full pathname of the compiled metis library & CMake\\\hline
% \end{tabular}
% }
% \index{cgal!general-config-cmake-vars-dep-blas}\index{cgal configuration cmake variables - dependencies - blas}
% \subsubsection{\blas\ and \lapack\ libraries}
% A few demos require some \blas\ and \lapack\ functions. There are several
% implementations by different vendors that contains the required functions,
% and \cmake\ searches for most of them.
% If they are not found, you can indicate the directory containing the libraries, or provide a
% semi-colon separated list of pathnames to the libraries which collectively implement the functions.
% Many of the libraries implementing \blas\ and \lapack\ require the \ftoc\ library for Fortran-to-C conversion.
% If this is needed and not found, you may specify the fullpath of the library in the \texttt{F2C\_LIBRARIES}
% variable. You do not need to provide this, if the \blas\ \lapack\ libraries do not need \ftoc.
% {\ccTexHtml{\small}{}
% \renewcommand{\arraystretch}{1.3}
% \gdef\lcTabularBorder{2}
% \begin{tabular}{|l|l|l|} \hline
% \textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
% \texttt{BLAS\_INCLUDE\_DIR} & Directory containing \blas\ header files & CMake\\\hline
% \texttt{BLAS\_LIBRARIES\_DIR} & Directory containing the compiled libraries implementing \blas\ & Environment\\\hline
% \texttt{BLAS\_LIB\_DIR} & Idem & Environment\\\hline
% \texttt{BLAS\_LIBRARIES} & Semi-colon separated list of library pathnames implementing the \blas\ functions & CMake\\\hline
% \texttt{BLAS\_LINKER\_FLAGS} & Linker flags & CMake\\\hline
% \texttt{BLAS\_DEFINITIONS} & Preprocessor definitions & CMake\\\hline
% \texttt{LAPACK\_INCLUDE\_DIR} & Directory containing \blas\ header files & CMake\\\hline
% \texttt{LAPACK\_LIBRARIES\_DIR} & Directory containing the compiled libraries implementing \lapack\ & Environment\\\hline
% \texttt{LAPACK\_LIB\_DIR} & Idem & Environment\\\hline
% \texttt{LAPACK\_LIBRARIES} & Semi-colon separated list of library pathnames implementing the \lapack\ functions & CMake\\\hline
% \texttt{LAPACK\_LINKER\_FLAGS} & Linker flags & CMake\\\hline
% \texttt{LAPACK\_DEFINITIONS} & Preprocessor definitions & CMake\\\hline
% \texttt{F2C\_LIBRARIES} & Full pathname to the \ftoc library & CMake\\\hline
% \end{tabular}
% }
\index{cgal!general-config-cmake-vars-dep-qglviewer}\index{cgal configuration cmake variables - dependencies - qglviewer}
\subsubsection{QGLViewer library}
Some demos require the GLViewer library.
In most cases, if QGLViewer is not automatically found, setting the \texttt{QGLVIEWERROOT}
environment variable is sufficient. If it is not, you can specify the directory containing
the header files and the full pathnames of the release and debug libraries
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{QGLVIEWERROOT} & Root directory of the QGLViewer library & Environment\\\hline
\texttt{QGLVIEWER\_INCLUDE\_DIR} & Directory containing the \texttt{QGLViewer/qglviewer.h} file & CMake\\\hline
\texttt{QGLVIEWER\_LIBRARY\_RELEASE} & Full pathname to a release build of the QGLViewer library & CMake\\\hline
\texttt{QGLVIEWER\_LIBRARY\_DEBUG} & Full pathname to a debug build of the QGLViewer library & CMake\\\hline
\end{tabular}
}
\index{cgal!general-config-cmake-vars-dep-esbtl}\index{cgal configuration cmake variables - dependencies - esbtl}
\subsubsection{ESBTL library}
One skin surface example requires the ESBTL library in order to read \textsc{Pdb} files.
If ESBTL is not automatically found, setting the \texttt{ESBTL\_INC\_DIR}
environment variable is sufficient.
{\ccTexHtml{\small}{}
\renewcommand{\arraystretch}{1.3}
\gdef\lcTabularBorder{2}
\begin{tabular}{|l|l|l|} \hline
\textbf{Variable} & \textbf{Description} & \textbf{Type}\\\hline\hline
\texttt{ESBTL\_DIR} & Directory of \esbtl\ default installation & Environment\\\hline
\texttt{ESBTL\_INC\_DIR} & Directory containing the \texttt{ESBTL/default.h} file & Environment\\\hline
\texttt{ESBTL\_INCLUDE\_DIR} & Directory containing the \texttt{ESBTL/default.h} file & CMake\\\hline
\end{tabular}
}
\section{Compiler Workarounds}
\index{compilers!workarounds}\index{workaround flags}
A number of boolean flags are used to workaround compiler bugs and
limitations. They all start with the prefix \texttt{CGAL\_CFG}. These
flags are used to work around compiler bugs and limitations. For
example, the flag \texttt{CGAL\_CFG\_NO\_CPP0X\_LONG\_LONG} denotes
that the compiler does not know the type \texttt{long long}.
For each installation 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 \cmake,
and it is located in the \texttt{include} directory of where you run
\cmake. For an in-source configuration this means
\texttt{CGAL-x.y/include}.
The test programs used to generate the \texttt{compiler\_config.h}
file can be found in \texttt{config/testfiles}.
\index{directories!config/testfiles@\texttt{config/testfiles}} Both
\texttt{compiler\_config.h} and the test programs contain a short
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/config.h>}.\index{files!\texttt{config.h}}
which is included by all \cgal\ header files.
\section{Compiler Optimizations\label{sec:compiler-optimisations}}
\index{compilers!optimization}
\index{optimization compiler flags}
By default \cmake\ generates makefiles for Release mode, with
optimization flags switched on, and vcproj files for Release
and Debug modes.
%%
%% EOF
%%
Reference in New Issue View Git Blame Copy Permalink