{"id":33219,"date":"2023-11-16T18:19:50","date_gmt":"2023-11-16T18:19:50","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=33219"},"modified":"2023-11-16T18:19:50","modified_gmt":"2023-11-16T18:19:50","slug":"debug-vcpkg-portfiles-in-cmake-script-mode-with-visual-studio-code","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/debug-vcpkg-portfiles-in-cmake-script-mode-with-visual-studio-code\/","title":{"rendered":"Debug vcpkg portfiles in CMake script mode with Visual Studio Code"},"content":{"rendered":"

We recently announced support for <\/span>debugging the CMake language using the VS Code CMake Tools extension<\/span><\/a>. Now in version 1.16 of the extension, you can fine-tune the debugger configuration using a launch.json file. This enables debugging in CMake script mode in addition to the existing debugging of CMake project generation.<\/span>\u00a0<\/span><\/p>\n

CMake script mode<\/span><\/a> is an alternative way of running CMake that does not generate a build system, but instead uses the CMake language as a general-purpose scripting language. While script mode is not widely used (although there are <\/span>fun esoteric examples<\/span><\/a>), it is the mechanism that powers <\/span>vcpkg portfiles<\/span><\/a>. vcpkg uses portfiles to know how to acquire, build, and install libraries. Through a combination of the new <\/span>experimental \u201c–x-cmake-debug\u201d vcpkg option<\/span><\/a> and CMake Tools, it\u2019s now possible to debug these portfiles in VS Code. This is helpful when adding a library to the vcpkg catalog.<\/span>\u00a0<\/span><\/p>\n

Debugging vcpkg portfiles<\/h3>\n

As an example, <\/span>we\u2019ll<\/span> explore how to debug the <\/span>vcpkg<\/span> portfile<\/span> for <\/span>zlib<\/span>. First, ensure you have <\/span>CMake<\/span><\/strong> Tools 1.16<\/strong> and <\/span>CMake<\/span><\/strong> 3.27<\/strong> installed. Next, clone<\/span> the<\/span> vcpkg<\/span> repo <\/span>and open it in VS Code.<\/span><\/span>\u00a0<\/span><\/p>\n

\n
> git clone https:\/\/github.com\/microsoft\/vcpkg\r\n> cd vcpkg\r\n> .\\bootstrap-vcpkg.bat (or bootstrap-vcpkg.sh on Linux)\r\n> code .<\/pre>\n<\/blockquote>\n
We’ll use a tasks.json<\/code> to define a task that installs the zlib<\/code> library with the --x-<\/code><\/span>cmake<\/span>-debug <\/span><\/code>option<\/span> and a <\/span>launch.json<\/span> file to configure <\/span>CMake<\/span> Tools<\/span> to attach to the <\/span>zlib<\/span> portfile<\/span> as <\/span>it\u2019s<\/span> being <\/span>run<\/span>. In VS Code, create a new \u201c.<\/span>vscode<\/span>\u201d directory<\/span>. Add the following <\/span>tasks.json<\/span><\/code> and <\/span>launch.json<\/span><\/code> files to this directory.<\/span><\/p>\n
tasks.json<\/strong><\/p>\n
{<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 \"version\": \"2.0.0\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 \"tasks\": [<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"label\": \"Reinstall zlib\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"type\": \"shell\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"isBackground\": true,<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"command\": \"& \\\"${workspaceFolder}\/vcpkg.exe\\\" remove zlib; & \\\"${workspaceFolder}\/vcpkg.exe\\\" install zlib --no-binarycaching --x-cmake-debug \\\\\\\\.\\\\pipe\\\\portfile_debugging\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"problemMatcher\": [<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"pattern\": [<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"regexp\": \"\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"file\": 1,<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"location\": 2,<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"message\": 3<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ],<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"background\": {<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"activeOnStart\": true,<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"beginsPattern\": \".\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"endsPattern\": \"Waiting for debugger client to connect\"<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ]<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 ]<\/span>\u00a0<\/span>\r\n\r\n}<\/span>\u00a0<\/span><\/pre>\n
\nThe important parts of the configuration are the command, which removes zlib<\/span> if <\/span>it\u2019s<\/span> already installed and then reinstalls it, and the <\/span>endsPattern<\/span><\/code>,<\/span> which tells VS Code when it can consider the task complete. <\/span>CMake<\/span> will output the \u201cWaiting for debugger client to connect\u201d string as soon as <\/span>it has finished initializing the debugger. The rest of the <\/span>problemMatcher<\/span><\/code>\u00a0<\/span>values are<\/span> required<\/span> to <\/span>satisfy<\/span> VS Code\u2019s launch configuration <\/span>schema but<\/span> are not used in this example.<\/span>\u00a0<\/span><\/span><\/p>\n
launch.json<\/strong><\/p>\n
{<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 \"version\": \"0.2.0\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 \"configurations\": [<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"type\": \"cmake\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"request\": \"launch\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"name\": \"Debug zlib portfile\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"cmakeDebugType\": \"external\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"pipeName\": \"\\\\\\\\.\\\\pipe\\\\portfile_debugging\",<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"preLaunchTask\": \"Reinstall zlib\"<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<\/span>\u00a0<\/span>\r\n\r\n\u00a0\u00a0\u00a0 ]<\/span>\u00a0<\/span>\r\n\r\n}<\/span>\u00a0<\/span><\/pre>\n
This CMake Debugging configuration uses <\/span>a <\/span>cmakeDebugType<\/span><\/code>\u00a0<\/span>of external<\/code>,<\/span> meaning the <\/span>CMake<\/span> Tools extension is not responsible for launching <\/span>CMake<\/span> (in this case <\/span>vcpkg<\/span> is<\/span> launching <\/span>CMake<\/span>). <\/span>Notice how we use the same pipe name as the <\/span>vcpkg<\/span> install task.<\/span><\/span><\/p>\n
Finally, <\/span>open ports\/<\/span>zlib<\/span>\/<\/span>portfile.cmake<\/span> and set a breakpoint <\/span>on line 2 (the call to <\/span>vcpkg_from_github<\/span>). In the <\/span>VS Code Run and Debug view, select the Debug <\/strong><\/span>zlib<\/span> portfile<\/span><\/strong>\u00a0configuration and click the play button to start debugging. VS Code will automatically <\/span>run the <\/span>vcpkg<\/span> install task<\/span> until the debugger is ready for client connections, then start a debugging session. At this point <\/span>it\u2019s<\/span> possible to step through the <\/span>portfile<\/span> and inspect variables.<\/span><\/span>\u00a0<\/span><\/span><\/p>\n
Debugging in CMake script mode without a configuration<\/h3>\n
It\u2019s<\/span> also possible to <\/span>quickly<\/span> debug <\/span>CMake<\/span> scripts without a <\/span>launch.json<\/span> configuration. This can be a handy way <\/span>to experiment with <\/span>CMake<\/span> commands. To try it, create a new <\/span>file named “<\/span>debugging<\/span>_example<\/span>.cmake”<\/span>\u00a0in VS Code<\/span>, <\/span>open it in the editor<\/span>, and add this content:<\/span><\/span>\u00a0<\/span><\/p>\n
debugging_example.cmake<\/strong><\/p>\n
set(WORLD \"World!\")<\/span>\u00a0<\/span>\r\n\r\nmessage(STATUS \"Hello ${WORLD}\")<\/span>\u00a0<\/span><\/pre>\n
Set a breakpoint on line 1 of this file.  In the Run and Debug view, select the <\/span>\u201c<\/span>CMake<\/span> Debugger\u2026” <\/span><\/strong>option<\/span> from the <\/span>debug configuration dropdown<\/span> and <\/span>choose \u201c<\/strong><\/span>CMake<\/span>: <\/span>CMake<\/span><\/strong> Script\u201d<\/strong> from the quick pick menu. Click the play button and the <\/span>script will start running under the debugger, with no <\/span>launch.json<\/span> configuration <\/span>needed<\/span>!<\/span><\/p>\n
\"Debugging<\/a><\/p>\n
What’s next?<\/h3>\n
CMake<\/span> script mode debugging currently only <\/span>works<\/span> in VS Code, but we are planning to bring the same functionality to Visual Studio<\/span> in a future release. Learn more about <\/span>all the options for debugging <\/span>CMake<\/span> scripts in <\/span><\/span>our documentation<\/span><\/span><\/a>.<\/span><\/span>\u00a0<\/span><\/p>\n
Send us your feedback!<\/h3>\n
We hope this helps your <\/span>CMake<\/span> workflows in VS Code.<\/span> Download the\u202f<\/span><\/span>CMake\u202fTools extension\u202f<\/span><\/span><\/a>for Visual Studio Code and let us know what you think. We would love to see what you contribute to our\u202f<\/span><\/span>repo<\/span><\/span><\/a>\u202fand are active on reviews and collaboration. If you have any issues, please file an issue to our repo\u202f<\/span><\/span>here<\/span><\/span><\/a>. Comment below or reach us via email at\u202f<\/span><\/span>visualcpp@microsoft.com<\/span><\/span><\/a>\u202for via\u202fTwitter at\u202f<\/span><\/span>@VisualC<\/span><\/span><\/a>.<\/span><\/span>\u00a0<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"
We recently announced support for debugging the CMake language using the VS Code CMake Tools extension. Now in version 1.16 of the extension, you can fine-tune the debugger configuration using a launch.json file. This enables debugging in CMake script mode in addition to the existing debugging of CMake project generation.\u00a0 CMake script mode is an […]<\/p>\n","protected":false},"author":72332,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1,266,272],"tags":[],"class_list":["post-33219","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-cplusplus","category-cmake","category-vcpkg"],"acf":[],"blog_post_summary":"
We recently announced support for debugging the CMake language using the VS Code CMake Tools extension. Now in version 1.16 of the extension, you can fine-tune the debugger configuration using a launch.json file. This enables debugging in CMake script mode in addition to the existing debugging of CMake project generation.\u00a0 CMake script mode is an […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/33219","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/72332"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=33219"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/33219\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=33219"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=33219"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=33219"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\"Debugging<\/a><\/p>\n