In the world of firearms, “lock and load” means that you ensure the gun’s safety is locked before you load ammunition into the gun. This is not a domain in which you want unexpected behavior.
Our world is focused on software libraries, but the metaphor applies. In software development, surprises are usually not welcome. Locking your ModusToolbox library may be exactly what you want to do to avoid a surprise. That’s what we’re going to talk about here. It is another axis of freedom provided to you by the ModusToolbox design.
Back in the day, libraries locked up their books – they were way too valuable and hard to replace. So chains were the order of the day. We’ve moved on from medieval times, so why lock a software library?
Hereford Cathedral Chained Library
ModusToolbox software comes with a tool called the Library Manager you use to add, remove, or update libraries. I talked about that here. How this works behind the scenes can lead to a surprise. Avoiding the surprise is trivially easy.
First, some background on how it works.
The ModusToolbox project creation system uses .lib or .mtb files to identify what libraries (and what version of each) to get for an application. Here’s a snippet from a .lib file that loads the CapSense library into an application. I highlighted a key part of that information.
The bold text highlights a tag on the GitHub repo that points to the most recent release. Our libraries (and there are a lot of them) update independently and asynchronously. This is a genuinely Good Thing, because we can get bug fixes and improvements to you without having to wait for a massive SDK release.
Every time we release a new version of a library, we repoint the “latest” tag to – you guessed it – the latest release. So today latest-v2.x points to release v2.10.0. Next time we update the library it will point to the newer (and different!) release. That could be a problem for you.
This tag is hiding inside a text file that you may never open, because all of this “just works.” Hence the chance for a surprise.
The “latest” tag works great for us. Why? Because our engineers do not have to change anything when a library has a minor release. An example application or a BSP might use a bunch of libraries. By using the “latest” tag for any library, we set it up so that you always get the latest and greatest when you create an application. Which is way cool. Most of the time this strategy works flawlessly. But “most of the time” is not “always.”
The latest tag may not work so great for your application. Why? If you update the libraries in your application, and there is a new release, you get new code. It’s not a major release, but it is still new code. In my experience, developers do not want libraries changing unexpectedly. That is a certifiable Bad Thing.
Avoiding the problem is trivial. The choice is in the Library Manager. For the libraries you care about, simply click the version, and pick the one you want. You are now locked to a specific version of the library, not a tag with a moveable destination. Every current release of every library is available.
When you click Update, the library manager gets the code, but it also updates the tag in the local copy of the .lib or .mtb file in the application to reflect your choice. You don’t have to edit the file directly, and the tag is always correct.
If you are cool with using the latest, have fun! If you want to lock your library, nail it down! The choice is yours, the implementation is simple. Use it as you want to, not as we tell you to.
We may change the default behavior here to automagically lock on the specific “latest” release when you create an application. Although the BSP or example says latest-v2.X when you create the application the .lib or .mtb files automatically update to point to the actual latest release at that moment.
That would minimize the chance of a surprise. You can always use the Library Manager to change versions explicitly, in which case there are no surprises.
What do you think?