VisualGDB Project Type Overview
Overview
This page provides an overview of various VisualGDB project types. We will explain the advantages and limitations of those types, and will show how to understand the type of your existing project. You can find an overview of the most commonly used project types below:
| Project Type | Supported Targets | Build Settings Stored in | Build Managed by | Tools Needed to Build |
| MSBuild | Embedded, Linux | .vcxproj file | MSBuild + VisualGDB | Visual Studio + VisualGDB |
| Legacy GNU Make | Embedded, Linux, Android, MinGW/Cygwin | Makefile | GNU Make | GNU Make |
| Advanced CMake | Embedded, Linux, Windows (import only), Android | CMakeLists.txt | CMake | CMake, Ninja/Make |
| Legacy QMake and CMake | Linux | QMake/CMake | QMake/CMake | |
| Custom Imported | external files | external tools | external tools | |
| Advanced Mbed | Mbed | mbed_app.json | mbed-cli | python, mbed |
| Advanced Arduino | Arduino | .vgdbproj file | arduino-builder.exe | Arduino Build Tools |
| Advanced ESP-IDF | ESP32 | component.mk/CMakeLists.txt | ESP-IDF | ESP-IDF, CMake, Ninja |
The legacy project types work by creating a VC++ project on top of the actual build scripts (e.g. Makefile or CMakeLists.txt). VisualGDB updates the underlying scripts to reflect files added via Solution Explorer, but the rest of the build settings are disconnected from the Visual Studio GUI (most can be edited via VisualGDB Project Properties).
The advanced projects query the exact project structure from the underlying build system (e.g. Arduino or CMake) and render it in Solution Explorer. VisualGDB fully controls the contents of Solution Explorer for those projects and provides convenient commands and settings windows for editing various common settings.
MSBuild
The MSBuild-based projects are very similar to the regular VC++ Windows projects. VisualGDB provides its own highly optimized backend for the MSBuild system, supporting GCC, Clang IAR and Keil compilers. You can tell an MSBuild-based project by the “VisualGDB” platform name in Configuration Manager and the regular VC++ project icon: 
VisualGDB fully controls the build process of MSBuild-based projects and allows tweaking it via numerous settings in the regular VS properties windows. You can find a detailed description of the MSBuild projects on this page.
MSBuild-based projects support most properties and features of the regular Win32 projects: property sheets, per-configuration settings, custom targets, etc. We recommend using them for all new Embedded projects. If you are familiar with Visual Studio and VC++, we also recommend using MSBuild for Linux projects. Otherwise, please consider Advanced CMake.
Note that MSBuild-based projects do not support the ESP32 devices, as they come with their own SDK (ESP-IDF). If you are targeting an ESP32 device, please use the Advanced ESP-IDF Project Subsystem instead.
Legacy GNU Make
The GNU Make-based projects consist of a Makefile containing the actual build settings, and a dummy VC++ project that hands over the build logic to VisualGDB.exe. You can tell a GNU Make-based project (and other legacy projects) by the “x86” or “Win32” platform name and the regular VC++ project icon:
VisualGDB, in turn, launches GNU Make, that handles the build.
You can edit most build settings of GNU Make projects via VisualGDB Project Properties:
Any changes made here will be saved to the Makefile, and the IntelliSense settings of the dummy VC++ project will be updated accordingly. Note that this only works for Makefiles created with VisualGDB (that follow the VisualGDB Makefile structure).
This project type is recommended if you are familiar with GNU Make and are planning to extend the Makefile with custom targets. For all other scenarios, please consider using Advanced CMake or MSBuild instead.
Advanced CMake
Advanced CMake projects are thin wrappers on top of the CMakeLists.txt files. The build settings for CMake projects are stored in the CMakeLists.txt files, allowing the projects to be built on any machine that has CMake installed. VisualGDB provides convenient GUI for most commonly used CMake settings and will automatically edit CMakeLists.txt when you change them. You can tell an Advanced CMake project by the CMake icon in Solution Explorer:
Advanced CMake projects support multiple targets per project (e.g. executable + static library), allow stepping through CMakeLists.txt files and are generally recommended over other project types, as long as your platform is supported.
Starting from VisualGDB 5.5, the Advanced CMake Project Subsystem fully supports embedded projects. See this page for detailed documentation on them.
Legacy QMake and CMake
The legacy QMake and CMake projects are similar to the GNU Make-based projects, having the same advantages and disadvantages:
We generally do not recommend them for new projects, unless you need compatibility with earlier VisualGDB versions.
Custom Imported Projects
This project type is used for existing complex projects that are not based on CMake and do not follow the VisualGDB Makefile layout. You can create it by selecting the generic “Import” option in either Embedded or Linux project wizard:
Custom imported projects are very similar to the Legacy projects. Unlike GNU Make projects, VisualGDB does not make any assumptions about the underlying build system. It will simply launch the build/clean command line specified via VisualGDB Project Properties and will assume that it produced the binary specified in the “Main binary” field:
For this type of project, VisualGDB will not automatically update the IntelliSense settings, so you would need to configure IntelliSense manually via VisualGDB Project Properties.
We recommend using this type to quickly import existing large projects into VisualGDB without converting any settings. You will be instantly able to build and debug the project, although IntelliSense will not be precise, and changing build settings would require manually editing your existing Make files. Once you get comfortable with VisualGDB, we advise converting your project to CMake and using the Advanced CMake Project Subsystem with it.
Advanced Mbed
Advanced Mbed projects work by integrating the mbed-cli tools into Visual Studio. VisualGDB lets mbed handle the actual build of the project, discovers the underlying project structure and renders it in Solution Explorer, allowing you to tweak various build parameters:
Advanced Mbed projects can support multiple targets (i.e. boards) that can be added via the Add->Manage mbed Boards command in Solution Explorer.
You can build Advanced Mbed projects outside VisualGDB by running the build command shown in the VisualGDB Build window. This will produce the same results as building the project with VisualGDB.
We recommend using Mbed (and the Advanced Mbed Project System) if you are targeting one of the platforms supported by mbed and would like to take advantage of the libraries included with the Mbed OS. Another good use for Mbed would be to create portable projects that can simultaneously target multiple boards supported by mbed.
Advanced Arduino
Advanced Arduino projects work by integrating the Arduino Build system (arduino-builder.exe) into Visual Studio. They use the same build logic and produce the same results as Arduino IDE. VisualGDB supports the regular Arduino targets as well as the ESP32, ESP8266, STM32 and Bluno M3 Arduino cores. The project structure shown in Solution Explorer is queried directly from the Arduino build tools and hence 100% matches the built project:
VisualGDB also supports numerous Arduino libraries and packages that can be managed via Tools->VisualGDB->Manage VisualGDB Packages.
We recommend using Arduino projects for quick prototyping, or if you would like to use a specific Arduino-based library. As most settings for Arduino projects are automatically guessed by the Arduino build system, the initial setup is considerably easier, compared to other project types. That said, the auto-detection of settings makes it harder to tweak and understand the build process, so if you are planning a large project, please consider using MSBuild instead.
For more information see our documentation on the Advanced Arduino Project Structure.
Advanced ESP-IDF
The Advanced ESP-IDF projects are specifically designed to integrate the ESP-IDF framework into Visual Studio. They are based on the Advanced CMake projects and render the detailed and precise structure of your project (including the ESP-IDF framework) in Solution Explorer, providing numerous commands and settings pages for controlling most commonly used settings:
If you are targeting an ESP32 device (or an ESP8266 device with RTOS SDK 3.0+) and do not want to use the Arduino core, the Advanced ESP-IDF project type is the project type to use.
For more information, see our documentation on Advanced ESP-IDF Project Structure.