ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/configuration/reference/flags.md

@@ -0,0 +1,296 @@
+# `:flags`
+
+**Configure preprocessing, compilation, and linking command line flags**
+
+Ceedling’s internal, default tool configurations execute compilation and linking
+of test and source files among a variety of other tooling needs. (See later
+`:tools` section.)
+
+These default tool configurations are a one-size-fits-all approach. If you need
+to add flags to the command line for individual tests or a release build, the
+`:flags` section allows you to easily do so.
+
+Entries in `:flags` modify the command lines for tools used at build time.
+
+## Contexts, Operations, and Matchers
+
+The basic layout of `:flags` involves the concepts of contexts and operations.
+
+General case:
+```yaml
+:flags:
+  :<context>:      # :test or :release
+    :<operation>:  # :preprocess, :compile, :assemble, or :link
+      - <flag>
+      - ...
+```
+
+Advanced matching for **_test_** build handling only:
+```yaml
+:flags:
+  :test:
+    :<operation>:  # :preprocess, :compile, :assemble, or :link
+      :<matcher>:  # Matches a subset of test executables 
+        - <flag>   # List of flags added to that subset’s build operation command line
+        - ...
+```
+
+A context is the build context you want to modify — `:test` or `:release`.
+Plugins can also hook into `:flags` with their own context.
+
+An operation is the build step you wish to modify — `:preprocess`, `:compile`,
+`:assemble`, or `:link`.
+
+* The `:preprocess` operation is only used from within the `:test` context.
+* The `:assemble` operation is only of use within the `:test` or `:release`
+  contexts if assembly support has been enabled in `:test_build` or
+  `:release_build`, respectively, and assembly files are a part of the project.
+
+You specify the flags you want to add to a build step beneath `:<context>` ↳
+`:<operation>`. In many cases this is a simple YAML list of strings that will
+become flags in a tool’s command line.
+
+**_Specifically and only in the `:test` context_** you also have the option to
+create test file matchers that apply flags to some subset of your test build.
+Note that file matchers and the simpler flags list format cannot be mixed for
+`:flags` ↳ `:test`.
+
+## `:flags` ↳ `:release` ↳ `:compile`
+
+This project configuration entry adds the items of a simple YAML list as flags
+to compilation of every C file in a release build.
+
+**Default**: `[]` (empty)
+
+## `:flags` ↳ `:release` ↳ `:link`
+
+This project configuration entry adds the items of a simple YAML list as flags
+to the link step of a release build artifact.
+
+**Default**: `[]` (empty)
+
+## `:flags` ↳ `:test` ↳ `:compile`
+
+This project configuration entry adds the specified items as flags to
+compilation of C components in a test executable’s build.
+
+Flags may be represented in a simple YAML list or with a more sophisticated
+file matcher YAML key plus flag list. Both are documented below.
+
+**Default**: `[]` (empty)
+
+## `:flags` ↳ `:test` ↳ `:preprocess`
+
+This project configuration entry adds the specified items as flags to any
+needed preprocessing of components in a test executable’s build. Preprocessing
+must be enabled for this matching to have any effect. (See `:project` ↳
+`:use_test_preprocessor`.)
+
+Preprocessing here refers to handling macros, conditional includes, etc. in
+header files that are mocked and in complex test files before runners are
+generated from them. (See more about the
+[Ceedling preprocessing](../../testing-guide/conventions.md#test-preprocessing)
+feature.)
+
+Flags may be represented in a simple YAML list or with a more sophisticated
+file matcher YAML key plus flag list. Both are documented below.
+
+!!! note "`:preprocess` flags default behavior"
+    Left unspecified, `:preprocess` flags default to behaving identically
+    to `:compile` flags. Override this behavior by adding `:test` ↳ `:preprocess`
+    flags. If you want no additional flags for preprocessing regardless of test
+    compilation flags, simply specify an empty list `[]`.
+
+**Default**: Same flags as specified for test compilation
+
+## `:flags` ↳ `:test` ↳ `:link`
+
+This project configuration entry adds the specified items as flags to the link
+step of test executables.
+
+Flags may be represented in a simple YAML list or with a more sophisticated
+file matcher YAML key plus flag list. Both are documented below.
+
+**Default**: `[]` (empty)
+
+## `:flags` ↳ `:<plugin context>`
+
+Some advanced plugins make use of build contexts as well. For instance, the
+Ceedling Gcov plugin uses a context of `:gcov`, surprisingly enough. For any
+plugins with tools that take advantage of Ceedling’s internal mechanisms, you
+can add to those tools' flags in the same manner as the built-in contexts and
+operations.
+
+## Simple `:flags` configuration
+
+A simple and common need is enforcing a particular C standard. The following
+example illustrates simple YAML lists for flags.
+
+```yaml
+:flags:
+  :release:
+    :compile:
+      # Add `-std=c99` to compilation of all C files in the release build
+      - -std=c99
+  :test:
+    :compile:
+      # Add `-std=c99` to the compilation of all C files in all test executables
+      - -std=c99
+```
+
+Given the YAML above, when test or release compilation occurs, the flag
+specifying the C standard will be in the command line for compilation of all C
+files.
+
+## Advanced `:flags` per-test matchers
+
+Ceedling treats each test executable as a mini project. As a reminder, each
+test file, together with all C sources and frameworks, becomes an individual
+test executable of the same name.
+
+_In the `:test` context only_, flags can be applied to build step operations —
+preprocessing, compilation, and linking — for only those test executables that
+match file name criteria. Matchers match on test filenames only, and the
+specified flags are added to the build step for all files that are components
+of matched test executables.
+
+In short, for instance, this means your compilation of _TestA_ can have
+different flags than compilation of _TestB_. And, in fact, those flags will be
+applied to every C file that is compiled as part those individual test
+executable builds.
+
+### `:flags` per-test matcher examples with YAML
+
+Before detailing matcher capabilities and limits, here are examples to
+illustrate the basic ideas of test file name matching.
+
+```yaml
+:flags:
+  :test:
+    :compile:
+      :*:              #  Wildcard: Add '-foo' for all files compiled for all test executables
+        - -foo         
+      :Model:          # Substring: Add '-Wall' for all files compiled for any test executable with 'Model' in its filename
+        - -Wall
+      :/M(ain|odel)/:  #     Regex: Add 🏴‍☠️ flag for all files compiled for any test executable with 'Main' or 'Model' in its filename
+        - -🏴‍☠️
+      :Comms*Model:
+        - --freak      #  Wildcard: Add your `--freak` flag for all files compiled for any test executable with zero or more
+                       #            characters between 'Comms' and 'Model'
+    :link:
+      :tests/comm/TestUsart.c:  # Substring: Add '--bar --baz' to the link step of the TestUsart executable
+        - --bar
+        - --baz
+```
+
+### Using `:flags` per-test matchers
+
+These matchers are available:
+
+1. Wildcard (`*`)
+    1. If specified in isolation, matches all tests.
+    1. If specified within a string, matches any test filename with that 
+      wildcard expansion.
+1. Substring — Matches on part of a test filename (up to all of it, including
+   full path).
+1. Regex (`/.../`) — Matches test file names against a regular expression.
+
+Notes:
+
+* Substring filename matching is case sensitive.
+* Wildcard matching is effectively a simplified form of regex. That is, 
+  multiple approaches to matching can match the same filename.
+
+Flags by matcher are cumulative. This means the flags from multiple matchers
+can be applied to all files processed by the named build operation for any
+single test executable.
+
+Referencing the example above, here are the extra compilation flags for a
+handful of test executables:
+
+* _test_Something_: `-foo`
+* _test_Main_: `-foo -🏴‍☠️`
+* _test_Model_: `-foo -Wall -🏴‍☠️`
+* _test_CommsSerialModel_: `-foo -Wall -🏴‍☠️ --freak`
+
+The simple `:flags` list format remains available for the `:test` context. Of
+course, this format is limited in that it applies flags to all C files processed
+by the named build operation for all test executables.
+
+This simple list format for the `:test` context…
+
+```yaml
+:flags:
+  :test:
+    :compile:
+      - -foo
+```
+
+…is equivalent to this matcher version:
+
+```yaml
+:flags:
+  :test:
+    :compile:
+      :*:
+        - -foo
+```
+
+### Distinguishing similar / identical filenames
+
+You may find yourself needing to distinguish test files with the same name or
+test files with names whose base naming is identical.
+
+Of course, identical test filenames have a natural distinguishing feature in
+their containing directory paths. Files of the same name can only exist in
+different directories. As such, your matching must include the path.
+
+```yaml
+:flags:
+  :test:
+    :compile:
+      # Match any test names beginning with 'test_startup' in hardware/ directory
+      :hardware/test_startup:
+        - A                 
+      # Match any test names beginning with 'test_startup' in network/ directory 
+      :network/test_startup:
+        - B
+```
+
+It’s common in C file naming to use the same base name for multiple files.
+Given the following example list, care must be given to matcher construction to
+single out test_comm_startup.c.
+
+* tests/test_comm_hw.c
+* tests/test_comm_startup.c
+* tests/test_comm_startup_timers.c
+
+```yaml
+:flags:
+  :test:
+    :compile:
+      # Full filename with extension distinguishes this file test_comm_startup_timers.c
+      :test_comm_startup.c:
+        - FOO
+```
+
+The preceding examples use substring matching, but, regular expression matching
+could also be appropriate.
+
+### YAML anchors & aliases
+
+See the short but helpful article on [YAML anchors & aliases][yaml-anchors-aliases]
+to understand these features of YAML.
+
+Particularly in testing complex projects, per-test file matching may only get
+you so far in meeting your build step flag needs. For instance, you may need to
+set various flags for operations across many test files, but no convenient name
+matching scheme works. Advanced YAML features can help you copy the same flags
+into multiple `:flags` test file matchers.
+
+Please see the discussion in [`:defines`][defines] for a complete example.
+
+[yaml-anchors-aliases]: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
+[defines]: defines.md
+
+<br/><br/>

data/docs/mkdocs/configuration/reference/index.md

@@ -0,0 +1,168 @@
+# Configuration Reference
+
+All top-level keys of the Ceedling project configuration file, each on its own page.
+
+## Project & Build Structure
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant: **[`:project` — Global Project Settings][ref-project]**
+
+    ---
+
+    Build root, default tasks, parallelism, test preprocessor, release build
+    toggle, crash backtrace, and more.
+
+-   :material-book-open-variant: **[`:mixins` — Mixins][ref-mixins]**
+
+    ---
+
+    Load and merge additional YAML configuration files into your base project
+    configuration for flexible, composable builds.
+
+-   :material-book-open-variant: **[`:test_build` — Test Build Settings][ref-test-build]**
+
+    ---
+
+    Assembly file support for test suite builds.
+
+-   :material-book-open-variant: **[`:release_build` — Release Build Settings][ref-release-build]**
+
+    ---
+
+    Output artifact name, assembly support, and additional artifact file copying.
+
+-   :material-book-open-variant: **[`:environment` — Environment Variables][ref-environment]**
+
+    ---
+
+    Define shell environment variables that are set before tools are invoked,
+    with support for inline Ruby string expansion.
+
+</div>
+
+## Files, Paths & Extensions
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant: **[`:paths` — Search Paths][ref-paths]**
+
+    ---
+
+    Directory path lists for source, tests, headers, support files, and libraries.
+    Supports globs, subtractive entries, and inline Ruby string expansion.
+
+-   :material-book-open-variant: **[`:files` — File Collections][ref-files]**
+
+    ---
+
+    Fine-grained tailoring of the file collections assembled from `:paths` —
+    add or subtract individual files with globs and subtractive entries.
+
+-   :material-book-open-variant: **[`:extension` — File Extensions][ref-extension]**
+
+    ---
+
+    Override the default filename extensions for source, header, object, assembly,
+    executable, and other file types.
+
+</div>
+
+## Compilation & Linking
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant: **[`:defines` — Compilation Symbols][ref-defines]**
+
+    ---
+
+    Add `-D` symbols to compiler command lines for release builds, all tests, or
+    individual test executables matched by name, substring, or regex.
+
+-   :material-book-open-variant: **[`:flags` — Compilation & Link Flags][ref-flags]**
+
+    ---
+
+    Add flags to preprocessor, compiler, assembler, and linker command lines for
+    release builds, all tests, or individual test executables via matchers.
+
+-   :material-book-open-variant: **[`:libraries` — Libraries][ref-libraries]**
+
+    ---
+
+    Specify test, release, and system libraries to include at link time, with
+    configurable flag formats and library search paths.
+
+</div>
+
+## Frameworks
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant: **[`:unity` — Unity][ref-unity]**
+
+    ---
+
+    Compile-time symbol definitions to configure Unity's behavior, plus
+    parameterized test case support.
+
+-   :material-book-open-variant: **[`:cmock` — CMock][ref-cmock]**
+
+    ---
+
+    CMock code generation options, strict ordering, Unity helper paths, and
+    compile-time symbol definitions.
+
+-   :material-book-open-variant: **[`:cexception` — CException][ref-cexception]**
+
+    ---
+
+    Compile-time symbol definitions to configure CException's behavior.
+
+-   :material-book-open-variant: **[`:test_runner` — Test Runner Generation][ref-test-runner]**
+
+    ---
+
+    Options passed to Unity's test runner generation script, including additional
+    header includes.
+
+</div>
+
+## Tools & Extensions
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant: **[`:tools` — Command Line Tools][ref-tools]**
+
+    ---
+
+    Full tool definitions for every build step: compiler, assembler, linker, and
+    test fixture. Includes shortcuts for modifying built-in tools.
+
+-   :material-book-open-variant: **[`:plugins` — Ceedling Extensions][ref-plugins]**
+
+    ---
+
+    Enable built-in and custom plugins, and specify additional plugin load paths.
+
+</div>
+
+[ref-project]:       project.md
+[ref-mixins]:        mixins.md
+[ref-test-build]:    test-build.md
+[ref-release-build]: release-build.md
+[ref-paths]:         paths.md
+[ref-files]:         files.md
+[ref-environment]:   environment.md
+[ref-extension]:     extension.md
+[ref-defines]:       defines.md
+[ref-libraries]:     libraries.md
+[ref-flags]:         flags.md
+[ref-cexception]:    cexception.md
+[ref-cmock]:         cmock.md
+[ref-unity]:         unity.md
+[ref-test-runner]:   test-runner.md
+[ref-tools]:         tools.md
+[ref-plugins]:       plugins.md
+
+<br/><br/>

data/docs/mkdocs/configuration/reference/libraries.md

@@ -0,0 +1,82 @@
+# `:libraries`
+
+**Pull in specific libraries for release and test builds**
+
+## `:libraries` example YAML
+
+```yaml
+:paths:
+  :libraries:
+    - proj/libs     # Linker library search paths
+
+:libraries:
+  :test:
+    - test/commsstub.lib  # Imagined communication library that logs to console without traffic
+  :release:
+    - release/comms.lib   # Imagined production communication library
+  :system:
+    - math          # Add system math library to test & release builds 
+  :flag: -Lib=${1}  # This linker does not follow the gcc convention
+```
+
+## `:libraries` ↳ `:test`
+
+Libraries that should be injected into your test builds when linking occurs.
+
+These can be specified as naked library names or with relative paths if search
+paths are specified with `:paths` ↳ `:libraries`. Otherwise, absolute paths
+may be used here.
+
+These library files **must** exist when tests build.
+
+**Default**: `[]` (empty)
+
+## `:libraries` ↳ `:release`
+
+Libraries that should be injected into your release build when linking occurs.
+
+These can be specified as naked library names or with relative paths if search
+paths are specified with `:paths` ↳ `:libraries`. Otherwise, absolute paths
+may be used here.
+
+These library files **must** exist when the release build occurs **unless** you
+are using the [`dependencies`](../../plugins/dependencies.md) plugin. In that case, the plugin will attempt to
+build the needed library for you as a dependency.
+
+**Default**: `[]` (empty)
+
+## `:libraries` ↳ `:system`
+
+Libraries listed here will be injected into releases and tests.
+
+These libraries are assumed to be findable by the configured linker tool, should
+need no path help, and can be specified by common linker shorthand for libraries.
+
+For example, specifying `m` will include the math library per the GCC
+convention. The file itself on a Unix-like system will be `libm` and the `gcc`
+command line argument will be `-lm`.
+
+**Default**: `[]` (empty)
+
+## `:flag`
+
+Command line argument format for specifying a library.
+
+**Default**: `-l${1}` (GCC format)
+
+## `:path_flag`
+
+Command line argument format for adding a library search path.
+
+Library search paths may be added to your project with `:paths` ↳ `:libraries`.
+
+**Default**: `-L "${1}"` (GCC format)
+
+## `:libraries` notes
+
+* If you've specified your own link step, you are going to want to add `${4}` to
+  your argument list in the position where library files should be added to the
+  command line. For `gcc`, this is often at the very end. Other tools may vary.
+  See the `:tools` section for more.
+
+<br/><br/>

data/docs/mkdocs/configuration/reference/mixins.md

@@ -0,0 +1,24 @@
+# `:mixins`
+
+**Configuring your project by merging more configuration**
+
+Mixins allow you to merge configuration with your project configuration
+just after the base project file is loaded.
+
+This project configuration section is documented extensively 
+in the [discussion of project files and mixins][mixins-config-section].
+
+## Notes
+
+* A `:mixins` section is only recognized within a base project configuration 
+  file. Any `:mixins` sections within mixin files are ignored.
+* A `:mixins` section in a Ceedling configuration is entirely filtered out of
+  the resulting configuration. That is, it is unavailable for use by plugins
+  and will not be present in any output from `ceedling dumpconfig`.
+* A `:mixins` section supports [inline Ruby string expansion][inline-ruby-string-expansion].
+  See the full documetation on Mixins for details.
+
+[mixins-config-section]: ../mixins.md
+[inline-ruby-string-expansion]: ../project-file.md#inline-ruby-string-expansion
+
+<br/><br/>