Generated on Mon Aug 25 11:35:46 2008 for Gecode by doxygen 1.5.6

Compiling and installing Gecode

The Gecode library, including examples and documentation, can be built on all recent versions of Windows, Linux, and MacOS X. Porting to other Unix flavors should be easy, if any change is necessary at all.

Prerequisites

In order to compile Gecode, you need a standard Unix toolchain including the following programs:

  • a bash-compatible shell
  • GNU make
  • sed
  • cp
  • diff
  • tar
  • perl

These are available in all standard installations of Linux. On MacOS X, you need to install the Apple developer tools. For Windows, we require the Cygwin environment that provides all necessary tools.

We currently support

  • the Microsoft Visual C++ compilers for Windows. The Microsoft Visual C++ 2005 Express Edition is available free of charge from the MSDN web pages.
  • the GNU Compiler Collection (gcc) for Windows and Unix flavors such as Linux and MacOS X. The GNU gcc is open source software and available from the GCC home page. It is included in all Linux distributions and the Apple MacOS X developer tools. Gecode requires at least version 3.4 of gcc. We recommend using version 4.2 or higher. Very unfortunately, the parser used in versions of gcc before 3.4 is broken and hence cannot compile Gecode.

The Intel C++ compiler is currently not supported.

Configuring the sources

Gecode uses GNU autoconf to acquire information about the system it is compiled on. Typically, you need to run the configure script in the toplevel directory.

To setup Gecode for your particular system, you may need to add one or more of the following options to configure:

  • When using the GNU compiler gcc on Windows instead of the Microsoft compiler, add CC=gcc CXX=g++ to your invocation of configure
  • To install Gecode somewhere else than the default /usr/local, use the --prefix=[...] switch
  • You can enable and disable the individual modules Gecode consists of using --enable-[MODULE] and --disable-[MODULE]

You can get a list of all supported configuration options by calling configure with the --help switch.

Example configurations

To compile Gecode on a Windows machine using the GNU compiler, use

./configure CC=gcc CXX=g++

To compile only the Gecode library without examples on a Unix machine, use

./configure --disable-examples

To compile on a Unix machine using a different than the default gcc compiler, and install under /opt/gecode, use

./configure --prefix=/opt/gecode CC=gcc-4.0 CXX=g++-4.0

To compile a debug build on Unix, turning on all assertions and not inlining anything, use

./configure --enable-debug

To compile on Cygwin, but linking against the Windows libraries instead of the Cygwin libraries, use

./configure CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin" Note that we only support building static libraries on Cygwin.

To compile on a system using a different than the default compiler, and a /bin/sh that is not bash compatible (e.g. a Solaris machine), use

./configure --with-host-os=linux \
   CC="gcc-4.0" CXX="g++-4.0" \
   SHELL="/bin/bash"
make SHELL="/bin/bash"

You can compile as "universal binary" on a Mac OS machine. Configure with

./configure --with-architectures=i386,ppc

For building universal binaries on a PowerPC machine, you have to supply the path to the universal SDK (which is the default on Intel based Macs):

./configure --with-architectures=i386,ppc    --with-sdk=/Developer/SDKs/MacOSX10.4u.sdk

Passing options for compilation

Additional options for compilation can be passed to the compiler from the make commandline via the variable CXXUSR. For example, to pass to gcc the additional option "-mtune=i686" the following can be used:

make CXXUSR="-mtune=i686"

Compiling in a separate directory

The Gecode library can be built in a separate directory. This is useful if you do not want to clutter the source tree with all the object files and libraries.

Configuring Gecode in a separate directory is easy. Assume that the sources can be found in directory $GSOURCEDIR, change to the directory where you want to compile Gecode and call

$GSOURCEDIR/configure [options]

This will generate all necessary files in the new build directory.

Compiling the sources

After successful configuration, simply invoking

make

in the toplevel Gecode directory will compile the whole library.

Running the examples

After compiling the examples, they can be run directly from the command line. For instance, try the Golomb Rulers Problem:

./examples/golomb

or (when running Windows):

./examples/golomb.exe

On some platforms, you may need to set environment variables like LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac OS) to the toplevel compile directory (where the dynamic libraries are placed after compilation).

For more information on example scripts see Example scripts (models).

Installation

After a successful compilation, you can install the Gecode library and all header files necessary for compiling against it by invoking

make install

in the build directory.

Dependency management

The dependencies between source files are not handled automatically. If you are using a Gecode version from our subversion repository or if you modified any of the source files, you will have to call make depend before compilation in order to determine the source dependencies.

Dependency management is only needed for recompiling Gecode after changing something. In an unmodified version (or after a make clean) all files are compiled anyway.

Compiling for unsupported platforms

If you want to try compiling Gecode on a platform that we do not mention, you can override the platform tests during configure. There are two options to specify the type of platform:

  • --with-host-os=[linux|darwin|windows]
  • --with-compiler-vendor=[gnu|microsoft]

Using the first option, you can state that your platform should behave like Linux, Darwin (which is actually BSD), or Windows. This affects mainly the filenames and the tools used to generate shared and static libraries.

The second option says that your compiler can be used very much like the gnu compiler gcc, or the Microsoft compiler cl. Please let us know of any successfull attempt at compiling Gecode on other platforms.

Useful Makefile targets

The main Gecode Makefile supports the following useful targets:

  • all compiles all parts of the library that were enabled during configure, and the examples if enabled
  • install installs library, headers and examples (if enabled) into the prefix given at configure
  • clean removes object files
  • veryclean removes object files, libraries, and all files + generated during make
  • distclean removes object files, libraries, and all generated files
  • depend generates dependencies between source files
  • test compiles the test suite
  • doc generates this reference documentation using doxygen
  • installdoc installs the documentation
  • dist creates a source distribution as a tgz archive, not including the contributions found in the contribs directory
  • distdir creates a source distribution in a directory, not including the contributions found in the contribs directory
  • distdoc creates tgz and zip archives of the documentation
  • distzip creates a binary distribution as a zip archive
  • disttgz creates a binary distribution as a tgz archive

Compilation with Gist

The Gecode Interactive Search Tool (Gist) is a graphical search engine for Gecode, built on top of the Qt GUI toolkit.

In order to compile Gecode with Gist, you need an installation of the Qt library including the development header files. The source code for Qt is available from Trolltech under the GPL license.

Please note that if you want to develop closed-source software with Gecode and Gist, you will need to get a commercial license for Qt from Trolltech!

If you are developing on Windows using the Microsoft Visual C++ compiler, make sure to compile the Qt library with the same compiler (this is possible with Qt version 4.3.2, even if the download page does not say so).

If the qmake tool is in your shell path, all you need to do to enable Gist is to configure Gecode with the switch --enable-gist.