Skip to content

:files

Tailoring file collections

Ceedling relies on file collections to do its work. These file collections are automagically assembled from paths, matching globs / wildcards, and file extensions. See project configuration :extension.

Entries in :files accomplish filepath-oriented tailoring of the bulk file collections created from :paths directory listings and filename pattern matching.

On occasion you may need to remove from or add individual files to Ceedling’s file collections.

The path grammar documented in the :paths configuration section largely applies to :files path entries — albeit with regard to filepaths and not directory paths. The :files grammar and YAML examples are documented below.

Example :files YAML

Simple tailoring

:paths:
  # All <dirs>/*.<source extension> => test/release compilation input
  :source:
    - src/**

:files:
  :source:
    - +:callbacks/serial_comm.c  # Add source code outside src/
    - -:src/board/atm134.c       # Remove board code

Advanced tailoring

:paths:
  # All <dirs>/<test prefix>*.<source extension> => test compilation input + test suite executables
  :test:
     - test/**

:files:
  :test:
    # Remove every test file anywhere beneath test/ whose name ends with 'Model'. 
    # String replacement inserts a global constant that is the file extension for 
    # a C file. This is an anchor for the end of the filename and automaticlly 
    # uses file extension settings.
    - "-:test/**/*Model#{EXTENSION_SOURCE}"

    # Remove test files at depth 1 beneath test/ with 'analog' anywhere in their names.
    - -:test/*{A,a}nalog*

    # Remove test files at depth 1 beneath test/ that are of an "F series"
    # test collection FAxxxx, FBxxxx, and FCxxxx where 'x' is any character.
    - -:test/F[A-C]????

:files ↳ :test

Modify the collection of unit test C files.

Default: [] (empty)

:files ↳ :source

Modify the collection of all source files used in unit test builds and release builds.

Default: [] (empty)

:files ↳ :assembly

Modify the (optional) collection of assembly files used in release builds.

Default: [] (empty)

:files ↳ :include

Modify the collection of all source header files used in unit test builds (e.g. for mocking) and release builds.

Default: [] (empty)

:files ↳ :support

Modify the collection of supporting C files available to unit tests builds.

Default: [] (empty)

:files ↳ :libraries

Add a collection of library paths to be included when linking.

Default: [] (empty)

:files options & notes

  1. A path can be absolute (fully qualified) or relative.
  2. A path can include a glob matcher (more on this below).
  3. A path can use inline Ruby string expansion.
  4. Subtractive paths prepended with a -: decorator are possible and useful. See the documentation below.

:files Globs

Globs are effectively fancy wildcards. They are not as capable as full regular expressions but are easier to use. Various OSs and programming languages implement them differently.

For a quick overview, see this tutorial.

Ceedling supports globs so you can specify patterns of files as well as simple, ordinary filepaths.

Ceedling :files globs operate identically to Ruby globs except that they ignore directory paths. Only filepaths are recognized.

Glob operators include the following: *, **, ?, [-], {,}.

  • *
    • When used within a character string, * is simply a standard wildcard.
    • When used after a path separator, /* matches all subdirectories of depth 1 below the parent path, not including the parent path.
  • **: All subdirectories recursively discovered below the parent path, not including the parent path. This pattern only makes sense after a path separator /**.
  • ?: Single alphanumeric character wildcard.
  • [x-y]: Single alphanumeric character as found in the specified range.
  • {x, y, ...}: Matching any of the comma-separated patterns. Two or more patterns may be listed within the brackets. Patterns may be specific character sequences or other glob operators.

Subtractive :files entries

Tailoring a file collection includes adding to it but also subtracting from it.

Put simply, with an optional preceding decorator -:, you can instruct Ceedling to remove certain file paths from a collection after it builds that collection.

By default, paths are additive. For pretty alignment in your YAML, you may also use +:, but strictly speaking, it’s not necessary.

Subtractive paths may be simple paths or globs just like any other path entry.

Quote the whole entry, decoration included

YAML keeps quote marks that begin partway through a value as part of the value. Quoting only the path leaves quote marks in the path, and Ceedling rejects the entry. Quote an entry whenever it holds #{…} inline Ruby string expansion, because YAML otherwise reads the # as the start of a comment.

# Correct
- "-:#{ENV['SRC_ROOT']}/platform/uptime.c"

# Incorrect -- the quote marks become part of the path
- -:"#{ENV['SRC_ROOT']}/platform/uptime.c"

See the example section.