Install Instructions Copyright 1998-2010 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.3.tar.gz | tar xvf - mkdir coin-build # 2. Run configure from the build directory: cd coin-build ../Coin-3.1.3/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.3 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.3/configure && make && make install and not like this .../Coin-3.1.3/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= 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= 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= 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= 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= 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= 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=" on the coin-config command line. --with-suffix= 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="" CFLAGS="" CXXFLAGS="" LDFLAGS="" LIBS="" 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 (subscribtion is needed for posting), or you can contact 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.