Documentation > General > Importing Projects into VisualGDB

Importing Projects into VisualGDB

VisualGDB provides several mechanisms for importing external projects so that you could build and debug with Visual Studio. This page outlines these mechanisms and explains the differences between different ways of importing projects.

Contents

Managed vs. External Build

VisualGDB supports 2 different ways of importing most external projects:

  • Managed Build where VisualGDB will directly manage the build process. It requires more initial setup, but provides deeper GUI and IntelliSense integration.
  • External Build where VisualGDB will launch the explicitly specified command line to build the process and will use the explicitly specified output file for debugging.  Although you won’t be able to edit the project settings via VisualGDB GUI, the building and debugging will work. IntelliSense would also work after you configure it manually.

Normally, we advise starting with the External Build to quickly get building and debugging to work, and then switching to Managed Build for projects that will be actively edited.

Additionally, if your projects are compatible with one of VisualGDB’s Advanced Project Subsystems (e.g. CMake, Arduino, ESP-IDF, Mbed, NRFConnect), you can enjoy the benefits of both approaches. VisualGDB will use the external tools (e.g. mbed-cli) to build the project, while fully mapping the low-level build settings to convenient Solution Explorer GUI.

External Build

In order to import an externally built project, simply select “Specify a build command line manually” in the Embedded (or Linux) project wizard:VisualGDB will ask for the build/clean command lines, as well as the path of the build output, and will create a basic project.

If you are importing an embedded project, VisualGDB will also ask for the toolchain and device type, however it will only be used to automatically configure debug tools and IntelliSense, and hence can be set very loosely.

Changing Settings

You can later change the build/clean command lines and the output path via VisualGDB Project Properties:This type of import will work with any project type regardless of the underlying tools. It could be using an exotic compiler, domain-specific build tools or BSP, etc. As long as the build command line produces a debuggable ELF file, VisualGDB will be able to build and debug it.

As a side effect, the contents of Solution Explorer (that drives IntelliSense) will be completely independent from the actual build process. Initially, VisualGDB will populate it with the source files from the project directory, but adding/removing them will not affect the actual build.

Debugging

When you debug an externally built project, VisualGDB will use the gdb debugger from the toolchain you specified to debug the main binary configured via VisualGDB Project Properties. Note that the actual tools used to build the project can come from a different toolchain, or not be GCC-based at all.

The list of source files used to set breakpoints and step through the code is taken from the debug symbols (special data inside the ELF file) that are produced during build. They don’t have to match the Solution Explorer contents and will be accurate even if you keep Solution Explorer out-of-sync.

IntelliSense

Externally built projects are internally implemented as NMake VC++ projects. You can use the regular VS Project Properties to specify the list of include directories and preprocessor macros to use for IntelliSense:For convenience, VisualGDB provides its own IntelliSense page for managing IntelliSense directories. It will edit the same directory list as the regular VC++ Project Properties page shown above:

Managed Build

A better long-term alternative to externally built projects would be letting VisualGDB manage the build. This has several advantages over external build:

  • IntelliSense will always be synchronized with the actual build settings
  • Adding/removing files to Solution Explorer will affect the build
  • You would be able to edit various build settings via Solution Explorer

However, this requires additional setup. Specifically, VisualGDB will need to know the exact list of files participating in the build, and all the build settings (e.g. preprocessor macros, include directories, special optimization flags, etc.).

You will also need to decide on the build subsystem to use:

  • MSBuild offers the best integration with Visual Studio and is very similar to the regular VC++ projects. It is recommended for all new projects.
  • GNU Make can be useful if you are familiar with the Makefile structure and would like to customize it (e.g. add custom Make targets). Also Make-based projects can be built without Visual Studio, or VisualGDB.
  • Advanced CMake combines the advantages of both MSBuild and CMake, but requires CMake for building.

Once you decide on the build subsystem, there are several ways of importing the project structure into VisualGDB:

  1. You can start with creating a new project and incrementally adding existing source files to it. If you are using the Custom edition or higher, consider using the Add->Import Directory Recursively command in Solution Explorer to quickly add large sets of files.
  2. You can use the Import mode in the VisualGDB wizards (other than “specify a build command line manually”). This will be equivalent to creating a new project and adding all files from the specified directory to it. You would still need to manually set various build settings.
  3. If you are importing an embedded project from CrossWorks, IAR, Keil, STM32CubeIDE or SW4STM32, you can use one of VisualGDB’s project importing plugins to convert many of the common settings automatically. The next section explains this is in detail.

Using Project Importing Plugins

Project importing plugins can save considerable time by automatically converting the following project settings:

  • The exact list of source files actually used in the build
  • The target microcontroller
  • Linker script
  • Preprocessor macros
  • Include directories

Note that they will not recognize many advanced settings (e.g. target-specific optimization flags) that would still need to be configured manually.

The project importing plugins can be selected in the Embedded Project Wizard as shown below:You can find the source code of VisualGDB’s project importing plugins in our GitHub repository, so you can customize them to handle previously unsupported project formats, or other special cases. We can also convert existing large projects for you as a part of our consulting services.

Porting Projects between Compilers

Note that if a project compiles with IAR or Keil, getting to build with GCC may involve some manual adjustments. Specifically, the following parts are not compatible between Keil, IAR and GCC:

  • Target memory layout definitions (linker scripts vs. scatter files).
  • Assembly files.
  • Language extensions (e.g. placing variables at a specified address).

If you would like to avoid porting the project between the compilers, make sure you select the original compiler when importing the project:

Troubleshooting Imported Projects

Sometimes, the imported project would output would be different from the original project. This usually happens if some fine-level settings were not automatically converted. VisualGDB provides the following mechanisms for troubleshooting it:

  • You can compare the memory footprint of the VisualGDB project against the original ELF file to narrow down the problem to a specific source file.
  • You can extract the exact command lines used by MSBuild or GNU Make and compare them to the command lines used by the original project.

See this tutorial for a very detailed example of a side-by-side comparison of the build command lines between Keil uVision and VisualGDB used to track down a difference in optimization setting.

Read More

You can find numerous tutorials on importing various project types in VisualGDB on this page.