ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/getting-started/index.md

@@ -1,41 +0,0 @@
-# Getting Started
-
-<div class="grid cards" markdown>
-
--   :material-rocket-launch: **[Quick Start](quick-start.md)**
-
-    ---
-
-    Steps from installation through running your first build tasks — 
-    get up and running fast.
-
--   :material-download: **[Installation](installation.md)**
-
-    ---
-
-    Install Ceedling as a Ruby Gem or use a prepackaged _MadScienceLab_
-    Docker image with Ceedling, GCC, and supporting tools already bundled.
-
--   :material-console: **[Command Line](command-line.md)**
-
-    ---
-
-    Application commands (project creation, help, config inspection) and
-    build & plugin tasks (test runs, release builds, clean, and more).
-
--   :material-file-code: **[Commented Sample Test File](../testing-guide/test-sample.md)**
-
-    ---
-
-    A sample test file illustrating the Ceedling conventions that make it go. 
-    Includes a discussion of what gets compiled and linked into a test executable.
-
--   :material-package-variant-closed-check: **[Example Projects](example-projects/index.md)**
-
-    ---
-
-    Ceedling includes several readymade example projects for learning and reference.
-
-</div>
-
-<br/><br/>

data/docs/mkdocs/getting-started/installation.md

@@ -1,179 +0,0 @@
-# Ceedling Installation & Set Up
-
-**How Exactly Do I Get Started?**
-
-!!! tip
-    You will see various references to Ruby. You do not need to know Ruby
-    to use Ceedling! Ruby is simply the implementation language and 
-    software packaging for Ceedling as a tool.
-
-    Once Ceedling is installed, you interact with it as a command line
-    utility (`ceedling ...`).
-
-You have two good options for installing and running Ceedling:
-
-1. The Ceedling Ruby Gem
-1. Prepackaged _MadScienceLab_ Docker images
-
-One way to get started is to 
-[install Ceedling as a Ruby gem](#installation-as-a-ruby-gem). Gems are 
-simply prepackaged Ruby-based software. Other options exist, but the 
-Ceedling Gem is perhaps the simplest option for local installation.
-However, please note that you will also need a compiler toolchain 
-installed (e.g. GCC — GNU Compiler Collection) plus any supporting tools 
-used by any Ceedling plugins you enable.
-
-If you are familiar with the virtualization technology Docker, our premade
-Docker images will get you started with Ceedling and all the accompanying
-tools lickety split. Install Docker, pull down one of the
-[_MadScienceLab_](#madsciencelab-docker-images) images and go.
-
-## Installation as a [Ruby Gem][ruby-gem]
-
-!!! warning "Use `--no-document` for gem installation"
-    `--no-document` opts out of the RDoc tool’s automatic scanning of
-    Ceedling source code during installation. This documentation step is not 
-    needed by a user, and, more importantly, RDoc can cause installation 
-    failures due to bugs or language incompatibilities in RDoc’s custom 
-    language parser.
-
-1. [Download and install Ruby][ruby-install]. Ruby 3 is required.
-1. Use Ruby‘s command line gem package manager to install Ceedling from
-   the public [RubyGems repository][rubygems-repo]: `gem install ceedling --no-document`.
-    * Unity and CMock come along with Ceedling at no extra charge.
-    * Installing from the official RubyGems repository will automatically 
-      install Ceedling‘s dependencies.
-1. Use [Ceedling’s command line][command-line] to export an example 
-   project (`ceedling examples` for a listing) or create an empty Ceedling 
-   project with `ceedling new`. Of course, executing `ceedling help` first 
-   is, well, helpful.
-
-[ruby-gem]: http://docs.rubygems.org/read/chapter/1
-[ruby-install]: http://www.ruby-lang.org/en/downloads/
-[rubygems-repo]: http://rubygems.org
-[command-line]: 
-
-### Gem install notes
-
-Steps 1–2 above are a one-time affair for your local environment. 
-When steps 1-2 are completed once, only step 3 is needed for each new 
-code project.
-
-If you are working with prerelease versions of Ceedling or some other 
-off-the-beaten-path installation scenario, you may want to directly 
-install the Ceedling .gem file attached to any of the Github releases.
-No problem.
-
-The steps are similar to the preceding with two changes:
-
-1. `gem install --local <ceedling .gem filepath> --no-document`
-1. Any missing dependencies must be manually installed before 
-   installation of the local Ceedling gem will succeed. A local 
-   installation attempt will complain about any missing dependencies. 
-   Simply `gem install` them by name.
-
-## _MadScienceLab_ Docker Images
-
-As an alternative to local installation, fully packaged Docker images containing Ruby, Ceedling, the GCC toolchain, and more are also available. [Docker][docker-overview] is a virtualization technology that provides self-contained software bundles that are a portable, well-managed alternative to local installation of tools like Ceedling.
-
-Four Docker image variants containing Ceedling and supporting tools exist. These four images are available for both Intel and ARM host platforms (Docker does the right thing based on your host environment). The latter includes ARM Linux and Apple‘s M-series macOS devices.
-
-1. **_[MadScienceLab][docker-image-base]_**. This image contains Ruby, Ceedling, CMock, Unity, CException, the GNU Compiler Collection (gcc), and a handful of essential C libraries and command line utilities.
-1. **_[MadScienceLab Plugins][docker-image-plugins]_**. This image contains all of the above plus the command line tools that Ceedling‘s built-in plugins rely on. Naturally, it is quite a bit larger than option (1) because of the additional tools and dependencies.
-1. **_[MadScienceLab ARM][docker-image-arm]_**. This image mirrors (1) with the compiler toolchain replaced with the GNU `arm-none-eabi` variant. 
-1. **_[MadScienceLab ARM + Plugins][docker-image-arm-plugins]_**. This image is (3) with the addition of all the complementary plugin tooling just like (2) provides.
-
-See the Docker Hub pages linked above for more documentation on these images.
-
-Just to be clear here, most users of the _MadScienceLab_ Docker images will probably care about the ability to run unit tests on your own host. If you are one of those users, no matter what host platform you are on — Intel or ARM — you'll want to go with (1) or (2) above. The tools within the image will automatically do the right thing within your environment. Options (3) and (4) are most useful for specialized cross-compilation scenarios.
-
-!!! tip
-    If you are handy with Docker and want to create your own Docker image, please see the [MadScienceLab downloadable build artifacts](https://github.com/ThrowTheSwitch/MadScienceLabDocker/releases) at the source repository as a reference. The .zip archives for each release include the Dockerfiles and assets we used to build the MadScienceLab Docker images.
-
-### Usage basics
-
-To use a _MadScienceLab_ image from your local terminal:
-
-1. [Install Docker][docker-install]
-1. Determine:
-    1. The local path of your Ceedling project
-    1. The variant and revision of the Docker image you'll be using
-1. Run the container with:
-    1. The Docker `run` command and `-it --rm` command line options
-    1. A Docker volume mapping from the root of your project to the default project path inside the container (_/home/dev/project_)
-
-See the command line examples in the following two sections.
-
-Note that all of these somewhat lengthy command lines lend themselves well to being wrapped up in simple helper scripts specific to your project and directory structure.
-
-### Run as an interactive terminal
-
-When the container launches as shown below, it will drop you into a Z-shell command line that has access to all the tools and utilities available within the container. In this usage, the Docker container becomes just another terminal, including ending its execution with `exit`.
-
-```shell
- > docker run -it --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0
-```
-
-Once the _MadScienceLab_ container‘s command line is available, to run Ceedling, execute it just as you would after installing Ceedling locally:
-
-```shell
- ~/project > ceedling help
-```
-
-```shell
- ~/project > ceedling new ...
-```
-
-```shell
- ~/project > ceedling test:all
-```
-
-### Run as a command line utility
-
-Alternatively, you can run Ceedling through the _MadScienceLab_ Docker container directly from the command line as a command line utility. The general pattern is immediately below.
-
-```shell
- > docker run --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0 <Ceedling command line>
-```
-
-As a specific example, to run all tests in a suite, the command line would be this:
-
-```shell
- > docker run --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0 ceedling test:all
-```
-
-In this usage, the container starts, executes Ceedling, and then ends.
-
-[docker-overview]: https://www.ibm.com/topics/docker
-[docker-install]: https://www.docker.com/products/docker-desktop/
-
-[docker-image-base]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab
-[docker-image-plugins]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-plugins
-[docker-image-arm]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-arm-none-eabi
-[docker-image-arm-plugins]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-arm-none-eabi-plugins
-
-## Getting Started after installation
-
-1. Certain advanced features of Ceedling rely on `gcc` and `cpp` as
-   preprocessing tools. In most Linux systems, these tools are already available.
-   For Windows environments, we recommend the 
-   [MinGW project](http://www.mingw.org/) (Minimalist GNU for Windows). This 
-   represents an optional, additional setup / installation step to complement 
-   the list above. Upon installing MinGW ensure your system path is updated or 
-   set `:environment` ↳ `:path` in your project configuration (see `:environment`
-   section).
-
-1. Once Ceedling is installed, you'll want to start to integrate it with new
-   and old projects alike. If you wanted to start to work on a new project
-   named `foo`, Ceedling can create the skeleton of the project using `ceedling
-   new foo <destination>`. Likewise if you already have a project named `bar` 
-   and you want to "inject" Ceedling into it, you would run `ceedling new bar 
-   <destination>`, and Ceedling will create any files and directories it needs.
-
-1. Now that you have Ceedling integrated with a project, you can start using it.
-   A good starting point is to enable the [plugin](../plugins/index.md) 
-   `module_generator` in your project configuration file and create a source +
-   test code module to get accustomed to Ceedling by issuing the command 
-   `ceedling 'module:create[name]'`.
-
-<br/><br/>

data/docs/mkdocs/getting-started/quick-start.md

@@ -1,86 +0,0 @@
-# Quick Start
-
-For a test suite project using the default toolchain `gcc`, Ceedling’s
-configuration file could be as simple as this:
-
-```yaml
-:project:
-  :build_root: project/build/
-
-:paths:
-  :test:
-    - tests/**
-  :source:
-    - source/**
-  :include:
-    - inc/**
-```
-
-To execute all your unit tests, you would run `ceedling test:all`.
-
----
-
-## Handy Documentation
-
-* [Installation](installation.md)
-* [Sample test code file](../testing-guide/test-sample.md)
-* [Example Ceedling projects](example-projects/index.md)
-* [Simple Ceedling project file](../overview/build-system.md#simple-sample-project-file)
-* [Ceedling at the command line](command-line.md)
-* [All your project configuration file options](../configuration/index.md)
-
-## Quick Start Steps
-
-Below is a quick overview of how to get started from Ceedling installation 
-through running build tasks. Jump down just a teeny bit to see what the Ceedling 
-command line looks like and navigate to all the documentation for the steps 
-listed immediately below.
-
-!!! warning "C toolchain requirement"
-    Ceedling requires a command line C toolchain be available in your path and is
-    flexible enough to work with most anything. By default, Ceedling is ready to 
-    work with [GCC] out of the box (we recommend [MinGW] on Windows).
-
-1. [Install Ceedling](installation.md)
-1. Create a project
-    * Use Ceedling to generate an example project (see next section), or
-    * Add a Ceedling project file to the root of an existing project, or
-    * Create a project from scratch:
-        1. Create a project directory.
-        1. Add source code and optionally test code however you’d like it organized.
-        1. Create a Ceedling project file in the root of your project directory.
-1. Run Ceedling tasks (see next section) from the working directory of your project.
-
-A common build strategy is to use your target toolchain for release builds—with or 
-without Ceedling—but rely on Ceedling + GCC for test builds (more on this 
-[here][overview]).
-
-!!! tip "Ceedling VS Code extension"
-    If you are a Visual Studio Code user, you may want to install the
-    [Ceedling extension](https://marketplace.visualstudio.com/items?itemName=throw-the-switch.vscode-ceedling).
-
-[GCC]: https://gcc.gnu.org
-[MinGW]: http://www.mingw.org/
-[overview]: ../overview/index.md
-
-## Command Line & Build Tasks
-
-Once you have Ceedling installed, you always have access to `ceedling help`.
-
-Once you have Ceedling installed, you have options for project creation
-using Ceedling’s application commands:
-
-* `ceedling new <name> <destination>`
-* `ceedling examples` to list available example projects and 
-  `ceedling example <name> <destination>` to create a readymade sample 
-   project whose project file you can copy and modify.
-
-Once you have a Ceedling project file and a project directory structure for your
-code, Ceedling build tasks go like this:
-
-* `ceedling test:MyCodeModule`, or
-* `ceedling test:all`, or
-* `ceedling release`, or, if you fancy and have the GCov plugin enabled,
-* `ceedling clobber test:all gcov:all release --log --verbosity=obnoxious`
-
-<br/><br/>

data/docs/mkdocs/help.md

@@ -1,49 +0,0 @@
-# Help
-
-!!! sponsorship "Please consider sponsoring this project"
-    Ceedling, Unity, and CMock are free and open source, 
-    maintained by volunteers. [GitHub Sponsors](https://github.com/sponsors/ThrowTheSwitch) 
-    help fund ongoing maintenance, new features, and the infrastructure 
-    to host and develop the Ceedling Suite of tools.
-
-<div class="grid cards" markdown>
-
--   :material-bug: **[Submit an Issue][ceedling-issues]**
-
-    ---
-
-    Found a bug or want to suggest a feature? Open an issue in the Ceedling
-    GitHub repository.
-
--   :material-forum: **[Discourse Forums][forums]**
-
-    ---
-
-    Trying to understand a feature or work through a testing problem?
-    The ThrowTheSwitch community forums are the place to ask.
-
--   :material-handshake: **[Ceedling Assist][ceedling-assist]**
-
-    ---
-
-    Paid training, customizations, and support contracts are available
-    through [Ceedling Assist][ceedling-assist] offered by [ThingamaByte].
-
--   :material-school: **[Dr. Surly’s School For Mad Scientists][drsurlys-school]**
-
-    ---
-
-    A curriculum hosted at [Udemy](https://udemy.com) to promote good C development
-    techniques and embedded software practices through testing. So you too can
-    take over the world.
-
-</div>
-
-[ceedling-issues]:       https://github.com/ThrowTheSwitch/Ceedling/issues
-[forums]:                https://throwtheswitch.discourse.group
-[ceedling-assist]:       https://www.thingamabyte.com/ceedlingassist
-[ThingamaByte]:          https://www.thingamabyte.com/
-[thingamabyte-ceedling]: https://www.thingamabyte.com/ceedling
-[drsurlys-school]:       https://www.throwtheswitch.org/dr-surlys-school
-
-<br/><br/>

data/docs/mkdocs/index.md

@@ -1,222 +0,0 @@
-# Ceedling Packet
-
-Ceedling is a fancypants build system that greatly simplifies building 
-C projects. While it can certainly build release targets, it 
-shines at running unit test suites.
-
-!!! tip "New to Ceedling?"
-    <img src="assets/images/ceedling.svg" width="130"><br/>
-    Jump straight to the [Quick Start][quick-start] — installation,
-    project set up, and your first build tasks all in one place.
-
-In essence, Ceedling is a project configuration in YAML and a command line
-tool that executes from it. Code conventions and supporting features produce 
-executable test suites and/or release artifacts.
-Plugins provide reporting, code coverage, static analysis, and more.
-
-Ceedling and its suite of frameworks, including Unity and CMock, were developed 
-for use on platforms from heavy duty workstations to teeny tiny microcontrollers. 
-Features handy for low-level development have made these tools popular with 
-embedded systems developers.
-
-!!! feature "New in Ceedling 1.1.0 — Partials"
-    A [_Partial_](testing-guide/partials/index.md) is your C code sliced and diced
-    to expose functional elements for testing that you could not otherwise 
-    access without rewriting your source code. Think of Partials as a scalpel 
-    for testing your code.
-
-    👀 See the [Changelog](https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/Changelog.md)
-    for all the new goodness in 1.1.0.
-
----
-
-## Overview
-
-<div class="grid cards" markdown>
-
--   :material-hammer-wrench: **[A Build System for C][build-system]**
-
-    ---
-
-    Generate a complete test and release build from a single YAML file.
-    Provides a minimal sample project configuration and an explanation of Ceedling’s
-    design philosophy.
-
--   :material-toolbox: **[Tools & Frameworks][tools-and-frameworks]**
-
-    ---
-
-    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]**
-
-    ---
-
-    Native host builds, emulator-based runs, and on-target execution — choose the
-    right test suite strategy for your project.
-
-</div>
-
-## Getting Started
-
-<div class="grid cards" markdown>
-
--   :material-rocket-launch: **[Quick Start][quick-start]**
-
-    ---
-
-    Ready to go? Let’s go.
-
--   :material-download: **[Ceedling Installation & Set Up][installation]**
-
-    ---
-
-    Installing Ceedling and its prerequisites.
-
--   :material-console: **[Ceedling’s Command Line.][command-line]**
-
-    ---
-
-    Now what? How do I make it _Go_?
-
-</div>
-
-## Unit Testing
-
-<div class="grid cards" markdown>
-
--   :material-help-circle: **[How Does a Test Case Even Work?][test-cases]**
-
-    ---
-
-    A brief overview of what a test case is with simple examples illustrating
-    how test cases work.
-
--   :material-file-code: **[Commented Sample Test File][test-sample]**
-
-    ---
-
-    A sample test file illustrating test case creation and the conventions
-    that make it work. Includes a discussion of how test executables get built.
-
--   :material-layers: **[Anatomy of a Test Suite][test-suite-anatomy]**
-
-    ---
-
-    How a unit test grows up to become a test suite.
-
--   :material-link-variant: **[Using Unity and CMock][frameworks]**
-
-    ---
-
-    Ceedling links together Unity and CMock — each of which can
-    require configuration of their own. Ceedling facilitates this.
-
--   :material-book-open-page-variant: **[Important Conventions & Behaviors][conventions]**
-
-    ---
-
-    Much of testing in Ceedling is accomplished by convention.
-    Code and files structured and named in certain ways trigger sophisticated build
-    features.
-
--   :material-content-cut: **[Partials][partials]**
-
-    ---
-
-    Partials are like a scalpel for your source code. A generated partial allows 
-    you to test and mock parts of your code you could not otherwise access
-    without rewriting it first.
-</div>
-
-## Project Configuration
-
-<div class="grid cards" markdown>
-
--   :material-file-import: **[How to Load a Project Configuration][configuration-loading]**
-
-    ---
-    You have options, my friend. Load your base configuration via command line 
-    flag, environment variable, or default file. Add Mixins to merge configuration 
-    for different build scenarios.
-
--   :material-file-cog: **[The Mighty Project Configuration File][configuration-project-file]**
-
-    ---
-
-    Everything you need to know about the project configuration file. All in 
-    glorious YAML.
-
--   :material-book-open-variant: **[Project Configuration Reference][configuration-reference]**
-
-    ---
-
-    Exhaustive documentation for all project configuration options — project
-    paths, testing features, plugins, and much more.
-
--   :material-clipboard-play-multiple-outline: **[Parallel Builds][parallel-builds]**
-
-    ---
-
-    Configure Ceedling to take advantage of multiple CPU cores for faster build
-    steps and test suite execution.
-
--   :material-directions-fork: **[Which Ceedling?][which-ceedling]**
-
-    ---
-
-    Sometimes you may need to point to a different Ceedling to run.
-
-</div>
-
-## Advanced & Extending
-
-<div class="grid cards" markdown>
-
--   :material-pound: **[Build Directive Macros][build-directives]**
-
-    ---
-
-    Code macros to accomplish build goals when Ceedling's conventions aren't
-    quite enough.
-
--   :material-puzzle-plus: **[Ceedling Plugins][plugins]**
-
-    ---
-
-    Ceedling is extensible with built-in plugins for code coverage, test reporting,
-    CI integration, file scaffolding, sophisticated release builds, and more.
-
--   :material-database: **[Global Collections][global-collections]**
-
-    ---
-
-    Globally available Ruby lists of paths, files, and more — useful for advanced
-    project customization and plugin development.
-
-</div>
-
-[quick-start]:                 getting-started/quick-start.md
-[build-system]:                overview/build-system.md
-[tools-and-frameworks]:        overview/tools-and-frameworks.md
-[testing-abilities]:           overview/testing-abilities.md
-[test-environments]:           overview/test-environments.md
-[test-cases]:                  testing-guide/test-cases.md
-[test-sample]:                 testing-guide/test-sample.md
-[test-suite-anatomy]:          testing-guide/test-suite-anatomy.md
-[partials]:                    testing-guide/partials/index.md
-[installation]:                getting-started/installation.md
-[command-line]:                getting-started/command-line.md
-[conventions]:                 testing-guide/conventions.md
-[frameworks]:                  testing-guide/frameworks.md
-[configuration-loading]:       configuration/loading.md
-[configuration-project-file]:  configuration/project-file.md
-[configuration-reference]:     configuration/reference/index.md
-[parallel-builds]:             configuration/parallel-builds.md
-[which-ceedling]:              configuration/which-ceedling.md
-[build-directives]:            testing-guide/build-directives.md
-[plugins]:                     plugins/index.md
-[global-collections]:          configuration/global-collections.md
-
-<br/><br/>