-
Notifications
You must be signed in to change notification settings - Fork 106
BuildWithAutotools
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.
cd /tmp
git clone --recurse-submodules https://github.com/coin3d/coin coin
mkdir coin-build
cd coin-build
../coin/configure
make
make install
cd ..
rm -rf coin-build coin
Running "make install" directly instead of "make" first and then "make install" is not recommended, 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/configure && make && make install
and not like this
.../coin/configure; make; make install
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 without 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.
--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 man page generation, you can specify where the man pages should be installed with this option. The default is ${prefix}/man, but if you install to /usr you might prefer installing man pages 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 VCS 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 link 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 man pages for the C++ classes Coin consist of. See also the --mandir options listed above.
You need the "doxygen" utility to generate the man pages.
--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 runtime 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 source code. 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 runtime, 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 runtime, 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 runtime, 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 runtime, 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 runtime, 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 runtime, 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 configure 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 runtime. 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 runtime. 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=" 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.
--with-boost=DIR
This option can be used to specify where the Boost library was installed (prefix, not libdir), in case the configure script is not able to locate it on its own.
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.
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
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