ceedling 1.1.9 → 1.2.0

data/docs/mkdocs/overview/build-system.md

@@ -1,115 +0,0 @@
-# A Build System for All Your C Mad Scientisting Needs
-
-Ceedling allows you to generate an entire test and release build 
-environment for a C project from a single, short YAML configuration 
-file. It truly shines at supporting unit testing and managing test 
-builds.
-
-Ceedling and its bundled frameworks, Unity and CMock, don't
-want to brag, but they're also quite adept at supporting the tiniest of
-embedded processors, the beefiest 64-bit powerhouses available, and
-everything in between.
-
-Assembling build environments for C projects — especially with
-automated unit tests — is a pain. No matter the all-purpose build 
-environment tool you use, configuration is tedious and requires 
-considerable glue code to pull together the necessary tools and 
-libraries to run unit tests. The Ceedling bundle handles all this 
-for you.
-
-## Simple Sample Project File
-
-For a project including Unity/CMock unit tests and using the default 
-toolchain `gcc`, the configuration file could be as simple as this:
-
-```yaml
-:project:
-  :build_root: project/build/
-  :release_build: TRUE
-
-:paths:
-  :test:
-    - tests/**
-  :source:
-    - source/**
-  :include:
-    - inc/**
-```
-
-From the command line, to run all your unit tests, you would run 
-`ceedling test:all`. To build the release version of your project,
-you would simply run `ceedling release`. That's it!
-
-!!! tip "Want to see a real world project configuration?"
-    See this [commented project file][example-config-file] 
-    for a much more complete and sophisticated example of a project 
-    configuration.
-
-Of course, many more advanced options allow you to configure
-your project with a variety of features to meet a variety of needs.
-Ceedling can work with practically any command line toolchain
-and directory structure – all by way of the configuration file.
-
-See the later [configuration section][project-configuration] for 
-way more details on your project configuration options.
-
-A facility for [plugins](../plugins/index.md) also allows you to 
-extend Ceedling's capabilities for needs such as custom code metrics 
-reporting, build artifact packaging, and much more. A variety of 
-built-in plugins come with Ceedling.
-
-[example-config-file]: ../snapshot/assets/project.yml
-[project-configuration]: ../configuration/index.md
-
-## What's with this name?
-
-Glad you asked. Ceedling is tailored for unit tested C projects and is built
-upon Rake, a Make replacement implemented in the Ruby scripting language.
-
-So, we've got C, our Rake, and the fertile soil of a build environment in which
-to grow and tend your project and its unit tests. Ta da — _Ceedling_.
-
-Incidentally, though Rake was the backbone of the earliest versions of
-Ceedling, it is now being phased out incrementally in successive releases. 
-The name Ceedling is not going away, however!
-
-## “Tailored for unit-tested C projects”?
-
-Well, we like to write unit tests for our C code to make it lean and
-mean — that whole [Test-Driven Development][tdd] thing.
-
-Along the way, this style of writing C code spawned two
-tools to make the job easier:
-
-1. A unit test framework for C called _Unity_
-1. A mocking library called _CMock_
-
-And, though it's not directly related to testing, a C framework for 
-exception handling called _CException_ also came along.
-
-[tdd]: http://en.wikipedia.org/wiki/Test-driven_development
-
-These tools and frameworks are great, but they require quite
-a bit of environment support to pull them all together in a convenient,
-usable fashion. We started off with Rakefiles to assemble everything.
-These ended up being quite complicated and had to be hand-edited
-or created anew for each new project. Ceedling replaces all that
-tedium and rework with a configuration file that ties everything
-together.
-
-Though Ceedling is tailored for unit testing, it can also go right 
-ahead and build your final binary release artifact for you as well. 
-That said, Ceedling is more powerful as a unit test build environment 
-than it is a general purpose release build environment. Complicated 
-projects including separate bootloaders or multiple library builds, 
-etc. are not necessarily its strong suit (but the 
-[`dependencies`](../plugins/dependencies.md) plugin can 
-accomplish quite a bit here).
-
-It's quite common and entirely workable to host Ceedling and your 
-test suite alongside your existing release build setup. That is, you 
-can use make, Visual Studio, SCons, Meson, etc. for your release build
-and Ceedling for your test build. Your two build systems will simply
-"point" to the same project code.
-
-<br/><br/>

