DOM guide: Setting up
This article describes how to obtain the Collada DOM and use it in a program.
Downloading the COLLADA DOM
The latest official release of the DOM is version 2.1, which is available as a download on Sourceforge.
You can also get the DOM from the svn repo on Sourceforge. For that you'll need a Subversion client. To check out version 2.1, open a shell and run
svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/tags/2.1 colladadom
or, to check out the trunk, run
svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/trunk colladadom
Windows (Visual Studio)
Building the DOM
Project and solution files for Visual Studio are in
Project files for both VS 2005 and VS 2008 are provided. Open dom.sln and build the
dom project for the DLL DOM, or build
dom-static for the DOM static lib. The output goes to the
Building client applications
In several paths below you'll see "vc8" used. That's for Visual C++ 8 (Visual Studio 2005). If you're using Visual C++ 9 (Visual Studio 2008), substitute "vc9" for "vc8" everywhere.
You'll also see the text "1.4" and "14" below, which refers to Collada 1.4. If you're using Collada 1.5, use "1.5" and "15" instead.
Setting up include directories
Add the following information to your project:
- Add the following lines to the Additional include directories field in the General tab for the C/C++ project configuration settings:
Linking with the COLLADA DOM static lib
- Add the following lines to the Additional library directories field in the General tab for the Linker project configuration settings:
<dom-path>\build\vc8-1.4 (release) or <dom-path>\build\vc8-1.4-d (debug) <dom-path>\external-libs\libxml2\win32\lib <dom-path>\external-libs\pcre\lib\vc8
- Add the following lines to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada14dom21-s.lib (release) or libcollada14dom21-sd.lib (debug) libxml2_a.lib zlib.lib wsock32.lib pcre.lib (release) or pcre-d.lib (debug) pcrecpp.lib (release) or pcrecpp-d.lib (debug)
Linker warnings/Run time errors
When you build your app that links against the DOM statically you might get a Visual Studio warning like this.
LINK : warning LNK4098: defaultlib 'MSVCRT' conflicts with use of other libs; use /NODEFAULTLIB:library
If you ignore this warning you'll then get a runtime failure message that says
This application has failed to start because MSVCR80.dll was not found. ...
If you have this problem, go to the 'Ignore Specific Library' section in the linker settings of your project and add 'msvcrt'. Then relink your project. The link warning should be gone and your app should run fine.
Linking with the COLLADA DOM DLL
- Add the following line to the Preprocessor Definitions field in the Preprocessor tab for the C/C++ project configuration settings:
- Add the following to the Additional library directories field in the General tab for the Linker project configuration settings:
<dom-path>\build\vc8-1.4 (release) or <dom-path>\build\vc8-1.4-d (debug)
- Add the following to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada14dom21.lib (release) or libcollada14dom21-d.lib (debug)
Preparing the external libraries
You need both the libxml and PCRE headers and libs installed to build the DOM. For the domTest program you also need the Boost Filesystem library installed. These libraries are fairly popular and it's expected that most Linux distributions will provide them via the package manager, so these libs aren't provided with the DOM like they are on Windows and Mac. For example, in Ubuntu you could install these libraries using aptitude:
aptitude install libxml2-dev libpcre3-dev libboost-filesystem-dev
Building the DOM
On Linux the DOM builds as both a static lib (.a) and a shared lib (.so). All output goes to the <dom-path>/build folder.
Go to the COLLADA DOM directory and run
This builds a release version of the DOM. More extensive documentation of our make build system is available in the <dom-path>/make/readme file included with the DOM.
Important: Please note make version 3.81 or higher is required in order to build COLLADA DOM, make 3.80 will fail with strange error messages. Also, g++ version 3.4 or higher is required, version 3.3 is known not to be able to build the source code.
Building client applications
Building a client app
If you have a file test.cpp that works with the COLLADA DOM, you can build it to use the static DOM lib with g++ like this:
g++ -I<dom-path>/include -I<dom-path>/include/1.4 test.cpp <dom-path>/build/linux-1.4/libcollada14dom.a -lxml2 -lpcre -lpcrecpp -o test
Or you can build to use the DOM shared lib:
g++ -I<dom-path>/include -I<dom-path>/include/1.4 test.cpp <dom-path>/build/linux-1.4/libcollada14dom.so -o test
Installing the DOM for easier setup
When building client applications on Linux, it's convenient to install headers and libs to a standard system path, such as /usr/[include,lib] or /usr/local/[include,lib]. To install, go to the COLLADA DOM directory and run
which puts the headers in /usr/local/include and the libs in /usr/local/lib. The make install rule also takes a 'prefix' argument that allows you to specify where to install to. See the make readme for more info. You can uninstall by running
The DOM will remember where you installed to and uninstall itself from that location.
The main benefit of this is that you can make sure the DOM shared lib is in your PATH, so you can easily run a program that links against the shared lib.
Note that the only officially supported version of OS X is 10.5 (Leopard), but the DOM used to work on Tiger fine and might still work, as long as you have GNU make 3.81 (available via Macports).
Building the DOM
The Mac uses the same make build architecture as Linux and PS3. Simply run 'make' in the DOM folder to build a release framework. See the make readme for more info. The build output goes to <dom-path>/build.
'make install' is also available to copy the DOM framework to /Library/Frameworks.
Building client applications
In Xcode add the DOM framework to your project (Project->Add to Project). In the build configuration of your target, add <dom-path>/Collada14Dom.framework/Headers to Header Search Paths. For a debug build the framework name is Collada14Dom-d.framework, so adjust paths accordingly.
Important Note! By default, Xcode 3 adds a couple preprocessor flags (_GLIBCXX_DEBUG=1 and _GLIBCXX_DEBUG_PEDANTIC=1) to the debug build of an app to enable extra debugging of the C++ standard library. These settings are incompatible with the DOM or any library that isn't compiled with those settings. These settings cause the DOM to crash when it tries to use C++ containers like std::map. To fix this, remove those flags from your debug build settings (make sure to check the target settings, not just the normal project settings). Another option is to rebuild the DOM with those flags set. To do that open up the <dom>/make/common.mk file and add "-D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC" to the line "ccFlags += -g -D_DEBUG".
Using Make and gcc
Additional gcc compiler arguments:
Additional linker arguments:
-F<dom-path> (if the DOM isn't in a standard path like /Library/Frameworks) -framework Collada14Dom
For a debug build the framework name is Collada14Dom-d.framework, so adjust the gcc arguments accordingly.
Using different installation locations for DOM framework
You can install the DOM framework in a different location than /Library/Frameworks. For example, you might use it as an embedded framework in your application bundle. To avoid linker errors, you can either change the Installation Directory build setting in the DOM Xcode project and rebuild the project, or use otool and install_name_tool to modify an existing framework. For more information, see
The DOM can be built on Windows with the MinGW compiler, which can be obtained from Sourceforge. The compiler that comes with the MinGW 5.1.3 automated installer was used for testing and building the external libs. The external libs should also work with newer versions of the compiler but that hasn't been tested.
In addition to the compiler you need a Unix environment that includes GNU make 3.81. For this there are at least two choices: MSYS (which can be downloaded from the Sourceforge link above) and Cygwin. Both should work fine.
The MinGW build is very similar to the Linux build, so refer to that section and the make readme for more information.
The DOM works on the Cell OS Level 2, for example to be used in a PS3 game. The DOM uses the same make build architecture for PS3 as it does for Mac and Linux, so the same info applies. Run 'make os=ps3' in the DOM directory to do a release build. See the make readme for more info.
Some notes about the PS3 build:
- Cell OS Level 2 doesn't support shared libraries, so only static DOM libs are built.
- The DOM on PS3 uses TinyXml instead of libxml for XML parsing. You'll need to link TinyXml into your app.
- PS3 libraries for PCRE and TinyXml are provided in the external-libs folder.
- It should be possible to build the PS3 version of the DOM on Windows using the GNU makefiles via MinGW/MSYS, but this hasn't been tested.