This page explains how VisualGDB manages the shared files (such as the STM32 HAL drivers) for the barebone embedded devices.

Unlike Linux-based project where the low-level drivers are included in the Linux image, barebone projects need to be explicitly built with the device-specific startup code and drivers. In order to maximize code reuse, VisualGDB normally places these drivers in a shared location that can be reused between multiple projects. The shared files are grouped into BSPs (Board Support Packages), where each BSP can support multiple devices and boards by the same manufacturer. Additionally to BSPs, shared code can also reside in Framework Packages that could be referenced by projects.

Warning: the shared file structure shown here does not apply to ESP8266 and ESP32 projects. For more information on projects using ESP-IDF, see this page instead.

VisualGDB supports the following strategies for managing the shared code:

Shared BSPs
Relocated BSPs
Stand-alone Projects
Framework Packages
Stand-alone Frameworks
Custom BSPs
Project Templates

Shared BSPs

This is the default way of organizing shared embedded code. VisualGDB will automatically download the latest BSPs for the devices you target, and will store them under %LOCALAPPDATA%\VisualGDB\EmbeddedBSPs:You can manage the currently installed BSPs (1), or change the base BSP directory (2) via Tools->VisualGDB->Manage VisualGDB Packages:VisualGDB Custom edition or higher allows installing multiple versions of the same BSP at the same time (3). On lower editions you can achieve the same effect by manually changing the package ID in the <BSP directory>\BSP.XML file and moving the BSP into a different subdirectory.

VisualGDB will automatically download the missing BSP when you open a project that references it. However, if you make any changes to the BSP files, they will be lost next time the BSP is downloaded or updated.

VisualGDB locates the BSPs by checking the %LOCALAPPDATA%\VisualGDB\EmbeddedBSPs\<target>\<BSP ID>\BSP.XML files. Text files with the .bsplink extension inside the target directory are treated as symbolic links to the actual BSP folder. You can manually install, fork, copy or rename/move BSPs, as long as you follow this convention.  Open VisualGDB Package Manager to trigger a rescan of the installed BSPs.

As long as the project is using a shared BSP, you can change various BSP-related options via VisualGDB Project Properties. E.g. you can switch to a different device, or place all code in RAM:

BSPs are often subdivided into separate frameworks (e.g. STM32 HAL drivers, LL drivers and USB Device Library). You can reference individual frameworks, and tweak their parameters via VisualGDB Project Properties -> Embedded Frameworks:

Different versions of the same BSP (e.g. STM32) may have varying degrees of backward compatibility. If updating a BSP broke down some of your projects, you can always revert to the older BSP version as shown here.

Relocated BSPs

VisualGDB Custom Edition or higher allows moving the BSPs to an arbitrary location on your computer (e.g. inside a source control checkout). This can be done via the first page of VisualGDB Project Properties of via VisualGDB Package Manager:Relocated BSPs work the same way as the regular BSPs. VisualGDB will remember the new location for a specific BSP on this computer, and will use it for any projects referencing that BSP. Relocating the BSP on one computer will not affect other computers (or other user accounts). You can read more about relocating BSPs in this tutorial.

Stand-Alone Projects

Stand-alone projects do not reference any BSP. Instead, they include local copies if all relevant BSP files (typically in the ‘BSP’ subdirectory). This considerably increases the project size, but makes it possible to edit the BSP in-place:Note that to reduce the in-place BSP size, VisualGDB will expand and remove all configuration options and frameworks. E.g. if the original BSP contained support for 500 different devices, and a few frameworks, such as the USB Device Library, each supporting several different modes (e.g. USB HID vs CDC classes), the stand-alone project will only include the files used in the current configuration, and the configuration options will be removed.

Warning: if you want to remove the vendor-supplied files from the project (e.g. STM32 HAL driver), you do not need to convert it to a stand-alone one. Instead, try unreferencing the unneeded frameworks via VisualGDB Project Properties -> Embedded Frameworks.

Stand-alone projects are supported in VisualGDB Custom edition or higher. You can read more about them in our stand-alone project tutorial.

If you are using the Advanced CMake Project Subsystem, you can convert the in-place BSPs from stand-alone projects back into shared BSPs. This will preserve any modifications made to the BSP and will retain its relatively small size. See this section for more details.

Framework Packages

VisualGDB uses Embedded Framework Packages to store shared code that is compatible with several different BSPs. E.g. the Fast Semihosting/Profiler package supports most popular device families. Similarly, Test Framework Packages are used to run unit tests directly on the embedded devices. Embedded Framework Packages and Test Frameworks are installed to %LOCALAPPDATA%\VisualGDB\EmbeddedEFPs and TestFrameworks directories respectively and can be managed via VisualGDB Package Manager similarly to BSPs.

Stand-Alone Frameworks

If you are using the Advanced CMake Project Subsystem, you can fork individual frameworks from the BSP (e.g. STM32 USB Device Library) without cloning the entire BSP, or converting it into a stand-alone project.

Cloned frameworks are be referenced by relative paths, hence each set of projects can reference its own version of the cloned framework, while using the rest of the frameworks from the original BSP. Note that if you switch to a newer version of the BSP, the cloned framework may no longer be compatible with it until you manually merge it with the newer version from the BSP.

See this tutorial for a detailed step-by-step introduction to stand-alone frameworks.

Custom BSPs

You can automatically export an in-place BSP from a stand-alone project into a regular shared BSP. This will allow other projects to reference it instead of having a separate copy in each project. The custom BSP will typically only support 1 device and will have a separate ID from the original BSP.

Creating BSPs from stand-alone projects requires VisualGDB Custom edition or higher and only works with Advanced CMake projects. See this tutorial for a detailed overview of this process.

Project Templates

Project templates can be used as an easy way to clone projects. Templates created from stand-alone projects include the copy of the in-place BSP. Templates created from regular projects  reference the original BSP, but preserve the device type, configuration, and a specific list of referenced frameworks. You can create project templates via File->Export VisualGDB Project Template (requires Custom edition or higher):You can then select the template in the VisualGDB Project Wizard to automatically create a project based on it:See our tutorial on Embedded Project Templates for more details.