BuildWithCMake

Introduction

This document contains instructions for those who intend to build the Coin library from source and install it on their system.

It does not contain any information about installing binary distributions of Coin.

We encourage you to use the CMake build configuration in favor of Autotools as all development efforts are directed to this path. The Autotools build system is still maintained but at a significantly lower priority.

The Build Environment

CMake

Coin uses CMake 3.0 or later for the configuration, building, and installation procedures.
This means you need a build tool and a C/C++ compiler that is supported by CMake.

On Microsoft Windows platforms, you don't need to install the Cygwin environment or something equivalent anymore to get through the build procedure.
CMake will generate native projects for the build tools like Ninja, Make, XCode, or Microsoft Visual Studio/MSBuild.

Git

To get the sources you need a Git client, Git, Git GUI clients, or TortoiseGit are a good choice.
The Git command git need to be available at the command line.
Downloading the compressed sources from the Downloads section of the project won't work as the .git directory is not contained in the zip and therefore submodules are not be properly populated.
Instead of doing so you need to clone the repository, e.g. calling git clone --recurse-submodules https://github.com/coin3d/coin.

Boost

Boost C++ libraries are needed (at least version 1.45.0 from boost).
Up to now Coin only uses the header only libraries, so downloading and installing the sources without building is sufficient.
Boost binary packages are provided for Windows on sourceforge. To find out how the Visual Studio version is related to the internal numbering have a look at Internal_version_numbering.
On Linux prebuilt binaries for your distribution should be provided by the package manager.
Boost versions > 1.82 deprecated the support for C++03 standard. If you want to use such a version you may need to add -DCMAKE_CXX_STANDARD=11 to your CMake command line. See also CMake configuration options further down on this page. Building Coin itself only requires a compiler that supports the C++98 standard.

Doxygen

As the generation of the Coin documentation is enabled by default, Doxygen is required.

NSIS

If you intend to generate an installation package of the Coin library on Windows, NSIS is required.

XQuartz, OpenMotif

If you intend to build the Coin library on macOS using X11 an appropriate X11 implementation like XQuartz as well as OpenMotif are required. You may install the packages via homebrew or macports.

Coin build configuration using CMake

First you need to find out what generators are supported by CMake on your platform.
The command cmake --help on the command line provides you an extensive list of supported generators.
We strongly recommend you to specify the generator explicitly by using CMake's option -G as it makes your build behave deterministic.
E.g., when you install an additional development environment on Windows or a newer CMake version the default compiler for the platform selected by CMake may change.
Without the generator option CMake will pick up a different compiler by default. Otherwise CMake always uses the explicitly specified generator.

Step (5) is always an optional build step for those who intend to create distributable packages for a specific platform.

For additional configuration options not mentioned on the sample command lines see "CMake configuration options" on this page.

Linux

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cd coin_build
    make
(4) make install
(5) cd cpack.d
    cpack --config debian.cmake
    cpack --config fedora.cmake

or

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cmake --build coin_build --target all --config Release -- -j4
(4) cmake --build coin_build --target install --config Release -- -j4
(5) cd coin_build/cpack.d
    cpack --config debian.cmake
    cpack --config fedora.cmake

