Documentation > Project Types > VisualGDB MSBuild Project Structure

VisualGDB MSBuild Project Structure

This page describes the structure of the MSBuild-based VisualGDB projects and gives an overview of common settings and file types.

Overview

MSBuild-based projects are supported for most Embedded and Linux targets and are very similar to the regular Win32 C/C++ projects. The main advantages of MSBuild projects over other project types are:

  • Ability to define multiple configurations/platforms with different settings
  • Ability to customize build settings for individual files
  • Use of the VS configuration GUI similar to the regular Win32 projects
  • Ability to combine VisualGDB-based and non-VisualGDB-based platforms in the same project (see this tutorial)
  • Much faster building compared to GNU Make (same speed as CMake with Ninja)

The only drawback of the MSBuild-based projects is that they cannot be easily built outside Visual Studio (see this section for possible workarounds).

You can easily tell whether the current project is using MSBuild by checking the active platform name and the project icon:If the project has the regular VC++ project icon and the platform name is VisualGDB, this is an MSBuild-based project.

Files

A typical MSBuild-based project consists of the following files and subdirectories:

File/subdirectory Meaning Source Control Action
<Project>.vcxproj Visual Studio project file. Contains the list of source files, and various build settings. Check In
<Project>.vcxproj.filters Visual Studio virtual folders file. Maps files to virtual folders in Solution Explorer. Check In
*.user Contains non-vital per-user preferences Usually, ignore
<MCU>.xml Stores VisualGDB-specific settings that are specific to embedded projects (e.g. device type) Check In
<MCU>.props Generated property sheet containing device-specific build settings Check In
*.vgdbsettings VisualGDB-specific settings stored separately for each configuration Check In
.vs\* Temporary Visual Studio files Ignore
VisualGDB\* Generated object and binary files Ignore
.visualgdb\* Temporary VisualGDB files Ignore

The <MCU>.xml and <MCU>.props files are automatically generated by VisualGDB based on a device definition from the BSP (board support package). The device definitions are typically stored under %LOCALAPPDATA%\VisualGDB\EmbeddedBSPs\<target>\<ID>\BSP.XML files. See this page for a detailed description of the structure of embedded projects.

Settings

MSBuild projects contain 2 types of settings: MSBuild-level settings (e.g. preprocessor macros, optimization type, linker script) and VisualGDB-level settings (e.g. debug settings, static analysis settings, custom actions).

MSBuild-level settings can be edited by right-clicking on the project node in Solution Explorer and selecting “Properties” (or pressing Alt-Enter). The MSBuild settings for VisualGDB projects are similar to the regular VS project settings:Note that the MSBuild settings are defined separately for each configuration (e.g. Debug/Release).

You can also define MSBuild-level settings for individual files, overriding the per-project settings:VisualGDB-level settings are stored in the .vgdbsettings files and can be edited by right-clicking on the project and selecting VisualGDB Project Properties:Note that the MSBuild Settings page of VisualGDB Project Properties is a shortcut to the most commonly used MSBuild-level settings. Editing the settings there will have the same effect as using the regular Visual Studio Properties window:

Locations of Common Settings

Below are the locations of common MSBuild-level settings for VisualGDB projects (under the VS Project Properties window for the entire project):

Setting Location
Directory of the ELF file General -> Output Directory
Directory of the object files General -> Intermediate Directory
Name/Extension of the ELF file General->Target Name/Extension
Optimization Level C/C++->Optimization->Optimization Level
Preprocessor Macros C/C++->Preprocessor->Preprocessor Definitions
Include Directories C/C++->General->Additional Include Directories
Custom Post-Compile Step (per-file) C/C++->Custom Step
Additional Linker Inputs Linker->General (see here for more details)
Linker Script Linker->Linker Script
Map File Linker->Generate Map File/Map File Name
Additional CFLAGS (both C and C++) C/C++->Command Line
Additional CFLAGS/CXXFLAGS (per language) C/C++->Advanced->Additional Options (C/C++ files)
Additional LDFLAGS Linker->Command Line

Configurations

The recommended way of adding/removing configurations to MSBuild-based VisualGDB projects is via the top of VisualGDB Project Properties window:This will automatically create the .vgdbsettings files for the new configurations.

Alternatively, you can use the regular VS Configuration Manager:However, in this case, you would need to manually copy the .vgdbsettings file for the new configuration, or link the new configuration with an existing .vgdbsettings file:

Toolchain/BSP References

Embedded MSBuild-based projects use special variables, such as $(BSP_ROOT) to refer to files managed by VisualGDB:

    <ClCompile Include="$(BSP_ROOT)\STM32F4xxxx\StartupFiles\startup_stm32f407xx.c" />

These paths are resolved as shown below:

  1. When VisualGDB is initialized, it generates/updates the %LOCALAPPDATA%\VisualGDB\FindComponents.props file. Each MSBuild project implicitly references this file via the VisualGDB MSBuild platform.
  2. Each MSBuild-based project would define variables like BSP_ID (embedded only) and ToolchainID: 
      <PropertyGroup Label="Globals">
    <BSP_ID>com.sysprogs.arm.stm32</BSP_ID>
    <BSP_VERSION>2020.01</BSP_VERSION>
  </PropertyGroup>
  3. The FindComponents.props file (more specifically, FindBSP.props, FindToolchain.props, etc) would set the BSP_ROOT/ToolchainDir variables based on the ID and version defined in the project file. This allows sharing the same project file between multiple users with different BSP/toolchain installation directories.

You can force VisualGDB to regenerate the FindXXX.props files outside Visual Studio by running the following command:

VisualGDB.exe /pkgmgr

Note that it will also open the VisualGDB Package Manager, letting you install/uninstall various packages.

Troubleshooting Build

For projects built on the Windows machine, VisualGDB will save arguments for each tool involved in building the project in .rsp files in the object file directory. You can examine them to see what exact arguments are being passed to gcc, or edit them and quickly test out your changes by running the following command line from the project directory:

<full path to gcc.exe> @<relative path to the .rsp file>

Note that VisualGDB will overwrite any changes made to the .rsp files next time you build the project.

For projects built remotely, VisualGDB generates a special .msbuild-mak file based on the MSBuild project properties. The file contains all targets and command lines used to build the project and can be built using GNU Make.

You can analyze complicated build errors by enabling diagnostic MSBuild logging via Tools->Options->Projects And Solutions->MSBuild Log Verbosity:Once verbose logging is enabled, the View->Output window (not the VisualGDB Build window), or the build log file will show very detailed information about every MSBuild target, parameter and variable involved in build.

Building outside Visual Studio

You can configure VisualGDB to dump all command lines involved in building an MSBuild-based project into a .bat file as shown below:Note that the .bat file will reference the .rsp files that are created in the object file directory. If you would like to run the .bat file on a different machine, ensure you deploy the .rsp files together with it.

See Also

For more details on the embedded project structure, see this page.