ceedling 1.1.9 → 1.2.0

data/docs/mkdocs/plugins/index.md

@@ -1,261 +0,0 @@
-# Ceedling Plugins
-
-Ceedling includes a number of built-in plugins. Each plugin linked below
-includes full documentation of its capabilities and configuration options.
-
-!!! tip "Need a CI test build report?"
-    [Test Suite Report Log Factory](report-tests-log-factory.md) provides
-    a handful of popular reports and the ability to create your own.
-
-!!! tip "Have custom needs?"
-    Many find the handy-dandy [Command Hooks plugin](command-hooks.md)
-    is often enough as it allows you to connect your own scripts and tools 
-    to Ceedling build steps. Alternatively, you can 
-    [create your own plugins](../development/plugins/index.md).
-
-See the [`:plugins` configuration reference](../configuration/reference/plugins.md) 
-for how to enable built-in plugins and load custom plugins in your project.
-
----
-
-## Understanding plugin build duplication
-
-!!! warning
-    Build-related plugins intentionally execute duplicated builds.
-
-Plugins including [Gcov](gcov/index.md), [Bullseye](bullseye.md), and [Valgrind](valgrind.md)
-recreate test build tasks. That is, the command line build task `test:foo` also exists 
-as `gcov:foo`, `bullseye:foo`, and/or `valgrind:foo` if these plugins are enabled.
-Each of these triggers a full rebuild of the named test with instrumentation 
-activated. **This duplication is intentional and very necessary.**
-
-These plugins modify executable code or the environment in which a test suite 
-executable runs. Duplicating and segregating the build tasks addresses several 
-important issues:
-
-1. **Conflicting interactions**. Enabling multiple plugins without 
-   duplicated tasks (i.e. integrated build tasks) can bring about conflicts and
-   undefined behavior. For instance, Gcov’s instrumentation does not
-   necessarily play nice with Valgrind’s memory-instrumented emulation
-   runtime, and the two should be kept entirely segregated.
-2. **Unforeseen effects**. These plugins can directly alter the functioning of
-   the code under test. For instance, coverage instrumentation inserted into
-   your compiled code can alter its function or timing. As such, it is vital
-   to maintain distinct builds to compare them. Your vanilla test suite build
-   may function slightly differently than the coverage-instrumented build.
-3. **Optional instrumentation**. The `<plugin>:` command line task convention
-   also provides a very simple opt-in scheme. Plugins automatically enabled 
-   for every build drives the desire to optional disable them. Valgrind testing
-   can require 25-50x the execution time of a test suite, and you likely will
-   want the option to easily disable it. While Ceedling could certainly provide
-   that option at the command line for otherwise always-on plugins, this
-   plugin task namespacing scheme naturally accomplished this along with the
-   needs of (1) and (2).
-
----
-
-## Directory
-
-### Console Test Results
-
-<div class="grid cards" markdown>
-
--   :material-monitor-screenshot: **[`report_tests_pretty_stdout`](report-tests-pretty-stdout.md)**
-
-    ---
-
-    The default plugin for printing test results to the console. Produces a
-    well-formatted list of summary statistics, ignored and failed tests, and
-    any extraneous output collected from test fixtures.
-
--   :material-monitor-screenshot: **[`report_tests_ide_stdout`](report-tests-ide-stdout.md)**
-
-    ---
-
-    Formats test results for the console such that an IDE executing Ceedling
-    tasks can recognize file paths and line numbers in test failures and link
-    them for direct file navigation.
-
--   :material-monitor-screenshot: **[`report_tests_gtestlike_stdout`](report-tests-gtestlike-stdout.md)**
-
-    ---
-
-    Prints test results to the console in a format that mimics
-    [Google Test's output][gtest-sample-output] — both human readable and
-    recognized by a variety of reporting tools, IDEs, and CI servers.
-
--   :material-monitor-screenshot: **[`report_tests_teamcity_stdout`](report-tests-teamcity-stdout.md)**
-
-    ---
-
-    Processes test results into [TeamCity] service messages printed to the
-    console, allowing the CI server to extract build steps and test results
-    from software builds.
-
-</div>
-
-### Test Results Reports
-
-<div class="grid cards" markdown>
-
--   :material-file-chart: **[`report_tests_log_factory`](report-tests-log-factory.md)**
-
-    ---
-
-    Produces any or all of four useful test suite reports in JSON, JUnit XML,
-    CppUnit XML, or HTML format. Also provides a mechanism for custom reports 
-    with a small amount of Ruby rather than a full plugin.
-
--   :material-file-chart: **[`report_tests_raw_output_log`](report-tests-raw-output-log.md)**
-
-    ---
-
-    Captures extraneous console output generated by test executables —
-    typically for debugging — to log files named after the test executables.
-
--   :material-file-chart: **[`report_build_warnings_log`](report-build-warnings-log.md)**
-
-    ---
-
-    Scans the output of build tools for console warning notices and produces
-    a simple text file that collects all such warning messages.
-
-</div>
-
-### Static & Dynamic Analysis
-
-!!! tip "Ceedling includes integrated `gdb` support"
-    Tracking down weird test failures can require multiple approaches and tools. 
-    Diagnosing a bug causing a test executable crash can benefit from either or 
-    both of these plugins plus Ceedling’s 
-    [backtrace feature](../configuration/reference/project.md#use_backtrace).
-
-<div class="grid cards" markdown>
-
--   :material-file-check: **[`cppcheck`](cppcheck.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute static analysis with [Cppcheck]. Cppcheck helps
-    find bugs related to undefined behavior, dangerous code patterns, and
-    coding style. Cppcheck is even able to analyze non-standard syntax C/C++ code, 
-    as is common in embedded projects. The plugin can produce various reports.
-
--   :material-memory: **[`valgrind`](valgrind.md)**
-
-    ---
-
-    Adds Ceedling tasks to run test executables under [Valgrind] memory error
-    detection. Valgrind catches memory leaks, invalid accesses, and use-after-free
-    bugs. The plugin produces per-test log files in the build artifacts directory.
-
-</div>
-
-### Code Coverage
-
-<div class="grid cards" markdown>
-
--   :material-percent: **[`gcov`](gcov/index.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute tests with GNU code coverage
-    instrumentation. Manages use of [gcov], optional Python-based [GCovr],
-    and .Net-based [ReportGenerator] to produce coverage reports in a
-    variety of formats.
-
--   :material-percent: **[`bullseye`](bullseye.md)**
-
-    ---
-
-    Adds Ceedling tasks to execute tests with code coverage instrumentation
-    provided by the commercial [Bullseye] tool, which provides visualization
-    and report generation from the coverage results.
-
-</div>
-
-### Mocking & Test Doubles
-
-<div class="grid cards" markdown>
-
--   :material-ghost: **[`fff`](fff.md)**
-
-    ---
-
-    Replaces Ceedling’s CMock-based mock generation with the
-    [Fake Function Framework][FFF] — an alternative approach to
-    [test doubles][test-doubles] using simple fake functions.
-
-<!--Spacer so the single fff card does not stretch across multiple grid columns-->
-<div style="visibility:hidden"></div>
-
-</div>
-
-### Build Integration
-
-<div class="grid cards" markdown>
-
--   :material-script-text-play: **[`command_hooks`](command-hooks.md)**
-
-    ---
-
-    Connects Ceedling's build events to tool entries you define in your
-    project configuration. Easily attach your own scripts or command line
-    utilities to build steps without writing a full custom plugin.
-
--   :material-database: **[`compile_commands_json_db`](compile-commands-json-db.md)**
-
-    ---
-
-    Creates a [JSON Compilation Database][json-compilation-database] — a
-    `compile_commands.json` file useful to any editor or IDE that implements
-    [`clangd`][clangd] Language Server Protocol support.
-
--   :material-bell-ring: **[`beep`](beep.md)**
-
-    ---
-
-    Provides a simple audio notification when a test build completes suite
-    execution or fails due to a build error, intended to support developers
-    running time-consuming test suites locally in the background.
-
-</div>
-
-### Project & Release Builds
-
-<div class="grid cards" markdown>
-
--   :material-package-variant-closed: **[`module_generator`](module-generator.md)**
-
-    ---
-
-    Saves time in Test-Driven Development by generating a templated triplet
-    of source file, header file, and test file — scaffolded such that they
-    refer to one another — with convenient command line tasks.
-
--   :material-package-variant-closed: **[`dependencies`](dependencies.md)**
-
-    ---
-
-    Manages release build dependencies (e.g. static libraries) including 
-    fetching those dependencies and calling a given dependency‘s build 
-    process to generate the components needed by your Ceedling release 
-    build target.
-
-</div>
-
-[gtest-sample-output]: https://subscription.packtpub.com/book/programming/9781800208988/11/ch11lvl1sec31/controlling-output-with-google-test
-[TeamCity]: https://jetbrains.com/teamcity
-[Cppcheck]: https://cppcheck.sourceforge.io
-[Valgrind]: https://valgrind.org
-[gcov]: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-[GCovr]: https://www.gcovr.com/
-[ReportGenerator]: https://reportgenerator.io
-[Bullseye]: http://www.bullseye.com
-[FFF]: https://github.com/meekrosoft/fff
-[test-doubles]: https://blog.pragmatists.com/test-doubles-fakes-mocks-and-stubs-1a7491dfa3da
-[json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
-[clangd]: https://clangd.llvm.org
-[IDEs]: https://www.throwtheswitch.org/ide
-
-<br/><br/>

data/docs/mkdocs/plugins/module-generator.md

@@ -1,267 +0,0 @@
-# Module Generator
-
-This plugin adds a pair of new commands to Ceedling allowing you to generate or remove 
-module skeletons according to predefined templates.
-
-## Overview
-With a single call, Ceedling can generate a source, header, and test file for a new 
-module. If given a pattern, it can even create a series of submodules to support 
-specific design patterns. Finally, it can just as easily remove related modules, 
-avoiding the need to delete each individually.
-
-Let's say, for example, that you want to create a single module named `MadScience`.
-
-```sh
-ceedling module:create[MadScience]
-```
-
-It says we're speaking to the module plugin, and we want to create a new module. The
-name of that module is between the brackets. It will keep this case, unless you have
-specified a different default (see configuration). It will create three files:
-`MadScience.c`, `MadScience.h`, and `TestMadScience.c`. *NOTE* that it is important that
-there are no spaces between the brackets. We know, it's annoying... but it's the rules.
-
-## Patterns
-
-You can also create an entire pattern of files. To do that, just add a second argument
-to the pattern ID. Something like this:
-
-```sh
-ceedling module:create[SecretLair,mch]
-```
-
-In this example, we'd create 9 files total: 3 headers, 3 source files, and 3 test files. These
-files would be named `SecretLairModel`, `SecretLairConductor`, and `SecretLairHardware`. Isn't
-that nice?
-
-The module generator understands the following patterns:
-
-- `src` -- generate only a source file
-- `test` -- generate only a test file
-- `dh` -- generate 6 files for the driver-hardware pattern
-- `dih` -- generate 9 files for the driver-interrupt-hardware pattern
-- `mch` -- generate 9 files for the model-conductor-hardware pattern
-- `mvp` -- generate 9 files for the model-view-presenter pattern
-
-## Paths
-
-The directories found in the project `:paths:` are reused. You can also specify an alternative default generation path using: 
-
-```yaml
-:module_generator:
-  :path_src: src/
-  :path_inc: src/
-  :path_tst: test/
-```
-
-But what if I don't want it to place my new files in the default location?
-
-It can do that too! You can give it a hint as to where to find your files. The pattern matching
-here is fairly basic, but it is usually sufficient. It works perfectly if your directory structure
-matches a common pattern. For example, let's say you issue this command:
-
-```sh
-ceedling module:create[lab:SecretLair,mch]
-```
-
-Say your directory structure looks like this:
-
-```yaml
-:paths:
-  :source:
-    - lab/src
-    - lair/src
-    - other/src
-  :test:
-    - lab/test
-    - lair/test
-    - other/test
-```
-
-In this case, the `lab:` hint would make the module generator guess you want your files here:
-
-- source files: `lab/src` (because it's a close match)
-- include files: `lab/src` (because no include paths were listed)
-- test files: `lab/test` (because it's a close match)
-
-Instead, if your directory structure looks like this:
-
-```yaml
-:paths:
-  :source:
-    - src/**   #this might contain subfolders lab, lair, and other
-  :include:
-    - inc/**   #again, this might contain subfolders lab, lair, other, and shared
-  :test:
-    - test
-```
-
-In this case, the `lab:` hint would make the module generator guess you want your files here:
-
-- source files: `src/lab` (because it's a close match)
-- include files: `inc/lab` (because it's a close match)
-- test files: `test` (because there wasn't a close match, and this was the first entry on our list)
-
-You can see that more complicated structures will have files placed in the wrong place from time to
-time... no worries... you can move the file after it's created... but if your project has any kind of 
-consistent structure, the guessing engine does a good job of making it work.
-
-A few more quick notes about the path-matching:
-
-1. You can give multiple ordered hints that map roughly to folder nesting! `lab:secret:lair` will 
-   happily match to put `lair.c` in a folder like `my/lab/secret/`.
-
-2. If the matcher isn't given any path information or it finds multiple equally good candidates, 
-   it will always guess in the order you have the paths listed in your project.yml file
-
-3. If the matcher completely fails to find a good candidate, it will return an error, allowing you
-   to rectify the situation.
-
-4. What path is "first" when you're using `**` pattern in your `:paths:` specifications? The parent
-   folder is used first, then its children alphabetically, and so on. This is important when 
-   considering where files (or especially subfolders... see below) will be generated.
-
-### Adding to Paths
-
-In addition to the pattern matching above, you can add slashes (`/`) to your filename specification.
-When a slash is used instead of a colon (`:`), it will stop using pattern matching and assume the
-subdirectory is supposed to be there. If the subdir is NOT there, it will automatically add it.
-
-Let's try an example with our previous path specification:
-
-```yaml
-:paths:
-  :source:
-    - src/**   #this might contain subfolders lab, lair, and other
-  :include:
-    - inc/**   #again, this might contain subfolders lab, lair, other, and shared
-  :test:
-    - test
-```
-
-Then, use the following command:
-
-```sh
-ceedling module:create[newlab/SecretLair]
-```
-
-This will create the following 3 files:
-
-- `src/newlab/SecretLair.c`
-- `inc/newlab/SecretLair.h`
-- `test/newlab/TestSecretLair.c`
-
-Technically, you can start with a colon and specify part of a path, then use a slash
-to specify the remainder of the path to use. In most circumstances, this should work... however
-it suffers from the same potential issues as the matcher above, with the added joy of creating 
-new subdirectories for you without asking. 
-
-It's important to note the module generator doesn't care if these new subdirectories are covered 
-by the current path specification. This allows you to create the files before updating the
-`project.yml` file if desired, but it also means you might accidentally think you've created
-a file that Ceedling can see, when it can't. 
-
-## Stubbing
-
-Similarly, you can create stubs for all functions in a header file just by making a single call
-to your handy `stub` feature, like this:
-
-```sh
-ceedling module:stub[SecretLair]
-```
-
-This call will look in `SecretLair.h` and will generate a file `SecretLair.c` that contains a stub
-for each function declared in the header! Even better, if `SecretLair.c` already exists, it will
-add only new functions, leaving your existing calls alone so that it doesn't cause any problems.
-
-## Configuration
-
-Enable the plugin in your project.yml by adding `module_generator`
-to the list of enabled plugins.
-
-Then, like much of Ceedling, you can just run as-is with the defaults, or you can override those
-defaults for your own needs. For example, new source and header files will be automatically
-placed in the `src/` folder while tests will go in the `test/` folder. That's great if your project
-follows the default ceedling structure... but what if you have a different structure?
-
-```yaml
-:module_generator:
-  :naming: :bumpy
-  :includes: 
-    - :src: []
-    - :inc: []
-    - :tst: []
-  :boilerplates:
-    - :src: ""
-    - :inc: ""
-    - :tst: ""
-```
-
-Now I've redirected the location where modules are going to be generated.
-
-### Includes
-
-You can make it so that all of your files are generated with a standard include list. This is done
-by adding to the `:includes` array. For example:
-
-```yaml
-:module_generator:
-  :includes:
-    :tst:
-      - defs.h
-      - board.h
-    :src:
-      - board.h
-```
-
-### Boilerplates
-
-You can specify the actual boilerplate used for each of your files. This is the handy place to
-put that corporate copyright notice (or maybe a copyleft notice, if that's your preference?)
-
-Notice there is a separate template for source files, include files, and test files. Also, 
-your boilerplates can optionally contain `%1$s` which will inject the filename into that spot.
-
-```yaml
-:module_generator:
-  :boilerplates: 
-    :src: |
-      /***************************
-      * %1$s
-      * This file is Awesome.
-      * That is All.
-      ***************************/
-    :inc: |
-      /***************************
-      * Header. Woo.             *
-      ***************************/
-    :tst: |
-      /***************************
-      * My Awesome Test For %1$s
-      ***************************/
-```
-
-### Test Defines
-
-You can specify the "#ifdef TEST" at the top of the test files with a custom define.
-This example will put a "#ifdef CEEDLING_TEST" at the top of the test files.  
-
-```yaml
-:module_generator:
-  :test_define: CEEDLING_TEST
-```
-
-### Naming Convention
-
-Finally, you can force a particular naming convention. Even if someone calls the generator
-with something like `MyNewModule`, if they have the naming convention set to `:caps`, it will
-generate files like `MY_NEW_MODULE.c`. This keeps everyone on your team behaving the same way.
-
-Your options for `:naming:` are as follows:
-
-    - `:bumpy` - BumpyFilesLooksLikeSo
-    - `:camel` - camelFilesAreSimilarButStartLow
-    - `:snake` - snake_case_is_all_lower_and_uses_underscores
-    - `:caps`  - CAPS_FEELS_LIKE_YOU_ARE_SCREAMING
-
-<br/><br/>

data/docs/mkdocs/plugins/report-build-warnings-log.md

@@ -1,42 +0,0 @@
-# Build Warnings Log
-
-Capture build process warnings from command tools to a plain text log file.
-
-## Overview
-
-This plugin captures warning messages output by command line tools throughout a
-build. At the end of a build, any collected warning messages are written to one 
-or more plain text log files.
-
-Warning messages are collected for all compilation-related builds and
-differentiated by build context — `test`, `release`, or plugin-modified build 
-(e.g. `gcov`).
-
-Ceedling warning messages or warning messages from code generation will not
-appear in log files; warnings are only collected from build step command line
-tools for the predefined build steps of preprocessing, compilation, and
-linking.
-
-Log files are written to `<build root>/artifacts/<context>/`.
-
-## Setup
-
-Enable the plugin in your Ceedling project file:
-
-```yaml
-:plugins:
-  :enabled:
-    - report_build_warnings_log
-```
-
-## Configuration
-
-To change the default filename of `warning.log`, add your desired filename to
-your configuration file using `:report_build_warnings_log:` ↳ `:filename`.
-
-```yaml
-:report_build_warnings_log:
-  :filename: more_better_filename.ext
-```
-
-<br/><br/>

data/docs/mkdocs/plugins/report-tests-gtestlike-stdout.md

@@ -1,98 +0,0 @@
-# GTest-like Console Report
-
-Prints to the console ($stdout) test suite results in a GTest-like format.
-
-## Plugin Overview
-
-This plugin is intended to be used in place of the more commonly used "pretty" 
-test report plugin. Like its sibling, this plugin ollects raw test results from
-the individual test executables of your test suite and presents them in a more 
-readable summary form — specifically the GoogleTest format.
-
-This plugin is most useful when using an IDE or working with a CI system that
-understands the GTest console logging format.
-
-## Setup
-
-Enable the plugin in your Ceedling project by adding 
-`report_tests_gtestlike_stdout` to the list of enabled plugins instead of any 
-other `report_tests_*_stdout` plugin.
-
-```YAML
-:plugins:
-  :enabled:
-    - report_tests_gtestlike_stdout
-```
-
-## Configuration
-
-No additional configuration is needed once the plugin is enabled.
-
-## Plugin Output
-
-### Ceedling mapped to GoogleTest reporting elements
-
-Ceedling's conventions and output map to GTest format as the following:
-
-* A Ceedling test file — ultimately an individual test executable — is a GTest 
-  _test case_.
-* A Ceedling test case (a.k.a. unit test) is a GTest _test_.
-* Execution time is collected for each Ceedling test executable, not each 
-  Ceedling test case. As such, the test report includes only execution time for
-  each GTest _test case_. Individual test execution times are reported as 0 ms.
-
-GoogleTest generates reporting output incrementally. Ceedling produces test 
-results incrementally as well, but its plugin reporting structure does not 
-collect and format statistics until the end of a build. This plugin duplicates
-the tense of the wording in a GTest report, but it is unintentionally somewhat 
-misleading.
-
-### Example output (snippet)
-
-The GTest format is verbose. It lists all tests with success and failure results.
-
-The example output below shows the header and footer of test results for a suite 
-of 49 Ceedling tests in 18 test files but only includes logging for 6 tests.
-
-```sh
- > ceedling test:all
-```
-
-```
-[==========] Running 49 tests from 18 test cases.
-[----------] Global test environment set-up.
- 
- ...
-
-[----------] 4 tests from test/TestUsartModel.c
-[ RUN      ] test/TestUsartModel.c.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting
-[       OK ] test/TestUsartModel.c.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting (0 ms)
-[ RUN      ] test/TestUsartModel.c.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately
-[       OK ] test/TestUsartModel.c.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately (0 ms)
-[ RUN      ] test/TestUsartModel.c.testShouldReturnErrorMessageUponInvalidTemperatureValue
-[       OK ] test/TestUsartModel.c.testShouldReturnErrorMessageUponInvalidTemperatureValue (0 ms)
-[ RUN      ] test/TestUsartModel.c.testShouldReturnWakeupMessage
-[       OK ] test/TestUsartModel.c.testShouldReturnWakeupMessage (0 ms)
-[----------] 4 tests from test/TestUsartModel.c (1277 ms total)
-[----------] 1 tests from test/TestMain.c
-[ RUN      ] test/TestMain.c.testMainShouldCallExecutorInitAndContinueToCallExecutorRunUntilHalted
-[       OK ] test/TestMain.c.testMainShouldCallExecutorInitAndContinueToCallExecutorRunUntilHalted (0 ms)
-[----------] 1 tests from test/TestMain.c (1351 ms total)
-[----------] 1 tests from test/TestModel.c
-[ RUN      ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit
-test/TestModel.c(21): error: Function TaskScheduler_Init() called more times than expected.
- Actual:   FALSE
- Expected: TRUE
-[  FAILED  ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit (0 ms)
-[----------] 1 tests from test/TestModel.c (581 ms total)
-
-[----------] Global test environment tear-down.
-[==========] 49 tests from 18 test cases ran.
-[  PASSED  ] 48 tests.
-[  FAILED  ] 1 tests, listed below:
-[  FAILED  ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit
-
- 1 FAILED TESTS
-```
-
-<br/><br/>