DOM guide: Setting up

DOM 1.3	This revision of this article is current for COLLADA DOM version 1.3. See DOM 1.3 documentation for all related articles. See Portal:COLLADA DOM for other documentation versions.

This article describes how to set up your software and system to use the COLLADA DOM.

Overview

To use the COLLADA DOM in a client application, you must:

• Download the DOM
• Download and prepare the external libraries that the DOM uses
• Build the DOM
• Build your client application

Downloading the COLLADA DOM

The latest official release of the DOM is version 1.3.0, and is available as a zip file or a Windows installer from the SourceForge downloads page. The Subversion repository on SourceForge has the newest development code containing the most recent bug fixes and features. The rest of this page is written for the latest code in Subversion. If you're using DOM 1.3.0, use this page instead.

To use the code from Subversion, you'll first need to download and install a Subversion client for your platform from http://subversion.tigris.org/project_packages.html. Then, open a console and run the command:

svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/COLLADA_DOM/trunk COLLADA_DOM

That downloads the latest copy of the COLLADA DOM to the COLLADA_DOM subdirectory (as specified by the last parameter).

Setting up on Windows

Preparing the external libraries

All of the DOM's dependencies are packaged in an "external-libs" folder on SourceForge. You can get the external libs with this command:

svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/external-libs external-libs

Then create an environment variable called COLLADA_EXTERNAL_LIBS_LOCATION that points to the external-libs directory using an absolute path, like so: C:\collada\external-libs

Building the DOM

Project and solution files for Visual Studio can be found in

<COLLADA_DOM-directory>\projects

The files for VS 2003 will be in the "VC++7" folder and the files for VS 2005 will be in the "VC++8" folder. Open COLLADA_DOM.sln and build. If you want to use the DOM as a DLL, make sure to build the DLL DOM configuration.

The output goes to the lib folder for .lib files or the bin folder for DLLs.

Building client applications

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:

<COLLADA_DOM-path>\include
<COLLADA_DOM-path>\include\1.4

Linking with the static COLLADA DOM libararies

• Add the following lines to the Additional library directories field in the General tab for the Linker project configuration settings:

<COLLADA_DOM-path>\lib\vc8_1.4
$(COLLADA_EXTERNAL_LIBS_LOCATION)\libxml2\win32\lib
$(COLLADA_EXTERNAL_LIBS_LOCATION)\pcre\vc8\lib

• Add the following lines to the Additional Dependencies field in the Input tab for the Linker project configuration settings:

libcollada_dae.lib
libcollada_dom.lib
libxml2_a.lib
zlib.lib
wsock32.lib
pcre.lib
pcrecpp.lib

If you're using Visual Studio 2005, link against pcre-d.lib and pcrecpp-d.lib in your debug build, and pcre.lib and pcrecpp.lib in your release build.

Linking with the COLLADA DOM DLL

• Add the following line to the Preprecessor Definitions field in the Preprocessor tab for the C/C++ project configuration settings:

DOM_DYNAMIC

• Add the following line to the Additional library directories field in the General tab for the Linker project configuration settings:

<COLLADA_DOM-path>\lib\vc8_1.4_dll

• Add the following line to the Additional Dependencies field in the Input tab for the Linker project configuration settings:

libcolladadom13.lib

Additional configuration options

• If you are using Visual Studio 2003, substitute vc7 for vc8 in the DOM library search path. If using the static DOM libs, also substitute vc7.1 for vc8 in the PCRE library search path.
• To use the debug libraries append "_debug" to the end of the COLLADA DOM library path, for example "<COLLADA_DOM-path>\lib\vc8_1.4_debug".
• Make sure that your application is using the correct runtime libraries. The Runtime Library field in the Code Generation tab for the C/C++ configuration options should be set to:
  • "Multi-threaded DLL" if using the release builds of the library
  • "Multi-threaded Debug DLL" if using the debug builds

Setting up on Linux

