throwtheswitch/madsciencelab-arm-none-eabi repository overview

⁠Mad Science Lab C Unit Testing & Build System Docker Image

C unit testing & release build environment with Unity⁠, CMock⁠, and Ceedling⁠. This image is a self-contained environment for running unit test suites and release builds with Ceedling.

This image will run natively without internal emulation on most AMD64 and ARM64 systems, including Apple M-series hardware.

Find the source Dockerfile, assets, and documentation in the project Github repository⁠.

The Changelog is documented in the project’s Github Releases⁠. This image’s version tracks Ceedling’s version. Alphabetical characters trailing the numeric version string indicate a Docker image revision with no changes to Ceedling or its supporting frameworks.

🙏🏻 Please consider supporting this work as a Github Sponsor⁠

⁠Contents

This image contains Ceedling, Unity, CMock, the GCC toolchain arm-none-eabi-gcc, and essential Linux utilities & C libraries.

When launched in terminal mode — (A) below — a welcome message lists the components installed in the container. Standard command line conventions will provide version numbers, etc. for the various components.

Note: This is a specialty image intended for cross-compilation builds. If you need to run your build on one host platform with ARM binaries targeted for another platform, this image is for you. Keep in mind that such builds tend to require a variety of additional settings in your Ceedling project configuration. Perhaps most importantly, depending on your runtime environment, test builds may fail without some sort of emulator configured for the test fixture executable. See the section on derivative Docker images for more on your options.

⁠Usage

⁠A. Launch a terminal ready to run Ceedling

docker run -it --rm -v <local project path>:/home/dev/project throwtheswitch/madsciencelab-arm-none-eabi[:tag]

⁠B. Run Ceedling as a self-contained utility for your project

docker run --rm -v <local project path>:/home/dev/project throwtheswitch/madsciencelab-arm-none-eabi[:tag] <Ceedling command line>

⁠Security Considerations

⁠Overview

• This image is built on minideb⁠, a minimal, well-patched Debian base image.
• As a best practice, the default user within this container (username dev) has non-root privileges.
• As much as is practical, this image contains as few packages, libraries, and executables as possible. Other variations of this image available in the same Docker Hub ThrowTheSwitch repository⁠ contain additional tools or variations of tools. Choose the right image for you. The larger madsciencelab-* images are generally more useful but also increase the “threat surface” in your usage.

Please see the source repository security policy⁠.

⁠Working with the non-root dev user

A container user lacking root privileges has a couple consequences:

1. No software installation inside the running container.
2. Possible complications for host system file ownership and permissions of any generated files.

⁠User privilege & ownership options

1. Run the container with root privileges… docker run -u root .... Of course, this removes any protections of a default non-root user. Use with care. Any changes within the container such as software installation will not be permanent.
2. Use Docker and host system features to ensure the dev user is part of the same permissions group as your host system user. This is generally the easiest and most secure options for managing ownership & permissions issues files generated within the container but ending up on your host filesystem. Eventually, we’ll provide additional resources to help you automate this option.
3. Create derivative Docker images of your own (next section) and control user permissions and software installation per your needs.

⁠Derivative Docker image options

It’s entirely possible that you will want to install or change something within the available madsciencelab image. Some changes may make sense for all users and should be incorporated via feature request. Other changes will be specific to your project and team. You have two options for derivative Docker images.

1. Create a new Dockerfile of your own, referencing this Docker image as its base (Dockerfile FROM). Within your Dockerfile you may change back to the root user, install software & make other changes, and revert to the dev user for its security provisions.
2. Download the source Dockerfile⁠, change user handling and/or package installations, and build your own derivative image from the modified Dockerfile.

⁠Intro to Unit Testing Supported by the MadScienceLab containers

• The “stock” Docker images maintained by this repository use Ceedling to build “native” code as described here⁠. For additional help and tips for building native tests, read this⁠.
• Advanced users of Ceedling also have the option of creating cross-compiled ARM test executable binaries with the arm-none-eabi Docker image variants. These binaries could be native tests on a target platform, or you could run them with a simulator test fixture on a host system. Read more about the simulator option here⁠ and how to work with it here⁠.

⁠License(s)

• The base image, minideb⁠, for the MadScienceLab variants is Apache 2.0⁠ licensed.
• The ThrowTheSwitch work layered on top of minideb is MIT⁠ licensed (the license file is maintained in the root of this repository).