throwtheswitch/madsciencelab 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, 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.

⁠Usage

⁠A. Launch a terminal ready to run Ceedling

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

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

docker run --rm -v <local project path>:/home/dev/project throwtheswitch/madsciencelab[: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 Articles Discussing Unit Testing

• This docker image uses Ceedling to build “native” code as described here⁠
• For additional help and tips for building native tests, read this⁠