Diagnosing Build Errors for Arduino Projects

This tutorial shows how to diagnose build errors for Arduino-based projects built with VisualGDB, if you are also using Arduino IDE. Normally, VisualGDB will automatically manage the necessary Arduino packages and setup the underlying tools, so you won’t need to install the Arduino IDE to build Arduino-based projects. However if you are using both Arduino IDE and VisualGDB, some combinations of settings may prevent VisualGDB from building the projects same way the Arduino IDE does.

In this tutorial we will show how to collect the detailed build log from the Arduino IDE, extract the relevant library and core arguments and how to configure VisualGDB to match the results produced by the Arduino IDE.

Before you begin, install VisualGDB 5.5 or later and create a VisualGDB Project for the sketch file that otherwise works when built with the Arduino IDE.

  1. Launch Arduino IDE and enable verbose mode via File->Preferences:
  2. Build your sketch and locate the “arduino-builder -compile” line in the Arduino IDE log:The Arduino IDE uses the command-line arduino-builder tool to perform the actual build. The arduino-builder tool accepts a list of library and core directories and various build parameters and launches the underlying tools, such as gcc. VisualGDB also uses the arduino-builder tool to build Arduino-based projects, however depending on your Arduino and VisualGDB settings, it may pass a different set of library/core directories, causing different build results. In the next steps we will show how to compare the relevant parameters and how to adjust VisualGDB settings to control them.
  3. Try building the VisualGDB-based project. Whether it succeeds or fails, locate the arduino-builder command line in the VisualGDB Build window, right-click on it and select “Dump Command Line to Batch File”:
  4. This will create a .bat file with the exact command line (and environment) used by VisualGDB to launch arduino-builder:
  5. Create a list of the following parameters used by both VisualGDB and Arduino IDE (if you are using Notepad++, replace ” -“ with “\n -“ to make the command line more readable):
    • -hardware
    • -tools
    • -libraries
    • -prefs=

    Here is an example of typical values used by VisualGDB:

    Parameter Value
    -hardware C:\Program Files (x86)\Sysprogs\VisualGDB\Arduino/hardware
    -tools C:\Program Files (x86)\Sysprogs\VisualGDB\Arduino/tools-builder
    -libraries C:\Users\virtual.SYSPROGS\Documents/Arduino/Libraries
    -prefs= C:\Users\virtual.SYSPROGS\Documents/Arduino/Libraries
  6. In order to replicate the build results from Arduino IDE with VisualGDB, the -hardware, -tools, -libraries and -prefs values must be as close as possible to the values used by Arduino IDE. Make a copy of the original .bat file and edit it, replacing VisualGDB’s values for -hardware, -tools, -libraries and -prefs with the ones captured from the Arduino IDE. You can add the “pause” command at the end of the .bat file to keep the command line window open after it finishes running.
  7. Find a combination of flags copied from the Arduino IDE’s log that gets the project to build successfully when running the .bat file and make a table of them.
  8. Open Tools->VisualGDB->Arduino Settings window in Visual Studio and replace the Hardware Directories, Tool Directories and Library Directories with the values that resulted in a correct build:
  9. Alternatively, you can check the “Ignore default library directories” flag on the Arduino Project page of  VisualGDB Project Properties and enter the library directories there if you want to limit the changes to one specific project:
  10. Try building the project from VisualGDB. It should now produce the same results as the edited .bat file did. If not, dump the build command line into another .bat file and compare them to see what could be causing the difference.