safdariali/ceedling repository overview

⁠🧪 Ceedling Docker for C Unit Testing

Lightweight Docker image providing Ceedling for C unit testing and Test-Driven Development (TDD) on Alpine Linux.

⁠✨ Features

• 🔬 C Unit Testing with Ceedling, Unity, CMock, and CException
• 🏗️ Native C Toolchain: GCC, Make, binutils, musl-dev
• 🐳 Lightweight Base: Alpine Linux
• ⚡ CI/CD Ready: Designed for GitHub Actions and other CI/CD systems
• 📦 Reproducible Builds: Explicit version pinning for Ceedling, Ruby, and Alpine

⁠🚀 Quick Start

⁠Pull the image

docker pull safdariali/ceedling:latest

⁠Check Ceedling version

docker run --rm safdariali/ceedling:latest ceedling --version

⁠Run a Ceedling project

From the root directory of a Ceedling project:

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling test:all

⁠📖 Usage Examples

⁠1. Run all unit tests

Mount the project directory to /workspace:

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling test:all

This runs the complete Ceedling test suite.

⁠2. Run a specific test

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling test:test_blink

Replace test_blink with the name of the desired test target.

⁠3. Run tests with verbose output

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling test:all VERBOSE=1

⁠4. Generate a new Ceedling project

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling new my_project

This creates a new Ceedling project in the mounted workspace.

⁠5. Interactive shell

For debugging or inspecting the container environment:

docker run --rm -it \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  /bin/sh

⁠6. Check installed components

docker run --rm safdariali/ceedling:latest ceedling --version

The output includes the installed Ceedling version and its bundled testing frameworks.

⁠🏷️ Version Tags

Each image is published with both a latest tag and a complete version tag.

⁠Example

safdariali/ceedling:1.1.2-ruby-4.0.6-alpine-3.24

represents:

Ceedling = 1.1.2 Ruby = 4.0.6 Alpine = 3.24

Using the complete version tag is recommended when reproducibility is important.

The latest tag is intended for users who want the current published image without explicitly selecting component versions.

⁠🔧 GitHub Actions Integration

The image can be used directly as a container in GitHub Actions.

⁠Basic unit-test workflow

name: C Unit Tests

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest

    container:
      image: safdariali/ceedling:latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Show Ceedling version
        run: ceedling --version

      - name: Run unit tests
        run: ceedling test:all

⁠Using a fixed version

For reproducible CI builds, use a complete image tag:

container:
  image: safdariali/ceedling:1.1.2-ruby-4.0.6-alpine-3.24

This prevents a future latest update from changing the test environment unexpectedly.

⁠🏗️ Building from Source

⁠Prerequisites

• Docker
• Git (optional)

⁠Clone the repository

git clone https://github.com/SafdariAli/ceedling-docker.git
cd ceedling-docker

⁠Build using Docker directly

docker build \
  --build-arg CEEDLING_VERSION=1.1.2 \
  --build-arg RUBY_VERSION=4.0.6 \
  --build-arg ALPINE_VERSION=3.24 \
  -t safdariali/ceedling:custom \
  .

⁠Verify the image

docker run --rm \
  safdariali/ceedling:custom \
  ceedling --version

⁠🖥️ Local Build Scripts

The repository provides scripts for building the image locally.

⁠Windows PowerShell

.\build-ceedling-local.ps1

Custom versions can be specified:

.\build-ceedling-local.ps1 `
  -CeedlingVersion "1.1.2" `
  -RubyVersion "4.0.6" `
  -AlpineVersion "3.24"

⁠Linux / macOS

chmod +x build-ceedling-local.sh
./build-ceedling-local.sh

Custom versions:

./build-ceedling-local.sh \
  --CeedlingVersion "1.1.2" \
  --RubyVersion "4.0.6" \
  --AlpineVersion "3.24"

The local build scripts:

1. Check that Docker is available.
2. Validate the Dockerfile.
3. Build the image.
4. Apply the versioned image tag.
5. Apply the latest tag.
6. Run a basic Ceedling version test.

⁠🔄 Version Management

The project is designed to keep upstream component versions configurable rather than hard-coded into the Dockerfile.

The main components are:

Ceedling
Ruby
Alpine Linux

Ceedling is distributed as a RubyGem and currently requires Ruby 3.0 or newer.

The Docker image uses the official Ruby Docker image as its base, allowing Ruby and Alpine combinations to be selected through the image tag. The official Ruby image publishes Alpine-based tags such as 4.0.6-alpine3.24.

The project includes automation infrastructure for detecting newer upstream versions and updating the build configuration.

The goal is to make updating the image reproducible while keeping the repository itself minimal.

⁠🧪 Testing

The image performs a basic installation test during the Docker build:

RUN ceedling --version

A successful image build therefore verifies that Ceedling can be installed and executed inside the container.

After building the image locally, an additional test can be performed:

docker run --rm safdariali/ceedling:latest ceedling --version

For actual projects, the recommended validation is to mount the project and execute:

docker run --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  safdariali/ceedling:latest \
  ceedling test:all```

## 📦 Docker Image

The published image is available from Docker Hub:

```text
safdariali/ceedling

Pull the latest version:

docker pull safdariali/ceedling:latest

Pull a specific version:

docker pull safdariali/ceedling:1.1.2-ruby-4.0.6-alpine-3.24

⁠📄 License

This repository contains Docker packaging and automation for Ceedling.

⁠Packaging

The Dockerfile, build scripts, documentation, and other original files in this repository are licensed under the MIT License.

⁠Included software

The Docker image contains third-party software distributed under their respective licenses, including:

• Ceedling — MIT License
• Ruby — Ruby License / BSD-style terms
• Alpine Linux — various licenses depending on included packages
• GCC — GNU General Public License and related licenses
• binutils — GNU General Public License and related licenses
• musl — MIT License and related licenses
• Unity, CMock, and CException — their respective upstream licenses

The MIT license in this repository applies to the original packaging and automation provided by this project. It does not replace or modify the licenses of the software included in the Docker image.

See the LICENSE file and the respective upstream projects for complete license terms.

⁠🤝 Support

• Maintainer: Mohammad Ali Safdari
• Email: m.ali.safdari [at] gmail [dot] com
• GitHub: SafdariAli
• Docker Hub: safdariali
• Issues: Feature requests, bug reports, and suggestions are welcome through GitHub Issues.

⁠🌟 Show Your Support

If you find this image useful:

• ⭐ Star the GitHub repository
• 🐳 Pull the Docker image
• 📢 Share it with your team

Happy Testing with Ceedling! 🌱