Get the sources using Git clone command.
Configure the build.
If you just want a standard installation (or regenerate the Makefiles using cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an out-of-source build mode, i.e. you must not run the cmake command directly from the source directory. Instead you need to run it from a separate build directory, e.g. coin_build.
On recent CMake versions (3.13 and later) the option -H has been superseded by -S.
Or, if available, you can edit all options in a GUI like this
cmake-gui ./coin
Build the Coin library using the default build tool on the platform.
Or, alternatively use the CMake build tool mode. This uses coin_build as build directory, builds the target all for the Release configuration and passes -j4 (parallel building with 4 cores) to the underlying default build tool (the default build tool on Linux is make).
Install the Coin library using the default build tool on the platform.
Or, alternatively again use the CMake build tool mode. This uses coin_build as build directory, builds the target install for the Release configuration and passes -j4 (parallel building with 4 cores) to the underlying default build tool (the default build tool on Linux is make).
Build installation packages of the Coin library (optional)
This uses CPack, a packaging tool from the CMake suite.
If something does not work you may need to add the --verbose --debug options to the call to figure out what went wrong or is missing.
Finally when you are done remove the build directory
rm -rf coin_build

Windows

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Visual Studio 14 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D -DBOOST_ROOT=C:\Data\Boost-1.56.0 -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cmake --build coin_build --target ALL_BUILD --config Release -- /nologo /verbosity:minimal /maxcpucount
(4) cmake --build coin_build --target INSTALL --config Release -- /nologo /verbosity:minimal /maxcpucount
(5) cd coin_build/cpack.d
    cpack --config windows.cmake

or

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Visual Studio 14 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D -DBOOST_ROOT=C:\Data\Boost-1.56.0 -DCOIN_BUILD_DOCUMENTATION=OFF
(3) MSBuild /p:Configuration=Release /t:ALL_BUILD Coin.sln /nologo /verbosity:minimal /maxcpucount
(4) MSBuild /p:Configuration=Release /t:INSTALL Coin.sln /nologo /verbosity:minimal /maxcpucount
(5) cd coin_build/cpack.d
    cpack --config windows.cmake

Get the sources using Git clone command.
Configure the build.
If you just want a standard installation (or regenerate the build files using cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an out-of-source build mode, i.e. you must not run the cmake command directly from the source directory. Instead you need to run it from a separate build directory, e.g. coin_build.
On recent CMake versions (3.13 and later) the option -H has been superseded by -S.
Or, if available, you can edit all options in a GUI like this
cmake-gui ./coin On Windows the Boost root directory need to be explicitly specified as it could not be found otherwise.
Build the Coin library
Open Coin.sln in the build directory from Microsoft Visual Studio. Build the ALL_BUILD project from the Microsoft Visual Studio solution explorer.
Or, alternatively use the CMake build tool mode. This uses coin_build as build directory, builds the target ALL_BUILD for the Release configuration and passes /nologo /verbosity:minimal /maxcpucount (parallel building with maximum number of cores available) to the underlying default build tool (the default build tool on Windows is MSBuild).
Or, directly build the Coin library using the default build tool on the platform from the command line.
Install the Coin Library
Build the INSTALL project from the Microsoft Visual Studio solution explorer.
Or, alternatively again use the CMake build tool mode. This uses coin_build as build directory, builds the target INSTALL for the Release configuration and passes /nologo /verbosity:minimal /maxcpucount (parallel building with maximum number of cores available) to the underlying default build tool (the default build tool on Windows is MSBuild).
Or, install the Coin library using the default build tool on the platform from the command line.
Build NSIS installation packages of the Coin library (optional)
If something does not work you may need to add the --verbose --debug options to the call to figure out what went wrong or is missing.
Finally when you are done remove the build directory
rmdir /s coin_build

Note

NURBS rendering in Coin relies heavily on GLU 1.3. As Windows does not provide a proper GLU 1.3 implementation in its glu32.lib since years you need to build and install superglu before building Coin. Otherwise you will see tessellation artifacts.

(1) git clone --recurse-submodules https://github.com/coin3d/superglu superglu
(2) cmake -Hsuperglu -Bsuperglu_build -G "Visual Studio 14 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D
(3) cmake --build superglu_build --target ALL_BUILD --config Release -- /nologo /verbosity:minimal /maxcpucount
(4) cmake --build superglu_build --target INSTALL --config Release -- /nologo /verbosity:minimal /maxcpucount

To build Coin with superglu you need to add the prefix path of its installation directory -DCMAKE_PREFIX_PATH=C:\Coin3D and -DUSE_SUPERGLU=ON to the CMake command line, e.g.

cmake -Hcoin -Bcoin_build -G "Visual Studio 14 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D -DCMAKE_PREFIX_PATH=C:\Coin3D -DBOOST_ROOT=C:\Data\Boost-1.56.0 -DCOIN_BUILD_DOCUMENTATION=OFF -DUSE_SUPERGLU=ON

macOS

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D -DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF
(3) cd coin_build
    make
(4) sudo make install
(5) cd cpack.d
    cpack --config darwin-dmg.cmake
    cpack --config darwin-pkg.cmake

or

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D -DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build coin_build --target all --config Release -- -j4
(4) sudo cmake --build coin_build --target install --config Release -- -j4
(5) cd coin_build/cpack.d
    cpack --config darwin-dmg.cmake
    cpack --config darwin-pkg.cmake

Get the sources using Git clone command.
Configure the build.
If you just want a standard installation (or regenerate the Makefiles using cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an out-of-source build mode, i.e. you must not run the cmake command directly from the source directory. Instead you need to run it from a separate build directory, e.g. coin_build.
On recent CMake versions (3.13 and later) the option -H has been superseded by -S.
Or, if available, you can edit all options in a GUI like this
cmake-gui ./coin
Build the Coin framework using the default build tool on the platform.
Or, alternatively use the CMake build tool mode. This uses coin_build as build directory, builds the target all for the Release configuration and passes -j4 (parallel building with 4 cores) to the underlying default build tool (the default build tool on Linux is make).
Install the Coin framework using the default build tool on the platform.
Or, alternatively again use the CMake build tool mode. This uses coin_build as build directory, builds the target install for the Release configuration and passes -j4 (parallel building with 4 cores) to the underlying default build tool (the default build tool on Linux is make).
As you are like to install into system locations you need to prefix your command with sudo.
By default the name of the Coin framework is Inventor.
Build installation packages of the Coin framework (optional)
This uses CPack a packaging tool from the CMake suite.
If something does not work you may need to add the --verbose --debug options to the call to figure out what went wrong or is missing.
Finally when you are done remove the build directory
rm -rf coin_build

CMake configuration options

CMAKE_BUILD_TYPE

Probably the most common types are Debug and Release.
The Debug build will append a d to the target library name.

CMAKE_INSTALL_PREFIX

Install path prefix, prepended onto install directories. If set to /tmp then the library will install into /tmp/lib.
When building and installing Coin as framework on macOS (e.g. add -DCOIN_BUILD_MAC_FRAMEWORK=ON to the cmake call) you should set it to either ~/Library/Frameworks, /Library/Frameworks, /System/Library/Frameworks, or /Network/Library/Frameworks

CMAKE_PREFIX_PATH

Semicolon separated list of directories specifying installation prefixes to be searched by CMake find_package, find_library, find_... commands.
When CMake searches for config packages, e.g. for simage with find_package(simage), these directories are searched to find <PackageName>Config.cmake or <packagename>-config.cmake.
This can be used to specify non standard installation places for required package information, e.g. /opt/local/Boost;/opt/local/Qt5 or C:\Data\local\Boost;C:\Data\Qt-5.12.0.

COIN_BUILD_SHARED_LIBS

Build shared library when ON, static when OFF. Default is ON.

COIN_BUILD_DOCUMENTATION

Build HTML documentation on all platforms when ON, as well as man pages on platforms other than Windows. Default is OFF. The latest version of the documentation can always be found on the Documentation page of the wiki.

COIN_BUILD_DOCUMENTATION_MAN

Build Coin man pages when ON on platforms other than Windows. Default is OFF.

COIN_BUILD_DOCUMENTATION_QTHELP

Build QtHelp documentation when ON (requires Qt installation https://www.qt.io ) Default is OFF.

COIN_BUILD_DOCUMENTATION_CHM

Build compressed HTML help manual on Windows platform when ON (requires Microsoft HTML Help Workshop download). Default is OFF.

COIN_BUILD_INTERNAL_DOCUMENTATION

Depends on COIN_BUILD_DOCUMENTATION to be ON. When OFF (the default) only the documentation regarding the public API will be built, and warnings for undocumented entities are turned on.
When ON the generated documentation will include internal classes, which can be useful for Coin developers. Since it is less common to fully document internal entities, warnings for undocumented entities are turned off.

COIN_BUILD_MAC_FRAMEWORK

Build Coin as framework when ON, as library when OFF. Default is OFF.
On macOS, the default behavior 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 ${CMAKE_INSTALL_PREFIX}/{lib,include} instead, set this option to OFF.

COIN_BUILD_MAC_X11

Link Coin to the X11 implementation of GL when ON, to OpenGL framework when OFF. Default is OFF.
You need to have OpenMotif and XQuartz installed.

COIN_BUILD_TESTS

Build the provided test cases when ON. Default is ON.

HAVE_MULTIPLE_VERSION

Forces the use of versioned paths for includes and documentation when ON, usual behavior otherwise.

COIN_BUILD_SINGLE_LIB

Build only one library when ON, multiple when OFF. Default is ON for Windows, OFF for other platforms.

COIN_BUILD_MSVC_MP

Enable build with multiple processes in Visual Studio. Default is ON.
(Only available when using Visual C++ compiler)

BOOST_ROOT

If you placed your Boost installation into a directory that is not known to CMake you may need to specify BOOST ROOT on the CMake command line, e.g. -DBOOST_ROOT=/opt/local/boost-1.56.0 on Linux and -DBOOST_ROOT=C:\Data\Boost-1.56.0 on Windows.

CMAKE_CXX_STANDARD

If you are using a Boost version > 1.82 you may need (at least on macOS) to specify the C++ Standard version on the CMake command line, e.g. -DCMAKE_CXX_STANDARD=11.

USE_SUPERGLU

NURBS rendering in Coin relies heavily on GLU 1.3 support. As Windows does not provide a GLU 1.3 implementation in its glu32.lib but only GLU 1.1 we provide superglu (a library that contains the SGI GLU 1.3 implementation). By adding this setting to the command line Coin will search during the CMake configure step for the superglu library in the CMAKE_PREFIX_PATH. Default is OFF.

GUI-Toolkit (SoQt, SoWin, SoXt, Quarter) build configuration using CMake

Building the GUI toolkits is very similar to the Coin build commands.
To build a GUI toolkit different from SoQt simply replace soqt with sowin, soxt or quarter as well as SOQT with SOWIN, SOXT or QUARTER in the build commands. Step (5) is always an optional build step for those who intend to create distributable packages for a specific platform.

Linux

(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_PREFIX_PATH="/usr/local" -DSOQT_BUILD_DOCUMENTATION=OFF
(3) cmake --build soqt_build --target all --config Release -- -j4
(4) cmake --build soqt_build --target install --config Release -- -j4
(5) cd cpack.d
    cpack --config debian.cmake
    cpack --config fedora.cmake

Windows

(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Visual Studio 14 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D -DCMAKE_PREFIX_PATH="C:\Coin3D;C:\Qt\5.12.1\msvc2015_64" -DBOOST_ROOT=C:\Data\Boost-1.56.0 -DSOQT_BUILD_DOCUMENTATION=OFF
(3) cmake --build soqt_build --target ALL_BUILD --config Release -- /nologo /verbosity:minimal /maxcpucount
(4) cmake --build soqt_build --target INSTALL --config Release -- /nologo /verbosity:minimal /maxcpucount
(5) cd soqt_build/cpack.d
    cpack --config windows.cmake

macOS

(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D -DCMAKE_PREFIX_PATH="/Users/name/Coin3D;/usr/local/Cellar/qt/5.12.1" -DSOQT_BUILD_DOCUMENTATION=OFF -DSOQT_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build soqt_build --target all --config Release -- -j4
(4) cmake --build soqt_build --target install --config Release -- -j4
(5) cd cpack.d
    cpack --config darwin-dmg.cmake
    cpack --config darwin-pkg.cmake

macOS and X11

To use X11 on macOS you need to provide X11/XQuartz and OpenMotif packages and build Coin with an additional option -DCOIN_BUILD_MAC_X11=ON.

(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D -DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF -DCOIN_BUILD_MAC_X11=ON
(3) cmake --build coin_build --target all --config Release -- -j4
(4) cmake --build coin_build --target install --config Release -- -j4
(1) git clone --recurse-submodules https://github.com/coin3d/soxt soxt
(2) cmake -Hsoxt -Bsoxt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D -DCMAKE_PREFIX_PATH="/Users/name/Coin3D" -DSOXT_BUILD_DOCUMENTATION=OFF -DSXQT_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build soxt_build --target all --config Release -- -j4
(4) cmake --build soxt_build --target install --config Release -- -j4
...

Some build tips

CMake caches the build options and uses these as defaults during subsequent runs.
To clear the cache, delete the file CMakeCache.txt or empty the build directory completely.

If you build both Debug and Release configurations and don't want to make clean and reconfigure each time something changes, use a separate build directory for each type.

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 (subscription is needed for posting), or you can contact us per email for technical support.

Before asking, check that the subject hasn't been discussed and resolved already by looking through the coin-discuss mailing list or at the Coin issue tracker.

If you decide to send us an email about the problem or add an entry to the issue tracker, you should include all the information that is relevant to the problem together with your description.

This includes the terminal output from CMake for the compilation that fails or at least the entire CMake error message.

A description of the build environment you use may also be helpful, e.g. the compiler suite and versions of libraries and any system customization that may be relevant to the problem.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BuildWithCMake

Introduction

The Build Environment

CMake

Git

Boost

Doxygen

NSIS

XQuartz, OpenMotif

Coin build configuration using CMake

Linux

Windows

Note

macOS

CMake configuration options

GUI-Toolkit (SoQt, SoWin, SoXt, Quarter) build configuration using CMake

Linux

Windows

macOS

macOS and X11

Some build tips

When Things Fail

Clone this wiki locally