Update debugger tutorial for Arduino IDE >=2.0.3 #709
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Older versions of the "SEGGER J-Link GDB Server" were only available in a 32-bit package for Windows. For this reason, the path to the server in the tutorial's example debug_custom.json used the `C:\Program Files (x86)` path where the 32-bit package is installed by default on a 64-bit Windows machine. A 64-bit Windows package has been available starting with the 7.50 release (made on 2021-07-01). This package is installed under `C:\Program Files` by default (as is the 32-bit package on 32-bit Windows machines). Most users will have the file at this path. The tutorial will be most friendly to the reader if it uses the most common path in the example so it is hereby updated to that path.
…ion file of IDE 2.x debugger tutorial Installation of the "SEGGER J-Link GDB Server" software is required in order to use a J-Link debug proble with the Arduino IDE integrated sketch debugger. This installation includes two variants of the "J-Link GDB Server" tool, each executable with a different filename: - GUI: `JLinkGDBServer.exe` (Windows) / `JLinkGDBServerExe` (Linux/macOS) - Command Line: `JLinkGDBServerCL.exe` (Windows) / `JLinkGDBServer` (Linux/macOS) The user must specify the path to the tool executable in the debug_custom.json configuration file. The Arduino IDE 2.x debugger tutorial includes a sample debug_custom.json file. Previously this example used the filename of the GUI variant. Although technically inappropriate for this application, this variant worked fine with the previous version of the debugger extension (0.3.10) used by Arduino IDE 2.0.2 and older, and also offered the advantage of having the same filename as Linux and macOS users will need (confusingly, `JLinkGDBServer` is the filename of the GUI variant on Windows, and of the command line variant on the other operating systems). I found that the newer version of the debugger extension (1.5.1) used by Arduino IDE 2.0.3 fails on startup when the GUI variant is used, while the command line variant works fine. For this reason, the filename used in the example debug_custom.json file must now be updated to use the command line variant. This should not impact anyone who is following the tutorial while using an Arduino IDE version 2.0.2 or older because the command line variant works fine with those versions as well.
…er J-Link tutorial Installation of the "SEGGER J-Link GDB Server" software is required in order to use a J-Link debug probe with the Arduino IDE integrated sketch debugger. The user must specify the path to the command line version of the "J-Link GDB Server" tool executable in their debug_custom.json configuration files. The Arduino IDE 2.x debugger tutorial includes a sample debug_custom.json file. This example shows the filename of the tool on Windows, which would likely be sufficient documentation for the readers using that operating system. However, this will not be terribly helpful for the readers using other operating systems, for the following reasons: This installation includes two variants of the "J-Link GDB Server" tool, each executable with a different filename: - GUI: `JLinkGDBServer.exe` (Windows) / `JLinkGDBServerExe` (Linux/macOS) - Command Line: `JLinkGDBServerCL.exe` (Windows) / `JLinkGDBServer` (Linux/macOS) Confusingly, `JLinkGDBServer` is the filename of the GUI variant on Windows, and of the command line variant on the other operating systems Although technically inappropriate for this application, either variant worked fine with the previous version of the debugger extension (0.3.10) used by Arduino IDE 2.0.2 and older. However, I found that the newer version of the debugger extension (1.5.1) used by Arduino IDE 2.0.3 fails on startup when the GUI variant is used (tested on Windows), while the command line variant works fine. For this reason, it is now especially important to clearly document the filename to be used in the configuration file for each operating system.
…gger tutorial The screenshots included with the tutorial show breakpoints were placed at lines 33 and 35, yet the text is written as though the second breakpoint is at line 36. Since it is easier to update the text, and since line 35 is a more logical place for the breakpoint, the text is corrected.
…w behavior The version of the "Cortex-Debug" VS Code extension that provides the integrated sketch debugger for Arduino IDE 2.x was updated for the Arduino IDE 2.0.3 release. This update resulted in some changes in the behavior of the debugger. One of these changes is in how the debugger behaves when it is started: When started, the version of the debugger (0.3.10) used by Arduino IDE 2.0.2 and older would pause at some point at the start of the program (e.g., the `Reset_Handler` function in the cortex_handlers.c file of the "Arduino SAMD Boards (32-bits ARM Cortex-M0+)" platform). When started, the version of the debugger (1.5.1) used by Arduino IDE 2.0.3 and newer simply runs the sketch program, only automatically pausing if it reaches a breakpoint set by the user. The Arduino IDE 2.x debugger tutorial was written based on the previous behavior, and that information is not applicable to Arduino IDE 2.0.3 and newer. So the outdated information is hereby updated to be correct for the current IDE versions. This task was a bit challenging due to the tutorial being vague and inconsistent about the clicking of the "Start Debugging" button. It is not clear exactly when (or if!!!) the user will click this button: If they click it before adding the breakpoints, execution will pause at whichever breakpoint the execution reaches first. That will most likely be line 33, since there is only a 1 s time window when line 35 would be the next breakpoint, but it is not guaranteed. If they click it after adding the breakpoints, execution will pause at the first breakpoint at line 33.
per1234
added
bug
karlsoderby
approved these changes
Dec 7, 2022
There was a problem hiding this comment.
Hi @per1234 , thank you for updating the tutorial. Looks great!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What This PR Changes
The version of the "Cortex-Debug" VS Code extension that provides the integrated sketch debugger for Arduino IDE 2.x was updated for the Arduino IDE 2.0.3 release (arduino/arduino-ide#1706).
This significant update caused some changes in the way the debugger works. Some of the tutorial content, which was written for the older debugger version used by Arduino IDE 2.0.2 and older is no longer correct.
Updates are provided here for that outdated content. See the individual commit messages for details.
References:
[email protected]arduino-ide#1706 (review)Contribution Guidelines