Difference between revisions of "DOM guide: Setting up"

From COLLADA Public Wiki
Jump to navigation Jump to search
Line 75: Line 75:
 
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.
 
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.
  
==Setting up on Mac==
+
==Mac==
===Preparing the external libraries===
+
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.
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 <nowiki>https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/external-libs</nowiki> 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 [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 (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===
 
===Building the DOM===
''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].
+
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.
 
 
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 project file for Xcode to build the framework can be found in
 
  
<COLLADA_DOM-directory>/projects/Xcode
+
'make install' is also available to copy the DOM framework to /Library/Frameworks.
 
 
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 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===
 
===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
 
to build your client applications.
 
  
 
====Using Make and gcc====
 
====Using Make and gcc====
 
 
Additional gcc compiler arguments:  
 
Additional gcc compiler arguments:  
 
+
  -I<dom-path>/Collada14Dom.framework/Headers
  -I/Library/Frameworks/Collada141Dom.framework/Headers
 
 
 
 
Additional linker arguments:   
 
Additional linker arguments:   
 
+
-F<dom-path> (if the DOM isn't in a standard path like /Library/Frameworks)
  -framework Collada141Dom
+
  -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====
 
====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
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
 
  man otool
 
 
and  
 
and  
 
 
  man install_name_tool
 
  man install_name_tool
  

Revision as of 02:25, 8 April 2008

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.0, which is available as a download on Sourceforge. A zip containing the source is available, as are binary packages for several platforms. The binary downloads only include the headers and libs necessary for building an app. You won't be able to rebuild or debug the DOM using the binary packages.

You can also get the DOM from the svn repo on Sourceforge. For that you'll need a Subversion client. Open up a shell and run

svn co https://collada-dom.svn.sourceforge.net/svnroot/collada-dom/tags/2.0 colladadom

to check out version 2.0, or run

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

to check out the trunk.

Windows

Building the DOM

Project and solution files for Visual Studio can be found in

<dom-path>\projects

Currently only VS 2005 projects are provided, but VS 2008 can also be used by running Visual Studio's upgrade wizard. 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.

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:
<dom-path>\include
<dom-path>\include\1.4

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:
libcollada14dom20-s.lib (release) or libcollada14dom20-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)

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 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:
libcollada14dom20.lib (release) or libcollada14dom20-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 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

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 file included with the DOM.

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 -lxml2 -lpcre -lpcrecpp -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 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.

Mac

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.

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

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.

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 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

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 MinGW/MSYS, but this hasn't been tested.


COLLADA DOM - Version 2.4 Historical Reference
List of main articles under the DOM portal.
User Guide chapters:  • Intro  • Architecture  • Setting up  • Working with documents  • Creating docs  • Importing docs  • Representing elements  • Working with elements  • Resolving URIs  • Resolving SIDs  • Using custom COLLADA data  • Integration templates  • Error handling

Systems:  • URI resolver  • Meta  • Load/save flow  • Runtime database  • Memory • StringRef  • Code generator
Additional information:  • What's new  • Backward compatibility  • Future work
Terminology categories:  • COLLADA  • DOM  • XML