Install Instructions

Copyright 2001-2005 Systems in Motion

http://www.coin3d.org/

Introduction

============

This document contains instructions for those who have downloaded the

Coin source code and want to build the library and install it on their

system. It does not contain any information about installing binary

distributions of Coin.

Cookbook Procedure

==================

If you are impatient and just want a standard installation, you can go

ahead and run through the following cookbook procedure. If you get into

trouble following it, please read through the rest of this document

before contacting The Coin Team for technical support. Remember to

substitute "1.0.0" with the version identifier for the Coin library you

are building.

# 1. Unpack source code and make a build directory somewhere:

cd /tmp

gzip -cd Coin-1.0.0.tar.gz | tar xvf -

mkdir coin-build

# 2. Run configure from the build directory:

cd coin-build

../Coin-1.0.0/configure

# 3. Build the Coin library:

make

# 4. Install the Coin library:

make install

# 5. Remove source and object files when you don't need them anymore:

cd ..

rm -rf coin-build Coin-1.0.0

The Build Environment

=====================

Coin uses GNU Autoconf, Automake and Libtool for the configuration,

compilation, and installation procedures. This means you need a POSIX

shell environment and a decent "make" implementation. You also need a

compiler for C/C++.

All unixes have Bourne shells that are close enough to the POSIX

standard to be usable, and in the odd case where the vendor shell does

not cut it, you can install the GNU Bourne Again Shell (bash) as a

replacement. Many unixes have poor make implementations wihtout

proper support for VPATH and other features that GNU Automake depend

on. If you experience problems during the build phase, you might want

to try using GNU make instead of the vendor make program. Make sure

it is first in the PATH and that $MAKE is not set to another make

implementation.

On Microsoft Windows platforms, you need to install the Cygwin

environment (www.cygwin.com) or something equivalent to get a POSIX

shell and the extra utilities needed to get through the build procedure.

For compilation, the Visual C++ compiler is used. Using gcc may be

fully possible but has not been tested yet, and disabling the VC++

requirement needs special user intervention at configure time (see list

of configure options below).

The file INSTALL.GNU contains the standard, generic, installation

instructions for the GNU build environment.

Configuration Options

=====================

--help

Specifying this option will cause configure to list all its command

line options and exit.

--version

This option will cause the configure script to display version

information about the package and the version of GNU Autoconf that

created the configure script.

--cache-file=<FILE>

Configure tests can take a lot of time on some systems, so if you are

running configure multiple times it seems smart to cache the test

results in persistent storage so tests can be skipped on subsequent

configure runs. Using this option will enable caching of test

results. It is only useful for developers who develop on Coin while

working with old and slow hardware.

--prefix=<PATH>

This option decides where the Coin library is going to be installed.

The default is usually /usr/local but can be set to something else

with this option. Often used alternatives are /usr and /opt/Coin.

--mandir=DIR

If you enable manpage generation, you can specify where the manpages

should be installed with this option. The default is ${prefix}/man,

but if you install to /usr you might prefer installing manpages to

/usr/share/man instead of /usr/man.

--disable-dependency-tracking

Dependency tracking takes extra resources and slows down compilation

somewhat. It is necessary to use dependency-tracking for users that

update the Coin source code between compilations without cleaning out

the object files in the build directory. That means you either follow

update the Coin source code through CVS or are modifying the source

code yourself.

For single compilations in fresh/clean directories, dependency-

tracking is really a waste of resources and can make compilation take

about twice the time it takes without it.

--disable-build

This option makes make skip the compilation of the source code. It is

useful if you for instance only want to generate the documentation and

don't want to wait for the library to be built.

--disable-msvc

When using the cygwin environment, the default is to search for the

Microsoft Visual C++ compiler. The configure script aborts if it is

not found. If you know what you are doing, and really want to use

gcc instead, you can then disable the search for VC++ and consequently

the abort by using this option. Warning: This is untested/unsupported

ground, and we expect you to be able to get through this without

technical support if you decide to go for it.

--enable-msvcdsp

This option changes the make process from compiling the library to

building an MS DevStudio project and workspace file that you can later

use from the MSVC++ IDE to build Coin with.

--without-framework

On Mac OS X, the default behaviour is to install Coin as a framework

so you can compile/link with it by using the compiler option

"-framework Inventor". If you want to make a plain installation

into $prefix/{lib,include} instead, use this option.

--with-framework

To test the framework layout on non-Macs.

--with-framework-prefix=PATH

To install the framework into another directory than /Library/Frameworks,

use this option. Note also the DESTDIR make variable.

--enable-shared --disable-shared

--disable-static --enable-static

On UNIX platforms, the default configuration is to create a shared

library of Coin. The above options will change this behaviour. It is

