If you’re a firmware library author, please read on as the information below may be relevant to you.
Over the last few months, we’ve been doing some internal, behind the scenes work to clean up and improve the Particle firmware libraries ecosystem and experience. One of the initial steps has been to perform an inventory of the almost 1,000 public libraries and run some tests to make sure that the include/installation experience is smooth across Particle development environments.
One thing we found is that a number of community contributed libraries, though functional, fail to compile when installed via the Particle Build Web IDE. This post walks through the reason why some libraries fail to compile, and what library authors can do to resolve this issue.
Why some libraries fail to compile in the Web IDE
NOTE: The issues described below occur only in the Particle Web IDE and not when installing libraries with Workbench or the CLI.
When a library is installed in the Web IDE, Particle automatically places a #include statement at the top of your main firmware source file. This include statement is based on the name of your library as defined in your project.properties file and is not determined based on the header files in your library src directory.
For the large majority of libraries tracked by our system, the library name and header are the same, thus is not an issue. For instance, the neopixel library is named neopixel in our system, and the main header is neopixel.h.
It’s not uncommon, however, for engineers to give libraries a name that differs from the main header. In these cases, when such a library is installed in the Web IDE the auto-included header will cause the user’s project to fail to compile.
In the above case, inspecting the project source reveals that the expected include should be Adafruit_MAX31865.h
How to resolve the issue in your libraries
While there are a number of things the Particle team has discussed internally as options for resolving these issues, many of those solutions create new edge-cases that become hard to resolve. For instance, we could base the auto-include on a header file found in src, but if a library has more than one header in its src directory, which is the correct one to include?
And while we may pursue options for addressing this, in product, in the future, I wanted to create this post as a guide for library authors and maintainers who may run into this issue. Either of the fixes below will resolve this compiler error for folks who use your libraries.
1. Add a dummy header that matches your library name
This is the simplest fix, and is the least disruptive to your library source, which can be especially useful if you’ve ported a library from a place like Adafruit or Sparkfun and want to keep these up-to-date, over-time.
To perform this fix, simply add a new file with the name <libraryName>.h to your library src directory, ensuring that the name matches your library name exactly. For instance, using the example above, we’d create a new file named Adafruit_MAX31865_library.h
Then, in the body of your new header, simply add a single #include to pull in the main dependency for your library. Again using the example above, our Adafruit_MAX31865_library.h would contain the following:
#include "Adafruit_MAX31865.h"
Finally, bump the version on your library and re-publish. That’s it!
2. Rename your main header to match the library name
Alternatively, you can rename your main header file to match the library name. In the example above, you’d simply rename the Adafruit_MAX31865.h and .cpp files (as well as the header reference in the .cpp) to Adafruit_MAX31865_library.h and Adafruit_MAX31865_library.cpp.
This change may be a bit more involved as you’ll want to modify example projects as well to reference this new include, and it can be more disruptive if you’re maintaining a library port from a 3rd party.
If you’re a library author, hopefully this post helps you make sure you’re providing the smoothest installation and usage experience for your fellow Particle devs!
Finally, if you run across a library where you experience this issue. The quick fix as a library user is to replace the auto-include header with the correct header for the installed library. In addition, please consider posting an issue on the GitHub repo for the library in question and reference this post for a quick-fix.