Build Instructions

This page provides with Build Scripts for Windows, MacOS and Linux (Ubuntu and Debian). The scripts take care of downloading, building and installing OpenSim GUI and all of its dependencies.

For each platform you will find: build instructions, a configuration section, and a troubleshooting section with solutions to the most common problems we have identified. If you find an error in the build scripts or have any problem while executing them that is not addressed in the troubleshooting sections, please submit an Issue.

Table of Contents

• Windows
  • Build Instructions
  • Configuration
  • Troubleshooting
• Linux
  • Build Instructions
  • Configuration
  • Troubleshooting
• MacOS
  • Build Instructions
  • Configuration
  • Troubleshooting

Windows

Note: Tested on Windows 10 and Windows 11. These instructions should work for other versions with some modifications (e.g., package manager, package names, etc).

Build Instructions:

Note: Tested on Windows 10 and Windows 11.

1. Download the build script from here.

2. Open Windows PowerShell as Administrator and execute the script as follows:

   & 'opensim-windows-build-script.ps1'

3. Wait until the building process has finished.

Configuration:

1. Build type:

   • You can change the debug type by setting the -d flag value. The values allowed are:

     • Debug: debugger symbols. No optimizations (more than 10x slower). Library names end with _d.
     • Release: No debugger symbols. Optimized.
     • RelWithDebInfo: Debugger symbols. Optimized. Bigger but not slower than Release. Choose this if unsure.
     • MinSizeRel: Minimum size. Optimized.

   • The default value is Release.

   • Example: & 'opensim-windows-build-script.ps1' -d Release

   • Note: The same build type should be used for opensim-core and opensim-core-dependencies to avoid mysterious errors.

2. Number of jobs (threads):

   • You can change the number of jobs used to build by setting the -j flag value. The values allowed are integer numbers >=1.

   • The default value is 4.

   • Example: & 'opensim-windows-build-script.ps1' -j 4

3. Casadi/Tropter:

   • You can disable Moco build by setting the -s flag. This flag takes no arguments.

   • Example: & 'opensim-windows-build-script.ps1' -s

4. Branch name (for developers):

   • You can specify the opensim-core branch and the opensim-gui branch you want to clone by setting the -c and -g flags respectively.

   • The default values are main for both opensim-core and opensim-gui.

   • Example: & 'opensim-windows-build-script.ps1' -c main -g main

Troubleshooting:

1. Running scripts is disabled on the system:

   • Error message:

     &: File <path-to-script> cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.

   • Solution (more details on this link):

     In PowerShell, as Administrator, you can allow execution of scripts with the following command

     Set-ExecutionPolicy Unrestricted -Scope CurrentUser

     Once you are done, you can set the policy back to default (Recommended):

     Set-ExecutionPpolicy Restricted -Scope CurrentUser

Linux

Note: Tested on Ubuntu 18.04, 20.04 and 22.04, and Debian 10 and 11. These instructions should work for other distributions with some modifications (e.g., package manager, package names, etc).

Build Instructions:

1. Download the build script from here.

2. Open the terminal and execute the script as follows:

   ./opensim-linux-build-script.sh

3. Wait until the building process has finished.

Configuration:

1. Build type:

   • You can change the debug type by setting the -d flag value. The values allowed are:

     • Debug: debugger symbols. No optimizations (more than 10x slower). Library names end with _d.
     • Release: No debugger symbols. Optimized.
     • RelWithDebInfo: Debugger symbols. Optimized. Bigger but not slower than Release. Choose this if unsure.
     • MinSizeRel: Minimum size. Optimized.

   • The default value is Release.

   • Example: ./opensim-linux-build-script.sh -dRelease

   • Note: The same build type should be used for opensim-core and opensim-core-dependencies to avoid mysterious errors.

2. Number of jobs (threads) used to build:

   • You can change the number of jobs used to build by setting the -j flag value. The values allowed are integer numbers >=1.

   • The default value is 4.

   • Example: ./opensim-linux-build-script.sh -j4

3. Casadi/Tropter:

   • You can disable Moco build by setting the -s flag. This flag takes no arguments.

   • Example: ./opensim-linux-build-script.sh -s

4. Branch name (for developers):

   • You can specify the opensim-core branch and the opensim-gui branch you want to clone by setting the -c and -g flags respectively.

   • The default values are main for both opensim-core and opensim-gui.

   • Example: ./opensim-linux-build-script.sh -cmain -gmain

