Setting up a dev environment for the MSVC toolchain (Visual Studio 2022) for Windows

Introduction

Outlined below is a step-by-step guide to setting up a development environment on Windows using Visual Studio 2022.

Basic requirements

Install Microsoft Visual Studio 2022, and use the Visual Studio Installer application to install the “Desktop Development with C++” workload.

You will also need the Developer Powershell for VS2022 application in which you can run powershell scripts, which should come packaged with Visual Studio.

Download the Dissolve Github repository using the full Visual Studio 2022 Git integration for a streamlined development experience. Visual Studio will ask you sign in to GitHub with your credentials if you want to do this.

Install dependencies using powershell script

Open Developer Powershell for VS2022 from Windows as administrator, and navigate to the Dissolve Visual Studio repo folder.

Run the following Powershell command to enable scripts:

Set-ExecutionPolicy Bypass -Scope Process

There is a pre-packaged Powershell script (develop.ps1) which can be run from the top-level of the Dissolve project directory:

./develop.ps1 -qtVersion 6.4.2

This script can be used to install the following packages into a dependencies folder:

• Qt6
• Freetype
• FTGL
• Antlr4
• Java

A specific version of Qt can be specified for installation via the -qtVersion parameter (i.e. 6.4.2). If you have an existing system Qt6 installation, the script can attempt to use this instead via the -systemQt parameter. When installing from the official Qt website, the installation will usually be located in C:\Qt6, but this may vary depending on your system setup. Ensure that the system Qt msvc2019_64 binaries (bin) and CMake module (lib\cmake) directories are added to the PATH prior to using your own Qt installation.

The script defaults to configuring dependencies for Debug. If you want to develop in Release mode, use the appropriate flag:

./develop.ps1 -release -qtVersion 6.4.2

A flag -clean can be passed to the script to setup from a blank environment.

The output of the script is a custom CMakeUserPresets.json which contains configurations for building Dissolve CLI and GUI with CMake.

WARNING: Dissolve has a dependency on the antrl4-cpp-runtime package which is currently incompatible with MSVC latest (v143) and will lead to a compiler error. Therefore it is strongly recommended that you build this Dissolve MSVC environment with a previous version of MSVC - we recommend version 14.41.17.11. This toolset is available to download using the Visual Studio Installer via the individual components section. Once this toolset has been installed, navigate to the location of the system C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC. For example, the subdirectory corresponding to 14.41.17.11 is “14.41.34120”. When calling the develop.ps1 script, include the following arguments ... -msvcVersion 14.41.34120 -generator "Ninja".

Configure Dissolve in Visual Studio with CMake support

In Visual Studio, open the Dissolve repo. In the configurations dropdown you should see either

• CLI-Debug (CLI-Debug-MSVC)
• GUI-Debug (GUI-Debug-MSVC)

or

• CLI-Release (CLI-Release-MSVC)
• GUI-Release (GUI-Release-MSVC)

listed as available configurations. These are the user presets that we will be targetting to develop Dissolve in Visual Studio.

Once the preferred preset is selected, right-click the Dissolve CMakeLists.txt in the Visual Studio solution explorer, and select Configure Cache. This should start the CMake configuration process, which involves using the Conan package manager to install the remaining dependencies. Visual Studio may have been set up to do this automatically when the project is opened, or if any saved changes are made to CMakeLists.txt.

Note: on CMake configuration in Visual Studio, you may experience the following Conan errors:

1. “locked by another concurrent conan process”. Typically this can be resolved using the command conan remove --locks in a developer powershell. If this does not work, navigate to your C drive .conan folder and delete the data sub-directory.
2. Occasionally, configuring the cache leads to an unexplained CMake error conan install failed=1. If this happens try deleting the cache and reconfiguring, or ultimately, manually delete the build folder, restart Visual Studio and reconfigure from scratch.

Build project

Once configuration is complete, make sure to select the correct target executable from the startup item dropdown in Visual Studio. This will be either:

• Dissolve.exe (CLI version)
• Dissolve-GUI.exe (GUI version)

From the Build menu, select Build <EXECUTABLE>.