data/docs/mkdocs/overview/index.md

@@ -1,29 +0,0 @@
-# Overview
-
-<div class="grid cards" markdown>
-
--   :material-hammer-wrench: **[A Build System for C](build-system.md)**
-
-    ---
-
-    Generate a complete test and release build environment from a single
-    YAML file. Includes a minimal sample project configuration and an
-    explanation of Ceedling‘s design philosophy.
-
--   :material-toolbox: **[Tools & Frameworks](tools-and-frameworks.md)**
-
-    ---
-
-    Ruby, Rake, YAML, Unity, and CMock explained — the pieces
-    that make Ceedling possible and how they fit together.
-
--   :material-test-tube: **[Test Environments](test-environments.md)**
-
-    ---
-
-    Native host builds, emulator-based runs, and on-target execution —
-    choose the right test suite strategy for your project.
-
-</div>
-
-<br/><br/>

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

@@ -1,33 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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/docs/mkdocs/plugins/beep.md

@@ -1,134 +0,0 @@
-# Beep
-
-Hear a useful beep at the end of a build.
-
-## 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
-
-To use this plugin, it must be enabled:
-
-```yaml
-:plugins:
-  :enabled:
-    - beep
-```
-
-## 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
-
-When this plugin is enabled, a beep is sounded when:
-
-* A test build or release build finish successfully.
-* An error condition breaks a build.
-
-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
-
-The following options are fixed. At present, this plugin does not expose customization settings.
-
-* `:bell`
-
-  `:bell` is the simplest and most widely available option for beeping. This option simply `echo`s the unprintable [ASCII bell character][ascii-bel-character] to a command terminal. This option is generally available on all platforms, including Windows.
-
-  [ascii-bel-character]: https://en.wikipedia.org/wiki/Bell_character
-
-* `:tput`
-
-  [`tput`][tput] is a command line utility widely availble among Unix derivatives, including Linux and macOS. The `tput` utility uses the terminfo database to make the values of terminal-dependent capabilities (including the [ASCII bell character][ascii-bel-character]) and terminal information available to the shell.
-
-  If the `echo`-based method used by the `:bell` option is not successful, `:tput` is a good backup option (except on Windows).
-
-  [tput]: https://linux.die.net/man/1/tput
-
-* `:beep`
-
-  [`beep`][beep] is an old but widely available Linux package for tone generation using the PC speaker.
-
-  `beep` requires isntallation and the possibility of a complementary kernel module.
-
-  The original audio device in a PC before sound cards was a simple and limited speaker directly wired to a motherboard. Rarely, modern systems still have this device. More commonly, its functions are routed to a default mode of modern audio hardware. `beep` may not work on modern Linux systems. If it is a viable option, this utility is typically dependent on a PC speaker kernel module and related configuration.
-
-  [beep]: https://linux.die.net/man/1/beep
-
-* `:speaker_test`
-
-  [`speaker-test`][speaker-test] is a Linux package commonly available for tone generation using a system's audio features.
-
-  `speaker-test` requires installation as well as audio subsystem configuration.
-
-  _Note:_ `speaker-test` typically mandates a 4 second minimum run, even if the configured sound plays for less than this minimum. Options to limit `speaker-test`'s minimum time are likely possible but would require combining advanced Ceedling features.
-
-  [speaker-test]: https://linux.die.net/man/1/speaker-test
-
-* `:say`
-
-  macOS includes a built-in text-to-speech command line application, [`say`][say]. When Ceedling is running on macOS and this beep option is selected, Ceedling events will be verbally announced.
-
-  [say]: https://ss64.com/mac/say.html
-
-### Adding arguments to a beep tool
-
-Each of the sound options above map to a command line tool that Ceedling executes.
-
-The `:beep`, `:speaker_test`, and `:say` tools can accept additional command line arguments to modify their behavior and sound ouput.
-
-The `:speaker_test` tool is preconfigured with its `-t`, `-f`, and `-l` arguments to generate a 1 second 1000 Hz sine wave. Any additional arguments added through configuration will follow these (and could conflict).
-
-To add additional arguments, a feature of Ceedling's project file handling allows you to merge a partial tool definition with tools already fully defined.
-
-```yaml
-:tools_beep_<sound option>: # Fill in <sound option> as from the list above
-  :arguments:
-    - ...                   # Add any aguments as a list of strings
-```
-
-### Example beep configurations in YAML
-
-Enabling the plugin and event handlers with beep tool selections:
-
-```yaml
-:plugins:
-  :enabled:
-    - beep
-
-# The following is the default configuration.
-# It is shown for completeness, but it need not be duplicated in your project file 
-# if the default settings work for you.
-:beep:
-  :on_done: :bell
-  :on_error: :bell
-```
-
-Adding an argument to a beep tool:
-
-```yaml
-:plugins:
-  :enabled:
-    - beep
-
-:beep:
-  :on_done: :say # Choose the macOS `say` tool for build done events
-                 # `:bell` remains the default for :on_error:
-
-:tools_beep_say:
-  :arguments:
-    - -v daniel  # Change `say` command line to use Daniel voice
-
-```
-
-## 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/docs/mkdocs/plugins/bullseye.md

