Building OpenSim from Source

This document provides instructions for building OpenSim from source. Please note the following:

• Steps and settings may vary depending on the configuration of your system.
• Building from source is challenging and, as a non-commercial entity, we have limited resources to provide support for the build process.

In this document, we refer to OpenSim as the collection of C++ libraries and standalone executables distributed under the umbrella name "OpenSim". This does not include the OpenSim application GUI, and the tools necessary to build it and support it (Java, NetBeans, VTK); however, it does include the underlying SimTK dynamics engine (Simbody).

Prerequisites

Install or Build Simbody

You can install the Simbody libraries (binary release) or, if you want to enable debugging of Simbody calls, you should build Simbody from source. You must build Simbody from source if you are building OpenSim from trunk or for OpenSim 3.0 stream. If building OpenSim 3.0 then you should use the subversion branch Simbody3.0 for Simbody and the branch OpenSim30 for OpenSim.

Installing Simbody Binaries

To install Simbody libraries and include files from the binary release:

1. Visit  http://www.simtk.org  and search for the “Simbody” project or go directly to the webpage:   https://simtk.org/home/simbody
2. Click the  Downloads  tab on the left-hand side of the page.
3. Click on the download for your operating system (Windows, Macintosh, or Linux).
4. Install to your computer, by unzipping to a folder of your choice, e.g., C:\Simbody

Building Simbody From Source

Below are abbreviated instructions for building Simbody from source. You can find more detailed instructions at the Simbody Project Site. The instruction documents found at the Simbody project site also have lots of helpful information about setting up your system to build, getting cmake, etc.

1. Create a local Simbody directory to hold the Simbody source code (e.g. ../MyDocuments/Projects/Simbody)
2. Obtain the Simbody source code: 
   

   1. If building OpenSim from 3.0 Branch, svn checkout the Simbody 3.0 branch at https://simtk.org/svn/simbody/branches/Simbody3.0. (Go to the folder you created, right click and select "SVN Checkout". Then enter the url of the repository and verify the name of the local Checkout Directory is the directory you just created. Hit OK) 

   2. For older versions of OpenSim, you can download the Simbody source code in a zip file from the Simbody downloads page.
   3. If building OpenSim latest code (Trunk) then you need to use Simbody trunk as well.
3. Launch cmake:
   
   1. Where is the source code? Choose the Simbody source code directory you specified (e.g. ../MyDocuments/Projects/Simbody).
   2. Where to build the binaries? Choose a build location (e.g. ../MyDocuments/Projects/Simbody/build)

4. Press the Configure button (near the bottom). Let CMake create the build directory. Choose a “generator” that best matches the compiler you are using, for example “Visual Studio 10”. Select “Use default native compilers” and click Finish.

5. Specify an installation location for Simbody (e.g. SimTK_INSTALL_PREFIX = ../MyDocuments/Apps/SimbodyLocal)

6. Hit Configure again. This time there should be nothing in red and the Generate button will be available. 

7. Hit "Generate", which will create the Visual Studio solution files in the Simbody build directory
8. Go to the directory that you specified as your Simbody build directory. Launch Simbody.sln 
9. Make sure you are in "Debug" configuration (selection in the top center of the screen).
10. Build the project ALL_BUILD (right click and select "Build")
11. Build the project INSTALL to make a local installation of binaries (dll’s and exe’s) and documentation.
12. Build RUN_TESTS to make sure everything built correctly
13. Repeat steps 10 to 12 in the “RelWithDebInfo” configuration (right click project - Properties - Configuration drop down box). While the debug configuration is very useful for testing and debugging, it will betoo slow to use for most purposes. The production configuration we recommend is RelWithDebInfo. That runs just as fast as Release, but keeps extra debugging information around that can be helpful if you encounter a problem.

Build OpenSim

Building OpenSim consists of three primary steps; obtain the source code, generate solution file, then build binaries. 

1. Obtain OpenSim Source Code

As of OpenSim 3.0, the source code can be downloaded through either subversion or zip file.

• Subversion
  svn checkout from https://simtk.org/svn/opensim/Branches/OpenSim30.  (Go to the folder you created, right click and select "SVN Checkout". Then enter the url of the repository and verify the name of the local Checkout Directory is the directory you just created. Hit OK) If building Trunk then use https://simtk.org/svn/opensim/Trunk instead.
   
• Zip file
  you can download the OpenSim source code in a zip file from the OpenSim downloads page. (After 3.0 release)

2. Use CMake to Build the Solution (.sln) File

