{"id":4228,"date":"2018-10-10T12:00:10","date_gmt":"2018-10-10T19:00:10","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=4228"},"modified":"2018-10-10T12:06:25","modified_gmt":"2018-10-10T19:06:25","slug":"debugging-cmake-scripts-with-visual-studio","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/cmake\/debugger\/","title":{"rendered":"Debugging CMake Scripts with Visual Studio"},"content":{"rendered":"

This tutorial shows how to use VisualGDB to\u00a0step through the CMake scripts while\u00a0analyzing CMake configuration problems. We will create a basic\u00a0CMake project using a Linux cross-toolchain,\u00a0add macros to read the version number from a text file, and will then step through the CMake statements in the debugger\u00a0and show how to modify the version read from the file on-the-fly.<\/p>\n

Before you begin, install VisualGDB 5.4 Preview 7 or later.<\/p>\n

    \n
  1. Start Visual Studio and open the VisualGDB Linux Project Wizard:\"01-prj\"<\/a><\/li>\n
  2. Select “Create a new\u00a0project” -> “Application” -> “CMake”\u00a0and ensure that the “Use the\u00a0advanced CMake Project Subsystem” checkbox is set:
    \n    \"02-newprj\"<\/a><\/li>\n
  3. On the next page select\u00a0the machine you want to target. You can\u00a0either build the code on the Windows machine using\u00a0a cross-toolchain, or build it\u00a0directly on the Linux machine, depending on your configuration. In this tutorial we will\u00a0build the code locally using the Raspberry Pi cross-toolchain:\"03-buildlocal\"<\/a><\/li>\n
  4. Press “Finish” to create the project. VisualGDB will\u00a0generate a simple CMake project with\u00a0one target:\"04-created\"<\/a><\/li>\n
  5. Open the\u00a0Visual Studio project properties for the target and\u00a0add “PROJECT_VERSION=1” to the preprocessor definitions:\"05-ver\"<\/a><\/li>\n
  6. VisualGDB will automatically insert the\u00a0corresponding statement into the CMakeLists.txt file:\"06-updated\"<\/a><\/li>\n
  7. Now we will replace the hardcoded version with\u00a0a\u00a0CMake function that will read the version from a text file. First of all, create a file called version.txt<\/strong> in your project directory and ensure it contains a single character: “1”\"07-ver\"<\/a><\/li>\n
  8. Then add the following code to your CMakeLists.txt file:\n
    function(set_version_from_file target)\r\n file(READ \"version.txt\" VERSION_FROM_FILE)\r\n\r\n if (${VERSION_FROM_FILE} LESS \"2\")\r\n  message(FATAL_ERROR \"Invalid version\")\r\n endif()\r\n\r\n target_compile_definitions(${target} PRIVATE PROJECT_VERSION=${VERSION_FROM_FILE})\r\nendfunction()\r\n\r\n<...>\r\nset_version_from_file(<your target name>)<\/pre>\n<\/li>\n
  9. Save the CMakeLists.txt and see how CMake reports a configuration error (as the version stored in the file is less than the version checked in CMakeLists.txt):
    \n    \"08-readver\"<\/a><\/li>\n
  10. Now we will\u00a0use the CMake Script Debugger to step\u00a0through the CMakeLists.txt file and see what exactly CMake is doing\u00a0and also to\u00a0skip the error statement. Right-click on your project in Solution Explorer and select “Launch CMake Debugger”:\"09-debug\"<\/a><\/li>\n
  11. VisualGDB will\u00a0stop at the first statement of the file:\"statement\"<\/a><\/li>\n
  12. The easiest way to get to the error message would be to simply press F5 to continue debugging. Once CMake hits a fatal error, VisualGDB will automatically stop at that statement:\"stopped\"<\/a>You can use the Call Stack and Watch windows to examine the program state, however as the message was already triggered, it is too late to change anything or skip the error line.<\/li>\n
  13. Restart the CMake debugging an put a breakpoint on the line comparing VERSION_FROM_FILE. Wait for it to trigger:
    \n<\/a>     \"11-ver1\"<\/a><\/li>\n
  14. Now instead of stepping\u00a0into the check, simply right-click on the “target_compile_definitions” line and select “Set Next Statement”:
    \n    \"12-setnext\"<\/a><\/li>\n
  15. Press F5 to continue the CMake configuration process. Once it is complete, the project will be configured with PROJECT_VERSION=1\u00a0as the error statement was successfully skipped:
    \n    \"13-configured\"<\/a><\/li>\n
  16. Now we will show how to modify the version\u00a0after it was read from the file. Ensure the breakpoint on the VERSION_FROM_FILE\u00a0check is still set and start another debug session. Once the breakpoint triggers, hover the mouse over VERSION_FROM_FILE and change its value to 2:
    \n    \"14-ver2\"<\/a><\/li>\n
  17. Step through the rest of the set_version_from_file() function to see that the error doesn’t trigger anymore:
    \n    \"15-stepped\"<\/a><\/li>\n
  18. Now the project got configured with PROJECT_VERSION=2 as we have manually changed it during CMake configuration:\"16-ver2\"<\/a>Changing variable values manually and\u00a0setting next statement could be useful\u00a0to quickly\u00a0get past errors (e.g. missing tools) without\u00a0restarting the entire configuration process\u00a0each time. E.g. you\u00a0could also edit the version.txt file and then force CMake to re-run the file()<\/strong>\u00a0statement to read the updated version from the file.<\/li>\n
  19. Finally we will show how to use the advanced CMake breakpoints to quickly locate the relevant parts of the\u00a0CMake scripts. Start another debug session and remove all breakpoints. Now instead of setting a breakpoint on a specific line, click “New Advanced CMake Breakpoint” -> “Breakpoint on variable change” and enter “VERSION_FROM_FILE” as the variable name:\"17-bkpt\"<\/a><\/li>\n
  20. The breakpoint will trigger when any statement anywhere in the CMake scripts will modify the VERSION_FROM_FILE variable in any scope:
    \n    \"18-changed\"<\/a>Note that\u00a0when\u00a0an\u00a0advanced breakpoints triggers, CMake has already started processing a\u00a0statement, so you won’t be able to use the “Set next statement” command until you step to the next one, or stop at a regular breakpoint.<\/li>\n<\/ol>\n
    If you are\u00a0running CMake on a remote Linux system,\u00a0ensure you build our open-source fork of CMake<\/a> that provides the script debugger functionality.\u00a0Our port is fully backward-compatible with the\u00a0regular CMake,\u00a0so you can keep on using the original CMake builds\u00a0on the machines where the script debugging functionality is not required.<\/p>\n","protected":false},"excerpt":{"rendered":"
    This tutorial shows how to use VisualGDB to\u00a0step through the CMake scripts while\u00a0analyzing CMake configuration problems. We will create a<\/p>\n","protected":false},"author":1,"featured_media":4250,"comment_status":"closed","ping_status":"closed","sticky":true,"template":"","format":"standard","meta":{"footnotes":""},"categories":[172],"tags":[77,33],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4228"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=4228"}],"version-history":[{"count":1,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4228\/revisions"}],"predecessor-version":[{"id":4249,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/4228\/revisions\/4249"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media\/4250"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=4228"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=4228"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=4228"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}