Troubleshooting:

1. Permission denied:

   • Error message:

     bash: ./opensim-linux-build-script.sh: Permission denied

   • Solution: Grant execution permission to the script:

     sudo chmod +x opensim-linux-build-script.sh

2. Failed to load libraries when executing opensim after build:

   • Error message: Error: While executing opensim once installed: Failed to load one or more dynamic libraries for OpenSim. java.langUnsatisfiedLinkError: /opt/opensim-gui/sdk/lib/libosimJavaJNI.so: libadolc.so.2: cannot open shared object file: No such file or directory.

   • Solution: Add the following two lines to the beginning of the file: /opt/opensim-gui/bin/opensim.

     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/<user>/opensim-workspace/opensim-core-dependencies-install/adol-c/lib64

     export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/<user>/opensim-workspace/opensim-core-dependencies-install/ipopt/lib

3. Build process is consuming more virtual memory than available:

   • Error message: The error message can be different depending of your OS. Here are examples of error messages in Ubuntu and Debian.

     killed: signal terminated program cc1plus

     virtual memory exhausted: Cannot allocate memory

     Additionally, you can confirm that the error is caused by the build process consuming too much virtual memory by executing the following command:

     sudo dmesg | grep cc1plus

     The following line should appear (among others):

     Out of memory: Killed process <process-number> (cc1plus)...

   • Solution: The most probable scenarios when this error appears are:

     • You are using more jobs when executing the build script (-j flag) than your system can afford. Increasing the number of jobs increases the virtual memory consumption of the build process. The solution, in this case, is to decrease the number of jobs. Remember that the default number of jobs in our script is 4, so you may need to set it to a lower value.
     • You have low virtual memory (RAM) available. The solution, in this case, is to increase the memory of your machine (this should be easy if your are building OpenSim in a virtual machine)

4. After installing OpenSim, libopenblas.so.0 cannot be found:

   • Error message:

     error while loading shared libraries: libopenblas.so.0: cannot open shared object file: No such file or directory

   • Solution: We do not distribute low level libraries like this, these need to be installed outside in standard system locations. In the case of this library, you can install it with:

     sudo apt install libopenblas-base

MacOS

Note: Tested on MacOS 11 (Big Sur). These instructions should work for other Mac versions with some modifications (e.g., package names, etc).

Build Instructions:

1. Download the build script from here.

2. Open the terminal and execute the script as follows:

   ./opensim-macos-build-script.sh

3. Wait until the building process has finished.

Configuration:

1. Build type:

   • You can change the debug type by setting the -d flag value. The values allowed are:

     • Debug: debugger symbols. No optimizations (more than 10x slower). Library names end with _d.
     • Release: No debugger symbols. Optimized.
     • RelWithDebInfo: Debugger symbols. Optimized. Bigger but not slower than Release. Choose this if unsure.
     • MinSizeRel: Minimum size. Optimized.

   • The default value is Release.

   • Example: ./opensim-macos-build-script.sh -dRelease

   • Note: The same build type should be used for opensim-core and opensim-core-dependencies to avoid mysterious errors.

2. Number of jobs (threads) used to build:

   • You can change the number of jobs used to build by setting the -j flag value. The values allowed are integer numbers >=1.

   • The default value is 4.

   • Example: ./opensim-macos-build-script.sh -j4

3. Casadi/Tropter:

   • You can disable Moco build by setting the -s flag. This flag takes no arguments.

   • Example: ./opensim-macos-build-script.sh -s

4. Branch name (for developers):

   • You can specify the opensim-core branch and the opensim-gui branch you want to clone by setting the -c and -g flags respectively.

   • The default values are main for both opensim-core and opensim-gui.

   • Example: ./opensim-macos-build-script.sh -cmain -gmain

Troubleshooting:

1. Permission denied:

   • Error message:

     zsh: Permission denied ./opensim-macos-build-script.sh

   • Solution: Grant execution permission to the script:

     sudo chmod +x opensim-macos-build-script.sh

2. Need sudo access on macOS:

   • Error message:

     Need sudo access on macOS (e.g. the user <user-name> needs to be an Administrator)!

   • Solution: Execute the following command to have sudo access:

     sudo su -- <user-name>

     Where <user-name> is the username logged in on your machine.