Working with Visual Studio Code

This section describes the basic setup for Visual Studio Code.

../../_images/vscode_quick_intro.png

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.

  • win_only 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

win_only MSYS2/MinGW configuration adapter

  1. Open the repository as folder, e.g. by calling code openpass after checking out. Say yes, when CMake Tools ask to configure the project. This creates a build folder, but fails (well, we need to config some stages).

Configuration

win_only 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.

IDEs, as Qt Creator, might set this variable base on the current build type on their own.

Build Kit

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
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    [
    {
        "name": "MinGW64",
        "preferredGenerator": { "name": "MinGW 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:

    settings.json
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
    {
    //
    // CMAKE
    //
    // Following settings are from the MSYS2 extension documentation
    "cmake.cmakePath": "${command:cmake.buildkit.cmake.exe}",
    "cmake.preferredGenerators": ["Unix Makefiles"],
    "cmake.configureSettings": {
        "CMAKE_MAKE_PROGRAM": "${command:cmake.buildkit.generator.exe}",
        "CMAKE_VERBOSE_MAKEFILE": false
    },
    // Optional: Adjust to your needs
    "cmake.parallelJobs": 4,
    // See openPASS documentation for individual WITH_* settings
    "cmake.configureArgs": [
    "-DCMAKE_INSTALL_PREFIX=C:\\openPASS\\bin\\core",
    // Adjust paths depending on your system
    "-DCMAKE_PREFIX_PATH=${workspaceFolder}/deps/thirdParty/win64/minizip;${workspaceFolder}/deps/thirdParty/win64/FMILibrary;${workspaceFolder}/deps/thirdParty/win64/protobuf-shared;${workspaceFolder}/deps/thirdParty/win64/protobuf;${workspaceFolder}/deps/thirdParty/win64/zlib;${workspaceFolder}/deps/thirdParty/win64/osi;${workspaceFolder}/deps/thirdParty/win64/units;${workspaceFolder}/deps/thirdParty/win64/googletest;${workspaceFolder}/deps/thirdParty/win64/scenario_api;${workspaceFolder}/deps/thirdParty/win64/openScenario.v1_0.API;${workspaceFolder}/deps/thirdParty/win64/openScenarioEngine/release;${command:mingw64.root};${command:mingw64.root}/bin;${command:mingw64.root}/lib",
    "-DUSE_CCACHE=ON",
    "-DCMAKE_BUILD_TYPE=Debug",
    "-DWITH_SIMCORE=ON",
    "-DWITH_TESTS=ON",
    "-DWITH_DOC=OFF",
    "-DWITH_DEBUG_POSTFIX=OFF",
    "-DINSTALL_SYSTEM_RUNTIME_DEPS=OFF",
    "-DINSTALL_EXTRA_RUNTIME_DEPS=ON",
    // For integration with IntelliSense (see c_cpp_properties.json)
    "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON"
    ],
    //
    // 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;C:\\openPASS\\bin\\core;C:\\openPASS\\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
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    {
    "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:

launch.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
    "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": "C:\\openPASS\\bin\\core\\opSimulation.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "C:\\openPASS\\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

win_only 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.