ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/overview/test-environments.md

@@ -0,0 +1,33 @@
+# Test Suite Execution Environments
+
+**All your sweet, sweet test suite options**
+
+Ceedling, Unity, and CMock help you create and run test suites using any 
+of the following approaches. For more on this topic, please see this 
+[handy dandy article][tts-which-build] and/or follow the links for each 
+item listed below.
+
+[tts-which-build]: https://throwtheswitch.org/build/which
+
+1. **[Native][tts-build-native].** This option builds and runs code on your 
+   host system.
+    * In the simplest case this means you are testing code that is intended
+      to run on the same sort of system as the test suite. Your test 
+      compiler toolchain is the same as your release compiler toolchain.
+    * However, a native build can also mean your test compiler is different
+      than your release compiler. With some thought and effort, code for
+      another platform can be tested on your host system. This is often
+      the best approach for embedded and other specialized development.
+1. **[Emulator][tts-build-cross].** In this option, you build your test code with your target's
+   toolchain, and then run the test suite using an emulator provided for
+   that target. This is a good option for embedded and other specialized
+   development — if an emulator is available.
+1. **[On target][tts-build-cross].** The Ceedling bundle of tools can create test suites that
+   run on a target platform directly. Particularly in embedded development
+   — believe it or not — this is often the option of last resort. That is,
+   you should probably go with the other options in this list.
+
+[tts-build-cross]: https://throwtheswitch.org/build/cross
+[tts-build-native]: https://throwtheswitch.org/build/native
+
+<br/><br/>

data/docs/mkdocs/overview/tools-and-frameworks.md

@@ -0,0 +1,115 @@
+# So Many Tools and Acronyms
+
+**Hold on. Back up. Unity? CMock? CException? Ruby? Rake? YAML?**
+
+## Ceedling suite frameworks
+
+### Unity
+
+[Unity] is a [unit test framework][unit-testing] for C. It provides facilities
+for test assertions, executing tests, and collecting / reporting test
+results. Unity derives its name from its implementation in a single C
+source file (plus two C header files) and from the nature of its
+implementation - Unity will build in any C toolchain and is configurable
+for even the very minimalist of processors.
+
+[Unity]: http://github.com/ThrowTheSwitch/Unity
+[unit-testing]: http://en.wikipedia.org/wiki/Unit_testing
+
+### CMock
+
+[CMock]<sup>†</sup> is a tool written in Ruby able to generate [function mocks & stubs][test-doubles] 
+in C code from a given C header file. Mock functions are invaluable in 
+[interaction-based unit testing][interaction-based-tests].
+CMock's generated C code uses Unity.
+
+<sup>†</sup> Through a [plugin][FFF-plugin], Ceedling also supports
+[FFF], _Fake Function Framework_, for [fake functions][test-doubles] as an
+alternative to CMock's mocks and stubs.
+
+[CMock]: http://github.com/ThrowTheSwitch/CMock
+[test-doubles]: https://blog.pragmatists.com/test-doubles-fakes-mocks-and-stubs-1a7491dfa3da
+[FFF]: https://github.com/meekrosoft/fff
+[FFF-plugin]: ../plugins/fff.md
+[interaction-based-tests]: http://martinfowler.com/articles/mocksArentStubs.html
+
+### CException
+
+[CException] is a C source and header file that provide a simple
+[exception mechanism][exn] for C by way of wrapping up the
+[setjmp / longjmp][setjmp] standard library calls. Exceptions are a much
+cleaner and preferable alternative to managing and passing error codes
+up your return call trace.
+
+[CException]: http://github.com/ThrowTheSwitch/CException
+[exn]: http://en.wikipedia.org/wiki/Exception_handling
+[setjmp]: http://en.wikipedia.org/wiki/Setjmp.h
+
+## Core tools
+
+### Ruby
+
+[Ruby] is a handy scripting language like Perl or Python. It's a modern, 
+full featured language that happens to be quite handy for accomplishing 
+tasks like code generation or automating one's workflow while developing 
+in a compiled language such as C.
+
+[Ruby]: http://www.ruby-lang.org/en/
+
+### Rake
+
+!!! warning "Migrating away from Rake"
+    Ceedling would not exist today if not for the help Rake provided to
+    get off the ground. As Ceedling matured it became apparent that 
+    Rake had become a limitation. The project is slowly removing its
+    dependency on Rake.
+
+[Rake] is a utility written in Ruby for accomplishing dependency 
+tracking and task automation common to building software. It's a modern, 
+more flexible replacement for [Make].
+
+Rakefiles are Ruby files, but they contain build targets similar
+in nature to that of Makefiles (but you can also run Ruby code in
+your Rakefile).
+
+[Rake]: http://rubyrake.org/
+[Make]: http://en.wikipedia.org/wiki/Make_(software)
+
+### YAML
+
+[YAML] is a "human friendly data serialization standard for all
+programming languages." It's kinda like a markup language but don't
+call it that. With a YAML library, you can [serialize] data structures
+to and from the file system in a textual, human readable form. Ceedling
+uses a serialized data structure as its configuration input.
+
+YAML has some advanced features that can greatly 
+[reduce duplication][yaml-anchors-aliases] in a configuration file 
+needed in complex projects. YAML anchors and aliases are beyond the scope
+of this document but may be of use to advanced Ceedling users. Note that 
+Ceedling does anticipate the use of YAML aliases. It proactively flattens 
+YAML lists to remove any list nesting that results from the convenience of
+aliasing one list inside another.
+
+[YAML]: http://en.wikipedia.org/wiki/Yaml
+[serialize]: http://en.wikipedia.org/wiki/Serialization
+[yaml-anchors-aliases]: https://blog.daemonl.com/2016/02/yaml.html
+
+---
+
+## Dependencies and Bundled Tools
+
+* By using the preferred installation options of the Ruby Ceedling gem or 
+  the prepackaged Docker images, all Ceedling dependencies will be installed 
+  for you. (See [installation section](../getting-started/installation.md).)
+
+* Regardless of installation method, Unity, CMock, and CException are bundled 
+  with Ceedling. Ceedling is designed to glue them all together for your 
+  project as seamlessly as possible.
+
+* YAML support is included with Ruby. It requires no special installation
+  or configuration. If your project file contains properly formatted YAML
+  with the recognized names and options (see later sections), you are good 
+  to go.
+
+<br/><br/>

