Debugging vcpkg portfiles.cmake with the VS Code CMake Tools Extensions

[Neumann-A]

Ever wonder how to correctly debug CMake? With CMake 3.27 the --debugger command was introduced and it can be used to debug vcpkg portfiles in VS Code.

Starting with vcpkg release 2023.10.19 vcpkg supports CMake debugging for portfiles and CMake projects.

The command line options for debugging are:

--x-cmake-debug <pipename>[;port1;port2;....] for debugging the script execution of vcpkg, e.g. portfiles etc. doc

--x-cmake-configure-debug <pipename>[;port1;port2;....] for debugging a CMake configure call of a port within vcpkg. doc

In both cases the command allows to specifiy which port the debugging should be activated for since cmake will otherwise stall the execution until a debugger is attached. This could get tedious if you want to debug a port with a lot of other dependencies since the debugger would need to be attached sequentially to all of them. So you definitly want to specify the port in most cases.

So how do you attach a debugger? You need a debugger which supports the debug adapter protocol and knows how to deal with the information CMake provides. One of those debuggers is integrated in the CMake Tools VS Code extension. Since version 1.16 the extension allows to attach to an external CMake debugger pipe which allows debugging of arbitrary CMake executions such as within vcpkg.

To now start debugging you would have e.g. the following code in your .vscode/launch.json:

  {
      "version": "0.2.0",
      "configurations": [
          {
              "type": "cmake",
              "cmakeDebugType" : "external",
              "request": "launch",
              "name": "vcpkg-debug",
              "pipeName": "\\\\.\\pipe\\vcpkg-cmake-debugging",
              "preLaunchTask": "Debug portfile execution"
          }
      ]
  }

and start vcpkg with the same pipename in the debugging commands as in your launch.json. You could also define a task in your .vscode/tasks.json to execute the required commands from within VS Code directly such as (vcpkg is the root of your workspace otherwise adapt paths accordingly):

  {
      "version": "2.0.0",
      "tasks": [
        {
          "label": "Remove-vcpkg-port",
          "type": "shell",  
          "command": "${workspaceFolder}/vcpkg remove zlib --recurse --host-triplet x64-windows-release --triplet x64-windows-release",
        },
        {
          "label": "Debug CMake configure within vcpkg",
          "type": "shell",
          "dependsOn" : [
            "Remove-vcpkg-port"
          ],
          "command": "${workspaceFolder}/vcpkg.exe",
          "args" : [
            "install",
            "zlib",
            "--binarysource=clear",
            "--x-cmake-configure-debug",
            "\\\\.\\pipe\\vcpkg-cmake-debugging",
            "--host-triplet", "x64-windows-release",
            "--triplet", "x64-windows-release" 
          ],
          "isBackground": true,
          "group": "none",
          "presentation": {
            "reveal": "always",
            "panel": "new"
          },
          "problemMatcher": [
            {
            "pattern": [
                {
                "regexp": ".",
                "file": 1,
                "location": 2,
                "message": 3
                }
            ],
            "background": {
                "activeOnStart": true,
                "beginsPattern": "Computing installation plan",
                "endsPattern": "Configuring",
            }
            }
        ]
        },
        {
          "label": "Debug portfile execution",
          "type": "shell",
          "dependsOn" : [
            "Remove-vcpkg-port"
          ],
          "command": "${workspaceFolder}/vcpkg.exe",
          "args" : [
            "install",
            "zlib",
            "--binarysource=clear",
            "--x-cmake-debug",
            "\\\\.\\pipe\\vcpkg-cmake-debugging",
            "--host-triplet", "x64-windows-release",
            "--triplet", "x64-windows-release" 
          ],
          "isBackground": true,
          "problemMatcher": [
            {
            "pattern": [
                {
                "regexp": ".",
                "file": 1,
                "location": 2,
                "message": 3
                }
            ],
            "background": {
                "activeOnStart": true,
                "beginsPattern": ".",
                "endsPattern": "Waiting for debugger client to connect",
            }
            }
        ]
        }
      ]
  }

