It is STRONGLY advised to read through this entire doc page before getting started.

Build tools

Compiler

SOFA requires a C++17 compatible compiler.
On Windows, we officially support Microsoft Visual Studio >= 2017 (version 15.7).
If you want to use Visual Studio IDE, install the complete Visual Studio solution.
If you want to use another IDE (like QtCreator), install the Build Tools only.

In the installer, you must enable:

1. In the main panel: the C++ development toolkit, called “C++ Build Tools” or “Desktop C++”.
2. In the side panel: the C++ ATL and C++ MFC components.

CMake: Makefile generator

SOFA requires at least CMake 3.22.1.
Install CMake with the latest official installer.

IMPORTANT: check the option “Add CMake to the system PATH for all users” during the install process.

[optional] Ninja: build system

We strongly advise you to use Ninja if you chose to install the Build Tools only (no IDE).

Ninja is an alternative to NMake. It has a better handling of incremental builds.
You can download the latest release from their GitHub repository.

IMPORTANT: do not forget to add ninja to your system PATH.

Dependencies

Core (required)

SOFA requires some libraries:

• Qt (>= 5.12.0) with Charts and WebEngine. We recommend to install Qt in your user directory with the unified installer.
  Make sure to enable Charts and WebEngine components.
  

• Boost (>= 1.65.1)
  Download and install the latest version compatible with your Visual Studio from https://sourceforge.net/projects/boost/files/boost-binaries/.

  • For Visual Studio 2022: choose boost_X_X_X-msvc-14.3-64.exe
  • For Visual Studio 2019: choose boost_X_X_X-msvc-14.2-64.exe
  • For Visual Studio 2017: choose boost_X_X_X-msvc-14.1-64.exe

• Python (= 3.10.x)
  Download and install the latest Python 3.10 (amd64). Then install the python dependencies. Run the following commands in cmd by replacing path\to\Python310\ by the path where python was installed on your OS. path\to\Python310\python.exe -m pip install --upgrade pip path\to\Python310\python.exe -m pip install numpy scipy pybind11==2.9.1

• Additional libraries: libPNG, libJPEG, libTIFF, Glew, Zlib, TinyXML2 Download the Windows dependency pack.
  You will need to unzip it directly in SOFA sources (later in this tutorial).

• SOFA v20.06 and newer also need Eigen (>= 3.2.10)
  Download and extract the latest Eigen sources.

[optional] PATH modification

You can add Boost and Qt to your PATH to ease their detection by CMake.
Boost: add your/Boost/path and your/Boost/path/libXX-msvc-XX
Qt: add your/Qt/path/msvcXXXX_XX/bin and your/Qt/path/msvcXXXX_XX/lib

Building SOFA

Setup your source and build directories

To set up clean repositories, we recommend to arrange the SOFA directories as follows:

sofa/
├── build/
│   ├── master/
│   └── v24.06/
└── src/
    └── < SOFA sources here >

First, checkout the sources from Git repository:

Get the current stable version on the v24.06 branch:

git clone -b v24.06 https://github.com/sofa-framework/sofa.git sofa/src

OR get the development unstable version on the master branch:

git clone -b master https://github.com/sofa-framework/sofa.git sofa/src

Next, unzip the SOFA dependencies for Windows (downloaded before) directly in the sources sofa/src/.

Finally, you should have something like this:

Generate a VS project (.sln) or a Makefile with CMake

1. Create build directories respecting the arrangement above.

2. In Windows Start menu, search for Native Tools Command Prompt and run the one corresponding to your Windows architecture (x64 for 64-bit, x86 for 32-bit).
   

3. In the command prompt, type cmake-gui and press Enter.
   If you get the error 'cmake-gui' is not recognized as an internal or external command, it means that your system PATH does not correctly include the path to cmake-gui. In this case, you need to provide the full path to your cmake-gui.

4. In CMake-GUI, set source folder and build folder.

5. Run Configure.

6. A popup will ask you to specify the generator for the project.

   • If you want use Visual Studio IDE, select “Visual Studio 15 2017 Win64” or “Visual Studio 16 2019 Win64” (or without the “Win64” if you are on Windows 32-bit).
   • If you want to use another IDE like QtCreator, select “CodeBlocks – Ninja” (recommended, needs Ninja) or “CodeBlocks – NMake”.

   Keep “Use default native compilers” and press “Finish”.

7. Fix eventual dependency errors by following CMake messages (see Troubleshooting section below). Do not worry about warnings.

   • e.g. define the Eigen3_DIR with the path where you installed Eigen

8. (optional) Customize SOFA via CMake variables

   • choose the build type by setting CMAKE_BUILD_TYPE to “Release” or “RelWithDebInfo” (recommended) or “Debug”
   • activate or deactivate plugins: see PLUGIN_XXX variables
   • activate or deactivate features: see SOFA_XXX variables

   Do not forget to Configure again to check if your changes are valid.

9. When you are ready, run Generate. In the build directory, this will create a Visual Studio project (.sln) or a Makefile depending on the generator you chose at step 4.

Compile

To build SOFA in Visual Studio, simply open the generated Sofa.sln. Finally, build the solution using the Visual Studio interface as shown in the image below:

If you chose another generator you will have to run the generator from the build directory.

Example with Ninja:

• In Windows Start menu, search for Native Tools Command Prompt and run the one corresponding to your Windows architecture (x64 for 64-bit, x86 for 32-bit).
• Go to the build directory with cd
• Run ninja

Time for a coffee!

Troubleshooting CMake errors

Qt detection error

To solve Qt detection errors, click on Add Entry and add CMAKE_PREFIX_PATH with path to your Qt directory (navigate until msvcXXXX_XX directory).
Example: CMAKE_PREFIX_PATH=C:/dev/Qt/5.11.3/msvc2017_64 Configure again.

A further dev warning may appear:

CMake Warning (dev) at YOUR_QT_PATH/lib/cmake/Qt5Core/Qt5CoreMacros.cmake:224 (configure_file):
configure_file called with unknown argument(s):

COPY_ONLY

Call Stack (most recent call first):
applications/projects/Modeler/exec/CMakeLists.txt:14 (qt5_add_resources)

This is just a typo with Qt5CoreMacros.cmake file. It uses COPY_ONLY instead of COPYONLY. Simply edit your Qt5CoreMacros.cmake, replace COPY_ONLY with COPYONLY and Configure again.

Setup script

To simplify the configuration of our continuous integration machines, we created a complete set of setup scripts.

These scripts install a lot of software directly in C:\ without any prealable check.
It is meant to be used on a fresh Windows. We use it on disposable virtual machines only.

Setup script: I am aware of the disclaimer above WARNING: USE AT YOUR OWN RISKS

The two scripts setup-windows_1.bat and setup-windows_2.bat install the minimum set of requirements.

Compilation tutorial

See our page presenting video tutorial for compilation on Windows.