Introduction

The adaptabuild project is a result of almost 40 years of embedded systems development - it's not at all perfect, but is adaptable to many development models. Let's start with what adaptabuild is not.

• It's not for building embedded Linux distributions - use Yocto for that.

• It's not for building cross platform applications that have to run on Windows, MacOS, and Linux - use CMake for that.

• It's not for building an embedded system for an incredibly wide variety of taget processors - use Zephyr for that.

• It's not for building an embedded system that can run Python - use MicroPython for that.

By now you are thinking what IS adaptabuild good for?

It is a development model that encourages truly modular code by providing an easy to set up environment that supports:

• Test Driven Development (TDD)

• Continuous Integration using your favorite CI tools (example uses GitHub actions)

• Useful documentation that is stored and versioned with the code (Sphinx)

• A makefile-based build system that lets you ignore the ugliest parts of make

• A set of "guiding star" principles that may simplify your ways of working

The adaptabuild model is suited to projects where you are building one or more products with some level of commonality, where there are variants of the the same product with configurable features, and where there may be more than one target MCU for the same product.

You can use adaptabuild to quickly get a new product variant or POC up and running without diving too far into the complexities of make, and where you can take advantage of automation to avoid error-prone manual steps.

[!NOTE] This is not the documentation for adaptabuild - it's an overview. For the actual docs look here when we have an action that build the docs :-)

Prerequisites

Using adaptabuild in your daily work has very few requirements - they are more like strong recommendations.

Container system compatible with Podman/Docker

Modern embedded systems developers are a diverse group that use Linux, Windows, and MacOS machines. This can lead to situations where things work for one developer and not another, so we encourage teams to move to a containerized Linux environment compatible with Podman/Docker.

Podman can read Docker config files, so we will use Docker filenames to reduce duplicating instructions for each environment.

No matter which host machine you develop on, the container environment is the same making it easier to coordinate changes to the standard environment.

For most of the projects that would use adaptabuild, the gcc compiler will support your target devices. If you are using IAR, the latest versions support running under Linux.

The adapatabuild-example project has a Dockerfile that works out of the box for `gcc-arm`` based development - it can be modified as needed for other target devices. It also installs all of the tools that support documentation and off target testing.

Visual Studio Code

Say what you will, VSCode is a hell of a good development environment, and this is coming from a guy that insisted on using vi up until very recently.

Once another developer showed me that it was possible to debug a micro that was attached to a J-Link debuuger running on a container image I was sold, and the great integration with Podman/Docker just put icing on the cake.

If you would rather not use a Microsoft supplied product, there is a truly open source build of the MIT-Licensed VSCode source called VSCodium.

For vi die-hards there's an almost-but-not-quite Vim simulator called VSCodeVim, but if you are the only developer on the team using it, then be prepared for some finger trouble when helping other developers, or when they help you.

Sphinx

The Dockerfile template installs a ReST based documentation system called Sphinx. So far it's the most useful way I know of for documenting an embedded system. It supports a number of plugins like:

• PlantUML - sequence diagrams, state diagrams
• Graphviz - tree structures, state diagrams
• Hawkmoth - documenting C code

The nice benefit of storing docs (and tests and ...) in the same repository as code is that when you check out a version, you get the tests and docs as they were when that version was tagged.

make

The build system for adaptabuild is based on make. The good news is that we have hidden all of the ugly bits of makefiles in a folder that you should almost never have to touch. Your submodules are just a list of files that make up a library - and adaptabuild manages creating and updating their dependencies based on standard rules. You can easily customize module specific compiler flags and #defines in one place for that module.

The adaptabuild system also supports building docs, running tests, and creating code coverage metrics.

Python

There was a time when I wrote all my automated processes as bash scripts using some of the excellent reference material availabe in the Bash Guide. The time has come to move on from bending my brain and yours around subtle shell quoting requirements and bizarre ways of handling basic things like lists.

Use Python for even your simplest scripts - you will benefit from thinking of your Python scripts as building blocks. Take advantage of the ability to write them to be run standalone or as an object in a larger context.

Yes, it might seem like overkill for the first few scripts, but once you get the hang of it, you will wonder why we stuck with bash for so long. Get into the habit of refactoring your scripts when it makes sense.

Next Steps

Check out the docs (when they are available add a link) and the adaptabuild-example that you can use to get started. It builds a progject for a common STM32 board and can be modified as needed.