ceedling 0.9.0 → 1.0.1

data/docs/ReleaseNotes.md

@@ -0,0 +1,353 @@
+# 🌱 Ceedling Release Notes
+
+These release notes are complemented by two other documents:
+
+1. 🪵 **[Changelog](Changelog.md)** for a structured list of additions, fixes, changes, and removals.
+1. 💔 **[Breaking Changes](BreakingChanges.md)** for a list of impacts to existing Ceedling projects.
+
+---
+
+# 1.0.1 - January 30, 2025
+
+This is a collection of bugfixes found after the 1.0.0 release. If you are upgrading from a pre-1.0 release of Ceedling, we highly recommend reading the `1.0.0` release notes as well!
+
+See [Changelog](Changelog.md) for a full list of bugfixes and improvements.
+
+The most significant issues addressed with this release are problems with preprocessor handling, particularly when discovering which header files are required for each test. If you were running into similar problems with `1.0.0`, we highly recommend this upgrade.
+
+# 1.0.0 — January 01, 2025
+
+**This Ceedling release is probably the most significant since the project was first [posted to SourceForge in 2009][sourceforge].**
+
+Ceedling now runs in Ruby 3. Builds can now run much faster than previous versions because of parallelized tasks. In test suites, header file search paths, code defines, and tool run flags are now customizable per test executable. Ceedling now also offers integrated debugging options to find the cause of crashing tests.
+
+* See all the [Highlights](#-highlights) below for an overview of everything in this big release.
+* See the [Changelog](Changelog.md) for a detailed list of new features, fixes, and changes in this release.
+* We’ve included below a [project configuration cheatsheet](#-project-configuration-cheatsheet-for-100-changes) for those already familiar with Ceedling that want to understand the various configuration changes.
+
+## 🏴‍☠️ Avast, Breaking Changes, Ye Scallywags!
+
+**_Ahoy!_** There be plenty o’ **[breaking changes](BreakingChanges.md)** ahead too, mateys! Arrr…
+
+## 📣 Shout-outs and Special Thank-You’s
+
+A **HUGE** Thanks to the ThrowTheSwitch.org community, for continuing to use, critique, and contribute to these tools. We're making the C world a better place and we appreciate all of you!
+
+We'd like to make some quick shout-outs to some especially helpful contributions. THANK YOU!
+
+  -- Mark VanderVoord & Machael Karlesky, ThrowTheSwitch.org Project Maintainers
+
+### Sponsors of Ceedling 1.0.0
+
+ - [ThingamaByte, LLC](https://thingamabyte.com) - For continuing to nurture these projects and community with so much of their time.
+ - [Kamstrup, A/S](https://kamstrup.com) - For sponsoring and testing Ceedling's new parallel build/test support
+ - [Fraunhofer Institute for Integrated Systems and Device Technology IISB](https://iisb.fraunhofer.de) - For also sponsoring and testing Ceedling's new parallel build/test support
+ - [Peter Membrey](https://github.com/pmembrey) - For sponsoring, helping to plan, and validating Ceedling's new dependencies plugin
+
+### Major Code/Doc Contributors 
+
+These individuals contributed significant features, bugfixes, and improvements. This list was generated by git, so if you feel you should be here, you're probably right. Please let us know and we're very sorry to have missed you!
+
+ - Dom Postorivo
+ - Cezary Gapinski
+ - Aaron Schlicht
+ - Tim Bates
+ - Patrick Junger
+ - Austin Glaser
+ - Łukasz Żegliński
+ - Anthony Male
+ - Peter Membrey
+ - Laurens Miers
+ - Alejandro Rosso
+ - Tony Webb
+ - Greg Williams
+ - John Van Enk
+ - Job Vranish
+
+### Major Forum Contributors
+
+These individuals have been a huge help in answering questions and guiding newcomers on our forums. Thanks for making this a welcoming community!
+
+ - @Letme
+ - @dpostorivo
+ - @swaldhoer
+ - @CezaryGapinski
+ - @aschlicht
+
+### Also, thanks for your contributions!
+
+Hiroaki Yamazoe, Lucas Becker, Rafael Campos Las Heras, Scott Vokes, Zane D. Purvis, Данила Вальковец, Aaron Schlicht,
+Carl-Oskar Larsson, Javier Tiá, Jesper L. Nielsen, MrRedKite, Nik Krause, Rasmus Melchior Jacobsen, serjche, 
+Andrei Korigodskii, Eder Clayton, Felipe Balbi, Hannes Bachl, Mike D. Lowis, Peter Horn, Rasmus Uth Pedersen, 
+Simon Grossenbacher, AlexandreMarkus, André Draszik, Aurelien CHAPPUIS, Austin Yates, Ben Wainwright, 
+Christopher Cichiwskyj, Crt Mori, Horacio Mijail Antón Quiles, John Hutchinson, Joseph Gaudet, Julien Peyregne, KGons,
+Kalle Møller, Peter Kempter, Luca Cavalli, Maksim Chichikalov, Marcelo Jo, Matt Chernosky, Niall Cooling, 
+Olivier C. Larocque, Patrick Little, Richard Eklycke, Serjche, Spencer Russell, Stavros Vagionitis, Steven Huang,
+Toby Mole, Tom Hotston, Yuanqing Liu, afacotti, ccarrizosa, diachini, Steven Willard
+
+## 📖 Project Configuration Cheatsheet for 1.0.0 Changes
+
+The following is not a complete project configuration. But, for those already familiar with Ceedling, this cheatsheet illustrates some of the important changes in this latest release of Ceedling through the lens of a project configuration.
+
+To be clear, more has changed than what is referenced in this YAML blurb. Most notably:
+
+* Ceedling’s command line is more robust and conforms to common CLI conventions.
+* Various plugins have grown in functionality and changed in name and configuration convention.
+* Build directive macros are available that provide build customization abilities through their use in your test files.
+
+```yaml
+# Mixins are an all new feature that allow you to easily merge alternate project configurations.
+# Mixins replace a variety of other features, namely the :import project file section and option: command line task.
+# A frequent need is a base project configuration complemented by variants of projects for different flavors of the same codebase. Mixins provide the features to support these kinds of needs.
+# Mixins have few limitations as compared to the features Mixins replace.
+# Mixins can be merged from within your project configuration file (shown here), from paths in environment variables, and from command line --mixin path switches.
+# ---------------------------
+:mixins:
+  :enabled:             # :enabled list supports names and filepaths
+    - enabled           # Look for enabled.yml in load paths and merge if found
+    - my/mixin/cfg.yml  # A full path to a configuration file to merge
+  :load_paths:          # Load paths to search for mixins specified by name only in :enabled
+    - support/mixins
+
+# Importing project configuration files with :import is superseded by the more capable Mixins (above).
+# ---------------------------
+# :import:
+#  - path/to/config.yml
+
+:project:
+  # Ceedling is now multi-threaded for speedy builds.
+  # The default is a single thread (setting of 1). :auto tells Ceedling to query your system and make an educated guess on a number of threads to use.
+  # Threading is broken into two categories to provide for controlling threading where build tooling and test executable tooling have different restrictions.
+  # ---------------------------
+  :compile_threads: :auto
+  :test_threads: :auto
+
+  # Ceedling's preprocessing abilities have been totally revamped to fix bugs, eliminate complexity, and improve results.
+  # Preprocessing can now be selectively applied to test files and to mockable headers using options :none, :mocks, :tests, or :all.
+  # ---------------------------
+  :use_test_preprocessor: :all
+
+  # The following configuration options have been deprecated.
+  # These are no longer available as the underlying functionality has been reimplemented with no need to configure it.
+  # If these settings remain in your configuration file, they are harmless but do zilch for you.
+  # ---------------------------
+  # :use_deep_dependencies
+  # :generate_deep_dependencies
+  # :auto_link_deep_dependencies
+
+  # Backtrace is an all new feature in Ceedling.
+  # When enabled (default is :simple), backtrace figures out which test case in a crashed test executable is exercising the bug causing you grief.
+  # If the :gdb option is enabled (and the GNU debugger is installed), Ceedling will provide you the trace to the line of code causing a test case to crash.
+  # ---------------------------
+  :use_backtrace: :simple
+
+# Complemeneting its existing abilities to build assembly code as part of a release artifact, Ceedling can now also incorporate assembly code into test builds.
+# See CeedlingPacket for full details on how to make use of this feature after enabling it.
+# In short, your assembly code will need to be findable in your project paths, and you will need to use the new test directive macro TEST_SOURCE_FILE() inside your test files to tell Ceedling which assembly file to include in the respective test executable build.
+:test_build:
+  :use_assembly: TRUE
+
+# Ceedling executables are now built as self-contained mini-projects.
+# You can now define symbols for a release build and each test executable build.
+# Symbols defined for a test executable are applied during compilation for each component of the executable.
+# The :defines section supports several syntaxes. 
+#  - Sophisticated matchers are available for test executable builds (shown here).
+#  - Simple lists to apply flags to all files in a build step are supported for release builds (only option) and test builds. 
+# See Ceedling Packet for details.
+# ---------------------------
+:defines:
+  :test:
+    :*:                 #  Wildcard: Add '-DA' for compilation of all files for all tests
+      - A               
+    :Model:             # Substring: Add '-DCHOO' for compilation of all files of any test with 'Model' in its name
+      - CHOO            
+    :/M(ain|odel)/:     #     Regex: Add '-DBLESS_YOU' for all files of any test with 'Main' or 'Model' in its name
+      - BLESS_YOU       
+    :Comms*Model:       #  Wildcard: Add '-DTHANKS' for all files of any test that have zero or more characters
+      - THANKS          #            between 'Comms' and 'Model'
+
+  :release:
+    - FEATURE_X=ON      # Add these two symbols to compilation of all release C files (:test supports this syntax too)
+    - PRODUCT_CONFIG_C
+
+# Ceedling executables are now built as self-contained mini-projects.
+# Flags can be specified for each build step and for each component of a build step.
+# The :flags section supports several syntaxes. 
+#  - Sophisticated matchers are available for test executable builds (shown here).
+#  - Simple lists to apply flags to all files in a build step are supported for release builds (only option) and test builds. 
+# See Ceedling Packet for details.
+# ---------------------------
+:flags:
+  :test:
+    :compile:
+      :*:               #  Wildcard: Add '-foo' for all files for all tests
+        - -foo          
+      :Model:           # Substring: Add '-Wall' for all files of any test with 'Model' in its name
+        - -Wall 
+      :/M(ain|odel)/:   #     Regex: Add 🏴‍☠️ flag for all files of any test with 'Main' or 'Model' in its name
+        - -🏴‍☠️ 
+      :Comms*Model: 
+        - --freak       #  Wildcard: Add your `--freak` flag for all files of any test name with zero or more
+                        #            characters between 'Comms' and 'Model'
+  :release: 
+    :compile: 
+      - -std=c99        # Add `-std=c99` to compilation of all release build C files (:test supports this syntax too)
+
+# Ceedling’s Unity configuration now properly supports test executable builds for Unity's parameterized test cases.
+# Previously a handful of settings were required throughout a project configuration to successfully use these abilities.
+# ---------------------------
+:unity:
+  :use_param_tests: TRUE
+
+```
+
+## 👀 Highlights
+
+### Big Deal Highlights 🏅
+
+#### Ruby3
+
+Ceedling now runs in Ruby3. This latest version of Ceedling is _not_ backwards compatible with earlier versions of Ruby.
+
+#### Way faster execution with parallel build steps
+
+Previously, Ceedling builds were depth-first and limited to a single line of execution. This limitation was an artifact of how Ceedling was architected and relying on general purpose Rake for the build pipeline. Rake does, in fact, support multi-threaded builds, but, Ceedling was unable to take advantage of this. As such, builds were limited to a single line of execution no matter how many CPU resources were available.
+
+Ceedling 1.0.0 introduces a new build pipeline that batches build steps breadth-first. This means all test preprocessor steps, all compilation steps, all linking steps, etc. can benefit from concurrent and parallel execution. This speedup applies to both test suite and release builds.
+
+#### Per-test-executable configurations
+
+In previous versions of Ceedling each test executable was built with essentially the same global configuration. In the case of `#define`s and tool command line flags, individual files could be handled differently, but configuring Ceedling for doing so for all the files in any one test executable was tedious and error prone.
+
+Now Ceedling builds each test executable as a mini project where header file search paths, compilation `#define` symbols, and tool flags can be specified per test executable. That is, each file that ultimately comprises a test executable is handled with the same configuration as the other files that make up that test executable.
+
+Now you can have tests with quite different configurations and behaviors. Two tests need different mocks of the same header file? No problem. You want to test the same source file two different ways? We got you.
+
+The following new features (discussed in later sections) contribute to this new ability:
+
+- `TEST_INCLUDE_PATH(...)`. This build directive macro can be used within a test file to tell Ceedling which header search paths should be used during compilation. These paths are only used for compiling the files that comprise that test executable.
+- `:defines` handling. `#define`s are now specified for the compilation of all modules comprising a test executable. Matching is only against test file names but now includes wildcard and regular expression options.
+- `:flags` handling. Flags (e.g. `-std=c99`) are now specified for the build steps — preprocessing, compilation, and linking — of all modules comprising a test executable. Matching is only against test file names and now includes more sensible and robust wildcard and regular expression options.
+
+#### Mixins for configuration variations
+
+Ever wanted to smoosh in some extra configuration selectively? Let’s say you have different build scenarios and you'd like to run different variations of your project for them. Maybe you have core configuration that is common to all those scenarios. Previous versions of Ceedling included a handful of features that partially met these sorts of needs.
+
+All such features have been superseded by _Mixins_. Mixins are simply additional YAML that gets merged into you base project configuration. However, Mixins provide several key improvements over previous features:
+
+1. Mixins can be as little or as much configuration as you want. You could push all your configuration into mixins with a base project file including nothing but a `:mixins` section.
+1. Mixins can be specified in your project configuration, via environment variables, and from the command line. A clear order of precedence controls the order of merging. Any conflicts or duplicates are automatically resolved.
+1. Logging makes clear what proejct file and mixins are loaded and merged at startup.
+1. Like built-in plugins, Ceedling will soon come with built-in mixins available for common build scenarios.
+
+#### A proper command line
+
+Until this release, Ceedling depended on Rake for most of its command line handling. Rake’s task conventions provide poor command line handling abilities. The core problems with Rake command line handling include:
+
+1. Only brief, limited help statements.
+1. No optional flags to modify a task — verbosity, logging, etc. were their own tasks.
+1. Complex/limited parameterization (e.g. `verbosity[3]` instead of `--verbosity normal`).
+1. Tasks are order-dependent. So, for example, `test:all verbosity[5]` changes verbosity after the tests are run.
+
+Ceedling now offers a full command line interface with rich help, useful order-independent option flags, and more.
+
+The existing `new`, `upgrade`, `example`, and `exampples` commands remain but have been improved. For those commands that support it, you may now specify the project file to load (see new, related mixins feature discussed elsewhere), log file to write to, exit code handling behavior, and more from the command line.
+
+Try `ceedling help` and then `ceedling help <command>` to get started.
+
+**_Important Notes on the New Command Line:_**
+
+* The new and improved features for running build tasks — loading a project file, merging mixins, verbosity handling, etc. — are documented within the application command `build` keyword. A build command line such as the following is now possible: `ceedling test:all --verbosity obnoxious --logfile my/path/build.log`. Run `ceedling help build` to learn more and definitely see the next bullet point as well.
+* The `build` keyword is assumed by Ceedling. That is, it’s optional. `ceedling test:all` is the same as `ceedling build test:all`. The `build` keyword handling tells the Ceedling application to execute the named build task dynamically generated from your project configuration. 
+* In the transition to remove Rake from Ceedling, two categories of command line interactions now exist. Note this distinction in the `help` headings.
+   1. **Application Commands** — `help`, `build`, `new`, `upgrade`, `environment`, `examples`, `example`, `dumpconfig`, and `version`. These have full help via `ceedling help <command>` and a variety of useful command line switches that conform to typical command line conventions.
+   1. **Build & Plugin Tasks** — Operations dynamically generated from your project configuration. These have only summary help (listed in `ceedling help`) and work just as they previously did. Common command line tasks including `ceedling test:all` and `ceedling release` are in this category.
+
+### Medium Deal Highlights 🥈
+
+#### `TEST_SOURCE_FILE(...)`
+
+In previous versions of Ceedling, a new, undocumented build directive feature was introduced. Adding a call to the macro `TEST_FILE(...)` with a C file’s name added that C file to the compilation and linking list for a test executable.
+
+This approach was helpful when relying on a Ceedling convention was problematic. Specifically, `#include`ing a header file would cause any correspondingly named source file to be added to the build list for a test executable. This convention could cause problems if, for example, the header file defined symbols that complicated test compilation or behavior. Similarly, if a source file did not have a corresponding header file of the same name, sometimes the only option was to `#include` it directly; this was ugly and problematic in its own way.
+
+The previously undocumented build directive macro `TEST_FILE(...)` has been renamed to `TEST_SOURCE_FILE(...)` and is now [documented](CeedlingPacket.md).
+
+#### Preprocessing improvements
+
+Ceedling has been around for a number of years and has had the benefit of many contributors over that time. Preprocessing (e.g. expanding macros in test files and header files to be mocked) is quite tricky to get right but is essential for big, complicated test suites. Over Ceedling’s long life various patches and incremental improvements have evolved in such a way that preprocessing had become quite complicated and often did the wrong thing. Much of this has been fixed and improved in this release. Considerable memory and performance improvements have been made as well.
+
+#### Test Suite Crash Handling
+
+Previously, if a test executable ran into a segmentation fault (usually caused by memory issues in the code), the entire test executable would report nothing but a simple error. This behavior has been expanded to handle any crash condition and further improved.
+
+By default, a crashed test executable is automatically rerun for each test case individually to narrow down which test case(s) caused the problem. If `gdb` is properly installed and configured the specific line that caused the crash can be reported.
+
+The `:simple` and `:gdb` options for this feature fully and correctly report each test case’s status for a crashed test executable. Crashed test cases are counted as failures. The `:none` option does not run each test case individually. Instead, in the case of crashed test executable, it marks each test case as a failure reporting that the entire test executable crashed.
+
+See _[CeedlingPacket](CeedlingPacket.md))_ for the new `:project` ↳ `:use_backtrace` feature to control how much detail is extracted from a crashed test executable to help you find the cause.
+
+#### Test builds can now incorporate assembly code
+
+See the documentation for `:test_build` ↳ `:use_assembly` to understand how to incorporate assembly code into a given test executable’s build. This complementes Ceedling’s existing ability to incorporate assembly code in a release artifact build.
+
+#### Configuration defaults and configuration set up order
+
+Ceedling’s previous handling of defaults and configuration processing order certainly worked, but it was not as proper as it could be. To oversimplify, default values were applied in an ordering that caused complications for advanced plugins and advanced users. This has been rectified. Default settings are now processed after all user configurations and plugins.
+
+#### Documentation
+
+The Ceedling user guide, _[CeedlingPacket](CeedlingPacket.md)_, has been significantly revised and expanded. We will expand it further in future releases and eventually break it up into multiple documents or migrate it to a full documentation management system.
+
+Many of the plugins have received documentation updates as well.
+
+There’s more to be done, but Ceedling’s documentation is more complete and accurate than it’s ever been.
+
+### Small Deal Highlights 🥉
+
+- Effort has been invested across the project to improve error messages, exception handling, and exit code processing. Noisy backtraces have been relegated to the verbosity level of DEBUG as <insert higher power> intended.
+- Logical ambiguity and functional bugs within `:paths` and `:files` configuration handling have been resolved along with updated documentation.
+- A variety of small improvements and fixes have been made throughout the plugin system and to many plugins.
+- The historically unwieldy `verbosity` command line task now comes in two flavors. The original recipe numeric parameterized version (e.g. `[4]`) exist as is. The new extra crispy recipe includes — funny enough — verbose task names `verbosity:silent`, `verbosity:errors`, `verbosity:complain`, `verbosity:normal`, `verbosity:obnoxious`, `verbosity:debug`. 
+- This release marks the beginning of the end for Rake as a backbone of Ceedling. Over many years it has become clear that Rake’s design assumptions hamper building the sorts of features Ceedling’s users want, Rake’s command line structure creates a messy user experience for a full application built around it, and Rake’s quirks cause maintenance challenges. Particularly for test suites, much of Ceedling’s (invisible) dependence on Rake has been removed in this release. Much more remains to be done, including replicating some of the abilities Rake offers.
+- This is the first ever release of Ceedling with proper release notes. Hello, there! Release notes will be a regular part of future Ceedling updates. If you haven't noticed already, this edition of the notes are detailed and quite lengthy. This is entirely due to how extensive the changes are in the 1.0.0 release. Future releases will have far shorter notes.
+- Optional Unicode and emoji decorators have been added for your output stream enjoyment. See the documentation for logging decorators in _[CeedlingPacket](CeedlingPacket.md)_.
+
+## 🚨 Important Changes in Behavior to Be Aware Of
+
+- **Test suite build order 🔢.** Ceedling no longer builds each test executable one at a time. From the tasks you provide at the command line, Ceedling now collects up and batches all preprocessing steps, all mock generation, all test runner generation, all compilation, etc. Previously you would see each of these done for a single test executable and then repeated for the next executable and so on. Now, each build step happens to completion for all specified tests before moving on to the next build step. 
+- **Logging output order 🔢.** When multi-threaded builds are enabled, logging output may not be what you expect. Progress statements may be all batched together or interleaved in ways that are misleading. The steps are happening in the correct order. How you are informed of them may be somewhat out of order.
+- **Files generated multiple times 🔀.** Now that each test is essentially a self-contained mini-project, some output may be generated multiple times. For instance, if the same mock is required by multiple tests, it will be generated multiple times. The same holds for compilation of source files into object files. A coming version of Ceedling will concentrate on optimizations to reuse any output that is truly identical across tests.
+- **Test suite plugin runs 🏃🏻.** Because build steps are run to completion across all the tests you specify at the command line (e.g. all the mocks for your tests are generated at one time) you may need to adjust how you depend on build steps.
+
+Together, these changes may cause you to think that Ceedling is running steps out of order or duplicating work. While bugs are always possible, more than likely, the output you see and the build ordering is expected.
+
+## 🩼 Known Issues
+
+1. The new internal pipeline that allows builds to be parallelized and configured per-test-executable can mean a fair amount of duplication of steps. A header file may be mocked identically multiple times. The same source file may be compiled identically multiple times. The speed gains due to parallelization help make up for this. Future releases will concentrate on optimizing away duplication of build steps.
+1. While header file search paths are now customizable per executable, this currently only applies to the search paths the compiler uses. Distinguishing test files or header files of the same name in different directories for test runner and mock generation respectively continues to rely on educated guesses in Ceedling code.
+1. Any path for a C file specified with `TEST_SOURCE_FILE(...)` is in relation to **_project root_** — that is, from where you execute `ceedling` at the command line. If you move source files or change your directory structure, many of your `TEST_SOURCE_FILE(...)` calls may need to be updated. A more flexible and dynamic approach to path handling will come in a future update.
+1. Ceedling’s many test preprocessing improvements are not presently able to preserve Unity’s special `TEST_CASE()` and `TEST_RANGE()` features. However, preprocessing of test files is much less frequently needed than preprocessing of mockable header files. Test preprocessing can now be configured to enable only one or the other. As such, these advanced Unity features can still be used in even sophisticated projects.
+
+## 📚 Background Knowledge
+
+### Parallel execution of build steps
+
+You may have heard that Ruby is actually only single-threaded or may know of its Global Interpreter Lock (GIL) that prevents parallel execution. To oversimplify a complicated subject, the Ruby implementations most commonly used to run Ceedling afford concurrency and true parallelism speedups but only in certain circumstances. It so happens that these circumstances are precisely the workload that Ceedling manages.
+
+“Mainstream” Ruby implementations — not JRuby, for example — offer the following that Ceedling takes advantage of:
+
+#### Native thread context switching on I/O operations
+
+Since version 1.9, Ruby supports native threads and not only green threads. However, native threads are limited by the GIL to executing one at a time regardless of the number of cores in your processor. But, the GIL is “relaxed” for I/O operations.
+
+When a native thread blocks for I/O, Ruby allows the OS scheduler to context switch to a thread ready to execute. This is the original benefit of threads when they were first developed back when CPUs contained a single core and multi-processor systems were rare and special. Ceedling does a fair amount of file and standard stream I/O in its pure Ruby code. Thus, when multiple threads are enabled in the proejct configuration file, execution can speed up for these operations.
+
+#### Process spawning
+
+Ruby’s process spawning abilities have always mapped directly to OS capabilities. When a processor has multiple cores available, the OS tends to spread multiple child processes across those cores in true parallel execution.
+
+Much of Ceedling’s workload is executing a tool — such as a compiler — in a child process. With multiple threads enabled, each thread can spawn a child process for a build tool used by a build step. These child processes can be spread across multiple cores in true parallel execution.
+
+
+[sourceforge]: https://sourceforge.net/projects/ceedling/ "Ceedling’s public debut"

data/docs/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for all `ThrowTheSwitch.org`
+projects, including `Unity`, `CMock`, and `Ceedling`.
+
+  * [Reporting a Bug](#reporting-a-bug)
+  * [Disclosure Policy](#disclosure-policy)
+  * [Comments on this Policy](#comments-on-this-policy)
+
+## Reporting a Bug
+
+The tools from `ThrowTheSwitch.org` are made to collaborate with other tools like compilers, 
+simulators, and such, and therefore have very low-level access to the world they live in. 
+However, they are typically used in controlled development-centered environments. As such, 
+they are typically not directly exposed to security concerns. 
+
+The `ThrowTheSwitch.org` community takes security bugs seriously. Where possible, we will
+make every effort to improve our tools safe use. Thank you for improving the security of 
+our tools. We appreciate your efforts and responsible disclosure and will make every effort 
+to acknowledge your contributions.
+
+Report security bugs by opening a Github Issue on the corresponding project or (when this
+itself would pose a risk) by emailing security@thingamabyte.com.
+
+Report security bugs in third-party modules to the person or team maintaining
+the module.
+
+## Disclosure Policy
+
+Each issue will be assigned to a primary handler. This person will coordinate the fix and 
+release process, involving the following steps:
+
+  * Confirm the problem and determine the affected versions.
+  * Audit code to find any potential similar problems.
+  * Prepare fixes for all releases still under maintenance. These fixes will be
+    released as fast as possible.
+
+## Comments on this Policy
+
+If you have suggestions on how this process could be improved please submit a
+pull request.

data/docs/ThrowTheSwitchCodingStandard.md

@@ -0,0 +1,207 @@
+# ThrowTheSwitch.org Coding Standard
+
+Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part,
+we try to follow these standards to unify our contributors' code into a cohesive
+unit (puns intended). You might find places where these standards aren't
+followed. We're not perfect. Please be polite where you notice these discrepancies
+and we'll try to be polite when we notice yours.
+
+;)
+
+
+## Why Have A Coding Standard?
+
+Being consistent makes code easier to understand. We've made an attempt to keep
+our standard simple because we also believe that we can only expect someone to
+follow something that is understandable. Please do your best.
+
+
+## Our Philosophy
+
+Before we get into details on syntax, let's take a moment to talk about our
+vision for these tools. We're C developers and embedded software developers.
+These tools are great to test any C code, but catering to embedded software has
+made us more tolerant of compiler quirks. There are a LOT of quirky compilers
+out there. By quirky I mean "doesn't follow standards because they feel like
+they have a license to do as they wish."
+
+Our philosophy is "support every compiler we can". Most often, this means that
+we aim for writing C code that is standards compliant (often C89... that seems
+to be a sweet spot that is almost always compatible). But it also means these
+tools are tolerant of things that aren't common. Some that aren't even
+compliant. There are configuration options to override the size of standard
+types. There are configuration options to force Unity to not use certain
+standard library functions. A lot of Unity is configurable and we have worked
+hard to make it not TOO ugly in the process.
+
+Similarly, our tools that parse C do their best. They aren't full C parsers
+(yet) and, even if they were, they would still have to accept non-standard
+additions like gcc extensions or specifying `@0x1000` to force a variable to
+compile to a particular location. It's just what we do, because we like
+everything to Just Work™.
+
+Speaking of having things Just Work™, that's our second philosophy. By that, we
+mean that we do our best to have EVERY configuration option have a logical
+default. We believe that if you're working with a simple compiler and target,
+you shouldn't need to configure very much... we try to make the tools guess as
+much as they can, but give the user the power to override it when it's wrong.
+
+
+## Naming Things
+
+Let's talk about naming things. Programming is all about naming things. We name
+files, functions, variables, and so much more. While we're not always going to
+find the best name for something, we actually put quite a bit of effort into
+finding *What Something WANTS to be Called*™.
+
+When naming things, we more or less follow this hierarchy, the first being the
+most important to us (but we do all four whenever possible):
+1. Readable
+2. Descriptive
+3. Consistent
+4. Memorable
+
+
+#### Readable
+
+We want to read our code. This means we like names and flow that are more
+naturally read. We try to avoid double negatives. We try to avoid cryptic
+abbreviations (sticking to ones we feel are common).
+
+
+#### Descriptive
+
+We like descriptive names for things, especially functions and variables.
+Finding the right name for something is an important endeavor. You might notice
+from poking around our code that this often results in names that are a little
+longer than the average. Guilty. We're okay with a tiny bit more typing if it
+means our code is easier to understand.
+
+There are two exceptions to this rule that we also stick to as religiously as
+possible:
+
+First, while we realize hungarian notation (and similar systems for encoding
+type information into variable names) is providing a more descriptive name, we
+feel that (for the average developer) it takes away from readability and
+therefore is to be avoided.
+
+Second, loop counters and other local throw-away variables often have a purpose
+which is obvious. There's no need, therefore, to get carried away with complex
+naming. We find i, j, and k are better loop counters than loopCounterVar or
+whatnot. We only break this rule when we see that more description could improve
+understanding of an algorithm.
+
+
+#### Consistent
+
+We like consistency, but we're not really obsessed with it. We try to name our
+configuration macros in a consistent fashion... you'll notice a repeated use of
+UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to
+remember each macro's details.
+
+
+#### Memorable
+
+Where ever it doesn't violate the above principles, we try to apply memorable
+names. Sometimes this means using something that is simply descriptive, but
+often we strive for descriptive AND unique... we like quirky names that stand
+out in our memory and are easier to search for. Take a look through the file
+names in Ceedling and you'll get a good idea of what we are talking about here.
+Why use preprocess when you can use preprocessinator? Or what better describes a
+module in charge of invoking tasks during releases than release_invoker? Don't
+get carried away. The names are still descriptive and fulfill the above
+requirements, but they don't feel stale.
+
+
+## C and C++ Details
+
+We don't really want to add to the style battles out there. Tabs or spaces?
+How many spaces? Where do the braces go? These are age-old questions that will
+never be answered... or at least not answered in a way that will make everyone
+happy.
+
+We've decided on our own style preferences. If you'd like to contribute to these
+projects (and we hope that you do), then we ask if you do your best to follow
+the same. It will only hurt a little. We promise.
+
+
+#### Whitespace
+
+Our C-style is to use spaces and to use 4 of them per indent level. It's a nice
+power-of-2 number that looks decent on a wide screen. We have no more reason
+than that. We break that rule when we have lines that wrap (macros or function
+arguments or whatnot). When that happens, we like to indent further to line
+things up in nice tidy columns.
+
+```C
+    if (stuff_happened)
+    {
+        do_something();
+    }
+```
+
+
+#### Case
+
+- Files - all lower case with underscores.
+- Variables - all lower case with underscores
+- Macros - all caps with underscores.
+- Typedefs - all caps with underscores. (also ends with _T).
+- Functions - camel cased. Usually named ModuleName_FuncName
+- Constants and Globals - camel cased.
+
+
+#### Braces
+
+The left brace is on the next line after the declaration. The right brace is
+directly below that. Everything in between in indented one level. If you're
+catching an error and you have a one-line, go ahead and to it on the same line.
+
+```C
+    while (blah)
+    {
+        //Like so. Even if only one line, we use braces.
+    }
+```
+
+
+#### Comments
+
+Do you know what we hate? Old-school C block comments. BUT, we're using them
+anyway. As we mentioned, our goal is to support every compiler we can,
+especially embedded compilers. There are STILL C compilers out there that only
+support old-school block comments. So that is what we're using. We apologize. We
+think they are ugly too.
+
+
+## Ruby Details
+
+Is there really such thing as a Ruby coding standard? Ruby is such a free form
+language, it seems almost sacrilegious to suggest that people should comply to
+one method! We'll keep it really brief!
+
+
+#### Whitespace
+
+Our Ruby style is to use spaces and to use 2 of them per indent level. It's a
+nice power-of-2 number that really grooves with Ruby's compact style. We have no
+more reason than that. We break that rule when we have lines that wrap. When
+that happens, we like to indent further to line things up in nice tidy columns.
+
+
+#### Case
+
+- Files - all lower case with underscores.
+- Variables - all lower case with underscores
+- Classes, Modules, etc - Camel cased.
+- Functions - all lower case with underscores
+- Constants - all upper case with underscores
+
+
+## Documentation
+
+Egad. Really? We use markdown and we like pdf files because they can be made to
+look nice while still being portable. Good enough?
+
+
+*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*

data/examples/temp_sensor/README.md

@@ -0,0 +1,18 @@
+# Ceedling Temp-Sensor Example
+
+*Welcome to the Temp-Sensor Example!* This is a medium-sized example of how Ceedling 
+might work in your system. You can use it to verify you have all the tools installed.
+You can use it as a starting point for your own code. You can build upon it for your
+own creations, though honestly it's a bit of a mess. While it has some good ideas in
+it, really it serves as a testing ground for some of Ceedling's features, and a place
+for you to explore how Ceedling works.
+
+You'll find all the source files in the `src` folder. You'll find all the tests in 
+(you guessed it) the `test` folder (and its sub-folders). There are also some files
+in the `test/support` folder, which demonstrate how you can create your own assertions.
+
+This project assumes you have `gcov` and `gcovr` installed for collecting coverage 
+information. If that's not true, you can just remove the `gcov` plugin from the 
+`plugins` list. Everything else will work fine. 
+
+Have fun poking around!