Marc Dougherty

⚒ ⚙ ⛵

Vim and Arduino

16 January 2018

TL;DR - I made a vim compiler plugin for arduino that parses errors into the quickfix list, and learned a bunch about the quickfix list and compiler plugins.

I’ve been working on several small arduino projects lately (mostly the series of bluetooth projects posted earlier). While I find the arduino toolchain easy to use, I’ve never enjoyed using the editor, or having to use the mouse to click the Verify and Upload buttons.

Existing vim-arduino integration

A bit of googling brought to my attention that the arduino tool can also be used as a commandline tool as of version 1.15, and has a man page. Much of the desired vim integration exists already, in the github/stevearc/vim-arduino plugin, but the one thing I was still missing was the quickfix list of errors.

A small discussion of vim variables

This sent me down the rabbithole of reading vim’s help about quickfix, and several other related topics (setqflist, QuickfixCmdPost, errorformat, efm-entries, etc). The first lesson is one of maintainability, as there are many errorformat strings on github, but most of them are just there as one long string, with commas, like the default one in this vim session:

errorformat=%*[^"]"%f"%*\D%l: %m,"%f"%*\D%l: %m,%-G%f:%l: (Each undeclared identifier is reported only once,%-G%f:%l: for each function it appears in.),%-GIn file included from %f:%l:%c:,%-GIn file included from %f:%l:%c\,,%-GIn file included from %f:%l:%c,%-GIn file included from %f:%l,%-G%*[ ]from %f:%l:%c,%-G%*[ ]from %f:%l:,%-G%*[ ]from %f:%l\,,%-G%*[ ]from %f:%l,%f:%l:%c:%m,%f(%l):%m,%f:%l:%m,"%f"\, line %l%*\D%c%*[^ ]%m,%D%*\a[%*\d]: Entering directory%*[`']%f',%X%*\a[%*\d]: Leaving directory %*[`']%f',%D%*\a: Entering directory%*[`']%f',%X%*\a: Leaving directory %*[`']%f',%DMaking %*\a in %f,%f|%l| %m'

The first little vim trick is that the option errorformat (and all other options, actually), can be set as variables by prepending &. The following two lines do the same thing:

filetype=markdown
let &filetype=markdown

Why would we choose the second syntax? I learned from the vim help for efm-entries that there are multiple ways to change the value of long strings like errorformat. We can build them up from smaller strings by appending, by using .= instead of =. According to efm-entries, += and -= can be used to add and remove entries in errorformat.

Setting errorformat

The format of errors is tricky here because the arduino toolchain actually pre-processes the arduino sketch files into a standard C++ file before building, so the resulting error messages do not always contain a filename. Sample output:

Picked up JAVA_TOOL_OPTIONS: 
Loading configuration...
Initializing packages...
Preparing boards...
Verifying...
sketch_file:32: error: 'asdf' does not name a type
 asdf
 ^
/path/to/sketch_file.ino: In function 'void setupCandleService()':
sketch_file:59: error: 'candleService' was not declared in this scope
   candleService.begin();
   ^
exit status 1

Ignoring the “standard” output lines is easy enough with the errorformat specifier %-G, which ignores the lines that match it. (e.g. %-GInitializing packages...).

The next tricky bit was that the two errors above only show one full file path, and it is for the second error. Here I considered fetching the existing quickfix list in a QuickfixCmdPost, and “fixing” the files to be opened, but after spending some time on this solution, it occurred to me that the most likely outcome was that the error was in the current buffer.

Putting it all together

To get the right compiler options set, I created my own vim compiler plugin, for arduino. Since the existing plugin from stevearc/vim-arduino sets up make, I used that. The only real settings here are for the errorformat parsing (the top bit is all boilerplate for vim compiler plugins, and copied from the help docs). Here is the custom arduino compiler plugin, and to make it work automatically, I set the compiler in the filetype plugin for arduino.

Now when I open an arduino sketch file in vim, I can verify the build, and get decent quickfix integration as well!