(--binarysource=clear is used to avoid pulling in previously build binaries. Also don't forget to set breakpoints in the code you want to debug and make sure the execution actually hits that point since otherwise you might see the debugger directly close. Also works on !Windows just change the pipename to a domain socket as required by CMake and change the triplet in the example)

Other ways of debugging without attaching a debugger:

• pass --trace-expand via --cmake-args. E.g. --cmake-args=--trace-expand for script tracing or --cmake-args=-DVCPKG_CMAKE_CONFIGURE_OPTIONS=--trace-expand for cmake configure within a port.
• add --trace-expand to the OPTIONS parameter in the vcpkg_cmake_configure call.
• pass --debug to see which commands vcpkg itselfs executes.

[jiayuehua]

@Neumann-A
I follow the define task way. But when I run 'Debug portfile execution' task . The Terminal windows output below message, and keep waiting. What I should do next?

-- Setting "%LQ_PROXY%" environment variables to "1".
Installing 1/2 vcpkg-cmake:x64-windows-release...
Building vcpkg-cmake:x64-windows-release...
warning: -- Using community triplet x64-windows-release. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: C:\d\src\vcpkg\triplets\community\x64-windows-release.cmake
Running with debugger on.
Waiting for debugger client to connect...

[Neumann-A]

Switch to the debugger? Go to "Run & Debug" -> Launch/Start "vcpkg-debug" to start the debugger

The message you are seeing basically says: I am ready to connect to a debugger.
Don't know if tasks.json can be configured to automatically do that.

[jiayuehua]

I will try later.thanks very much..

[jiayuehua]

thanks, this work.

[touraill-adobe]

@Neumann-A
I'm not sure if this is the good location to ask this question or if I should open an issue, but I have trouble debugging the configure of packages with --x-cmake-configure-debug (debugging portfile works fine, and it is super handy, thanks for implementing that!).

Here is my setup:

• I am on Linux
• I use the manifest mode, with vcpkg.cmake as my toolchain file
• I define in my cmake preset VCPKG_INSTALL_OPTIONS=--x-cmake-configure-debug=/tmp/vcpkg_configure_pipe
• I have this configuration in my launch.json:

{
   "name": "Debug vcpkg (configure)",
   "type": "cmake",
   "cmakeDebugType": "external",
   "request": "launch",
   "pipeName": "/tmp/vcpkg_configure_pipe"
}

• I launch cmake from a terminal somewhere.

Whenever I do that, the configure stops at the beginning, presumably waiting for a debugger to be attached, but when I launch the configuration, I get an error connect ENOENT /tmp/vcpkg_configure_pipe. Looking at processes, I see that there are multiple (3) cmake processes running with the same --debugger-pipe.

I tried launching two cmake processes with the same pipe and the second one fails with

Error: Failed to create debugger adapter.
Failed to bind name '/tmp/vcpkg_configure_pipe' to socket: Address already in use

, after what trying to connect to the pipe produces the ENOENT error, so it does seem to be the cause of the failure.

Is it expected that vcpkg calls multiple cmake with a debugger-pipe when configuring? If yes, should it append some kind of counter to ensure the unicity of the pipe or something like that?

[Neumann-A]

So make sure all pipes with the name are closed. Then do the following:

a) specify the port via --x-cmake-configure-debug <pipename>[;port1;port2;....]
b) use a release only triplet like x64-linux-release or deactivate parallel configure. Otherwise you are generating two cmake process fighting for the same pipe.

[touraill-adobe]

Indeed the parallel configure seems to be the culprit, thanks! Setting VCPKG_BUILD_TYPE to release does fix the issue 👍. If I understand correctly, DISABLE_PARALLEL_CONFIGURE can be used to do the debug and release configure sequentially but it requires updating the vcpkg_cmake_configure call, is there a way to disable it without modifying the ports?