Ceedling

Ceedling 1.1.8 is the latest and greatest.

See [Release Notes][release-notes], Changelog, [Breaking Changes][breaking-changes], and [Known Issues][known-issues].

See 🚀 Getting Started for installation and new project set up.

New goodies in 1.1.x:

• A Partial allows a test to mix mocked and real functions from the same source module in a single test file and enables testing of static and inline functions without modifying source code.
• Ceedling is now complemented by a full, searchable documentation site available both online and as a local bundle exported from Ceedling’s command line.
• A new Discourse community forum to supersede the old, spammy Google Group and handful of disparate support channels.
• More and expanded example projects.
• New stock plugins for Valgrind memory checking and Cppcheck static analysis.
• The GCov plugin:
  • Now supports coverage reports for all sources.
  • Adds support for Modified Condition / Decision Coverage.
• Mixins improvements including an option for inline YAML at the command line.
• Ceedling’s test preprocessing is once again compatible with Unity’s parameterized test cases (support was temporarily removed with 1.0.0).
• Incorporates the latest updates to CMock and Unity.

🌱 Ceedling is a handy-dandy build system for C projects

Developer-friendly release and test builds

Ceedling can build your release artifact but is especially adept at building unit test suites for your C projects — even in tricky embedded systems.

⭐️ Eager to just get going? Jump to 📚 Documentation & Learning and 🚀 Getting Started.

For a test suite project using the default toolchain gcc, Ceedling’s configuration file could be as simple as this:

:project:
  :build_root: project/build/

:paths:
  :test:
    - tests/**
  :source:
    - source/**
  :include:
    - inc/**

To execute all your unit tests, you would run ceedling test:all. That‘s it!

Ceedling works the way developers want to work. It is flexible and entirely command-line driven. It drives code generation and command line tools for you. All generated and framework code is easy to see and understand.

Ceedling’s features support all types of C development from low-level embedded to enterprise systems. No tool is perfect, but Ceedling can do a whole lot to help you and your team produce quality software.

Supporting this work

Ceedling and its 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

Ceedling is a suite of tools

Ceedling is also a suite of tools. It is the glue for bringing together two other awesome open-source projects you can’t live without if you‘re creating awesomeness in the C language.

1. Unity, an xUnit-style test framework.
2. CMock^†, a code generating, function mocking & stubbing kit for interaction-based testing.

If you are a Visual Studio Code user, you may also be interested in the Ceedling extension.

^† Through a plugin, Ceedling also supports FFF for fake functions as an alternative to CMock’s mocks and stubs.

But, wait. There’s more.

For simple project structures, Ceedling can build and test an entire project from just a few lines in its project configuration file.

Because it handles all the nitty-gritty of rebuilds and because of Unity and CMock, Ceedling makes Test-Driven Development in C a breeze. It even provides handy backtrace debugging options for finding the source of crashing code exercised by your unit tests.

Ceedling is extensible with a simple plugin mechanism. It comes with a number of [built-in plugins][ceedling-docs-plugins] for code coverage, test suite report generation, Continuous Integration features, IDE integration, release library builds & dependency management, and more.

📦 Releases

Ceedling release numbering follows SemVer convention. See the Getting Started section for installation details for both official releases and prereleases.

Official releases

Releases have a version number #.#.# (..). Production systems and automated tooling should rely on official releases and not prereleases.

Official releases are available as:

1. A prepackaged Ruby Gem available through the public RubyGems repository (installable with gem install ceedling --no-document at the command line).
2. Ready-to-run Docker images.

The latest . version is supported with limited support for earlier minor releases.

Bug fix patches .. are official releases. Generally speaking, if you have adopted a . release, you should update to bug fix releases when available.

All official releases are retained historically.

In rare cases of fatal flaws, severe security vulnerabilities, etc. an official release may be pulled.

Prereleases

Prerelease versions include pre in their version numbering (#.#.#-pre.#). Prereleases are only available as downloadable .gem files attached to release listings. These require local installation steps including some basic dependencies management.

Prereleases are ephemeral and will be pulled as development continues or bugs are found. Prereleases should not be relied upon in production systems or automated tooling. At an official release, all prior prereleases will be pulled.

Prereleases are not officially supported, but feedback through submitting issues is very much welcome. As much help as is practical will be offered to support those exercising prereleases.

🙋‍♀️ Need Help? Want to Help?

• Found a bug or want to suggest a feature? Submit an issue at this repo.
• Trying to understand features or solve a testing problem? Hit the Discourse forums.
• Paid training, customizations, and support contracts are available through Ceedling Assist.

The ThrowTheSwitch community follows a code of conduct.

Please familiarize yourself with our guidelines for contributing to this project, be it code, reviews, documentation, or reports.

Yes, work has begun on Ceedling Certified, a validated version of Ceedling to meet the needs of industry software certification.

🧑‍🍳 Sample Unit Testing Code

While Ceedling can build your release artifact, its claim to fame is building and running