for most UNIX platforms possible to create both shared and static

libraries at the same time.

On Windows platforms, the default configuration is to create a dynamic

loadable library (DLL) of Coin. It is *not* possible to create both

a DLL and a static library at the same time because the object files

are compiled differently in those two modes. Enabling static will

automatically disable shared, but the -shared options has precedence

over the -static options. Warning: Do not first build one library

and then build the other in the same build directory - the object

files must the removed to avoid trouble.

--enable-man

This option is used to enable the generation of manpages for the C++

classes Coin consist of. See also the --mandir options listed above.

You need the "doxygen" utility to generate the manpages.

--enable-html

This option is used to enable the generation of HTML documentation for

the C++ classes Coin consist of.

There is no --htmldir option available for GNU autoconf scripts, but

you can specify the "htmldir" variable instead, like this:

configure --enable-html htmldir=doc/html

This will make HTML documentation be installed in ${prefix}/doc/html.

Absolute paths are also possible.

You need the "doxygen" utility to generate the HTML documentation.

--disable-debug

This options turns off some run-time checking, warnings and asserts.

The default is to have them enabled.

Note that you also need to use the "--disable-symbols" option

described below to make a library which is as "slim" as possible, as

you would typically do for a release version of your software.

--disable-symbols

This option turns off debug symbols. Debug symbols are needed to

get call stacks if the library crashes, and to make it possible to

trace the code inside a debugger with enough information available

within that environment to match up with the sourcecode. The

default is to have debug symbols enabled.

--enable-rtti

This option enables C++ RTTI (Run-Time Type Information). RTTI takes

extra space, and is not needed for type-information in Open Inventor,

which implements it's own type system.

Make sure the RTTI on/off setting is identical in both the library

and the application code using the library. If they are not, the

library and application will expect objects passed back and forth to

have a different memory footprint than they have, which can cause

weird crashes.

--enable-exceptions

The default is to disable C++ exceptions in Coin. Coin does not throw

or catch exceptions, and does not need it enabled. You can enable it

with this option nevertheless.

--enable-profile

If you want to enable profiling with Coin, you can use this option.

It only works for gcc.

--disable-warnings

This options will disable compiler warnings when building Coin. It may

not work for all compilers.

--disable-dl-simage

If you don't want Coin to load the simage library at run-time, but want

a link-time binding to simage instead, use this option.

--disable-dl-glu

If you don't want Coin to load the GLU library at run-time, but want a

link-time binding to GLU instead, use this option.

--disable-dl-libbzip2

If you don't want Coin to try to load the bzip2 compression library at

run-time, but want link-time binding instead, use this option.

--disable-dl-gzip

If you don't want Coin to try to load the gzip compression library at

run-time, but want link-time binding instead, use this option.

--disable-dl-freetype

If you don't want Coin to try to load the FreeType font library at

run-time, but want link-time binding instead, use this option.

--disable-dl-openal

If you don't want Coin to try to load the OpenAL library at

run-time, but want link-time binding instead, use this option.

--enable-compact

On some architectures, the final library linkage is done by specifying

all the object files in the Coin library on the same linker command

line. This line becomes quite long, and on certain architectures,

most notably IRIX and HPUX, the default maximum command line length is

too small.

This option will cause all the source code in each subdir of src/ to

be compiled as one gigantic object file, which solves this limitation.

It will slow down compilation a great deal though, but if you must,

you must.

--enable-hacking

Normally, Coin is linked into one library, which is rather large. For

developers working on Coin, the time to do the final link stage is

a problem - the turn-around time for Coin development is slowed down

because of it.

When you use this option, the Coin library will be configured as a set

of smaller library, each of which takes a lot less time to link. This

option should not be used for anyone that do not do development on the

Coin library itself.

--disable-optimization

It is default to enable optimization when compiling Coin. Most compiler

bugs are related to optimization, so this option can be used to disable

compiler optimization for Coin.

--with-msvcrt=<crt>

This option sets which C library to link with for MS Visual C++ builds.

The options are (with aliases on the right):

* singlethread-static [ /ml | ml | libc ]

singlethread-static-debug [ /mld | mld | libcd ]

multithread-static [ /mt | mt | libcmt ]

multithread-static-debug [ /mtd | mtd | libcmtd ]

multithread-dynamic [ /md | md | msvcrt ]

multithread-dynamic-debug [ /mdd | mdd | msvcrtd ]

[*] default choice

--with-doxygen=<PATH>

With this option, you can specify where doxygen is installed, in case

the configure script can not find it by doing a path search.

--with-dl=<DIR>

With this option, you can specify where the dl (dynamic loading)

library can be located, in case the counfigure script can not find it

on its own.

--without-dl

Many UNIX and UNIX-like platforms -- including Sun Solaris, SGI

