Difference between revisions of "DOM guide: Setting up"

From COLLADA Public Wiki
Jump to navigation Jump to search
m (Note dead link)
 
(59 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{DOMversion|1.3}}
+
This article describes how to obtain the Collada DOM and use it in a program.
 
 
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==
 
==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 [http://sourceforge.net/project/showfiles.php?group_id=157838 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 [http://collada.org/mediawiki/index.php?title=DOM_guide:_Setting_up&oldid=4635 this page] instead.
+
The latest official release of the DOM is version 2.2, which is available as a [http://sourceforge.net/project/showfiles.php?group_id=157838 download] on Sourceforge.
  
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:
+
You can also get the DOM from the SVN repository on Sourceforge. For that you'll need a [http://subversion.tigris.org/project_packages.html Subversion client]. To check out version 2.2, open a shell and run
  <nowiki>svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/COLLADA_DOM/trunk COLLADA_DOM</nowiki>
+
  svn co <nowiki>https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/tags/2.2</nowiki> colladadom
That downloads the latest copy of the COLLADA DOM to the COLLADA_DOM subdirectory (as specified by the last parameter).
+
or, to check out the trunk, run
 +
svn co <nowiki>https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/trunk</nowiki> colladadom
  
==Setting up on Windows==
+
==Windows (Visual Studio)==
===Preparing the external libraries===
+
===Building the DOM===
All of the DOM's dependencies are packaged in an "external-libs" folder on SourceForge. You can get the external libs with this command:
+
Project and solution files for Visual Studio are in
<nowiki>svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/external-libs external-libs</nowiki>
+
<dom-path>\projects
 +
Project files for both VS 2005 and VS 2008 are provided. Open dom.sln and build the <code>dom</code> project for the DLL DOM, or build <code>dom-static</code> for the DOM static lib. The output goes to the <code>''<dom-path>''\build</code> folder. Before building the DOM static lib be sure to include daeZAEUncompressHandler.cpp in the project source files. This can be found in <code>''<dom-path>''\include\dae</code> folder.
  
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 client applications===
  
===Building the DOM===
+
In several paths below you'll see "vc8". That's for Visual C++ 8 (Visual Studio 2005). If you're using Visual C++ 9 (Visual Studio 2008), substitute "vc9" for "vc8" everywhere.
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.
 
  
===Building client applications===
+
You'll also see "1.4" and "14", which refers to COLLADA 1.4. If you're using COLLADA 1.5, use "1.5" and "15" instead.
  
 
====Setting up include directories====
 
====Setting up include directories====
Add the following information to your project:
+
*In your project, add these lines to the '''Additional include directories''' field in the '''General''' tab for the '''C/C++''' project configuration settings:
*Add the following lines to the '''Additional include directories''' field in the '''General''' tab for the '''C/C++''' project configuration settings:
+
  <dom-path>\include
  <COLLADA_DOM-path>\include
+
  <dom-path>\include\1.4
  <COLLADA_DOM-path>\include\1.4
+
<dom-path>\external-libs\boost
 +
 
 +
====Setting up preprocessor definitions====
 +
*In '''dom''' or '''dom-static''' project, add these lines to the '''Preprocessor Definitions''' field in the '''Preprocessor''' tab for the '''C/C++''' project configuration settings:
 +
BOOST_ALL_NO_LIB
 +
PCRE_STATIC
 +
DOM_INCLUDE_LIBXML
  
====Linking with the static COLLADA DOM libararies====
+
====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:
 
*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 (for VS 2005)
+
  ''<dom-path>''\build\vc8-1.4 (release) or ''<dom-path>''\build\vc8-1.4-d (debug)
<COLLADA_DOM-path>\lib\vc7_1.4 (for VS 2003)
+
  ''<dom-path>''\external-libs\libxml2\win32\lib
  $(COLLADA_EXTERNAL_LIBS_LOCATION)\libxml2\win32\lib
+
''<dom-path>''\external-libs\pcre\lib\vc8
 +
''<dom-path>''\external-libs\minizip\win32\lib\
 +
''<dom-path>''\external-libs\boost\lib\vc8
 
*Add the following lines to the '''Additional Dependencies''' field in the '''Input''' tab for the '''Linker''' project configuration settings:
 
*Add the following lines to the '''Additional Dependencies''' field in the '''Input''' tab for the '''Linker''' project configuration settings:
  libcollada_dae.lib
+
  libcollada14dom22-s.lib (release) or libcollada14dom22-sd.lib (debug)
libcollada_dom.lib
 
 
  libxml2_a.lib
 
  libxml2_a.lib
 
  zlib.lib
 
  zlib.lib
 
  wsock32.lib
 
  wsock32.lib
 +
pcre.lib (release) or pcre-d.lib (debug)
 +
pcrecpp.lib (release) or pcrecpp-d.lib (debug)
 +
minizip.lib (release) or minizip-d.lib (debug)
 +
libboost_filesystem.lib (release) or libboost_filesystem-d.lib (debug)
 +
libboost_system.lib (release) or libboost_system-d.lib (debug)
 +
 +
=====Linker warnings/Runtime errors=====
 +
When you build an application 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 <code>msvcrt</code>. Then relink your project. The link warning should be gone and your application should run fine.
  
 
====Linking with the COLLADA DOM DLL====
 
====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:
+
*Add the following line to the '''Preprocessor Definitions''' field in the '''Preprocessor''' tab for the '''C/C++''' project configuration settings:
 
  DOM_DYNAMIC
 
  DOM_DYNAMIC
*Add the following line to the '''Additional library directories''' field in the '''General''' tab for the '''Linker''' project configuration settings:
+
*Add the following to the '''Additional library directories''' field in the '''General''' tab for the '''Linker''' project configuration settings:
  <COLLADA_DOM-path>\lib\vc8_1.4_dll (for VS 2005)
+
  <dom-path>\build\vc8-1.4 (release) or <dom-path>\build\vc8-1.4-d (debug)
  <COLLADA_DOM-path>\lib\vc7_1.4_dll (for VS 2003)
+
  <dom-path>\external-libs\boost\lib\vc8
*Add the following line to the '''Additional Dependencies''' field in the '''Input''' tab for the '''Linker''' project configuration settings:
+
*Add the following to the '''Additional Dependencies''' field in the '''Input''' tab for the '''Linker''' project configuration settings:
  libcolladadom13.lib
+
  libcollada14dom22.lib (release) or libcollada14dom22-d.lib (debug)
 
+
libboost_filesystem.lib (release) or libboost_filesystem-d.lib (debug)
====Additional configuration options====
+
libboost_system.lib (release) or libboost_system-d.lib (debug)
*If you are using Visual Studio .NET 2003, substitute '''vc7''' for '''vc8''' in the '''Additional library directories''' field.
 
*To use the debug version of the libraries:
 
*# Append "_d" to the end of the COLLADA DOM library names, for example, libcollada_dae_d.lib.
 
*# Replace "lib" with "lib-dbg" in the library path.
 
*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==
+
==Linux==
 
===Preparing the external libraries===
 
===Preparing the external libraries===
On Linux, make sure the libxml2 headers and libs are installed. On Debian-based systems you can install the package libxml2-dev:
+
You need both the libxml and [http://www.pcre.org/ PCRE] headers and libs installed to build the DOM. For the domTest program you also need the [http://www.boost.org/doc/libs/1_35_0/libs/filesystem/doc/index.htm 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 libraries aren't provided with the Linux DOM as they are for Windows and Mac. For example, in Ubuntu you could install these libraries using aptitude:
  apt-get install libxml2-dev
+
  aptitude install libxml2-dev libpcre3-dev libboost-filesystem-dev
  
 
===Building the DOM===
 
===Building the DOM===
There are no prebuilt binaries available for Linux, so you'll have to build the DOM yourself. Also, currently there is no shared library version of the COLLADA DOM on Linux. Only static libs are available.
+
On Linux, the DOM builds as both a static lib (.a) and as a shared lib (.so). All output goes to the <code>''<dom-path>''/build</code> folder.
  
 
Go to the COLLADA DOM directory and run
 
Go to the COLLADA DOM directory and run
 
  make
 
  make
for a debug build or
 
make RELEASE=1
 
for a release build.
 
  
===Building client applications===
+
This builds a release version of the DOM. More extensive documentation of our make build system is available in the [http://collada-dom.svn.sourceforge.net/viewvc/collada-dom/trunk/dom/make/readme?view=markup ''<dom-path>''/make/readme] ''(DEAD LINK)'' file included with the DOM.
  
====Adding the COLLADA DOM to /usr/include and /usr/lib====
+
'''Important:''' <code>make</code> version 3.81 or higher is required to build COLLADA DOM. <code>make</code> 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.
When building client applications on Linux, it's convenient to install the DOM headers and libs to <code>/usr/include</code> and <code>/usr/lib</code>, 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====
+
===Building client applications===
If you have a file test.cpp that works with the COLLADA DOM, you can build it with g++ like this:
 
g++ -Wall -I/usr/include/collada test.cpp -lcollada_dae -lcollada_dom
 
    -lcollada_dae -lcollada_STLDatabase -lcollada_stdErrPlugin -lcollada_LIBXMLPlugin -lxml2 -o test
 
  
The <code>collada_dae</code> is deliberately included twice. This is necessary to resolve all the dependencies between the DAE and the DOM libraries.
+
====Building a client app====
 +
If you have a file named 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 -L''<dom-path>''/build/linux-1.4
 +
  ''<dom-path>''/build/linux-1.4/libcollada14dom.a -lxml2 -lpcre -lpcrecpp -lboost_filesystem -lminizip -o test
 +
'''NOTE:''' you may need to add -lcollada14dom after specifying where the libraries are with -L.
  
==Setting up on Mac==
+
Or you can build to use the DOM shared lib:
===Preparing the external libraries===
+
g++ -I''<dom-path>''/include -I''<dom-path>''/include/1.4 test.cpp  -L''<dom-path>''/build/linux-1.4  
On OS X Tiger (10.4) all dependencies to build the COLLADA DOM are shipped with the OS. No additional installations are required.  
+
  ''<dom-path>''/build/linux-1.4/libcollada14dom.so -lxml2 -lpcre -lpcrecpp -lboost_filesystem -lminizip -o test
  
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 [http://www.explain.com.au/oss/libxml2xslt.html here]. That is because of a bug in an earlier libxml2-version that is shipped with OS X Tiger. However, the DOM itself is not affected by it and runs perfectly with the Tiger-shipped libxml2 version.
+
====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
 +
make install
 +
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 [http://collada-dom.svn.sourceforge.net/viewvc/collada-dom/trunk/dom/make/readme?view=markup make readme] for more info.
  
===Building the DOM===
+
You can uninstall by running
''NOTE: Mac-projects are currently available in SVN only.'' Get a current precompiled UniversalBinary SVN-version from [http://stud4.tuwien.ac.at/~e0425503/collada_osx_binaries/DOM_SVN here].
+
make uninstall
 +
The DOM remembers your installation location and uninstalls itself from that location.
  
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 [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html here] for more information about the concept of frameworks).  
+
The main benefit of this is that you can make sure that the DOM shared lib is in your PATH, so you can easily run a program that links against the shared lib.
  
The project file for Xcode to build the framework can be found in
+
==Mac==
 +
'''Note:''' The only officially supported version of OS X is 10.5 (Leopard), but the DOM used to work on Tiger and might still work, as long as you have GNU make 3.81 (available via Macports).
  
  <COLLADA_DOM-directory>/projects/Xcode
+
===Building the DOM===
 +
====Using Xcode====
 +
Xcode project files are in
 +
  ''<dom-path>''/projects
 +
The build output goes to the <code>''<dom-path>''/build</code> folder.
  
Note that you should use Xcode 2.4 or better. You can download the latest version from [http://developer.apple.com/tools/xcode/ here].  
+
====Using make and gcc====
 +
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 [http://collada-dom.svn.sourceforge.net/viewvc/collada-dom/trunk/dom/make/readme?view=markup make readme] for more info. The build output goes to ''<dom-path>''/build.
  
Using the Release configuration, the DOM is built as a '''Universal Binary''' for PPC and Intel. The preferred installation location is /Library/Frameworks.
+
'make install' is also available to copy the DOM framework to /Library/Frameworks.
  
 
===Building client applications===
 
===Building client applications===
Copy the DOM-framework to /Library/Frameworks, the standard location for external frameworks.
 
 
 
====Using Xcode====
 
====Using Xcode====
 +
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.
  
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
+
'''Important!''' By default, Xcode 3 adds two preprocessor flags (_GLIBCXX_DEBUG=1 and _GLIBCXX_DEBUG_PEDANTIC=1) to the debug build of an application 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 so:
to build your client applications.
+
# Open the ''<dom>''/make/common.mk file.
 
+
# Add "<code>-D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC</code>" to the line "<code>ccFlags += -g -D_DEBUG</code>".
====Using Make and gcc====
 
  
 +
====Using make and gcc====
 
Additional gcc compiler arguments:  
 
Additional gcc compiler arguments:  
 +
-I''<dom-path>''/Collada14Dom.framework/Headers
 +
Additional linker arguments: 
 +
-F''<dom-path>'' (if the DOM isn't in a standard path such as /Library/Frameworks)
 +
-framework Collada14Dom
 +
For a debug build, the framework name is Collada14Dom-d.framework, so adjust the gcc arguments accordingly.
  
-I/Library/Frameworks/Collada141Dom.framework/Headers
+
====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
 +
* Use '''otool''' and '''install_name_tool''' to modify an existing framework.
 +
For more information, see
 +
man otool
 +
and
 +
man install_name_tool
  
Additional linker arguments:
+
==Windows (MinGW)==
 +
The DOM can be built on Windows with the MinGW compiler, which can be obtained from [http://sourceforge.net/project/showfiles.php?group_id=2435 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.
  
-framework Collada141Dom
+
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 [http://www.cygwin.com/ Cygwin]. Both should work fine.
  
====Using different installation locations for DOM framework====
+
===Building the DOM===
 +
On Windows, the DOM builds as both a static lib (.a) and as a shared lib (.dll). All output goes to the <code>''<dom-path>''/build</code> folder.
  
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
+
Go to the ''<dom-path>'' directory and run
 
+
  make
  man otool
 
  
and  
+
The MinGW build is very similar to the Linux build, so refer to that section and the [http://collada-dom.svn.sourceforge.net/viewvc/collada-dom/trunk/dom/make/readme?view=markup make readme] for more information.
 
man install_name_tool
 
  
 +
==PS3==
 +
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 [http://collada-dom.svn.sourceforge.net/viewvc/collada-dom/trunk/dom/make/readme?view=markup make readme] for more info.
  
{{DOM navigation}}
+
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.
  
 
[[Category:COLLADA DOM|Setting up]]
 
[[Category:COLLADA DOM|Setting up]]

Latest revision as of 01:33, 16 July 2013

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.2, which is available as a download on Sourceforge.

You can also get the DOM from the SVN repository on Sourceforge. For that you'll need a Subversion client. To check out version 2.2, open a shell and run

svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/tags/2.2 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

<dom-path>\projects

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 <dom-path>\build folder. Before building the DOM static lib be sure to include daeZAEUncompressHandler.cpp in the project source files. This can be found in <dom-path>\include\dae folder.

Building client applications

In several paths below you'll see "vc8". 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 "1.4" and "14", which refers to COLLADA 1.4. If you're using COLLADA 1.5, use "1.5" and "15" instead.

Setting up include directories

  • In your project, add these lines to the Additional include directories field in the General tab for the C/C++ project configuration settings:
<dom-path>\include
<dom-path>\include\1.4
<dom-path>\external-libs\boost

Setting up preprocessor definitions

  • In dom or dom-static project, add these lines to the Preprocessor Definitions field in the Preprocessor tab for the C/C++ project configuration settings:
BOOST_ALL_NO_LIB
PCRE_STATIC
DOM_INCLUDE_LIBXML

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
<dom-path>\external-libs\minizip\win32\lib\
<dom-path>\external-libs\boost\lib\vc8
  • Add the following lines to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada14dom22-s.lib (release) or libcollada14dom22-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)
minizip.lib (release) or minizip-d.lib (debug)
libboost_filesystem.lib (release) or libboost_filesystem-d.lib (debug)
libboost_system.lib (release) or libboost_system-d.lib (debug)
Linker warnings/Runtime errors

When you build an application 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 application 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:
DOM_DYNAMIC
  • 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)
<dom-path>\external-libs\boost\lib\vc8
  • Add the following to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada14dom22.lib (release) or libcollada14dom22-d.lib (debug)
libboost_filesystem.lib (release) or libboost_filesystem-d.lib (debug)
libboost_system.lib (release) or libboost_system-d.lib (debug)

Linux

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 libraries aren't provided with the Linux DOM as they are for 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 as a shared lib (.so). All output goes to the <dom-path>/build folder.

Go to the COLLADA DOM directory and run

make

This builds a release version of the DOM. More extensive documentation of our make build system is available in the <dom-path>/make/readme (DEAD LINK) file included with the DOM.

Important: make version 3.81 or higher is required 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 named 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 -L<dom-path>/build/linux-1.4
 <dom-path>/build/linux-1.4/libcollada14dom.a -lxml2 -lpcre -lpcrecpp -lboost_filesystem -lminizip -o test

NOTE: you may need to add -lcollada14dom after specifying where the libraries are with -L.

Or you can build to use the DOM shared lib:

g++ -I<dom-path>/include -I<dom-path>/include/1.4 test.cpp  -L<dom-path>/build/linux-1.4 
 <dom-path>/build/linux-1.4/libcollada14dom.so -lxml2 -lpcre -lpcrecpp -lboost_filesystem -lminizip -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

make install

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

make uninstall

The DOM remembers your installation location and uninstalls itself from that location.

The main benefit of this is that you can make sure that the DOM shared lib is in your PATH, so you can easily run a program that links against the shared lib.

Mac

Note: The only officially supported version of OS X is 10.5 (Leopard), but the DOM used to work on Tiger and might still work, as long as you have GNU make 3.81 (available via Macports).

Building the DOM

Using Xcode

Xcode project files are in

<dom-path>/projects

The build output goes to the <dom-path>/build folder.

Using make and gcc

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

Using Xcode

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! By default, Xcode 3 adds two preprocessor flags (_GLIBCXX_DEBUG=1 and _GLIBCXX_DEBUG_PEDANTIC=1) to the debug build of an application 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 so:

  1. Open the <dom>/make/common.mk file.
  2. Add "-D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC" to the line "ccFlags += -g -D_DEBUG".

Using make and gcc

Additional gcc compiler arguments:

-I<dom-path>/Collada14Dom.framework/Headers

Additional linker arguments:

-F<dom-path> (if the DOM isn't in a standard path such as /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
  • Use otool and install_name_tool to modify an existing framework.

For more information, see

man otool

and

man install_name_tool

Windows (MinGW)

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.

Building the DOM

On Windows, the DOM builds as both a static lib (.a) and as a shared lib (.dll). All output goes to the <dom-path>/build folder.

Go to the <dom-path> directory and run

make

The MinGW build is very similar to the Linux build, so refer to that section and the make readme for more information.

PS3

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.