1. Launch CMake:
   
   1. "Where is the source code?" Choose the OpenSim source code directory you specified (e.g. ../MyDocuments/Projects/OpenSim).  This designates the folder containing the top-level CMake file named CMakeLists.txt.
   2. "Where to build the binaries?" Choose a build location (e.g. ../MyDocuments/Projects/OpenSim/build). This designates the folder for compiler files, debug and release sub-folders, etc.
2. Press the Configure button (near the bottom). Let CMake create the build directory. Choose a “generator” that best matches the compiler you are using, for example “Visual Studio 10”. Select “Use default native compilers” and click Finish.
3. To avoid building the command line utilities and associated tests (faster), check BUILD_API_ONLY. This is an Advanced Option in CMake GUI.
4. Specify an installation location for OpenSim (e.g. CMAKE_INSTALL_PREFIX = ../MyDocuments/Apps/OpenSimLocal)
5. Verify that BUILD_USING_NAMESPACE is set to the same value used when building Simbody (either left blank or set to "OpenSim" to create simbody libraries with prefix "OpenSim_").
6. Point SimTK_INSTALL_DIR to where you installed Simbody (e.g. C:/Apps/SimbodyLocal if you build from source or XXXX if you installed the binary). 
   
   1. Make sure Simbody_INCLUDE_DIR, Simbody_LIB_DIR, Simbody_BIN_DIR have been set based on SimTK_INSTALL_DIR (these are shown only in Advanced View in CMake)
7. Hit Configure again. This time there should be nothing in red and the Generate button will be available.
8. Hit "Generate", which will create the Visual Studio solution files in the OpenSim build directory

3. Build Binaries

1. Launch OpenSim.sln from the OpenSim build directory
2. Make sure you are in "Debug" configuration (selection in the top center of the screen).
3. Build the project ALL_BUILD (right click and select "Build")
4. Build the project INSTALL to make a local installation of binaries (dll’s and exe’s) and documentation
5. Build RUN_TESTS to make sure everything built correctly
6. Repeat steps 2 to 5  in the “RelWithDebInfo” configuration (right click project - Properties - Configuration drop down box). While the debug configuration is very useful for testing and debugging, it will be too slow to use for most purposes. The production configuration we recommend is RelWithDebInfo. That runs just as fast as Release, but keeps extra debugging information around that can be helpful if you encounter a problem.
7. Ensure the ${install directory}/bin folder is on a path specified in your computer’s PATH environment variable, (e.g., ensure PATH includes C:\OpenSim Local\bin)

Mac-Specific Instructions

• If you are building on a Mac, set the DYLD_LIBRARY_PATH variable so that the SimTK and OpenSim libraries can be found. (On Windows that is done by setting the system PATH, and on Linux it is done with LD_LIBRARY_PATH.) 
• If you are building Simbody on OS X 10.7 (Lion) you will need to use the SDK 10.6 instead of 10.5, and SimTKlapack must be used rather than the Mac native lapack. This is done by changing your cmake configuration as follows:
  • Set CMAKE_OSX_DEPLOYMENT_TARGET to "10.6", and CMAKE_OSX_SYSROOT to /Developer/SDKs/MacOSX10.6.sdk"
  • Set BUILD_USING_OTHER_LAPACK to "SimTKlapack", and add the Simbody build directory to my DYLD_LIBRARY_PATH

Troubleshooting

• Check out the instructions at the Simbody Project Site. These documents have lots of helpful information about setting up your system to build, getting cmake, etc.
• Windows has two PATH environment variables, one under "User variables" and another under "System variables." OpenSim\bin must be prepended to the PATH environment variable under "System variables," otherwise you may receive runtime errors.
• One key issue you need to be aware of is the possible interaction between a development environment and installed versions of OpenSim on the same machine. This can happen if you allow the OpenSim installer to add the install directory/bin to the path and have it ahead of the path to the dynamic libraries that you build/install yourself. The symptom is that you'll see some random unexpected behavior and/or crashes. Things to do to minimize these possible interactions:
  1. Do not add the install directory of OpenSim to your "Path" environment variable (or remove it if it's already there). The GUI DOES NOT NEED path setting but command line tools do. If you want to know what's on your path, open a command prompt window and type "path".
  2. Make debug builds only from source. Debug libraries have different names than release libraries (with trailing _d for debug), so there's no possibility of collision/mixup. The code runs an order of magnitude slower in some cases but should be good enough for troubleshooting which is the most time consuming task.
  3. Be aware of library name conventions, for example the simtk libraries included with OpenSim distributions come with a prefix OpenSim_ you can configure your libraries to use or not use a prefix by setting the "BUILD_USING_NAMESPACE" CMake variable, if you do please sure it's set consistently in both Simbody and OpenSim builds.