Working with Visual Studio Code

This section describes the basic setup for Visual Studio Code.

Correctly configured Visual Studio Code showing – among other things – left, debugging, testmate, and cmake pane selectors, and at the bottom, build type, kit, current target, and CTest runner.

Assumptions

• For brevity, non-standard libraries are expected to be in the folder ./deps/thirdParty.

• MSYS2/MinGW 64 Bit is used.

Installation

1. Install Visual Studio Code (https://code.visualstudio.com)

2. Install Extensions

Name	Purpose
C/C++	Support for C/C++, including IntelliSense and debugging
CMake Tools	Extended CMake support
C++ Testmate	Run and debug GoogleTest
MSYS2/Cygwin/MinGW/Clang support	MSYS2/MinGW configuration adapter
Remote Development	Development using DevContainers
Docker	Additional information for DevContainer prerequisites

Set Up Development Containers in Visual Studio Code

Introduction

This section provides step-by-step instructions on setting up development containers in Visual Studio Code (VSCode). Development containers allow you to define and manage your development environment using Docker containers, ensuring consistent and reproducible setups across different machines.

Prerequisites

Before you begin, make sure docker is installed in your system. If docker is not installed, follow the below steps.

WindowsLinux

1. Open PowerShell in Administrator Mode by right-clicking and selecting “Run as administrator.”.

2. To install wsl, run the following command and then restart the machine:

   wsl --install
   

   The above command only works if WSL is not installed at all. If you run wsl --install and see the WSL help text, try running wsl --list --online to see a list of available distros and run wsl --install -d <Linux DistroName> to install a distro. The recommended distro is Ubuntu and the following steps assumes the distro as Ubuntu

3. Once the distro is installed, check the version of the installed distro

   wsl -l -v
   

   If the version is 1, then change it to 2 using the command wsl --set-version <distro> 2

4. After successful installation, open Ubuntu by searching Ubuntu in windows search bar

5. Install the dependencies to run docker on the distro using the following command

   sudo apt install --no-install-recommends apt-transport-https ca-certificates curl
   

6. On Debian or Ubuntu, first temporarily set some OS-specific variables:

   . /etc/os-release
   

   Then, make sure apt trust the docker repo

   curl -fsSL https://download.docker.com/linux/${ID}/gpg | sudo tee /etc/apt/trusted.gpg.d/docker.asc
   

   ID will be either ubuntu or debian, as appropriate, depending on what is in /etc/os-release.

7. Add docker repo information to the apt to install docker.

   echo "deb [arch=amd64] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list
   sudo apt update
   

8. Install Docker and add user to the docker group

   sudo apt install docker-ce docker-ce-cli containerd.io
   sudo usermod -aG docker $USER
   

   Replace $USER with your user name on distro. Then close the WSL window, and launch WSL again. You should see docker when you run the command groups on command prompt to list group memberships.

9. Launch dockerd using the following command

   sudo dockerd
   

   There should be several lines of info, warnings related to cgroup blkio, and the like, with something like API listen on /var/run/docker.sock at the end. If so, you have success. If there is any network controller issue, execute the following compile_commands

   echo -e "[network]\ngenerateResolvConf = false" | sudo tee -a /etc/wsl.conf
   sudo unlink /etc/resolv.conf
   echo nameserver 1.1.1.1 | sudo tee /etc/resolv.conf
   

   Also switch to legacy iptables using the following command

   update-alternatives --config iptables
   

   And select iptables-legacy Rerun the command sudo dockerd and check if it is succeeded.

10. To check if docker is running from Windows, in PowerShell execute the following command.

wsl -d Ubuntu docker -H unix:///var/run/docker.sock --version

Note

For more detailed instructions and troubleshooting related to Docker, refer to the official Docker documentation: https://docs.docker.com/get-docker/

DevContainers

Open the repository in VSCode as folder, e.g. by calling code openpass after checking out and then define the development container configuration.

1. Open the repository as folder, e.g. by calling code openpass after checking out.

2. Create the folder .devcontainer at the root of the project and configure your development container using JSON format. Below is an example configuration:

   WindowsLinux

   devcontainer.json

   {
     "name": "openPASS DevContainer",
     "dockerFile": "../utils/Dockerfile",
     "workspaceFolder": "/workspaces/openPASS"
   }
   

   Download

   Note

   To use docker daemons running on WSL, open settings in VSCode and search for Execute In WSL and select the option to execute in WSL. Also, under Execute in WSLDistro enter your distro name, for example: Ubuntu

3. Open Your Project in a Development Container:

   1. Open the command palette by pressing Ctrl+Shift+P.

   2. Type “Dev Containers: Open Folder in Container” and select your project folder.

   3. VSCode will build the Docker container based on the configuration and open your project inside it.

4. Developing in the Container:

   1. You can now edit files, install packages, and run code within the development container.

   2. Installed extensions and settings in the container will be isolated from your local environment.

5. To exit the container, click on the bottom left status bar where it shows the container name and click “Close Remote Connection.”

Configuration

MSYS2 Path

Normally, runtime dependencies (DLLs) are not copied into the executables folder within the build process. This means, that programs cannot be executed natively from Windows shells or the explorer. It is therefore highly recommended, to set the environmental variable MSYSTEM=MINGW64 and CHERE_INVOKING=1. The setting of MSYSTEM will cause the environment to be set up correctly for MinGW64. Windows will then look for DLLs within the msys64 folders, allowing native execution. CHERE_INVOKING makes sure the shell stays in the current working directory. As investigated recently, the C:\msys64\usr\bin``must also be added to the ``PATH environment variable in order to resolve dependencies to cygpath.exe.

Note

If C:\msys64 is not already listed in PATH variable, then add C:\msys64 in PATH variable before adding C:\msys64\usr\bin to the PATH variable. If there are any other Unix like environments installed on Windows operating systems (example: cygwin), there might even be file collisions when calling certain cmake commands. Therefore, it is suggested to add C:\msys64 in PATH variable before any other Unix like environmental calls.

Either set environment variable through the Windows PowerShell

# check if set
echo ${env:path}
echo ${env:MSYSTEM}
echo ${env:CHERE_INVOKING}

# if not
setx path "%PATH%;C:\msys64\usr\bin"
setx MSYSTEM "MINGW64"
setx CHERE_INVOKING "1"

or

1. Open the start search

2. Type in “env” and choose “Edit the system environment variables”

3. Choose “Environment Variables…”

4. Set the environment variables:

   1. MSYSTEM=MINGW64

   2. CHERE_INVOKING=1

   3. Add C:\msys64\usr\bin to PATH

Visual Studio Code needs to be reloaded/restarted after the path update.

Note

An optimal solution would be to set the system environment variables in VSCode under settings.json. This is currently not possible. Please contact us if you find a better solution.

Build Kit

WindowsLinux

Add and select MSYS2/MinGW64 Build Kit:

1. Execute Ctrl+Shift+P: CMake: Edit User-Local CMake Kits

2. Insert/Update:

   cmake-tools-kits.json

   [
       {
           "name": "MinGW64",
           "preferredGenerator": {
               "name": "MSYS Makefiles"
           },
           "environmentVariables": { "PATH": "${command:mingw64.path}" },
           "compilers": {
               "C": "${command:mingw64.cc.exe}",
               "CXX": "${command:mingw64.cxx.exe}",
               "Fortran": "${command:mingw64.fc.exe}"
           },
           "keep": true
       }
   ]
   

   Download

3. Ctrl+Shift+P: CMake: Select a Kit = MinGW64

User Settings

1. Execute Ctrl+Shift+P: Preferences Open Workspace Settings (JSON)

2. Insert/Update:

   WindowsLinux

   settings.json

   {
       //
       // CMAKE
       //
       // Following settings are from the MSYS2 extension documentation
       "cmake.cmakePath": "C:\\msys64\\mingw64\\bin\\cmake.exe",
       "cmake.preferredGenerators": [
           "MSYS Makefiles"
       ],
       "cmake.configureSettings": {
           "CMAKE_MAKE_PROGRAM": "C:\\msys64\\mingw64\\bin\\make.exe",
           "CMAKE_PREFIX_PATH": [
               "${workspaceRoot}/deps/thirdParty/win64/Yase",
               "${workspaceRoot}/deps/thirdParty/win64/FMILibrary",
               "${workspaceRoot}/deps/thirdParty/win64/MantleAPI",
               "${workspaceRoot}/deps/thirdParty/win64/osi",
               "${workspaceRoot}/deps/thirdParty/win64/protobuf",
               "${workspaceRoot}/deps/thirdParty/win64/protobuf-shared",
               "${workspaceRoot}/deps/thirdParty/win64/googletest",
               "${workspaceRoot}/deps/thirdParty/win64/minizip",
               "${workspaceRoot}/deps/thirdParty/win64/openscenario_engine/release",
               "${workspaceRoot}/deps/thirdParty/win64/openscenario_api",
               "${workspaceRoot}/deps/thirdParty/win64/zlib",
               "${workspaceRoot}/deps/thirdParty/win64/open-simulation-interface",
               "${workspaceRoot}/deps/thirdParty/win64/units",
               "${workspaceRoot}/deps/scmThirdParty/win64/stochastics",
               "C:/msys64/mingw64/bin"
           ],
           "CMAKE_INSTALL_PREFIX": "${workspaceRoot}/bin/core",
           "CMAKE_BUILD_TYPE": "Debug",
           "USE_CCACHE": true,
           "WITH_DEBUG_POSTFIX": false,
           "OPENPASS_ADJUST_OUTPUT": false,
           "WITH_API_DOC": false,
           "WITH_DOC": false,
           "INSTALL_EXTRA_RUNTIME_DEPS": true,
           "INSTALL_SYSTEM_RUNTIME_DEPS": true,
           // For integration with IntelliSense (see c_cpp_properties.json)
           "CMAKE_EXPORT_COMPILE_COMMANDS": true
       },
       // Optional: Adjust to your needs
       "cmake.parallelJobs": 4,
       //
       // TESTMATE
       //
       // Optional: Adjust to your needs
       "testMate.cpp.test.parallelExecutionLimit": 4,
       "testMate.cpp.test.parallelExecutionOfExecutableLimit": 2,
       // Optional: Set, if you like to debug test discovery and test start issues
       "testMate.cpp.log.logfile": "C:\\temp\\cpp.testmate.log",
       // Optional:    As CTest triggers the install step, dependencies between test executables
       //              and openpass libraries can be resolved by linking text executables to
       //              openpass install directory
       // Alternative: Check dependencies of test executables by 'ldd <_Tests.exe> and copy
       //              libraries right next to test executable within build direcory
       "testMate.cpp.test.advancedExecutables": [
           {
               "pattern": "build/**/*{tests,Tests,TESTS}*",
               "env": {
                   "Path": "C:\\msys64\\mingw64\\bin;${workspaceFolder}\\bin\\core;${workspaceFolder}\\bin\\core\\lib;${os_env:PATH};${workspaceFolder}\\deps\\thirdParty\\win64\\FMILibrary\\lib;${workspaceFolder}\\deps\\thirdParty\\win64\\osi\\lib\\osi3"
               }
           }
       ],
       //
       // VSCODE
       //
       // Optional: Integration of MinGW64 Terminal in VS Code
       "terminal.integrated.profiles.windows": {
           "MinGW64": {
               "overrideName": true,
               "path": [
                   "C:\\msys64\\usr\\bin\\bash.exe"
               ],
               "args": ["--login", "-i"],
               "icon": "terminal-bash",
               "env": {
                   "MSYSTEM": "MINGW64",
                   "CHERE_INVOKING": "1",
                   "MSYS2_PATH_TYPE": "inherit"
               }
           }
       },
       "terminal.integrated.defaultProfile.windows": "MinGW64",
       // Enforce usage of .clang-format of modified code
       "editor.formatOnSave": true,
       "editor.formatOnSaveMode": "modifications",
       // EOL and whitespace enforcement
       "editor.detectIndentation": true,
       "editor.insertSpaces": true,
       "editor.renderFinalNewline": "dimmed",
       "files.insertFinalNewline": true,
       "files.trimFinalNewlines": true,
       "files.trimTrailingWhitespace": true
   }
   

   Download

C++ and IntelliSense

1. Execute Ctrl+Shift+P: C/C++: Edit Configurations (JSON)

2. c_cpp_properties.json

   {
       "configurations": [
           {
               "name": "openpass",
               "cStandard": "c99",
               "cppStandard": "c++17",
               "configurationProvider": "ms-vscode.cmake-tools",
               "compileCommands": "${workspaceFolder}/build/compile_commands.json",
               "intelliSenseMode": "linux-gcc-x64"
           }
       ],
       "version": 4
   }
   

   Download

Configure the Build

Execute Ctrl+Shift+P: CMake: Configure

CMake should now be able to configure the project. If not, cmake should give you at least a hint, what’s missing (normally external libraries). Read CMake Variables and Options or Installing Prerequisites for more information.

CMake

Some changes such as changing the build type (Debug/Release) will cause CMake to updates the configuration automatically. Other changes won’t trigger an update, such as changing the paths to libraries (CMAKE_PREFIX_PATH), the cmake cache needs to be cleared before reconfiguration: Ctrl+Shift+P > CMake: Delete Cache and Reconfigure

Debug Targets

CMake Tools and C++ Testmate automatically use custom launch configurations, if available. When using the debugging functionality, the according executable will be executed from where they are built (per default inside the build folder).

• This is acceptable for unit test, which do not require openPASS specific libraries. The corresponding config is CMake Target.

• For the core, located at ./build/sim/src/core/opSimulation/opSimulation, this does not work, as no libraries and no configurations are available. As a solution, a second debug target opsimulation points at the installed executable instead.

  Warning

  Don’t forget to run the target install before debugging .

1. Got to “Run and Debug” (Ctrl+Shift+D) and create a launch.json file.

2. Insert/Update:

WindowsLinux

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            // FOR TESTMATE (SELECTED TEST) AND CMAKE (DEBUG CMAKE TARGET)
            "name": "CMake Target",
            "type": "cppdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [
                {
                    "name": "PATH",
                    "value": "$PATH:${command:msys2.root}\\bin;${command:mingw64.root}\\x86_64-w64-mingw32\\lib${command:cmake.buildkit.launch.path}"
                }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "${command:cmake.buildkit.gdb.exe}",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        },
        {
            // FOR DEBUGGING opSimulation (DON'T FORGET TO CALL make install)
            "name": "opsimulation",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}\\bin\\core\\opSimulation.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}\\bin\\core",
            "environment": [
                {
                    "name": "PATH",
                    "value": "$PATH:${command:msys2.root}\\bin;${command:mingw64.root}\\x86_64-w64-mingw32\\lib${command:cmake.buildkit.launch.path}"
                }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "${command:cmake.buildkit.gdb.exe}",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

Download

Note

IntelliSense uses the compile_commands.json of generated through CMAKE_EXPORT_COMPILE_COMMANDS=ON (see settings.json). This is necessary for proper resolution of the include files.

Troubleshooting

Program does not start

The most effective way to debug startup issues is by means of the Process Monitor.

But normally, its a missing DLL. When executing the program via command line or explorer a message box should prompt which DLLs are missing. A simple solution is to copy the according DLLs into the folder of the executable. Another solution is to make the path available by extending the PATH environment variable. Potential sources for missing DLLs are C:\msys64\mingw64\bin, C:\msys64\mingw64\x86_64-w64-mingw32\lib, and the build folder itself.

Tests are not listed

For test discovery, C++ Testmate needs to know the location of all additional dependencies. This information is retrieved from the current debug configuration.

1. Testmate discovers tests only after they are built. It pays to Run CTest to build all test targets. After this, you should see all tests in the testing pane on the left.

2. Still not listed? Set testMate.cpp.log.logfile in settings.json and check log.

   1. Test executable not mentioned at all: Executable name might not fit (check glob pattern in testMate.cpp.test.executables).

   2. Log reports Error: Not a supported test executable: a library/DLL might be missing.