data/{plugins/beep/README.md → docs/mkdocs/plugins/beep.md}

@@ -1,13 +1,13 @@
-# Ceedling Plugin: Beep
+# Beep
 
 Hear a useful beep at the end of a build.
 
-# Plugin Overview
+## Plugin Overview
 
 Are you getting too distracted surfing the internet, chatting with coworkers, or swordfighting while a long build runs? A friendly beep will let you know
 it's time to pay attention again.
 
-# Setup
+## Setup
 
 To use this plugin, it must be enabled:
 
@@ -17,14 +17,14 @@ To use this plugin, it must be enabled:
     - beep
 ```
 
-# Configuration
+## Configuration
 
 Beep includes a default configuration. By just enabling the plugin, the simplest cross-platform sound mechanism (`:bell` below) is automatically enabled for both
 build completion and build error events.
 
 If you would like to customize your beeps, the following explains your options.
 
-## Events
+### Events
 
 When this plugin is enabled, a beep is sounded when:
 
@@ -33,7 +33,7 @@ When this plugin is enabled, a beep is sounded when:
 
 To change the default sound for each event, define `:on_done` and `:on_error` beneath a top-level `:beep` entry in your configuration file. See example below.
 
-## Sound options
+### Sound options
 
 The following options are fixed. At present, this plugin does not expose customization settings.
 
@@ -77,7 +77,7 @@ The following options are fixed. At present, this plugin does not expose customi
 
   [say]: https://ss64.com/mac/say.html
 
-## Adding arguments to a beep tool
+### Adding arguments to a beep tool
 
 Each of the sound options above map to a command line tool that Ceedling executes.
 
@@ -93,7 +93,7 @@ To add additional arguments, a feature of Ceedling's project file handling allow
     - ...                   # Add any aguments as a list of strings
 ```
 
-## Example beep configurations in YAML
+### Example beep configurations in YAML
 
 Enabling the plugin and event handlers with beep tool selections:
 