IRIX, Linux, and HP-UX 11 -- has a library "libdl" that presents an

interface to the operating system's dynamic linking loader.

Functions of libdl is used for dynamically binding to libraries and

their symbols at run-time. In Coin, this mechanism is used among

other things to load the simage library, and to pick up OpenGL

recent features and extensions.

To disable using libdl, this option can be used. Note that this

should very rarely be of any interest for anybody but the Coin

developers.

Note also that this has nothing to do with Coin being built as a

shared or static library, it only influences the internal workings

of Coin.

--disable-loadlibrary

The Microsoft Windows Win32 API has a function "LoadLibrary()",

which is used for dynamically binding to libraries and their symbols

at run-time. In Coin, this mechanism is used among other things to

load the simage library, and to pick up OpenGL recent features and

extensions.

To disable using LoadLibrary(), this option can be used. Note that

this should very rarely be of any interest for anybody but the Coin

developers.

Note also that this has nothing to do with Coin being built as a

shared or static library, it only influences the internal workings

of Coin.

--with-simage=DIR

This option can be used to specify where the simage library was

installed (prefix, not libdir), in case the configure script is not

able to locate it on its own.

--with-x=DIR

This option can be used to specify where X is installed, in case the

configure script is not able to locate it on its own.

--with-mesa

This option can be used to indicate to the configure script to

prefer the Mesa library (i.e. libMesaGL / mesagl.lib) over an OpenGL

library installed under the default libGL / opengl32.lib name.

--with-opengl=DIR

This option can be used to specify where the OpenGL library is

installed, in case the configure script is not able to locate it on

its own.

--with-pthread=DIR

This option can be used to specify where the POSIX threads library is

installed, in case the configure script is not able to locate it on

its own.

--with-glu=DIR

This option can be used to specify where the GLU library is installed,

in case the configure script is not able to locate it on its own.

--with-alternate=<string>

This option makes sure the given Coin library build gets configured

as an alternate configuration. The default string is "default". To

use an alternate configuration of Coin, you specify the option

"--alternate=<string>" on the coin-config command line.

--with-suffix=<string>

This option appends a suffix to the filename of the Coin library. It

can be used to e.g. append "_g" to a debug version of Coin. It is

used together with the --with-alternate option to avoid installing

the new Coin library over the old one. The default is the empty

string.

CPPFLAGS="<string>"

CFLAGS="<string>"

CXXFLAGS="<string>"

LDFLAGS="<string>"

LIBS="<string>"

If you need to add command line flags to respectively the source code

preprocessor, the C compiler, the C++ compiler, and the linker, invoke

configure with an argument like one of the above.

[coin]/configure CFLAGS="-ansi -pedantic" CXXFLAGS="-ansi -pedantic" [...]

This would cause compilation of both C and C++ files to be done with

the "-ansi" and "-pedantic" options.

You can also use this technique to add MSVC++ command line compiler

options, like e.g. CXXFLAGS="/WX" for treating warnings as errors.

You can also override other things like which compiler is used by

setting $CC, $CXX, $LD, $AR and $RANLIB amongst other variables.

Build Options

=============

Although you take care of setting most configurable things when you run

the configure script, there are a couple of things you can specify at

the build phase.

Parallel Builds

If your build system has much available memory and perhaps multiple

processors, you can speed up the compilation by getting "make" to

compile multiple files at the same time. This is (for GNU make)

specified through the "-j" option. If you want four concurrent jobs

managed by make at all times, try starting the build like this:

make -j 4

Install Options

===============

When you have built Coin and want to install it, there are still a few

options you can do.

Installing onto mounted root file system

If you are making a special root disk that are mounted somewhere else

besides /, you can still configure it with root-relative paths and

install onto it when the disk is mounted somewhere else. If the new

file system is mounted on /mnt/newrootfs, you only need to run the

installation step like this.

make DESTDIR=/mnt/newrootfs install

When Things Fail

================

If you experience configure/build/install problems beyond what can be

resolved by following the instructions in this file and the relevant

README files and the FAQ, you can ask for help on the mailing list

<coin-discuss@coin3d.org> (subscribtion is needed for posting), or you

can contact <coin-support@coin3d.org> for technical support. Before

asking, check that the subject hasn't been discussed and resolved

already by looking through the coin-discuss web archive at

http://auto.coin3d.org/coin-discuss/index.html

If you decide to send mail about the problem, you need to include all

the information that is relevant to the problem with your description.

This includes the file 'config.log' and the terminal output from around

where things fail (the compiler output for the compilation that fails or

the last lines of output from the configure script). A description of

the build environment you use may also be helpful, e.g. the compiler

suite and versions of libraries and any system customizations that may

be relevant to the problem.