Friday 28 January 2011

Building and installing ODE for Visual C++ 2008 / 2002 / 2005 / etc

This is a small step-by-step instructions to make your ODE compile in MSVC 2008 (2002+).
Complete printer-friendly ODE manual can be found here.
1) First, download the latest ODE package from SourceForge (I've downloaded ODE ver. 0.11.1)
2) Unpack package .tar.bz2, .zip or .tar.gz with, for example 7-zip (I've unpacked it to E:\Projects\SDK\ODE\ode-0.11.1). Try avoiding spaces in the path.

3) Go to build dir and create shortcut to premake4.exe (Quick Start Guide to Premake4.3,User guide). Open shortcut properties and type vs2008 (for VStudio 2008) after the name premake4.exe, so it will look like this: "\ode-0.11.1\build\premake4.exe vs2008" (without quotes). For Visual Studio 2005 - type vs2005, and vs2002 for Visual Studio 2002.
Tip: There is no such option like vs2010 for latest studios, so you have to choose maximal available solution version like vs2008 and then run .sln and apply solution conversion in appeared dialog to make solution compile for you. To get all options for premake, you shall run premake4.exe --help from command line (win+R, type cmd, then CD to your ODE build dir).
4) Go to created folder \ode-0.11.1\build\vs2008 and open solution ode.sln
5) If you have solution configuration toolbox opened, you will notice DebugDoubleDLL configuration selected by default at start up. These configurations will be determined by the way you would like to use your project. I'm trying to use static linking most of the time to minimize dependencies and total executable size, so my choice is DebugSingleLib configuration. I have chosen single precision because of speed required, - double precision will decrease ODE computational speed 2-5 times (since you will lost SSE optimizations this way), but if you need better convergence and precision, - the Double configuration is your choice. Anyways, the Single precision configuration will be slow in debug mode, since optimizer will be turned on only in Release mode.
6) Build your solution (Build->Build solution).
After build, a lot of .obj files will be generated inside solution dir (e.g. "ode-0.11.1\build\vs2008\obj\DebugSingleLib").
But, in case of static linking, you will need the only one .lib file, placed inside "ode-0.11.1\lib\DebugSingleLib\ode_singled.lib"
You will add this path to your linker when making your project later.
7) Now, it would be nice to make also a Release build. So, change project configuration to ReleaseSingleLib. But do not haste to build it now. First, check if project configuration is correct - ODE project properties->C++->Code Generation page. Look at Runtime Library field, - it is highly required for you to make sure it is the same as in your Release project configuration (the project, where you would like to use ODE). If you just left it as it is - "Multi-threaded DLL" - your release project will require "Visual studio 20xx runtime" installation from end-user, which is not good.
Tip: In all of my release project configurations I always change this option to "Multi-threaded (/MT)" (and also when building any other library from sources like OpenCV, Qt, qwt etc.). /MT configuration might also be little bit faster than dynamic, but this is not just that simple question.
Also check if you would like using SSE or SSE2 with ODE. I always choose "Streaming SIMD Extensions (/arch:SSE)" in Enable Enhanced Instruction Set field, since SSE2 does not give much more speed for my machine. If you strike for performance, you shall do a little benchmarks for it later. Also change Floating point model to Fast, to make sure SSE will not conflict with precise configuration. Now, build release configuration. As previously, you will get alot of .obj files, and in case of successful build, - go to ode-0.11.1\lib\ReleaseSingleLib to check if ode_single.lib is generated for your release build config.

8) Now it is time to test your project working with ODE. Create new or open an existing Win32 or Console application.
9) Set debug configuration, in Project Properties->C/C++-> Additional include directories add full path to ODE include directory (e.g. "E:\Projects\SDK\ODE\ode-0.11.1\include" in my case). Go to Linker->General page and add directory for your debug library (e.g. "E:\Projects\SDK\ODE\ode-0.11.1\lib\DebugSingleLib"). In Linker->Input->Additional Dependencies field type ode_singled.lib.
10) Do the same for your release configuration, except place another linker path for release library ("E:\Projects\SDK\ODE\ode-0.11.1\lib\ReleaseSingleLib") and input library ode_single.lib. Now it is right time to check if C/C++->Code Generation-> Runtime library is the same in runtime version as was in ODE when you compiled it, - in our case it must be /MT.
Notice: to use different runtime libraries configuration in several projects, you have to use dynamic linking, and also ignore conflicts in Linker-> Ignore Specific Library (just type there a library that brings conflict). Also, it would be great to check if debug library is the same as in ODE debug build configuration.
11) Open your main header file, or precompiled header like stdafx.h and write to the end:
#include <ode/ode.h>
#include <windows.h>  // you might also include windows for timing functions
12) In the beginning of your main function (main(), t_main(), WinMain(), etc)
write single line:
dWorldID odeWorld = dWorldCreate();

and rebuild your project's solution. Make sure it builds successfully.
If you have compiler error, like undefined symbol dWorldCreate - make sure to include ode.h headers properly and add ODE include path to your solution like in step 9.
If you get some unresolved external symbol error, go to step 9 and retry it.
If problem still unsolved, go to step 3 and rebuild ODE debug config.
If you get some multiple definitions linker errors - check steps 7 and 9 for C++ runtime library /MT.
In a later article I will write about how to start using ODE in a game-like application and will give some tips.
Locations of visitors to this page