Manual (Install and Use)

From ODE Wiki

This article is part of the ODE Manual

Chapters ...

Introduction Install and Use Concepts Data Types and Conventions World Rigid Body Functions Joint Types and Functions StepFast Support Functions Collision Detection

Contents 1 Getting the Source Code 2 Before You Build 2.1 Building with Automake 2.2 Building with Premake 3 Using ODE

Getting the Source Code

ODE is currently (and contrary to the Download page on the official website) distributed in source code form only; there are no pre-built binary packages available. Because of the many different ways in which ODE can be configured it is considered best practice to start with the source code and create a build tailored to your particular project. For the same reason, Linux distributions are discouraged from trying to develop a "canonical" binary version.

Stable releases are available from the the SourceForge.net project page.

A Subversion repository is also available on SourceForge.

If you have any questions, there is a very helpful mailing list. If you plan on using ODE you should definitely sign up. The list is fairly low traffic, high signal-to-noise, and extremely useful. You might also want to search the archive of the old mailing list.

Before You Build

Before you start, you should know that there are two parts to ODE. There is "ODE", which is the physics and collision detection library. Then there is "DrawStuff", a simple wrapper over Win32/X11 and OpenGL which is used for the demo applications. This often causes confusion: DrawStuff is a simple library written only to display the ODE demos and is not intended to be used in your own projects. DrawStuff requires OpenGL, and X11 on Mac OS X; ODE does not. You do not have to build DrawStuff or the demo applications in order to use ODE.

Due to the wide variety of platforms, environments, and tools used by the ODE community, two different build approaches are provided. If the sequence ./configure; make; make install is your preferred approach (*nix and Mac OS X, primarily), see Building with Automake below. If you prefer an IDE, see Building with Premake, farther down.

Building with Automake

If you downloaded the source code from Subversion, bootstrap autotools by running the autogen.sh script. If you downloaded a stable release package this has already been done for you.

 $ sh autogen.sh

Note that you need to have a recent autoconf (2.61), automake (1.10) and libtool. You may see some "underquoted definition" warnings depending on your platform, these are (for now) harmless warnings regarding scripts from other m4 installed packages.

Next, configure the build by running the command:

 $ ./configure

By default this will set up ODE to build a static library with single precision math, trimesh support, and debug symbols enabled. You can modify this default configuration by supplying options to the configure command. Type the command

 $ ./configure --help

...for a full list of available options. Here are a few of the most important ones:

• --enable-double-precision enables double precision math
• --with-trimesh=opcode use OPCODE trimesh support (default)
• --with-trimesh=gimpact use GIMPACT trimesh support
• --with-trimesh=none disable trimesh support
• --enable-new-trimesh enable alternative OPCODE trimesh support (must be used together with --with-trimesh=opcode)

Once configure has run successfully, you can build ODE with:

 $ make
 $ sudo make install

The latter command will also enable pkg-config support by installing the ode-config and ode.pc scripts. To build your programs with pkg-config, add (including the backticks):

 `pkg-config ode --cflags`

to your compiler flags (CFLAGS or CXXFLAGS), and

 `pkg-config ode --libs`

to your linker flags (LDFLAGS). This pair of commands will set all of the appropriate compiler and linker flags, based on the ODE configuration. If used inside a Makefile, you can use the $(shell) function instead of the backticks because it is more portable.

MinGW/MSYS users will need the msysDTK package with updated autoconf, automake and libtool packages, in order to run autogen.sh, and should avoid building ODE in directories with spaces. If you don't already have a working MSYS setup, the Premake build instructions below will be much more helpful.

Building with Premake

Premake is a build configuration tool which generates customized project files for Visual Studio, Code::Blocks, CodeLite, and GNU Make (XCode support is coming). The ODE source code includes a Windows version of the Premake executable at ode/build/premake4.exe; users of other platforms can download a source or binary package.

To generate the project files, run Premake in the ode/build directory and specify your toolset of choice. For instance, this will generate files for Visual Studio 2008:

 $ cd ode/build
 $ premake4 vs2008

The generated project files (.sln, .vcproj) will be placed in an appropriately named subdirectory, in this case ode/build/vs2008.

For a complete list of supported toolsets and options, type:

 $ premake4 --help

Several configuration options are available, the most notable include:

• --with-demos includes the demo applications and Drawstuff library
• --with-tests includes the automated test suite, recommended if you intend to modify ODE.
• --no-trimesh excludes support for triangle mesh collision geometries, reducing the size of the library.

Specify options before the toolset when running Premake, like so:

 $ premake4 --with-demos --with-tests vs2008

The generated project files provide several different possible build configurations, including use of single or double precision numbers, and static or shared libraries. If you used Premake to generate GNU makefiles, see the comments at the start of Makefile for instructions on selecting a configuration when building. IDE users can set the build configuration as they normally would.

Premake has recently added experimental support for cross-compiling "platforms", enabling it to target the Xbox 360, Playstation 3, and (not really cross-compiling, but still) Mac OS X universal binaries.

You can see a complete list of available platforms in Premake's help.

Rather than cluttering up the default project files with a ton of platform combinations that most people won't use, I'd suggest that people who want to target these platforms generate their own project files, using the --platform argument to add support for their preferred targets.

 $ premake4 --platform=ps3 vs2008

Using ODE

The best way to understand how to use ODE is to look at the supplied test/example programs, located in ode/ode/demo.

To create an application using ODE, follow these steps:

• Add ode/include to your list of include file paths.
• #include <ode/ode.h>
• Look in ode/lib and add the appropriate library search path and file name, depending on which build configuration was used. For instance, ode/lib/DebugSingleDLL and ode_singled.lib.
• Add one of the preprocessor symbols dSINGLE (single precision) or dDOUBLE (double precision), depending on how ODE was configured. If none is defined, single precision is assumed; if the wrong precision is enabled all floating-point data going in and out of ODE will be corrupt, producing all kinds of errors.

When ODE is used with the dWorldStep function, heavy use is made of the stack for storing temporary values. For very large systems several megabytes of stack can be used. If you experience unexplained out-of-memory errors or data corruption, especially on Windows, try increasing the stack size, or switching to dWorldQuickStep.