Manifests: Project Sanity in the Ever-Changing Zephyr World

If you take one thing away from this [talk], it should be this: Manifest files are a great way to manage revision control in your Zephyr applications.

Mike Szczys is my teammate in the Developer Relations group and the primary firmware engineer creating Golioth Reference Designs. We build on top of the Golioth Zephyr SDK to create showcase examples of how you can use Golioth firmware and cloud capabilities to create real-world applications quickly.

To keep everything straight, we rely heavily on Zephyr manifest files to ensure we are always building the correct code each time. We include things like the Zephyr codebase, the Golioth Zephyr SDK codebase, the Nordic Connect SDK codebase, and any custom code we write, all of which might be at different points in their lifecycles. It’s not a stretch to say that it’d be nearly impossible to manage all the code we use on a daily basis without manifest files. Mike used the knowledge he has built to give the above talk at the Zephyr Developer Summit 2023, which was part of the larger Embedded Open Source Summit in Prague in June of this year.

What is a manifest?

Zephyr utilizes a manifest file, which is part of the west meta-tool. These are a tough topic at first because they have multiple levels of inheritance possible. If you’re using a vendor-provided manifest file (or using one of the vendor SDK tools that hides the complexity), you likely will have an easy time following along their path. But once you want to start customizing your own project, you need to dig in and learn how they work.

Mike points out that at their core, manifest files manage hierarchy and provide a revision-controlled record of what should be included in a project. You can directly call out which version of a piece of code you want to include. As the subsystems you utilize in your project continue to upgrade over time, you can choose to lock to the older version. More importantly, you can make a concerted effort to change the version and then test the upgrade has not broken your build or introduced unknown behaviors in your program.

Structuring your Zephyr application

While we normally avoid being overly prescriptive on this blog, we have a few opinions about how to find success with Zephyr applications. Some of this comes from seeing Zephyr projects go wrong in the past. Some examples of this are:

• Cloning the Zephyr tree and putting it into your project repository
• Placing your code among Zephyr samples
• Having a standalone application repository (good) that references the Zephyr tree somewhere else on your machine (bad, because you don’t have a guarantee that the tree isn’t being used by some other Zephyr repo)

The Right Way™ (at least how we see it!) is to put a manifest file in your application and then specifically call out the versions of all dependencies. Asgeir Stavik Hustad guest-wrote about this method on the Golioth blog last year and we have taken those ideas and extended them even further (and changed a few things). The downside is that you will have many independent copies of the Zephyr tree on your hard drive…but hard drive space is cheap and making mistakes in a repo is very expensive. 

Examples and more!

I could continue to summarize the talk here, but it’s best to go and watch Mike’s examples as part of the talk. If you’re not a video person, feel free to scroll through the slides, embedded below. We love talking about Zephyr and would love to hear about your challenges and successes using manifests over on our forum.

https://www.youtube.com/watch?v=PVhu5rg_SGY