This manual was written by Michael Hoffmann and Wieger Wesselink. This work was supported by the ESPRIT IV Long Term Research Projects No. 21957 (CGAL) and No. 28155 (GALIA).
CGAL is a Computational Geometry Algorithms Library written
in C++, which is developed in an
This document describes how to install CGAL on your system. Besides
that, you will find some information about the makefile structure of
CGAL and the support for simultaneously using CGAL and LEDA, the
Library of Efficient Datatypes and Algorithms1,
and/or the
In order to build the CGAL libraries you need a C++ compiler. Currently only a small number of recent compilers on unix platforms are supported. The reason is that most compilers do not conform to the upcoming ANSI/ISO standard2 and some of them have so many limitations/bugs that we could not work around all of them.
More precisely, CGAL-1.2 supports the following Unix compilers/operating systems:
compiler | operating system |
| IRIX 6.2 |
| Solaris 2.5 |
| IRIX 6.2 / SUN Solaris 2.5 / Linux 2.0 |
| IRIX 5.3 / IRIX 6.2 / Solaris 2.5 / Linux 2.0 |
There are plans to support PC compilers (
The CGAL library can be downloaded in two different ways: using ftp or using WWW. If you have a WWW connection, the easiest way to download CGAL is via the CGAL homepage:
http://www.cs.uu.nl/CGALand go to the `Software' section.
Just follow the instructions on this page to obtain your copy of the library. The CGAL library can also be downloaded using FTP. The library can be found at the following location:
ftp.cs.uu.nl
in the directory /pub/CGAL. This directory contains release 1.2 of the CGAL library. There is also a README file that contains descriptions of the files in this directory. An example of an FTP-session is given below.
$ ftp ftp.cs.uu.nl Name (ftp.cs.uu.nl:<your username>): anonymous Password: <type your email address here> ftp> cd pub/CGAL ftp> get README ftp> binary ftp> get CGAL-1.2.tar.gz ftp> quit
After you have downloaded the file containing the CGAL library, you have to decompress it. For the zipfile use the command
unzip <filename>.zip
and for the gzipped file use the commands
gunzip <filename>.tar.gz tar xvf <filename>.tar
In both cases the directory CGAL-1.2 will be created. This directory contains the following subdirectories:
directory | contents |
auxiliary | packages that can optionally be used with CGAL |
config | configuration files for install script |
demo | demo programs (some of them need LEDA) |
doc_html | documentation (HTML) |
doc_pdf | documentation (PDF) |
doc_ps | documentation (Postscript) |
examples | example programs |
include | header files |
lib | (shared) object libraries |
make | files with platform dependent makefile settings |
src | source files |
The directory CGAL-1.2 contains a Bourne shell script called install_cgal. The script can be run in two modes: a menu-driven interactive mode and a non-interactive mode. Normally you should use the interactive mode, but in case you run into problems with it or do not like it for some reason, you can still use the non-interactive mode.
We first describe a sample installation in section
. This provides you with an overview on how the
interactive installation works. If you want more detailed information
about specific menus and their options, take a look at section
. Finally, for the non-interactive mode
refer to section
.
If you want to use LEDA in combination with CGAL, there might be
some compatibility issues that need to be addressed first. See
section and http://www.cs.uu.nl/CGAL/Compilers/ for more information about
this.
In this section we sketch an example installation on a .
Go to the CGAL-1.2 directory and enter the command
./install_cgal -i
You get a message indicating the CGAL version you are going to install and that you are running the interactive mode. Then it takes some time while the script locates a number of utility programs. You will not get informed about this3, but see some dots written to the screen indicating progress.
--------------------------------------------------------
This is the install script for CGAL 1.2
--------------------------------------------------------
starting interactive mode - one moment, please
......
Choosing compiler SUNPRO 4.2.
Testing for builtin STL ... no.
.
If there is any compiler installed on your system and accessible
through your PATH environment variable that is supported by
CGAL, one of these compilers is chosen and it is checked whether it
has a ``builtin'' STL, i.e. if STL works without adding any
specific compiler flags. Here the chosen compiler is
A menu similar to the following will appear on your screen.
****************************************************************
** CGAL 1.2 Installation Main Menu **
** ------------------------------- **
** **
** OS: sparc_SunOS-5.5 **
** Compiler: SUNPRO CC 4.2 **
** STL_DIR: please configure!!! **
** LEDA: not supported. **
** GMP: not supported. **
** **
** The setup has not been tested. **
** **
** There are no libs for this os/compiler. **
** **
** <C> Compiler Menu **
** <L> LEDA Menu **
** <G> GMP Menu **
** <T> Test (and save) setup **
** <A> Run all setup tests (no cache) **
** **
** <B> Build CGAL Libraries **
** **
** <Q> Back to OS **
** **
** Your Choice: **
** **
****************************************************************
The first lines below the headline contain some kind of status report: current OS and compiler, are LEDA and GMP supported etc., in this case it also tells you that STL still has to be configured.
Moreover you can see that the current setup has not been tested yet and that there do not exist CGAL libraries for this OS/compiler combination in the CGAL lib directory by now. It is always a good idea to test your configuration before you start building the CGAL libraries, but before that we first have to setup STL.5
Please type ``c'' to go to the compiler menu where all
compiler specific options can be configured. Then type ``i''
and you will be prompted to enter the include directory where STL
header files reside on your system. The script only accepts
directories that exist and pass a confidence test.6 Let's
assume, you have a
After you set up the STL directory, the script tries to compile some small example programs to check whether STL works principally and if it does, which language features are supported by your compiler and your STL version. This is necessary, since there are many different STL implementations and CGAL (partly) depends on which implementation is used. A message ok always indicates that your compiler works as it should i.e. a feature is supported resp. a bug is not present. On the other hand no resp. unfortunately indicate a lack of support resp. bug.
****************************************************************
** CGAL 1.2 Installation Compiler Menu **
** ----------------------------------- **
** **
** OS: sparc_SunOS-5.5 **
** Compiler: SUNPRO CC 4.2 **
** STL_DIR: please configure!!! **
** LEDA: not supported. **
** GMP: not supported. **
** **
** The setup has not been tested. **
** **
** <C> Choose compiler **
** <I> STL include directory **
** <undefined> **
** <F> Set custom compiler flags **
** <none> **
** <L> Set custom linker flags **
** <none> **
** <T> Test (and save) setup **
** **
** <Q> Back to Main Menu **
** **
** New STL_DIR: /pub/local/STL/HP **
** **
****************************************************************
Testing for STL ... ok.
Testing for SGI STL 3.0 ... no.
Testing for SGI 6/97 STL ... no.
Testing for SGI 1996 STL ... no.
Testing for SGI CC STL ... no.
Testing for HP STL ... ok.
...
<tests for several compiler features>
...
Saving current setup ... done.
If the STL test succeeds, the current setup is marked as tested and the settings are saved to a file in the directory CGAL-1.2/config/install. Thus, if you run the install script a second time for this OS/compiler, you will not have to enter the STL directory again, but it is retrieved from the corresponding config file instead.
Now we are ready to build the CGAL libraries. First go back to the main menu with ``q`` and then type ``b'' to start compilation. Building consists of three steps:
****************************************************************
** **
** Compiling CGAL 1.2 **
** ------------------ **
** **
****************************************************************
OS: sparc_SunOS-5.5
COMPILER: SUNPRO CC 4.2
STL: CGAL_STL_HP
LEDA: not supported
GMP: not supported
Generating Makefiles ... done.
Building CGAL_lib ... done.
Building CGAL_sharedlib ... done.
****************************************************************
** Please press <ENTER> to continue. **
****************************************************************
That's all, it's done. Press ``<ENTER>'' to return to the main menu and proceed by installing for a different compiler (go to the compiler menu and choose ``c'' to get a list of supported compilers detected on your system) or with LEDA or GMP support (go to the LEDA resp. GMP menu) or simply quit the install script by typing ``q''. When leaving the script, you get a list of successful builds during the session.
Now it would be a good idea to print and read the document getting_started.ps that can be found in the doc_ps directory.
To run the install script in the interactive mode, go to the CGAL-1.2 directory and enter the command
./install_cgal -i
After initialization during which certain utility programs are located
and your system is searched for compilers supported by CGAL, you get
into the CGAL installation main menu (see page
for a picture).
From the main menu you can reach a number of different sub-menus, of
which the most important maybe is the compiler menu. This is
where you can choose the compiler you want to work with and setup
STL. The compiler menu is described in section
.
If you want to use LEDA or resp.
to the gmp menu described in section
.
Finally you can build the CGAL libraries by typing b. However, it is recommended to run the setup test which is available in all menus as option t before. The setup test includes an STL test, a LEDA test and a GMP test, but not all tests are performed always; e.g. the LEDA test is only done, if you enabled LEDA support. The install script keeps track of the tests passed and only tests again, if you change the setup in a way that might affect the test result. If you want to redo all tests, you have to choose option ``a'' from the main menu. This also retests for LEDA or GMP installation in system directories which otherwise is only done the first time you enable LEDA/GMP support for an OS/compiler combination.
The install script stores all relevant settings for an OS/compiler combination in the directory
Besides the config files, install_cgal uses several temporary files during interactive installation. Most of them are removed after use, but some are not, since it might be helpful to keep some information about the last run. You can keep or delete them as you like, as they are not needed anymore once the script terminated. It follows a list of these files (all are plain ASCII and reside in CGAL-1.2).
filename | content |
install.log | detailed overall protocol |
install.completed | list of systems for which CGAL libraries have been built |
compile.log | output of the last compiler call |
Here is the place to setup the compiler specific options, such as the compiler to use (if more than one has been detected) and the location of the STL files.
Some compilers come with their own STL adaption to which we refer as builtin and some compilers are not shipped with STL. In the latter case you have to supply an STL_DIR, i.e. the path to a directory where the STL header files are stored.8 In this case we speak of an external STL. Even if your compiler has builtin STL, you can still choose to use an external STL by setting STL_DIR appropriately.
|
This is the place to setup LEDA specific options, if you plan to use
LEDA together with CGAL (see also section ). In
order to enable LEDA support in CGAL, LEDA has to be installed on
your system.
If LEDA support is enabled the first time, the script tests whether LEDA is installed in standard system directories. If this test does not succeed, you have to supply directories containing the LEDA header files (LEDA_INCL_DIR) and LEDA libraries (LEDA_LIB_DIR). Even if the tests are passed, you still have the option to set these directories differently.
|
This menu is to setup GMP (
If GMP support is enabled the first time, the script tests whether GMP is installed in standard system directories or in the CGAL tree. If this test does not succeed, you have to supply directories containing the GMP header files (GMP_INCL_DIR) and GMP libraries (GMP_LIB_DIR). Even if the tests are passed, you still have the option to set these directories differently.
|
To run the install script in the non-interactive mode, go to the CGAL-1.2 directory and enter the command
./install_cgal -ni <compiler>where <compiler> is the C++ compiler executable.
There are a number of additional command line options to customize your CGAL setup which are discussed below. You should read the corresponding paragraphs before you continue, especially if one or more of the following conditions apply to you:
Once you started the script, it should give you a message indicating
the CGAL version you are going to install and that you are running
the non-interactive mode. Then it proceeds by locating some utility
programs, determining your OS and compiler version, displaying the
settings you gave via command line and classifying (see also section
) the STL version used (which - of course - will not
work, if you did not set up STL correctly, see section
below). Your compiler is also checked for a number
of bugs resp. support of certain language features; a message
ok always indicates that your compiler works as it should
i.e. a feature is supported resp. a bug is not present. On
the other hand no resp. unfortunately indicate a
lack of support resp. presence of a bug.
Finally the current setup is summarized, system specific directories for makefiles and libraries are created (if they did not exist before) and a new include makefile is written into the makefile directory. If there already exists a makefile for the current OS/compiler combination, it is backuped and you should get a corresponding message.
To compile the CGAL libraries go now to the src directory.
Then type make -f makefile_lib to compile the CGAL object
library and make -f makefile_sharedlib to compile the CGAL
shared object library. If you want to make changes to the makefiles
first, see section for an explanation of the
makefile structure of CGAL.
When this is finished it would be a good idea to print and read the `Getting Started with CGAL' document getting_started.ps that can be found in the doc_ps directory.
The install script and the makefiles use the variable STL_DIR to indicate the STL that shall be used with CGAL. This variable should point to the directory where STL header files are stored. It can be set from command line with option ``-STL_DIR dir''. If you do not set STL_DIR this way, it is assumed that the compiler has ``builtin'' STL and this is used. If your compiler does not have builtin STL, you have to supply an STL_DIR to get things running.
See also section . By default there is no support for
LEDA, but you can change this easily by use of the command line
option ``-leda''. If LEDA is installed in system
directories on your system, you should indicate this by setting the
flags ``-leda-sys-incl'' resp. ``-leda-sys-lib''. If
this is not the case, you have to supply the directories containing
the LEDA header files (``-LEDA_INCL_DIR
dir'') resp. the LEDA libraries for your compiler
(``-LEDA_LIB_DIR dir'').
By default there is no support for GMP, but you can change this easily by use of the command line option ``-gmp''. If GMP is installed in system directories on your system, you are already done now. If this is not the case, you have to supply the directories containing the GMP header files (``-GMP_INCL_DIR dir'') and the GMP library (``-GMP_LIB_DIR dir'').
There are some more less important features of the install script we will summarize here.
First of all you can get the version number of cgal_install with option ``-version''. Note that all other options are ignored in this case.
Second there is an option ``-os compiler''
where compiler is your C++ compiler. This allows you
to determine your CGAL-OS description (see section
). The compiler can either be given by an
absolute path like
./install_cgal -os /usr/local/gcc-2.8.1/sun/bin/g++or just by denoting its basename, as long as it is on your path:
./install_cgal -os CCThe option is intended for testing purposes and automatic detection of the correct include makefile (see also section
Finally there exists an option ``-verbose'' that can be set in interactive mode as well as in non-interactive mode. When set you get a detailed summary of error messages occurring during any compiler test (determining STL version etc.). Normally you only get these messages, if a required test (such as the general STL test) fails, otherwise you are just informed, if it succeeded or not. This option is not recommended for general use, but it can be useful to check why a certain test fails that was expected to be passed.
In case you run into problems with CGAL, you should first have a look at the CGAL homepage:
http://www.cs.uu.nl/CGALIf you cannot find a solution to your problem there, please send email to cgal@cs.uu.nl.
Since CGAL supports several different operating systems and compilers, this is also reflected in the structure of the CGAL directory tree. Each OS/compiler combination has its own lib directory under CGAL-1.2/lib) (and analogously its own include makefile in CGAL-1.2/make) named as determined by the following scheme.
The suffix _LEDA is appended to indicate LEDA support. This distinction is necessary, because the object libraries look (at least possibly) different.
We call the resulting string CGAL-OS description.
Examples are mips_IRIX-6.2_CC-7.2 or sparc_SunOS-5.5_g++-2.8.1_LEDA. You can use the install
script to get your CGAL-OS description, see section
.
The CGAL distribution contains the following makefiles:
All these makefiles are generic: they can be used for more than one compiler. To achieve this, the first section of each makefile contains an include statement that looks as follows:
CGAL_MAKEFILE = /users/jannes/CGAL-1.2/make/makefile_<CGAL-OS description> include $(CGAL_MAKEFILE)
The file CGAL_MAKEFILE is an include file with platform
dependent makefile settings. The abbreviation <CGAL-OS
description> (see section for details) is
used to identify the operating system and compiler for which the
settings hold. For example, the file
makefile_mips_IRIX64-6.2_CC-n32-7.20 contains makefile
settings for the IRIX 6.2 operating system and the
If you want to compile an application or an object library with a
different compiler, the only thing you need to do is to substitute
another include makefile for the CGAL_MAKEFILE variable. An
alternative way to do this is to create an environment variable
CGAL_MAKEFILE. To pass the value of the environment variable
to the makefile you can either comment out the CGAL_MAKEFILE
line in the makefile or use an appropriate command line option for
the make utility.
A comfortable way to set CGAL_MAKEFILE is by using
install_cgal -os (see section ).
E.g. if your compiler is g++, you would type
CGAL_MAKEFILE=`$<$insert your CGAL-1.2 dir$>$/install_cgal -os g++`in bourne shell resp.
setenv CGAL_MAKEFILE `$<$insert your CGAL-1.2 dir$>$/install_cgal -os g++`in csh derivatives.
All makefiles contain sections with compiler and linker flags. You can add your own flags here. For example, you might want to add the flag -DCGAL_NO_PRECONDITIONS to turn off precondition checking. The flags $(CGAL_CXXFLAGS) and $(CGAL_LDFLAGS) should never be removed.
The default extension for CGAL source files is .C. The last section of the makefiles contains a suffix rule that tells the compiler how to create a .o-file from a .C-file. If you want to use the default rule that is defined by the make utility, you may want to remove this suffix rule. However, note that this may have consequences for the makefile variables CGAL_CXX and CXXFLAGS.
Furthermore the directories CGAL-1.2/examples and CGAL-1.2/demo contain many subdirectories with non-graphical and graphical example programs. In all these directories you will find a makefile that is ready for use.
The include makefiles in the CGAL-1.2/make directory corresponding to LEDA can be recognized by the suffix ``_LEDA''.
If you are using an old compiler or an old version of STL, the combination of LEDA and STL may give some problems. In order to avoid them, it is highly recommended to use the latest LEDA release9, since this is what we test CGAL with.
If a compiler does not support the keyword bool, libraries like LEDA and STL provide their own definition of bool. Unfortunately the LEDA definition of bool is incompatible with the definition in most STL implementations. One of them needs to be changed. The easiest solution is to modify STL as follows:
typedef int bool;
in a file called bool.h or stl_config.h
#ifdef CGAL_USE_LEDA #include <LEDA/bool.h> #else typedef int bool; #endif
The flag CGAL_USE_LEDA ensures that you can continue to use STL wwithout depending on LEDA.
REMARK: If you do not like to modify centrally managed STL files, it is possible to fake it. This can be done by making changes to a copy of the STL file bool.h or stl_config.h. After this you have to make sure that this copy is found earlier on the include path than the original file. It is also possible to modify LEDA instead of STL. However, then you have to modify and recompile (if you have the source code) LEDA.
When compiling the graphical demo programs that use LEDA windows with LEDA versions prior to 3.6.1, you may encounter a name clash. This is because LEDA defines the colors 'red' and 'black' in the file <LEDA/impl/x_window.h>, whereas some STL implementations use 'red' and 'black' in the implementation of trees. One of the libraries needs to be modified. In this case the easiest solution seems to prefix the LEDA color constants with something like leda_.
For using the CGAL library, the Standard Template Library is required. Recent compilers provide their own implementation of STL. There are also free implementations. Most notable are the implementation from Silicon Graphics (http://www.sgi.com/Technology/STL/, also contains documentation and links to other STL resources) and a port of this SGI version to a lot of other compilers (http://www.metabyte.com/~fbp/stl/).
The install_cgal script tries to figure out which STL is
used. This is necessary for the circulator package, and also to work
around some bugs. In case the right version is not recognized, you
could try to use the non-interactive mode of the
install_cgal script (see section ).
The compiler flag CGAL_STL_VERSION can take the following
values:
CGAL_STL_GCC | STL version that comes with gcc-2.7.2 |
CGAL_STL_HP | Free HP version |
CGAL_STL_SGI_3_0 | SGI STL 3.0 or newer |
CGAL_STL_SGI_WWW | SGI STL prior to 3.0 |
CGAL_STL_SGI_WWW_OLD | SGI STL for older compilers |
CGAL_STL_SGI_CC | SGI STL that comes with their 7.0/7.1 compilers |
CGAL_STL_UNKNOWN | unknown STL version (this will probably not work) |
Most STL libraries consist of only header files. An exception is HP's STL, which also has source files random.cpp and tempbuf.cpp. The CGAL makefiles do not take care of this. You have to compile these files yourself and add them to the custom linker flags during the installation of CGAL, or enter them manually in the makefiles.
cp -r <OLD_CGAL_DIR>/config/install <NEW_CGAL_DIR>/configwhere <OLD_CGAL_DIR> is your CGAL 1.1 root directory (e.g. /pub/local/CGAL-1.1) and
It is strongly recommended to rerun all tests using the option A from the main menu.
For each compiler a file <CGAL/compiler_config.h> is defined, with the correct settings of all flags. This file is generated automatically by the install_cgal script. For this the test programs in the directory CGAL-1.2/config/testfiles are used. The file <CGAL/compiler_config.h> and the test programs contain a description of the problem, so in case of trouble with a CGAL_CFG flag it is a good idea to take a look at it.
The file <CGAL/config.h> manages all configuration problems of the compiler. This file includes the file CGAL/compiler_config.h. It is therefore important that the file <CGAL/config.h> is always included before any other CGAL source file that depends on workaround flags. In most cases you do not have to do anything special for this, because many CGAL files already take care of including <CGAL/config.h>. Nevertheless it would be a good idea to always start your CGAL programs with including <CGAL/config.h> (or <CGAL/basic.h>, which contains some more basic CGAL definitions).
1 | see http://www.mpi-sb.mpg.de/LEDA/index.html for information. |
2 | see e.g. http://reality.sgi.com/austern/std-c++/faq.html\#PartB for information |
3 | If you are that curious what happens exactly, have a look at the file CGAL-1.2/install.log. |
4 | If your compiler has a builtin STL, you will have to wait for a moment while the script tests for a number of language features, which cannot be done without STL. |
5 |
This
is not necessary for compilers with builtin STL. So you might want
to skip the next section and go directly to section
![]() |
6 | In this case it checks for a file iterator.h in the directory. This file should be present in all STL implementations. |
7 | Note that these files are only OS/compiler specific, i.e. there are no different files for with and without LEDA support. |
8 |
See
section ![]() |
9 | At the moment this is LEDA 3.7. |