Prerequisites

The topics covered in this section include:

Overview

The requirements and examples in this guide are targeted for users running Windows or Mac OSX with Windows BootCamp or VMWare since the OpenSim application and libraries are built for Windows.  (Note, for those that are familiar with CMake and the compilers for their operating system, it is possible to build the OpenSim libraries from source, but that is currently beyond the scope of this guide.) To run the examples provided in the developer's guide, you will need:

1. CMake 2.6 or later (http://www.cmake.org/cmake/resources/software.html) 
2. Microsoft's Visual Studio (version 2005) or Visual C++ 2010 Express Edition (http://www.microsoft.com/express/vc/Default.aspx) capable of building 32 bit binaries.
3. The latest version of OpenSim installed

Each of these programs is described below in more detail.

We also recommend the following tools:

• An XML Editor for editing model and setup files, for example:
  • notepad++ (http://notepad-plus.sourceforge.net/uk/site.htm)
  • XMLMarker (http://symbolclick.com/download.htm)

CMake

CMake is a cross-platform open-source build system that will setup the build environment in a compiler-independent manner. Simple configuration files placed in each source directory (called CMakeLists.txt files) are used to generate standard build files (e.g., makefiles on Unix and projects/solution in Windows MSVC) which are then loaded into a compiler such as Visual Studio, for further programming and compilation. In the OpenSim API examples, you will use CMake to generate the correct build "solution" files for Visual Studio.

You will need CMake 2.6.0 or later. The latest CMake version is freely available from:
http://www.cmake.org/cmake/resources/software.html

Visual Studio

Visual Studio Express (VS) is a free Windows compiler that program developers at any level can use to create custom applications using basic and expert settings for the Windows operating system. In the OpenSim API examples, VS is used to view, edit and add new C++ code, and compile the resulting program to an executable or plug-in.
Install Visual C++ 2010 Express Edition freely available from http://www.microsoft.com/express/download/, if you do not already have VS 2005 or VS 2010 setup on your computer. As of OpenSim 2.4, there are no 64-bit libraries for OpenSim, so make sure to configure your build system to build 32-bit libraries (do not select x64 in CMake configuration even if you are on a 64 bit machine) .

OpenSim

1. Due to incompatibility between various versions of Microsoft Visual Studio, you need to download/install the distribution of OpenSim that is consistent with your development environment: either Visual Studio 2005 (Professional) or 2010 Express (2010 Express is free and recommended). To install OpenSim, which uses the OpenSim API, download the self-extracting executable from the download page of OpenSim (go to http://simtk.org/home/opensim and click on "Downloads"). The API is accessible with installation of the OpenSim application. Remember to make a note of where you installed OpenSim, which will be referred to as <OpenSimInstallDir>, which by default is "C:\OpenSim2.x".

2. Run the executable, following the on-line instructions.

To be able to run the main programs from the command line (outside Visual Studio), you need to add the OpenSim libraries to your PATH. This can be done during installation by selecting the radio button as illustrated below.

Warning: Earlier installations of OpenSim will continue to be accessible but only through the GUI, which sets its own environment (PATH) variable.

3. Make sure your system PATH contains only your <OpenSimInstallDir>\bin (e.g., "C:\OpenSim 2.x\bin"). You can check this by going to Start->configuration screen->system->advanced system settings->environmental variables->system variables->Path. If the correct OpenSim\bin path is not included, then add this to your PATH. Also, make sure that no other OpenSim "\bin" directory is in your PATH. If you've ever built OpenSim from source code, make sure no directory containing .lib or .dll files for OpenSim are present in your PATH either. If you don't do this, OpenSim may get confused and possibly use .dll and .lib files from other/older versions of OpenSim instead of the files from the current version of OpenSim and you will likely experience run-time errors.

4. Test your installation. Go to the <OpenSimInstallDir>\bin directory for the OpenSim installation (e.g., C:
OpenSim 2.x\bin). Copy the file testOpenSimAPI.exe to the <OpenSimInstallDir>\sdk\APIExamples\ExampleMain and then double-click on it to run the test. If the OpenSim libraries were added to the PATH while installing then you can just browse for the folder above then type testOpenSimAPI.exe at the command prompt. If everything was installed correctly, a window should pop up with message like that shown below:

Obtaining the Example Programs

The examples using the OpenSim API come with the OpenSim distribution and are located in the <OpenSimInstallDir>\sdk\APIExamples directory of your OpenSim installation.