Documentation > General > VisualGDB Toolchains

VisualGDB Toolchains

Toolchains are collections of tools (such as GCC, GNU Assembler or GDB) that are used to build and debug projects for a specific target. This page outlines how VisualGDB manages the toolchains for different targets.

Contents

Supported Toolchain Types
Installing Toolchains
Importing Existing Toolchains
Referencing Toolchains
Troubleshooting Toolchains
Integration with MSBuild

Supported Toolchain Types

VisualGDB supports the following types of toolchains:

  • GCC (GNU C/C++ compiler):
    • MinGW/Cygwin
    • Cross-compilers for Embedded or Linux targets
    • Native GCC running on Linux targets
    • Cross-GCC for Linux targets running on another Linux system
  • ARMCC and ARMClang (running on Windows only)
  • IAR (running on Windows only)

We provide pre-built toolchains for many popular platforms that can be downloaded here.

Installing Toolchains

VisualGDB can install many GCC-based toolchains out-of-the-box. Simply select a download link in one of the VisualGDB Project Wizards and it will automatically download and install a toolchain:If your firewall is preventing VisualGDB from downloading toolchains, you can always download and install them manually from the GNUToolchains site.

Importing Existing Toolchains

VisualGDB can automatically detect the following 3rd-party toolchains installed on your computer:

You can also import the toolchains (from both Windows or Linux machines) to VisualGDB by using the import buttons at the bottom of the Toolchain Selector:If the imported toolchain does not appear in the list, see the troubleshooting section that describes how VisualGDB stores the toolchains.

Referencing Toolchains

VisualGDB-based projects do not include a copy of a toolchain definition. Instead, they contain the following fields to uniquely identify an existing toolchain:

  • Toolchain ID
  • Toolchain version (GCC/GDB versions and a toolchain revision number)

You can find out the toolchain version used by a specific project by looking into VisualGDB Project Properties -> Build Settings (the exact page name depends on the project type) or by directly checking the VisualGDB settings file (*.vgdbsettings, *.vgdbcmake or *.vgdbproj) or the embedded profile file (e.g. stm32.xml):

  <ToolchainID>com.visualgdb.arm-eabi</ToolchainID>
  <ToolchainVersion>
    <GCC>9.3.1</GCC>
    <GDB>8.3.1</GDB>
    <Revision>1</Revision>
  </ToolchainVersion>

If you open a project that references an unknown toolchain, VisualGDB will automatically suggest downloading or locating it:If you would like to have multiple flavors of the same toolchain, try manually changing the toolchain ID in <Toolchain Directory>\Toolchain.xml file and re-importing it into VisualGDB.

Troubleshooting Toolchains

You can find a list of all toolchain known to VisualGDB via Tools->VisualGDB->Manage VisualGDB Packages->Installed->Toolchains:If the window doesn’t show the toolchain you imported, try enabling the View->Other Windows->VisualGDB Diagnostics Console before opening the VisualGDB Package Manager. It will contain a detailed diagnostic log on finding the toolchains.

How VisualGDB Locates Toolchains

VisualGDB uses the following logic to find installed toolchains:

  1. First, it checks the %LOCALAPPDATA%\VisualGDB\ToolchainProfiles\<host name> directory. Each directory there can contain one of the following:
    1. A CustomToolchain.xml file that contains location of the toolchain, and also the names/paths of various toolchain components.
    2. A ToolchainLink.txt file that contains the directory of the toolchain. The directory pointed by ToolchainLink.txt should contain either CustomToolchain.xml or Toolchain.xml. This only works for toolchains located on Windows.
  2. Then, it checks the Software\Sysprogs\GNUToolchains registry keys (both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER) for toolchains installed from GNUToolchains.
  3. Finally, it searches the registry keys specified in %VISUALGDB_DIR%\Rules\KnownToolchains.xml. This imports GNU ARM toolchain, as well as KEIL/IAR toolchains.

How VisualGDB Remembers Imported Toolchains

When you import a toolchain via the VisualGDB Project Wizard, it will try to create a Toolchain.xml or CustomToolchain.xml file in the toolchain directory, and the link to the toolchain by creating the ToolchainLink.txt file under %LOCALAPPDATA%. This preserves the toolchain settings even if you reset the VisualGDB’s %LOCALAPPDATA% directory.

If the toolchain directory is not writable, VisualGDB will create the Toolchain.xml or CustomToolchain.xml file directly under %LOCALAPPDATA%. It will have exactly the same effect as placing it to the toolchain directory and linking it with ToolchainLink.txt.

Toolchain.xml vs CustomToolchain.xml

Due to backward compatibility reasons, VisualGDB uses 2 different toolchain definition formats. The Toolchain.xml file is used for toolchains supplied by Sysprogs, while CustomToolchain.xml is used for toolchains that were imported manually. The CustomToolchain.xml-based toolchain definitions can be edited using the “Customize” button as shown below:

Integration with MSBuild

The MSBuild-based projects use a special mechanism for loading the toolchain descriptions. First of all, the project must specify the toolchain ID, version and build host in the MSBuild-level settings (it is updated automatically when using VisualGDB wizards and VisualGDB Project Properties GUI):You can use the “Rebuild MSBuild & IntelliSense files for this toolchain” link to automatically update the MSBuild-level properties based on VisualGDB-level properties: