Ceedling Documentation

Ceedling configuration is managed via a YAML file containing top-level keys that control different aspects of the build and test process. The configuration is organized into several functional areas:

Project & Build Structure

• :project: Global settings including build root, default tasks, parallelism, and release build toggles.
• :mixins: Allows loading and merging additional YAML configuration files for composable builds.
• :test_build: Settings specific to test suite builds, such as assembly file support.
• :release_build: Settings for production/release artifacts, including output names and file copying.
• :environment: Defines shell environment variables (supports inline Ruby string expansion) set before tools are invoked.

Files, Paths & Extensions

• :paths: Defines directory search paths for source, tests, headers, support files, and libraries. Supports globs and subtractive entries.
• :files: Provides fine-grained control to add or subtract specific files from the collections assembled by :paths.
• :extension: Allows overriding default filename extensions for source, header, object, assembly, and executable files.

Compilation & Linking

• :defines: Adds -D symbols to compiler command lines. Can be applied globally, to all tests, or to specific test executables using name, substring, or regex matchers.
• :flags: Adds flags to the preprocessor, compiler, assembler, or linker. Supports global, all-test, or matcher-based application.
• :libraries: Configures test, release, and system libraries for linking, including search paths and flag formats.

Frameworks

• :unity: Configures Unity behavior via compile-time symbols and parameterized test case support.
• :cmock: Configures CMock code generation, strict ordering, and Unity helper paths.
• :cexception: Configures CException behavior via compile-time symbols.
• :test_runner: Options for Unity's test runner generation script, such as additional header includes.

Tools & Extensions

• :tools: Full definitions for build step tools (compiler, assembler, linker, test fixture).
• :plugins: Enables built-in or custom plugins and specifies plugin load paths.

Ceedling supports glob patterns to specify directory patterns without listing every path individually. Globs in :paths match directories, not files.

Glob Operators:

• *: Standard wildcard. /* matches all subdirectories of depth 1 below the parent.
• **: Matches all subdirectories recursively (e.g., /**).
• ?: Matches a single alphanumeric character.
• [x-y]: Matches a character within a specified range.
• {x, y, ...}: Matches any of the comma-separated patterns.

Special Convention: If a globified path ends with /* or /**, the resulting list of directories also includes the parent directory.

Subtractive Entries: To exclude specific directories from a collection generated by a glob, use the -: prefix. While +: can be used for visual alignment, only -: performs subtraction.

Note: Subtraction occurs after all Mixins are merged.

:paths:
  :source:
    - +:project/src/**    # Recursive glob
    - -:project/src/exp   # Exclude experimental code

  :include:
    - +:project/src/**/inc
    - -:project/src/exp/inc

You do not need to enable preprocessing just because your files contain #ifdef statements. You only need it if those statements affect how Ceedling discovers the structure of your tests.

Use test file preprocessing if:

• #include statements are generated by macros.
• #include statements are conditionally present due to #ifdef statements.
• Test case function signatures are generated by macros.
• Test case function signatures are conditionally present due to #ifdef statements.

Do NOT use test file preprocessing if:

• Conditional directives are used inside the test case functions (e.g., choosing which assertion to run). The standard C preprocessor in your toolchain handles this during the build phase without Ceedling needing to 'see' the expanded version for discovery.

// NOT NEEDED: The toolchain handles this during compilation
void test_some_test_case(void) {
#ifdef BUILD_VARIANT_A
   TEST_ASSERT_EQUALS(...);
#endif
}

In the :test and :preprocess contexts, you can define C symbols that apply only to specific test executables based on their filenames. This allows you to test the same source file under different conditional compilation configurations (e.g., enabling different features) by using different test files.

Key behaviors:

• Scope: Matchers apply to the test filename. When a match occurs, the specified symbols are added to the build step for all C files that are components of that matched test executable.
• Cumulative Symbols: Symbols from multiple matchers are cumulative. If a test filename matches multiple matchers, all symbols from those matchers are applied.
• Contexts: This advanced matching is only available in :test and :preprocess contexts. In other contexts like :release, :defines applies to all builds.

# Example: Testing Comms.c with different feature sets
:defines:
  :test:
    :CommsFeatureX:
      - FEATURE_X=ON
      - FEATURE_Z=OFF
    :CommsFeatureZ:
      - FEATURE_X=OFF
      - FEATURE_Z=ON

The Module Generator uses the :paths: defined in your project.yml. You can influence where files are placed using two methods:

1. Directory Hints (Colon Syntax)

Use a colon (:) to provide a hint. The generator will attempt to match this hint against your existing :paths: configuration.

• ceedling module:create[lab:SecretLair] will attempt to place files in the lab/ subdirectory of your source/include/test paths.
• Multiple hints can be used for nested structures: lab:secret:lair.

2. Explicit Subdirectories (Slash Syntax)

Use a slash (/) to force a specific subdirectory. If the subdirectory does not exist, the generator will create it.

• ceedling module:create[newlab/SecretLair] will create src/newlab/SecretLair.c, inc/newlab/SecretLair.h, and test/newlab/TestSecretLair.c.

3. Default Configuration

You can override the default generation paths in project.yml using the :module_generator: key.

:module_generator:
  :path_src: src/
  :path_inc: src/
  :path_tst: test/