Debugging and development with Visual Studio Code

[philj404]

It would be nice to use a debugger while adding features and running my tests. Debuggers provide much faster feedback than editing/examining Serial.print(...) statements with every run. As a bonus, development under Linux can skip the "download sketch" step, which can take a while for large sketches.

https://github.com/philj404/EpoxyDebuggerDemo

So... this TEMPLATE/EXAMPLE library supports a Visual Studio Code workspace which can build and debug the library and its tests. To use this capability you must have the following installed:

• Only tested on a Linux computer!
• Visual Studio Code
  • C/C++ (Microsoft Extension)
  • C/C++ Extension Pack (Microsoft Extension)
  • C/C++ Extension Themes (Microsoft Extension)
  • Makefile Tools (Microsoft Extension)

At the top level of this library, I enter the command: code EpoxyDebuggerDemo.code-workspace to run VS Code. Specifying the code-workspace file helps give VS Code a base path from which to search for useful files and libraries.

Interesting magic is in:

• EpoxyDebuggerDemo.code-workspace
• .vscode/c_cpp_properties.json
• .vscode/launch.json
• .vscode/settings.json
• (not needed? .vscode/tasks.json)

It is important to do a ("clean" and) "debug" build before using the debugger.

I have been able to clean, build, set breakpoints in a regression test, examine variables, step, and continue.

I have set up the VS Code settings to support "Debug" and "Release" configurations. Usually I use the "Debug" configuration... but "Release" will behave differently and it's also worth testing. The GitHub regression test uses the "Release" build.

Under "Makefile Tools" tab:

• set "Configuration" to "Debug"
• set "Build target" to "configuredBuild"

Warnings:

• Only tested on a Linux system (may not work under Windows or MacOS).
• Right now the code must be supported for at least FOUR different platforms. Any changes need to be confirmed to STILL WORK for all these platforms:
  • Arduino IDE 1.0 (for users)
  • Arduino IDE 2.0 (for users)
  • Linux environment Makefile (for developers and GitHub integration tests)
  • Visual Studio Code (for local developer debugging)
• The VS code build controls and settings are a bit quirky. Probably could be cleaner (someday)
• The VS code formatter uses clang-format rather than "Arduino 1.0" or "Arduino 2.0" formatters. This auto-format mismatch could cause merge conflicts (for example it can keep generating trivial whitespace changes) if ALL developers are not consistent in which formatter they use.
• Note that VS code C++ Intellisense does NOT use the Makefiles to determine what the include paths and build-time #defines are. That needs to be coordinated (Makefiles and .vscode/c_cpp_properties.json). That should be OK for this example, but if the Makefile gets more complicated, c_cpp_properties.json (or the other .json files) may need to get more complicated too.

References

• Using C++ on Linux in VS Code https://code.visualstudio.com/docs/cpp/config-linux
• Makefiles in vscode https://earthly.dev/blog/vscode-make/
• Makefile support in vscode https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/
• The repository containing the template is at: https://github.com/philj404/EpoxyDebuggerDemo . (Remember that you really want to copy the files rather than cloning the repository -- your own library requirements are more interesting than my repository example will support).

[bxparks]

Thanks for the interesting and useful post for people wanting to use VS Code debugger. Here are my initial comment and suggestions:

1. Suggest removing the link to the uploaded ZIP file, which seems outdated already. Instead, link directly to the git repo instead.
2. Clarify that these instructions are for VS Code on Linux only (or has only been tested on Linux only).
3. Add example snippets and explanations of what these various configuration files are for. I have a passing familiarity with VS Code, but I don't know what any of these config files do, and what their configs means.
4. The part about, "copy this zip file, but be careful that you don't overwrite important files, like README.md" seems a bit clunky and dangerous. I think the problem is that you are trying to do 2 things at the same time with EpoxyDebuggerDemo: a) Contains the README.md file that describes how to create a compatible repo, b) Contains the various example config files and sample Arduino application with some of these config files. Maybe there is a better way to organize these so that 2 parts are separated more cleanly, to avoid the "make sure you don't overwrite important files."

Thanks for the post, hope it is helpful to someone.

[philj404]

I made some edits as you suggested.

Some of the VS Code changes I made are still "black magic" to me (especially for the .json files), but I will do what I can to clarify.

I agree my "template library" example is still a bit clunky, as it's not simply a template OR a library. For example it has library.properties and README.md files which aren't directly appropriate to consumers... but are still useful to understand or test the template as a library. Maybe I'll rename these files which need adjustments to help show this...

Thanks for the feedback. I appreciate the new perspective.