Preparing the external libraries

You need both the libxml and PCRE headers and libs installed. On a Debian-based system you can install them using apt-get:

apt-get install libxml2-dev libpcre3-dev

Most modern Linux distributions include packages for libxml and PCRE, but if yours doesn't you'll need to install them manually.

Building the DOM

On Linux the DOM builds as both a static lib (.a) and a shared lib (.so). Both types of files go to the lib folder.

Go to the COLLADA DOM directory and run

make

for a debug build or

make RELEASE=1

for a release build.

Building client applications

Adding the COLLADA DOM to /usr/include and /usr/lib

When building client applications on Linux, it's convenient to install the DOM headers and libs to /usr/include and /usr/lib, respectively. To install, go to the COLLADA DOM directory and run

make install

to install the debug COLLADA DOM or

make install RELEASE=1

to install the release version of the DOM. You can uninstall by running

make uninstall

Building the Client App

If you have a file test.cpp that works with the COLLADA DOM, you can build it to use the static DOM libs with g++ like this:

g++ -I/usr/include/collada test.cpp -lcollada_dae -lcollada_dom -lcollada_dae -lxml2 -lpcre -lpcrecpp -o test

Or you can build to use the DOM shared libs:

g++ -I/usr/include/collada test.cpp -lcollada_dae_shared -lcollada_dom_shared -o test

In the static linking example, the collada_dae lib is deliberately included twice. This is necessary to resolve all the dependencies between the DAE and the DOM libraries.

Setting up on Mac

Preparing the external libraries

The DOM requires libxml and PCRE. OS X 10.4 (Tiger) and up come with a libxml build that works fine with the DOM. For PCRE, headers and a Mac universal lib are provided in the external libs folder on SourceForge, which you can get with the following command:

svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/external-libs external-libs

The external libs folder should be placed at the same level in the folder hierarchy as the DOM and must be named "external-libs". Here's an example setup:

/Users/sthomas/cdom/colladaDom
/Users/sthomas/cdom/external-libs

If you want to use libxml2 to validate your COLLADA files against the schema, you have to download and install an updated version of libxml2 from here. That is because of a bug in an earlier libxml2-version that is shipped with OS X Tiger (steveT - is this fixed in Leopard?). However, the DOM itself is not affected by it and runs perfectly with the Tiger-shipped libxml2 version.

Building the DOM

NOTE: Mac-projects are currently available in SVN only. Get a current precompiled UniversalBinary SVN-version from here.

The preferred way of using the DOM on Mac OS X is to build a framework containing the shared library, necessary header files, and documentation (see here for more information about the concept of frameworks).

The project file for Xcode to build the framework can be found in

<COLLADA_DOM-directory>/projects/Xcode

Note that you should use Xcode 2.4 or better. You can download the latest version from here.

Using the Release configuration, the DOM is built as a Universal Binary for PPC and Intel. The preferred installation location is /Library/Frameworks.

Building client applications

Copy the DOM-framework to /Library/Frameworks, the standard location for external frameworks.

Using Xcode

In Xcode add the framework to your project (Project->Add to Project). In the build-configuration of your target, add -Library/Frameworks/Collada141Dom.framework/Headers to Header Search Paths. You are now ready to build your client applications.

Using Make and gcc

Additional gcc compiler arguments:

-I/Library/Frameworks/Collada141Dom.framework/Headers

Additional linker arguments:

-framework Collada141Dom

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 already build framework. For more information, see

man otool

and

man install_name_tool

Setting up on PS3

The DOM works on the Cell OS Level 2, for example to be used in a PS3 game. Building the DOM to run on the PS3 is exactly the same as building it to run on Linux, except that you pass the parameter PLATFORM_NAME=ps3 on the make command line. The other supported make parameters are the same as for the Linux build.

There are a few other differences between the DOM on PS3 and the DOM on Linux:

• 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 cygwin, but this hasn't been tested.