INSTALL

                          Install Instructions

            Copyright (C) Kongsberg Oil & Gas Technologies

                         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.

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

    cd /tmp
    gzip -cd Coin-3.1.2.tar.gz | tar xvf -
    mkdir coin-build

  # 2. Run configure from the build directory:

    cd coin-build
    ../Coin-3.1.2/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-3.1.2

Running "make install" directly instead of "make" first and then
"make install" is not recomended, since this will lead to partial
installations in the case where the build breaks for some reason.  Also, if
you want to launch all the build-commands on one command-line, don't separate
commands with ; but separate them with && so the failure of one will stop the
full chain of commands.  Like this:

  .../Coin-3.1.2/configure && make && make install

and not like this

  .../Coin-3.1.2/configure; make; make install


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.

--disable-vrml97

  If you want a smaller Coin binary and only need the core functionality,
  you can use this to disable building the vrml97 part of Coin.

--disable-nodekits

  If you want a smaller Coin binary and only need the core functionality,
  you can use this to disable building the nodekit part of Coin.  This
  severely cripples Coin, and Coin will no longer be standard compliant
  with regards to the Inventor file format.  Disabling nodekits also has
  additional implications, like disabling some foreign file formats, and
  the builtin visualization for the scene graph profiler.

--disable-draggers

  If you want a smaller Coin binary and only need the core functionality,
  you can use this to disable building the dragger part of Coin.  This
  severely cripples Coin, and Coin will no longer be standard compliant
  with regards to the Inventor file format.

--disable-manipulators

  If you want a smaller Coin binary and only need the core functionality,
  you can use this to disable building the manipulator part of Coin.  This 
  severely cripples Coin, and Coin will no longer be standard compliant
  with regards to the Inventor file format.

--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.

  On Mac OS X, this is default behaviour at the moment, done as a workaround
  for a problem with debugging symbols.

--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.