@@ -127,7 +127,8 @@ Adding an argument to a beep tool:
 
 ```
 
-# Notes
+## Notes
 
 * Some terminal emulators intercept and/or silence beeps. Remote terminal sessions can add further complication. Be sure to check relevant configuration options to accomplish what you want.
 
+<br/><br/>

data/{plugins/bullseye/README.md → docs/mkdocs/plugins/bullseye.md}

@@ -1,19 +1,13 @@
-Bullseye Code Coverage Plugin
-=============================
-
-# June 1, 2024 Bullseye Plugin Disabled
-
-Until the Bullseye Plugin can be updated for compatibility with Ceedling >= 1.0.0,
-it has been disabled.
-
-(The key hurdle is access to a license for the proprietary Bullseye coverage tooling.)
-
-# Plugin Overview
+# Bullseye
 
 Plugin for integrating Bullseye code coverage tool into Ceedling projects.
 This plugin requires a working license to Bullseye code coverage tools. The tools
 must be within the path or the path should be added to the environment in the 
-`project.yml file`.
+project configuration.
+
+!!! warning "Bullseye Plugin Disabled"
+    [June 1, 2024] Until the Bullseye Plugin can be updated for compatibility 
+    with Ceedling >= 1.0.0, it has been disabled.
 
 ## Configuration
 
@@ -79,3 +73,5 @@ by Ceedling. The following is a typical configuration example:
 ```sh
 ceedling bullseye:all utils:bullseye
 ```
+
+<br/><br/>

data/{plugins/command_hooks/README.md → docs/mkdocs/plugins/command-hooks.md}

@@ -1,12 +1,12 @@
-# Ceedling Plugin: Command Hooks
+# Command Hooks
 
 Easily run command line tools and scripts at various points in a Ceedling build.
 
-# Plugin Overview
+## Plugin Overview
 
 This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling's programmatic `Plugin` code hooks to easily managed tool definitions. 
 
-# Setup
+## Setup
 
 To use this plugin, it must be enabled:
 
@@ -16,9 +16,9 @@ To use this plugin, it must be enabled:
     - command_hooks
 ```
 
-# Configuration
+## Configuration
 
-## Overview
+### Overview
 
 To connect utilties or scripts to build step hooks, Ceedling tools must be defined.
 
@@ -26,7 +26,7 @@ A Ceedling tool is just a YAML blob that gathers together a handful of settings
 
 Example Ceedling tools follow. When enabled, this plugin ensures any tools you define are executed by the corresponding build step hook they are organized beneath. The configurtion of enabled hooks and tools happens in a top-level `:command_hooks:` block within your project configuration. One or more tools can be attached to a build step hook.
 
-## Tool lists
+### Tool lists
 
 A command hook can execute one or more tools.
 
@@ -36,15 +36,15 @@ If multiple tools are needed, they must be organized as entries in a YAML list.
 
 See the commented examples below.
 
-## Tool definitions
+### Tool definitions
 
-Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for project configuration [`:tools`][tools-doc] entries to understand how to craft your argument list and other tool options.
+Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See the [`:tools` configuration reference][tools-doc] to understand how to craft your argument list and other tool options.
 
-At present, this plugin passes at most one runtime parameter for use in a hook's tool argument list. If available, this parameter can be referenced with a Ceedling tool argument expansion identifier `${1}`. That is, wherever you place `${1}` in your tool argument list, `${1}` will expand in the command line Ceedling constructs with the parameter this plugin provides for that build step hook. The list of build steps hooks below document any single parameters they provide at execution.
+This plugin passes one or two runtime parameters for use in a hook's tool argument list depending on the hook. These parameters are referenced with Ceedling tool argument expansion identifiers `${1}`, `${2}`, etc. Wherever you place `${1}` or `${2}` in your tool argument list, they expand in the command line Ceedling constructs with the parameters this plugin provides for that build step hook. The list of build step hooks below documents which parameters are available for each hook.
 
-[tools-doc]: https://github.com/ThrowTheSwitch/Ceedling/blob/test/ceedling_0_32_rc/docs/CeedlingPacket.md#tools-configuring-command-line-tools-used-for-build-steps
+[tools-doc]: ../configuration/reference/tools.md
 
-## Hook logging
+### Hook logging
 
 In addition to the standard Ceedling tool definition elements, a hook configuration entry may optionally include a `:logging` setting.
 
