Manual: Install and Use

Getting the Source Code

ODE is currently 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:

• --disable-demos --without-x to let it compile on Mac OS X
• --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 to install some appropriate packages such as autoconf, automake and libtool, as well as pkg-config (not provided by the MinGW folks, but by the GTK+ project), in order to run autogen.sh. Like in *nix systems, 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 build/premake4.exe; users of other platforms can download a source or binary package.

To generate the project files you will need to run Premake in the ode/build directory and specify your toolset of choice (Premake is a command-line program and must be run from a console or terminal). 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.

• --with-gimpact

uses the GIMPACT library to check for triangle mesh collisions instead of OPCODE.

• --with-libccd

uses libccd to handle pairs of geoms that don't have yet specialized tests.

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

Install with Python bindings

Open Dynamics Engine can be used in Python software (does not matter if it is a simple script or a complex library) through the included bindings, which must be compiled for each platform.

These bindings are based in project PyODE, which is obsolete (as of 2013-01-21, its latest release dates from 2010-03-22), by Ethan Glasser-Camp and others. The work to bring them up to date, replace Pyrex with Cython and integrate them into the official ODE source code was done by Gideon Klompje.

Warning: The Python bindings are far more recent and less popular than ODE itself thus they probably have more bugs.

Linux

The complete process to compile and install an ODE release (more steps are needed for repository snapshots) with Python bindings is:

1. tar xf ode-0.12.tar.gz
2. cd ode-0.12
3. ./configure --enable-double-precision --with-trimesh=opcode --enable-new-trimesh --enable-shared
4. make
5. make install
6. cd bindings/python/
7. python setup.py install

(you may need to prepend sudo to make install and python setup.py install depending on your OS user's privileges)

(These instructions have been tested in Ubuntu 12.04 64-bits and Debian 7 64-bits)

Windows

Thanks to Christoph Gohlke there are available graphical installers for Windows (both 32 an 64 bits), Python versions 2.6, 2.7, 3.2 and 3.3. You can find them at his website Unofficial Windows Binaries for Python Extension Packages (if it's down, check here).

Uninstall

With make

To uninstall ODE (say, version 0.12), you must perform the same steps you did when installing, until before compiling. Then uninstall using make.

These are example steps. Replace the configure arguments with the ones you used in your installation.

1. tar xf ode-0.12.tar.gz
2. cd ode-0.12
3. ./configure --enable-double-precision --with-trimesh=opcode --enable-new-trimesh --enable-shared
4. make uninstall

(you may need to prepend sudo to the last command depending on your OS user's privileges)

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.