🧪 Mad Science Lab C Unit Testing & Build Environment Docker Images

Self-contained C unit testing & release build environment with Ceedling, Unity, CMock and supporting tools.

Overview & contents

The Docker images produced from this repository contain everything needed for running unit tests and release builds with Ceedling and its supporting frameworks.

This repository contains custom tooling, templates, and the assets necessary to produce multiple variations of the MadScienceLab Docker images targeting different toolchains and containing various collections of supporting tools. A Github Action builds the images and publishes them to Docker Hub.

• Docker Hub MadScienceLab images.
• See this repository’s releases for the versioned Dockerfiles produced by the Github Action builds.

The basic idea of this repository is to generate Dockerfiles rather than only maintain the text of one or more Dockerfiles. A custom Ruby-based command line tool uses a template and conventions for directories and files to build up Dockerfiles. This approach has a couple benefits:

1. In this way, common base elements can be easily maintained across multiple Dockerfiles.
2. Entirely new — potentially proprietary — Dockerfiles can be generated as extensions of the MadScienceLab images with elements maintained outside of this repository.

Supporting this work

These Docker images and complementary ThrowTheSwitch pieces and parts are and always will be freely available and open source.

💼 Ceedling Suite is a growing collection of paid products and services built around Ceedling to help you do even more. Ceedling Assist for support contracts and training is now available.

🙏🏻 Please consider supporting Ceedling as a Github Sponsor

🏭 Usage

January, 2025: More complete documentation on working with the contents of this repository is forthcoming. This repository underwent significant changes in step with the 1.0.0 release of Ceedling.

Generating Dockerfiles

To generate the four Dockerfiles and related artifacts managed by this project from a local clone of this repository, install all Ruby dependencies using the Gemfile in the root of the project and execute the build shell script also in the root of the repository:

Examples:

• ./build.sh --dir build/standard --variant "" --version <tag>
• ./build.sh --dir build/standard --dir build/plugins --version <tag>
• ./build.sh --dir build/arm-none-eabi --version 1.0.0
• ./build.sh --dir build/arm-none-eabi --dir build/plugins --dir build/arm-none-eabi-plugins --version <tag>

The Github Actions maintained in this repository use the same approach as the preceding to generate the Dockerfiles attached to workflow runs and releases:

• Any push or pull request generates the four Dockerfile/asset variants and validates each generated Dockerfile with hadolint (static lint) and docker buildx build --check (structural validation) — no Docker image is actually built, and the generated artifacts are attached to the workflow run.
• Pushing a pre-release tag (see Versioning, below) does all of the above, plus a real multi-platform Docker image build for each variant (not pushed to Docker Hub), plus a GitHub pre-release with the generated artifacts attached and release notes drawn from docs/Changelog.md.
• Pushing a release tag does all of the above, plus pushes the built images to Docker Hub, plus a full GitHub release.

Ruby tool & shell script

The Ruby tool maintained in this repository does all of the Dockerfile text generation.

The shell script that calls the Ruby tool includes many options useful to a developer working on this repostory or anyone working to extend the Dockerfiles created by the tooling. Run ./build.sh -h for a listing of the various options.

🔢 Versioning

Versioning of this repository and the resulting tags in Docker Hub track Ceedling’s version. Docker image changes are maintained with a lowercase letter suffix appended to the version of Ceedling contained in each MadScienceLab image itself.

Git tags drive the Github Actions release workflows and follow this pattern:

• v1.1.2 — a full release tracking Ceedling 1.1.2 with no image-only changes.
• v1.1.2a — a full release with an image-only revision (lowercase letter suffix) on top of Ceedling 1.1.2.
• v1.1.2a-pre.1 — a pre-release of the above; the -pre.N suffix always comes last. Pushing a tag like this builds real multi-platform images (without pushing to Docker Hub) and publishes a GitHub pre-release for testing before the corresponding non-suffixed tag is pushed.

Tags without a -pre.N suffix trigger a full release, including a push to Docker Hub. Only tags matching this v-prefixed pattern trigger release/pre-release Github Actions; all other pushes and pull requests only generate and validate the Dockerfiles (see Usage, above).

🔒 Security

Security documentation is maintained in the Docker Hub image repositories.

👩‍🏫 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).