@@ -56,7 +56,7 @@ When logging is enabled and logging conditions are appropriate, any output from
 * Debug logging naturally displays hook output as part of normal tool execution logging. It is not duplicated by hook logging.
 * At Normal verbosity, blank hook output is not logged at all; Obnoxious verbosity will display blank output as `<empty>`.
 
-## Command Hooks example configuration YAML
+### Command Hooks example configuration YAML
 
 ```yaml
 :command_hooks:
@@ -89,7 +89,7 @@ When logging is enabled and logging conditions are appropriate, any output from
         - memory_report.txt
 ```
 
-# Available Build Step Hooks
+## Available Build Step Hooks
 
 Define any of the following entries within a top-level `:command_hooks:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps.
 
@@ -98,144 +98,166 @@ Some hooks are called for every file-related operation for which the hook is nam
 As an example, consider a Ceedling project with ten test files and seventeen mocks. The command line `ceedling test:all` would trigger:
 
 * 1 occurrence of the `:pre_build` hook.
+* 1 occurrence of the `:pre_test_build` hook.
 * 10 occurrences of the `:pre_test` and `:post_test` hooks.
 * 17 occurrences of the `:pre_mock_generate` and `:post_mock_generate` hooks.
 * 10 occurrences of the `:pre_test_runner_generate` and `:post_test_runner_generate` hooks.
 * 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity's source, CMock's source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
 * 10 occurrences of the `:pre_link` and `:post_link` hooks for test executable creation.
-* 10 occurences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
-* 1 occurence of the `:post_build` hook unless a build error occurred (`:post_error` would be called isntead).
+* 10 occurrences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
+* 1 occurrence of the `:post_test_build` hook.
+* 1 occurrence of the `:post_build` hook unless a build error occurred (`:post_error` would be called instead).
 
-## `:pre_build`
+### `:pre_build`
 
 Called once just before Ceedling executes any tasks.
 
-No parameters are provided for a tool's argument list when the hook is called.
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_build` value can be used to compute the total build duration.
 
-## `:post_build`
+### `:post_build`
 
-Called once just before Ceedling terminates.
+Called once just before Ceedling terminates after a successful build.
 
-No parameters are provided for a tool's argument list when the hook is called.
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_build` value can be used to compute the total build duration.
 
-## `:post_error`
+### `:post_error`
 
 Called once just after any build failure and just before Ceedling terminates.
 
-No parameters are provided for a tool's argument list when the hook is called.
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds at the moment the error is handled.
 
-## `:pre_test`
+### `:pre_test`
 
 Called just before each test begins its build pipeline and just after all context for that build has been gathered.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-## `:post_test`
+### `:post_test`
 
 Called just after each test completes its build and execution.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-## `:pre_release`
+### `:pre_test_build`
+
+Called once just before the full test build pipeline begins (before any individual test's configure, preprocess, compile, link, or execute steps).
+
+Two parameters are available to a tool when the hook is called:
+
+* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
+* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `post_test_build` value can be used to compute the total test build duration.
+
+### `:post_test_build`
+
+Called once just after the full test build pipeline completes or terminates (including on error).
+
+Two parameters are available to a tool when the hook is called:
+
+* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
+* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `pre_test_build` value can be used to compute the total test build duration.
+
+### `:pre_release_build`
 
 Called once just before a release build begins.
 
-No parameters are provided for a tool's argument list when the hook is called.
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_release_build` value can be used to compute the total release build duration.
 
-## `:post_release`
+### `:post_release_build`
 
-Called once just after a release build finishes.
+Called once just after a release build finishes or terminates (including on error).
 
