Difference between revisions of "DOM guide: Setting up"

From COLLADA Public Wiki
Jump to navigation Jump to search
Line 17: Line 17:
 
That downloads the latest copy of the COLLADA DOM to the COLLADA_DOM subdirectory (as specified by the last parameter).
 
That downloads the latest copy of the COLLADA DOM to the COLLADA_DOM subdirectory (as specified by the last parameter).
  
==Preparing the External Libraries==
+
==Setting up on Windows==
 +
===Preparing the external libraries===
 
The COLLADA DOM and its client applications require certain libraries.
 
The COLLADA DOM and its client applications require certain libraries.
  
===Windows===
 
 
The COLLADA DOM and all client applications have three external dependencies, libxml2, zlib, and iconv. The latest Windows binaries for these libraries can be downloaded from http://www.zlatkovic.com/libxml.en.html. For convenience, these libraries are packaged together in the "External Libaries" package available from the COLLADA DOM SourceForge download page.
 
The COLLADA DOM and all client applications have three external dependencies, libxml2, zlib, and iconv. The latest Windows binaries for these libraries can be downloaded from http://www.zlatkovic.com/libxml.en.html. For convenience, these libraries are packaged together in the "External Libaries" package available from the COLLADA DOM SourceForge download page.
  
Line 31: Line 31:
 
* <code> libxml2/win32/lib/zlib.lib </code>
 
* <code> libxml2/win32/lib/zlib.lib </code>
  
===Linux===
+
===Building the DOM===
On Linux, make sure the libxml2 headers and libs are installed. On Debian-based systems you can install the package libxml2-dev:
 
apt-get install libxml2-dev
 
 
 
=== Mac ===
 
On OS X Tiger (10.4) all dependencies to build the COLLADA DOM are shipped with the OS. No additional installations are required.
 
 
 
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.
 
 
 
==Building the COLLADA DOM==
 
 
 
===Windows===
 
 
The Windows installers include prebuilt binaries (both DLLs and static libraries), so if you used the installers it isn't actually necessary to build the DOM yourself. Otherwise you'll have to build the DOM manually.
 
The Windows installers include prebuilt binaries (both DLLs and static libraries), so if you used the installers it isn't actually necessary to build the DOM yourself. Otherwise you'll have to build the DOM manually.
  
Line 52: Line 41:
 
Open the .sln file for your version of Visual Studio and build whatever configurations you're interested in.
 
Open the .sln file for your version of Visual Studio and build whatever configurations you're interested in.
  
===Linux===
+
Visual Studio requires additional path and dependency information to properly compile and link applications using the COLLADA 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.
 
 
 
Go to the COLLADA DOM directory and run
 
make
 
for a debug build or
 
make RELEASE=1
 
for a release build.
 
 
 
===Mac===
 
''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 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
 
 
 
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==
 
  
===Windows===
+
===Building client applications===
Visual Studio requires additional path and dependency information to properly compile and link applications using the COLLADA DOM.
 
  
 
====Setting up include directories====
 
====Setting up include directories====
Line 121: Line 87:
 
** "Multi-threaded Debug DLL" if using the debug builds
 
** "Multi-threaded Debug DLL" if using the debug builds
  
===Linux===
+
==Setting up on Linux==
 +
===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:
 +
apt-get install libxml2-dev
 +
 
 +
===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.
 +
 
 +
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====
 
====Adding the COLLADA DOM to /usr/include and /usr/lib====
Line 138: Line 118:
 
The <code>collada_dae</code> is deliberately included twice. This is necessary to resolve all the dependencies between the DAE and the DOM libraries.
 
The <code>collada_dae</code> is deliberately included twice. This is necessary to resolve all the dependencies between the DAE and the DOM libraries.
  
===Mac===
+
==Setting up on Mac==
 +
===Preparing the external libraries===
 +
On OS X Tiger (10.4) all dependencies to build the COLLADA DOM are shipped with the OS. No additional installations are required.
 +
 
 +
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.
 +
 
 +
===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 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
 +
 
 +
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===
 
Copy the DOM-framework to /Library/Frameworks, the standard location for external frameworks.
 
Copy the DOM-framework to /Library/Frameworks, the standard location for external frameworks.
  

Revision as of 20:56, 8 November 2007

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

The COLLADA DOM and its client applications require certain libraries.

The COLLADA DOM and all client applications have three external dependencies, libxml2, zlib, and iconv. The latest Windows binaries for these libraries can be downloaded from http://www.zlatkovic.com/libxml.en.html. For convenience, these libraries are packaged together in the "External Libaries" package available from the COLLADA DOM SourceForge download page.

Building the COLLADA DOM requires that the files for the external libraries on which it depends be in a specific directory structure. Set the environment variable COLLADA_EXTERNAL_LIBS_LOCATION to the directory that contains the following files:

  • libxml2/win32/include/libxml/* - The libxml2 headers from the distribution
  • libxml2/win32/include/iconv.h
  • libxml2/win32/include/zlib.h
  • libxml2/win32/lib/iconv_a.lib
  • libxml2/win32/lib/libxml2_a.lib
  • libxml2/win32/lib/zlib.lib

Building the DOM

The Windows installers include prebuilt binaries (both DLLs and static libraries), so if you used the installers it isn't actually necessary to build the DOM yourself. Otherwise you'll have to build the DOM manually.

Project and solution files for Visual Studio .NET 2003 can be found in

<COLLADA_DOM-directory>/projects/VC++7

Project and solution files for Visual Studio .NET 2005 can be found in

<COLLADA_DOM-directory>/projects/VC++8

Open the .sln file for your version of Visual Studio and build whatever configurations you're interested in.

Visual Studio requires additional path and dependency information to properly compile and link applications using the COLLADA DOM.

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

The COLLADA DOM is provided as both static and dynamic link libraries.

To link with the static COLLADA DOM libraries:

  • 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
<libxml2, zlib, and iconv lib directory-path> 
  • 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
libcollada_STLDatabase.lib
libcollada_LIBXMLPlugin.lib
libcollada_stdErrPlugin.lib
libxml2_a.lib
iconv_a.lib
zlib.lib
wsock32.lib

Linking with the dynamic COLLADA DOM library

To link with the dynamic COLLADA DOM library:

  • 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
  • Add the following line to the Additional Dependencies field in the Input tab for the Linker project configuration settings:
libcollada141dom13.lib

Additional configuration options

  • 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:
    1. Append "_d" to the end of the COLLADA DOM library names, for example, libcollada_dae_d.lib.
    2. 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

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:

apt-get install libxml2-dev

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.

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

On OS X Tiger (10.4) all dependencies to build the COLLADA DOM are shipped with the OS. No additional installations are required.

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


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