Building From Source

1. Building From Source#

Note

The build instructions here are for general users who just want to build OpenSim Creator.

Because everyone’s C++ build environment is slightly different, there are no catch-all build instructions that will work for everyone. Instead, we recommend reading + running the automated build scripts (located at scripts/ in the source tree), or reading Development Environment, which concretely covers tips-and-tricks for Visual Studio or QtCreator.

1.1. Building on Windows (10 or newer)#

1.1.1. Windows Environment Setup#

The OpenSim Creator build requires that the development environment has git, a C++-20 compiler, cmake, WiX (if packaging an installer), and python. These days, the Visual Studio installer provides the C++ compiler and cmake. Here is a step-by-step guide for setting up a typical development environment:

  1. Get git:

    1. Download and install git from https://git-scm.com/downloads

    2. Make sure to add it to the PATH. Usually, the installer asks if you want this. If it doesn’t ask, then you may need to add it manually (google: “Modify windows PATH”, add your git install, which defaults to C:\Program Files\Git\bin).

    3. Verify it’s installed by opening a terminal (Shift+Right-Click -> Open Powershell window here) and run git

  2. Get Visual Studio >=2022 (C++ compiler - note: Visual Studio is not the same as Visual Studio Code):

    1. Download and install it from https://visualstudio.microsoft.com/downloads/

    2. Make sure to select C/C++ development in the installer wizard when it asks you which parts you would like to install

  3. Get WiX (can be disabled with -DOSC_CONFIGURE_PACKAGING=OFF, builds the .msi installer):

    1. Download and install WiX3 (e.g. wix314.exe) from wixtoolset/wix3

    2. Avoid using newer WiX versions because GitHub runner images etc. currently still use WiX3 (see: actions/runner-images)

  4. Get python and pip:

    1. Download from https://www.python.org/downloads/

    2. Make sure python and pip are added to the PATH (the installer usually prompts this)

    3. Verify they are installed by opening a terminal (Shift+Right-Click -> Open Powershell window here) and run python --help and pip --help

  5. Clone the opensim-creator source code repository:

    1. Open a terminal, cd to your workspace directory (e.g. Desktop), and run git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator

    2. The resulting opensim-creator directory should contain all necessary source code to build the project (incl. third_party code etc.)

  6. Create a local python virtual environment with pip dependencies installed into it:

    1. Open a terminal, cd to the opensim-creator directory

    2. Run python .\scripts\setup_venv.py, which is roughly equivalent to python -m venv .venv/ followed by pip install -r requirements/all_requirements.txt

1.1.2. Windows Build#

Assuming your environment has been set up correctly (explained above), the easiest way to build OpenSim Creator is with an end-to-end build script. The steps are:

  1. Open a PowerShell terminal (Shift+Right-Click -> Open Powershell window here)

  2. Either cd into the opensim-creator directory (if cloned when you setup the environment, above), or clone it with git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator.

  3. Run ./scripts/ci_build_windows.bat Development

1.2. Building on MacOS (Sonoma or newer)#

1.2.1. MacOS Enrivonment Setup#

  1. Get brew:

    1. Go to https://brew.sh/ and follow installation instructions

  2. Get git:

    1. Can be installed via brew: brew install git

  3. Get C++23-compatible compiler (e.g. clang via brew, or newer XCodes):

    1. OpenSim Creator is a C++23 project, so you’ll have to use a more recent XCode (>=15), or install a newer clang from brew (e.g. brew install clang)

  4. Get cmake:

    1. Can be installed via brew: brew install cmake

  5. Get python and pip:

    1. Can be installed via brew: brew install python

  6. Clone the opensim-creator source code repository:

    1. Open a terminal, cd to your workspace directory (e.g. Desktop), and run git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator

    2. The resulting opensim-creator directory should contain all necessary source code to build the project (incl. third_party code etc.)

  7. Create a local python virtual environment with pip dependencies installed into it:

    1. Open a terminal, cd to the opensim-creator directory

    2. Run python .\scripts\setup_venv.py, which is roughly equivalent to python -m venv .venv/ followed by pip install -r requirements/all_requirements.txt

1.2.2. MacOS Build#

  1. Build OpenSim Creator in a terminal:

    1. If you have multiple C++ compilers, make sure that the CC and CXX environment variables point to compilers that are compatible with C++23. E.g. export CXX=$(brew --prefix llvm@15)/bin/clang++

    2. Run the build script: ./scripts/ci_build_unix.sh Development

1.3. Building on Ubuntu (22.04 or newer)#

1.3.1. Ubuntu Environment Setup#

  1. Get git:

    1. Install git via your package manager (e.g. apt-get install git)

  2. Use git to get OpenSim Creator’s (+ dependencies’) source code:

    1. Clone opensim-creator: git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator

    2. cd into the source dir: cd opensim-creator

    3. The remaining build steps are performed in the source directory

  3. Get apt dependencies:

    1. apt dependencies are listed in the docker/ directory with an _apt.txt suffix

    2. For example, if you’re on Ubuntu 22.04, you could run apt-get install $(sed 's/#.*//' "docker/ubuntu22_apt.txt" | xargs) to install the necessary Ubuntu 22.04 apt dependencies

  4. Setup Python Get python libraries:

    1. cd into the opensim-creator source directory (if you haven’t already)

    2. Install all necessary python libraries into your current python environment with pip install -r requirements/all_requirements.txt

1.3.2. Ubuntu Build#

  1. Build OpenSim Creator from source:

    1. cd into the opensim-creator source directory (if you haven’t already)

    2. Run the build script, you can use the CC and CXX environment variables to choose your C++ compiler if you’re using the non-default one, e.g. CC=gcc-12 CXX=g++-12 ./scripts/ci_build_unix.sh Development