-No parameters are provided for a tool's argument list when the hook is called.
+The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_release_build` value can be used to compute the total release build duration.
 
-## `:pre_mock_preprocess`
+### `:pre_mock_preprocess`
 
 If mocks are enabled and preprocessing is in use, this is called just before each header file to be mocked is preprocessed.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
 
-See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
 
-[ceedling-packet]: ../docs/CeedlingPacket.md
+[preprocessing]: ../testing-guide/conventions.md#test-preprocessing
 
-## `:post_mock_preprocess`
+### `:post_mock_preprocess`
 
 If mocks are enabled and preprocessing is in use, this is called just after each header file to be mocked is preprocessed.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
 
-## `:pre_mock_generate`
+### `:pre_mock_generate`
 
 If mocks are enabled, this is called just before each header file to be mocked is processed by mock generation.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
 
-## `:post_mock_generate`
+### `:post_mock_generate`
 
 If mocks are enabled, this is called just after each mock generation.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
 
-## `:pre_test_preprocess`
+### `:pre_test_preprocess`
 
 If preprocessing is in use, this is called just before each test file is preprocessed before runner generation.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
 
-## `:post_test_preprocess`
+### `:post_test_preprocess`
 
 If preprocessing is in use, this is called just after each test file is preprocessed.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
 
-## `:pre_runner_generate`
+### `:pre_runner_generate`
 
 Called just before each test file is processed by test runner generation.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-## `:post_runner_generate`
+### `:post_runner_generate`
 
 Called just after each test runner is generated.
 
 The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
 
-## `:pre_compile_execute`
+### `:pre_compile_execute`
 
 Called just before each C or assembly file is compiled.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the file to be compiled.
 
-## `:post_compile_execute`
+### `:post_compile_execute`
 
 Called just after each file compilation.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the input file that was compiled.
 
-## `:pre_link_execute`
+### `:pre_link_execute`
 
 Called just before any binary artifact—test or release—is linked.
 
 The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
 
-## `:post_link_execute`
+### `:post_link_execute`
 
 Called just after a binary artifact is linked.
 
 The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
 
-## `:pre_test_fixture_execute`
+### `:pre_test_fixture_execute`
 
 Called just before each test is executed in its corresponding test fixture.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact to be executed by the fixture.
 
-## `:post_test_fixture_execute`
+### `:post_test_fixture_execute`
 
 Called just after each test's fixture is executed and test results are collected.
 
 The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact that was executed by the fixture.
+
+<br/><br/>

data/{plugins/compile_commands_json_db/README.md → docs/mkdocs/plugins/compile-commands-json-db.md}

@@ -1,8 +1,8 @@
-# Ceedling Plugin: JSON Compilation Database
+# JSON Compilation Database
 
 Language Server Protocol (LSP) support for Clang tooling.
 
-# Background
+## Background
 
 Syntax highlighting and code completion are hard. Historically each editor or IDE has implemented their own and then competed amongst themselves to offer the best experience for developers. Good syntax highlighting can be so valuable as to outweigh the consideration of alternate editors. If implementing sytnax highlighting and related features in a tool is hard for one language — and it is — imagine doing it for dozens of them. Further, on the flip side, imagine the complexities involved for a developer working with multiple languages at once.
 
@@ -12,7 +12,7 @@ In June of 2016, Microsoft with Red Hat and Codenvy got together to create the [
 [lsp-community]: https://langserver.org/
 [lsp-tools]: https://microsoft.github.io/language-server-protocol/implementors/tools/
 
-# Plugin Overview
+## Plugin Overview
 
 For C and C++ projects, perhaps the most popular LSP server is the [`clangd`][clangd] backend. In order to provide features like _go to definition_, `clangd` needs to understand how to build a project so that it can discover all the pieces to the puzzle. Because of the various flavors of builds Ceedling supports and especially because of the complexities of test suite builds, components of a build can easily go missing from the view of `clangd`.
 
@@ -23,7 +23,7 @@ Once enabled, this plugin generates the database as `<build root>/artifacts/comp
 [clangd]: https://clangd.llvm.org
 [json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
 
-# Setup
+## Setup
 
 Enable the plugin in your Ceedling project file by adding `compile_commands_json_db` to the list of enabled plugins.
 
@@ -33,8 +33,10 @@ Enable the plugin in your Ceedling project file by adding `compile_commands_json
     - compile_commands_json_db
 ```
 
-# Configuration
+## Configuration
 
 There is no additional configuration necessary to run this plugin.
 
 `clangd` will search your build directory for the JSON compilation database, but in some instances on Unix-asbed platforms it can be easier and necessary to symlink the file into the root directory of your project (e.g. `ln -s ./build/artifacts/compile_commands.json .`).
+
+<br/><br/>