Skip to content

Ceedling Packet

Ceedling is a fancypants build system that greatly simplifies building C projects. While it can certainly build release targets, it shines at running unit test suites.

New to Ceedling?


Jump straight to the Quick Start — installation, project set up, and your first build tasks all in one place.

In essence, Ceedling is a project configuration in YAML and a command line tool that executes from it. Code conventions and supporting features produce executable test suites and/or release artifacts. Plugins provide reporting, code coverage, static analysis, and more.

Ceedling and its suite of frameworks, including Unity and CMock, were developed for use on platforms from heavy duty workstations to teeny tiny microcontrollers. Features handy for low-level development have made these tools popular with embedded systems developers.

New goodness

Ceedling 1.2.0 adds the most requested features and improvements

👀 See the Changelog.

Ceedling 1.2.0 includes:

  • Delta builds have been restored so that file regeneration and build actions only occur because of changed files or configuration.
  • #include relative paths & duplicate filename disambiguation. Ceedling now fully supports relative paths everywhere and offers options to distinguish files of the same name.
  • Multiple file extensions per file type. You may now provide a list of file types (e.g. .c and .cc) via :extension to gather files into your project’s build.
  • Shuffled test order. Ceedling now supports Unity’s randomized test case ordering (via a :unity configuration setting). Delta builds automatically adjust to always rerun test executables so test case ordering is shuffled.
  • The TEST_SOURCE_FILE() build directive macro can now be used to remove source files from a test executable build. This can be handy in overriding Ceedling’s conventions for associating source files with a test executable if your project structure does not match up with Ceedling’s conventions.
  • The new Sanitize plugin builds and runs tests with ASan, UBSan, and LeakSanitizer, naming each finding where a test fails and writing text, JSON, and SARIF reports.
  • The build warnings, JUnit report, IDE integration, GoogleTest report, module generator, and dependencies plugins all received numerous bug fixes and feature expansions.
  • Bullseye code coverage plugin re-enabled and modernized (disabled since 1.0.0).
  • Dedicated mocks and test runner generation build tasks. You may now run the test build pipeline only up through generating mocks or test runners with no compilation or test runs.
  • Ceedling prerelease and release builds now automatically generate Software Bills of Material (SBOMs) and attach them to GitHub pre/releases along with the final Ruby gem.

And, the headlining feature of Ceedling 1.1.0 was Partials. A Partial is your C code sliced and diced to expose functional elements for testing that you could not otherwise access without rewriting your source code. Think of Partials as a scalpel for testing your code.

Overview

  • A Build System for C

    Generate a complete test and release build from a single YAML file. Provides a minimal sample project configuration and an explanation of Ceedling’s design philosophy.

  • Tools & Frameworks

    Ruby, Rake, YAML, Unity, and CMock explained — the pieces that make Ceedling possible and how they fit together.

  • Test Environments

    Native host builds, emulator-based runs, and on-target execution — choose the right test suite strategy for your project.

Getting Started

Unit Testing

  • How Does a Test Case Even Work?

    A brief overview of what a test case is with simple examples illustrating how test cases work.

  • Commented Sample Test File

    A sample test file illustrating test case creation and the conventions that make it work. Includes a discussion of how test executables get built.

  • Anatomy of a Test Suite

    How a unit test grows up to become a test suite.

  • Using Unity and CMock

    Ceedling links together Unity and CMock — each of which can require configuration of their own. Ceedling facilitates this.

  • Important Conventions & Behaviors

    Much of testing in Ceedling is accomplished by convention. Code and files structured and named in certain ways trigger sophisticated build features.

  • Partials

    Partials are like a scalpel for your source code. A generated partial allows you to test and mock parts of your code you could not otherwise access without rewriting it first.

Project Configuration

  • How to Load a Project Configuration

    You have options, my friend. Load your base configuration via command line flag, environment variable, or default file. Add Mixins to merge configuration for different build scenarios.

  • The Mighty Project Configuration File

    Everything you need to know about the project configuration file. All in glorious YAML.

  • Project Configuration Reference

    Exhaustive documentation for all project configuration options — project paths, testing features, plugins, and much more.

  • Parallel Builds

    Configure Ceedling to take advantage of multiple CPU cores for faster build steps and test suite execution.

  • Which Ceedling?

    Sometimes you may need to point to a different Ceedling to run.

Advanced & Extending

  • Build Directive Macros

    Code macros to accomplish build goals when Ceedling's conventions aren't quite enough.

  • Ceedling Plugins

    Ceedling is extensible with built-in plugins for code coverage, test reporting, CI integration, file scaffolding, sophisticated release builds, and more.

  • Global Collections

    Globally available Ruby lists of paths, files, and more — useful for advanced project customization and plugin development.