Manual (Install and Use)
From ODE Wiki
Contents |
Getting Started
The latest "stable" release is available at the SourceForge.net file list. At the time of this writing, two packages are available: a build-it-yourself source code package and a prebuilt Windows binary package. For developers, a Subversion repository provides access to the development version of the library.
The prebuilt Windows binary package uses single-precision math and includes support for trimesh collision shapes. This package also includes the header files and linker import libraries -- everything you need to get started right away. If you choose to use these prebuilt binaries you can jump ahead to "Using ODE", below.
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.
Getting the Source Code (Subversion)
If you downloaded the source code package from SourceForge, you can skip ahead to the next section.
The latest development version of the source code is stored in a Subversion repository on SourceForge. The usual disclaimers for in-development code apply.
If you are unfamiliar with Subversion you can get up to speed by reading the OpenDE Subversion page. Once you have your Subversion client installed and ready to go you can get the latest version of ODE from the https://svn.sourceforge.net/svnroot/opende/trunk url. In summary, it comes down to executing the svn command:
$ svn co https://opende.svn.sourceforge.net/svnroot/opende/trunk opende
This command will create a directory called opende in your current working directory. To update it at a later time, simply execute this command in the opende/ directory:
$ svn update
If you use TortoiseSVN, create an opende/ directory, go there, right-click and select 'SVN Checkout'. Then use this URL and click OK:
https://opende.svn.sourceforge.net/svnroot/opende/trunk
Building ODE
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, ODE does not. You do not have to build DrawStuff or the demo applications in order to use ODE.
How To Build ODE With Visual Studio (2002 and up)
If you downloaded the source code from Subversion, copy the default configuration file `ode/build/config-default.h` to `ode/include/ode/config.h`. If you are using the stable source code package, this step has already been done for you.
The directory `ode/build` contains project files for all recent versions of Visual Studio. Locate the correct directory for your version of Visual Studio, open, and build. By default, the project files will use single-precision math. To switch to double-precision, edit `ode/include/ode/config.h` and replace `#define dSINGLE 1` with `#define dDOUBLE 1` and rebuild.
Note that Visual Studio 6 is no longer supported; please upgrade to Visual C++ Express Edition (it's free!).
How To Build ODE With Code::Blocks
Because Code::Blocks supports so many different platforms, we do not provide workspaces. Instead, use Premake to create a workspace tailored for your platform and project.
Download Premake and place it on your system path (or anywhere convenient). Then create a workspace like so:
$ cd ode/build $ premake --with-demos --with-tests --target cb-gcc
To see a complete list of options:
$ cd ode/build $ premake --help
How To Build ODE With MinGW and MSYS
MSYS is an environment that simulates most of the unix environment needed to build programs. The generic build instructions below should work for MinGW+MSYS. Just try to avoid building ODE in directories with spaces'.
If you are building from SVN, you'll need the msysDTK package, plus updated autoconf, automake and libtool packages.
How to Build ODE With MinGW alone
If you don't have (or don't want to use) MSYS you can use Premake. Just open a command prompt on the build directory, and run:
premake --with-demos --with-tests --target gnu cd gnu make
The library and executables will be generated in the "lib" directory. For more build options, run:
premake --help
How To Build ODE Just About Everywhere Else
If you downloaded the source code from Subversion, bootstrap autotools by running the command:
$ sh autogen.sh
Note that you need to have 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.
Configure the build by running the command:
$ ./configure
By default this will build ODE with as a static library with single precision math, with trimesh support, and debug symbols enabled. You can modify this default configuration by supplying options to configure. Type the command
$ ./configure --help
...for a full list of available options. Here are a few of the more important ones:
- `--enable-double-precision` enables double precision math
- `--with-trimesh=opcode` use OPCODE trimesh support
- `--with-trimesh=gimpact` use GIMPACT trimesh support
- `--with-trimesh=none` disable trimesh support
Once configure has run successfully, you can build ODE with:
$ make $ sudo make install
The latter command will also create an `ode-config` script which you can use to pass cflags and ldflags to your projects. Namely, "ode-config --cflags" and "ode-config --libs". This will also supply the correct precision ode was compiled (with either -DdSINGLE or -DdDOUBLE).
Building and Running ODE Tests on Mac OSX
The latest version now contains native support for MacOS X, so the following is a bit outdated. So don't be scared by references to X11, chances are you don't need to worry about it.
ODE uses XWindows and OpenGL to render the scene being simulated. In order to build the example you will need to install Apple X11 server and the X11SDK (as well as the normal developer tools).
These are available from Apple. As of writing this can be found at: http://www.apple.com/macosx/x11. NOTE: there is a tiny link at the bottom right of the page for the SDK
Once the software is installed follow the normal build instructions.
Since ODE uses X11 you need to run the X11 server (which you should have installed, it's in the Applications Folder).
If you run the test app in the XTerm that the X11 server opens by default then they should run fine. If however you run them from a MacOS X Terminal then you need to define the environment variable DISPLAY. If DISPLAY is not defined then you will get a message saying: "cannot open X11 display".
For example to run the boxstack test you would type cd ode/test DISPLAY=:0.0 ./test_boxstack.exe You can define this environment variable in your shell startup scripts (for example in ~/.bashrc if you are using bash)
Using ODE
The best way to understand how to use ODE is to look at the test/example programs that come with it. Note the following things:
- Source files that use ODE only need to include a single header file:
#include <ode/ode.h>Theodedirectory in this statement is actually theinclude/odedirectory of the ODE distribution. If you use the ode-config script, it will supply the compiler with the flags needed to find the headers. e.g.
gcc -c myprogram.cpp `ode-config --cflags`
- 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.
