{"id":2612,"date":"2017-05-09T22:47:42","date_gmt":"2017-05-10T05:47:42","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=2612"},"modified":"2025-09-09T19:29:55","modified_gmt":"2025-09-10T02:29:55","slug":"importing-esp32-projects-built-with-esp-idf-into-visualgdb","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/esp32\/esp-idf\/","title":{"rendered":"Creating Advanced ESP32 Projects with ESP-IDF"},"content":{"rendered":"

This tutorial shows how to use the new advanced ESP-IDF project subsystem to create projects based on the ESP-IDF framework. Unlike MSBuild-based projects, ESP-IDF based projects do not require a specific version of ESP-IDF and provide the best level of integration with various ESP-IDF components and settings.<\/p>\n

Before you begin, install VisualGDB 5.4 or later and the\u00a0latest ESP32 toolchain<\/a>.<\/p>\n

We will now\u00a0build the basic “Hello, World” sample from ESP-IDF and show how to use VisualGDB to edit and debug it.<\/p>\n

    \n
  1. Start Visual Studio and open the ESP-IDF Project Wizard:\"01-prj\"<\/a><\/li>\n
  2. Select “Create a new project based on a sample project” and click “Next”:\"02-new\"<\/a><\/li>\n
  3. On the next page select your ESP32 toolchain. If you don’t have it installed yet (or are not using the latest toolchain,\u00a0click “download” in the toolchain selector to install it automatically):
    \n    \"03-toolchain\"<\/a>Update:<\/strong> For better compatibility with the latest ESP32 tools, we recommend selecting the consolidated toolchain<\/a> instead.<\/li>\n
  4. On the next page select a sample project you want to use. In this example we will use the\u00a0hello_world project to demonstrate the basics of building and debugging:\"sample\"<\/a><\/li>\n
  5. Finally select your debug method. If you haven’t done this before, follow this tutorial<\/a> to setup JTAG debugging for your board:
    \n<\/a>     \"05-openocd\"<\/a><\/li>\n
  6. Press “Finish” to create the project. VisualGDB will\u00a0launch the ESP-IDF build system to query the precise project structure:\"06-loading\"<\/a><\/li>\n
  7. Once the project\u00a0structure is loaded, VisualGDB will display it in Solution Explorer and will open the main source file:\"07-loaded\"<\/a>If you are using a preview VisualGDB build, you\u00a0may get a spurious “found 1 additional include directory” message immediately after creating the project. It is shown because\u00a0the project is missing some include files that are generated\u00a0on first build. Simply build the project and re-open\u00a0your source file to eliminate the message.<\/li>\n
  8. VisualGDB will\u00a0use the ESP-IDF build scripts to build the project, producing exactly the same result as if you were using command-line tools. It will automatically detect the number of CPU cores on your machine and run a multi-threaded build using the corresponding amount of threads:\"08-built\"<\/a><\/li>\n
  9. If you are using the Custom edition or higher, Open VisualGDB Project Properties and\u00a0enable raw terminal on the\u00a0COM port corresponding to your ESP32 board. If not,\u00a0use any\u00a0other\u00a0terminal\u00a0program to connect to it:\"09-port\"<\/a><\/li>\n
  10. Set a breakpoint in app_main() and start debugging. The breakpoint will hit and you will see the output printed by the board:\"10-debug\"<\/a><\/li>\n
  11. You can use the Threads window to\u00a0see the state of different threads of your program:\"11-threads\"<\/a><\/li>\n
  12. Now we will show how to add new source files to your ESP-IDF projects. Stop debugging, right-click on “Source Files” and select “Add->New Item”:\"12-newfile\"<\/a><\/li>\n
  13. Then choose “C++ Source File” and\u00a0add “subdir” to the location field:\"13-subdir\"<\/a><\/li>\n
  14. VisualGDB will automatically edit the COMPONENT_SRCDIRS variable in the corresponding component.mk file to\u00a0reference the new directory. This will also work\u00a0when adding existing files.
    \n    \"14-components\"<\/a>Note that adding one file from a directory will automatically add all source files from the same directory due to the way\u00a0ESP-IDF handles source files. If this happens, VisualGDB will\u00a0let you double-check the implicitly added files before proceeding.<\/li>\n
  15. Add a new function in the newly created source file: \"15-func\"<\/a><\/li>\n
  16. Now create a header and\u00a0declaration for this function. Note that\u00a0if you want the\u00a0header to be used by both C and C++ files, you need to use conditionally compiled extern “C” wrapper:\n
    #pragma once\r\n\r\n#ifdef __cplusplus\r\nextern \"C\"\r\n{\r\n#endif\r\n \r\n void func();\r\n \r\n#ifdef __cplusplus\r\n}\r\n#endif<\/pre>\n
    \"16-header\"<\/a><\/li>\n
  17. Include <header.h> from your main file. VisualGDB will automatically suggest adding “subdir” to the include directory\u00a0list:
    \n    \"17-subdir\"<\/a><\/li>\n
  18. Click “Add now” and VisualGDB will automatically insert the correct relative path to\u00a0component.mk:\"srcdirs\"<\/a><\/li>\n
  19. If\u00a0the header\u00a0case doesn’t match the\u00a0case of the physical file name, VisualGDB will show a warning and let you automatically fix it so\u00a0you will be able to build the your sources on case-sensitive Linux systems:
    \n    \"18-fixheader\"<\/a><\/li>\n
  20. You can also use the regular VS property pages to edit various project\/target properties. See how the “subdir” is now shown in the “additional include directories” field:\"19-subdir\"<\/a><\/li>\n
  21. You can configure various properties of the ESP-IDF projects using the\u00a0first page of VisualGDB Project Properties. This is equivalent to the the “make menuconfig” command, but provides an easier searchable graphical interface:
    \n    \"20-settings\"<\/a><\/li>\n
  22. For\u00a0each ESP-IDF-based project VisualGDB will automatically parse the ESP-IDF sources and make them available to the Find All References, Go To Definition and Code Map. You can\u00a0use\u00a0these\u00a0features to\u00a0explore the relations between different parts of ESP-IDF and\u00a0to diagnose tough problems:\"map\"<\/a><\/li>\n
  23. Note that for debug configurations ESP-IDF will use the “-Og” optimization setting instead of “-O0”. This doesn’t affect most of debugging functionality, however can make some scenarios less convenient (e.g. may eliminate unused variables created just for checking values via watch). You can override this\u00a0via Project Properties for your project or specific components:\"21-optim\"<\/a><\/li>\n
  24. DO NOT use this setting for built-in ESP-IDF components, as it would result in random crashes. If your project suddenly stops working after using this setting, double-check all component.mk files for the code replacing -Og with -O0 and remove it if necessary (or simply\u00a0disable the setting via Project Properties so VisualGDB will remove those lines for you):\"22-flags\"<\/a><\/li>\n<\/ol>\n
    If you want to check the project into a source control system, such as Git, simply check in the files in the project directory (including the .vgdbproj<\/strong> and .sln<\/strong> files) and add the following subdirectories to .gitignore<\/strong>:<\/p>\n
      \n
    • CodeDB (contains IntelliSense cache)<\/li>\n
    • VisualGDB (contains built objects and libraries)<\/li>\n
    • VisualGDBCache (contains parameters queried from the toolchain)<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"
      This tutorial shows how to use the new advanced ESP-IDF project subsystem to create projects based on the ESP-IDF framework.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[142],"tags":[138,56,102],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2612"}],"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=2612"}],"version-history":[{"count":19,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2612\/revisions"}],"predecessor-version":[{"id":9046,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/2612\/revisions\/9046"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=2612"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=2612"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=2612"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}