@@ -1,83 +0,0 @@
-# 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 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.
-
-!!! note
-    The Bullseye plugin creates a duplicate test build with `bullseye:` 
-    command line plugin tasks. [This is intentional and needed](index.md#understanding-plugin-build-duplication).
-
----
-
-## Configuration
-
-The bullseye plugin supports configuration options via your `project.yml` provided
-by Ceedling. The following is a typical configuration example:
-
-```
-:bullseye:
-  :auto_license: TRUE
-:plugins:
-  :bullseye_lib_path: []
-:paths:
-  :bullseye_toolchain_include: []
-
-:tools:
-  :bullseye_instrumentation:
-    :executable: covc
-    :arguments:
-      - '--file $': ENVIRONMENT_COVFILE
-      - -q
-      - ${1}
-  :bullseye_compiler:
-    :executable: gcc
-    :arguments:
-      - -g
-      - -I"$": COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR
-      - -I"$": COLLECTION_PATHS_BULLSEYE_TOOLCHAIN_INCLUDE
-      - -D$: COLLECTION_DEFINES_TEST_AND_VENDOR
-      - -DBULLSEYE_COMPILER
-      - -c "${1}"
-      - -o "${2}"
-  :bullseye_linker:
-    :executable: gcc
-    :arguments:
-      - ${1}
-      - -o ${2}
-      - -L$: PLUGINS_BULLSEYE_LIB_PATH
-      - -lcov
-  :bullseye_fixture:
-    :executable: ${1}
-  :bullseye_report_covsrc:
-    :executable: covsrc
-    :arguments:
-      - '--file $': ENVIRONMENT_COVFILE
-      - -q
-      - -w140
-  :bullseye_report_covfn:
-    :executable: covfn
-    :arguments:
-      - '--file $': ENVIRONMENT_COVFILE
-      - --width 120
-      - --no-source
-      - '"${1}"'
-  :bullseye_browser:
-    :executable: CoverageBrowser
-    :optional: TRUE
-    :arguments:
-      - '"$"': ENVIRONMENT_COVFILE
-```
-
-## Example Usage
-
-```sh
-ceedling bullseye:all utils:bullseye
-```
-
-<br/><br/>