ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/configuration/parallel-builds.md

@@ -1,97 +0,0 @@
-# Parallel Build Steps
-
-Beginning with version 1.0.0, Ceedling supports parallelization of tasks.
-
-## Configuration
-
-To enable parallel builds, simply configure either or both of the following in
-your project configuration:
-
-* [`:project` ↳ `:compile_threads`](reference/project.md#compile_threads)
-* [`:project` ↳ `:test_threads`](reference/project.md#test_threads)
-
-These two settings allow you to separate build step parallelism from test suite
-execution parallelism. Why? A core reason is because some emulator setups
-necessary for test suite execution do not allow multiple instances running
-simultaneously.
-
-## Operating System restrictions
-
-!!! warning "Operating Systems security protections can limit parallelism"
-
-Modern versions of macOS and Windows both include security gatekeeping that can
-limit Ceedling’s ability to achieve speedups and true parallelism. These
-products can:
-
-1. Execute first-run security checks on newly built, unsgined executables
-(such as components of a test suite) that greatly slow down execution.
-1. Force one-at-a-time execution for any unsigned software attempting to 
-spawn multiple processes simultaneously.
-
-Signing the executables Ceedling generates is wildly complex and maybe even
-practically impossible.
-
-A current limitation of Ceedling since 1.0.0 also contributes to these
-bottlenecks. Namely, with the release of 1.0.0 Ceedling lost “delta” builds —
-the ability to only regenerate components of a test suite that have changed.
-This means Ceedling’s test suites are fully rebuilt each time with OS first-run
-security checks to fire at run time. Future versions of Ceedling will restore
-this ability.
-
-!!! tip "Configuring OS security restrictions"
-    Read up on your Operating System’s options for configuring the restrictions 
-    noted above. For instance, you may be able to configure certain exceptions 
-    for your terminal application that cascade to benefit Ceedling’s parallelism.
-
-## Parallel execution in Ruby
-
-You may have heard that Ruby is actually only single-threaded or may know of its
-Global Interpreter Lock (GIL) that prevents parallel execution
-[^python-note]. This is true but not the whole story.
-
-To oversimplify a complicated subject, the Ruby implementations typically used
-to run Ceedling do 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[^jruby-note], for example — offer
- the following exceptions and abilities of which Ceedling takes advantage.
-
-### I/O operations thread context switching
-
-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 key exception
-here is 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 project configuration,
-execution can speed up for these operations because Ruby’s GIL allows those I/O
-operations to execute with true parallelism.
-
-### 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.
-
-[^python-note]: Python and most other scripting-style languages rely on the
-Global Interpreter Lock concept for managing parallelism. A class of languages
-that includes Go, Rust, and Java fully support true parallelism.
-
-[^jruby-note]: JRuby implements the Ruby language by way of an underlying Java
-implementation. This allows Ruby to run in certain contexts it might not
-otherwise be able to — particularly in Enterprise systems. Ruby parallelism in
-JRuby is built atop Java’s true, native parallelism. Taking advantage of JRuby
-requires certain customization of the Ruby language, and Ceedling has never
-been tested for JRuby support.

data/docs/mkdocs/configuration/project-file.md

@@ -1,216 +0,0 @@
-# The Mighty Ceedling Project Configuration File
-
-**In glorious YAML**
-
-!!! tip "Complete project file example"
-    See this [commented project file][example-config-file] for a nice 
-    example of a complete project configuration.
-
-## Some YAML Learnin’
-
-We recommend [Wikipedia’s entry on YAML](http://en.wikipedia.org/wiki/Yaml)
-and [educative.io’s advanced YAML cheatsheet](https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet)
-for a simple overview of YAML and its syntax sufficient for 
-understanding your Ceedling project configuration.
-
-!!! tip "`ceedling dumpconfig` to verify your YAML"
-    Ceedling provides a means to export the final result of YAML
-    processing for your inspection via [`dumpconfig`](../getting-started/command-line.md#ceedling-dumpconfig-filepath-sections).
-    Dump output includes the resolution of advanced YAML features and 
-    Ceedling’s own manipulations. This is a good way to troubleshoot 
-    your project configuration.
-
-### YAML highlights & overview
-
-A few points from the preceding references:
-
-* YAML streams are encoded using the set of printable Unicode
-  characters, either in UTF-8 or UTF-16.
-
-* White space indentation is used to denote structure; however,
-  tab characters are never allowed as indentation.
-
-* Comments begin with the number sign (`#`), can start anywhere
-  on a line, and continue until the end of the line unless enclosed
-  by quotes.
-
-* List members are denoted by a leading hyphen (`-`) with one member
-  per line, or enclosed in square brackets (`[...]`) and separated
-  by comma space (`, `).
-
-* Hashes are represented using colon space (`: `) in the form
-  `key: value`, either one per line or enclosed in curly braces
-  (`{...}`) and separated by comma space (`, `).
-
-* Strings (scalars) are ordinarily unquoted, but may be enclosed
-  in double-quotes (`"`), or single-quotes (`'`).
-
-* YAML requires that colons and commas used as list separators
-  be followed by a space so that scalar values containing embedded
-  punctuation can generally be represented without needing
-  to be enclosed in quotes.
-
-### YAML anchors, aliases, and extensions
-
-YAML provides several “shortcuts” for referencing and modifying blocks
-of YAML so you can avoid duplication. This is advanced YAML and 
-well beyond the scope of Ceedling documentation. However, know that
-Ceedling’s YAML parser is entirely capable of handling these advanced 
-aspects of YAML.
-
-See this [cheatsheet entry](https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#anchors) 
-and [this guide](https://blog.daemonl.com/2016/02/yaml.html)
-for much more on these powerful but finicky features.
-
-## Notes on Project File Structure
-
-* Each of the following sections represent top-level entries
-  in the YAML configuration file. Top-level means the named entries
-  are furthest to the left in the hierarchical configuration file 
-  (not at the literal top of the file).
-
-* Unless explicitly specified in the configuration file by you, 
-  Ceedling uses default values for settings.
-
-* At minimum, these settings must be specified for a test suite:
-    * `:project` ↳ `:build_root`
-    * `:paths` ↳ `:source`
-    * `:paths` ↳ `:test`
-    * `:paths` ↳ `:include` and/or use of `TEST_INCLUDE_PATH(...)` 
-      build directive macro within your test files
-
-* At minimum, these settings must be specified for a release build:
-    * `:project` ↳ `:build_root`
-    * `:paths` ↳ `:source`
-
-* As much as is possible, Ceedling validates your settings in
-  properly formed YAML.
-
-* Improperly formed YAML will cause a Ruby error when the YAML
-  is parsed. This is usually accompanied by a complaint with
-  line and column number pointing into the project file.
-
-* Certain advanced features 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
-  (Minimalist GNU for Windows).
-
-* Ceedling is primarily meant as a build tool to support automated
-  unit testing. All the heavy lifting is involved there. Creating
-  a simple binary release build artifact is quite trivial in
-  comparison. Consequently, most default options and the construction
-  of Ceedling itself is skewed towards supporting testing, though
-  Ceedling can, of course, build your binary release artifact
-  as well. Note that some complex binary release builds are beyond
-  Ceedling's abilities. See the [`dependencies`](../plugins/dependencies.md)
-  plugin for extending release build abilities.
-
-[MinGW]: http://www.mingw.org/
-
-## Ceedling YAML Handling & Conventions
-
-### Inline Ruby string expansion
-
-!!! warning "Disabled by default for security"
-    Inline Ruby string expansion executes arbitrary Ruby code from a
-    project configuration, Mixins, and/or plugin config — so it's
-    **disabled by default**.
-
-    Enable it with `--ruby-replacement` for any [application command](../getting-started/command-line.md#application-commands) 
-    that loads project configuration (`build`, `check`, `dumpconfig`,
-    `environment`, `help`).
-    **Only enable Ruby string expansion for configurations you trust.**
-
-Ceedling is able to execute inline Ruby string substitution code within the
-entries of certain project file configuration elements. For instance,
-a commonly needed expansion is that of referencing an environment variable.
-Inline Ruby string expansion supports this. See the example below.
-
-In some cases, this evaluation may occur when elements of the project 
-configuration are loaded and processed into a data structure for use by the 
-Ceedling application (e.g. path handling). In other cases, this evaluation
-occurs each time a project configuration element is referenced (e.g. tools).
-
-!!! note
-    One good option for validating and troubleshooting inline Ruby string 
-    expansion is the use of `ceedling dumpconfig --ruby-replacement` at the 
-    command line. This application command causes your project configuration 
-    to be processed and written to a YAML file with any inline Ruby string 
-    expansions, well, expanded along with defaults set, plugin actions 
-    applied, etc.
-
-#### Ruby string expansion syntax
-
-To expand the string result of Ruby code within a configuration value string, 
-wrap the Ruby code in the substitution pattern `#{…}`.
-
-Inline Ruby string expansion may constitute the entirety of a configuration 
-value string, may be embedded within a string, or may be used multiple times
-within a string.
-
-Because of the `#` it's a good idea to wrap any string values in your YAML that
-rely on this feature with quotation marks. Quotation marks for YAML strings are
-optional. However, the `#` can cause a YAML parser to see a comment. As such,
-explicitly indicating a string to the YAML parser with enclosing quotation 
-marks alleviates this problem.
-
-#### Ruby string expansion example
-
-```yaml
-:some_config_section:
-  :some_key:
-    - "My env string #{ENV['VAR1']}"
-    - "My utility result string #{`util --arg`.strip()}"
-```
-
-In the example above, the two YAML strings will include the strings returned by
-the Ruby code within `#{…}`:
-
-1. The first string uses Ruby's environment variable lookup `ENV[…]` to fetch 
-the value assigned to variable `VAR1`.
-1. The second string uses Ruby's backtick shell execution ``…`` to insert the 
-string generated by a command line utility.
-
-#### Project file sections that offer inline Ruby string expansion
-
-* `:mixins`
-* `:environment`
-* `:paths` plus any second tier configuration key name ending in `_path` or
-  `_paths`
-* `:flags`
-* `:defines`
-* `:tools`
-* `:release_build` ↳ `:artifacts`
-
-See each section's documentation for details.
-
-[inline-ruby-string-expansion]: #inline-ruby-string-expansion
-
-### Path handling
-
-Any second tier setting keys anywhere in YAML whose names end in `_path` or
-`_paths` are automagically processed like all Ceedling-specific paths in the
-YAML to have consistent directory separators (i.e. `/`) and to take advantage
-of inline Ruby string expansion (see preceding section for details).
-
-## Let’s Be Careful Out There
-
-Ceedling performs validation of the values you set in your 
-configuration file (this assumes your YAML is correct and will 
-not fail format parsing, of course).
-
-That said, validation is limited to only those settings Ceedling
-uses and those that can be reasonably validated. Ceedling does
-not limit what can exist within your configuration file. In this
-way, you can take full advantage of YAML as well as add sections
-and values for use in your own custom plugins (documented later).
-
-The consequence of this is simple but important. A misspelled
-configuration section or value name is unlikely to cause Ceedling 
-any trouble. Ceedling will happily process that section
-or value and simply use the properly spelled default maintained
-internally — thus leading to unexpected behavior without warning.
-
-[example-config-file]: ../snapshot/assets/project.yml
-
-<br/><br/>

data/docs/mkdocs/configuration/reference/cexception.md

@@ -1,35 +0,0 @@
-# `:cexception`
-
-**Configure CException’s features**
-
-## Example `:cmock` YAML
-
-```yaml
-:cexception:
-  :defines:
-    # Enables CException `#include`ing CExceptionConfig.h
-    - CEXCEPTION_USE_CONFIG_FILE=1
-```
-
-## `:defines`
-
-List of symbols used to configure CException’s features in its source and
-header files at compile time.
-
-See [Using Unity, CMock & CException](../../testing-guide/frameworks.md) for
-much more on configuring and making use of these frameworks in your build.
-
-To manage overall command line length, these symbols are only added to
-compilation when a CException C source file is compiled.
-
-!!! note
-    No symbols must be set unless CException’s defaults are inappropriate for your
-    environment and needs.
-
-Note CException must be enabled for it to be added to a release or test build
-and for these symbols to be added to a build of CException (see link referenced
-earlier for more).
-
-**Default**: `[]` (empty)
-
-<br/><br/>

data/docs/mkdocs/configuration/reference/cmock.md

@@ -1,106 +0,0 @@
-# `:cmock`
-
-**Configure CMock’s code generation & compilation**
-
-Ceedling sets values for a subset of CMock settings. All CMock options are
-available to be set, but only those options set by Ceedling in an automated
-fashion are documented below. See [CMock documentation][cmock-docs].
-
-## Example `:cmock` YAML
-
-```yaml
-:cmock:
-  :when_no_prototypes: :warn
-  :enforce_strict_ordering: TRUE
-  :defines:
-    # Memory alignment (packing) on 16 bit boundaries
-    - CMOCK_MEM_ALIGN=1
-```
-
-## `:enforce_strict_ordering`
-
-Tests fail if expected call order is not same as source order
-
-**Default**: TRUE
-
-## `:verbosity`
-
-If not set, defaults to Ceedling’s verbosity level
-
-## `:defines`
-
-Adds list of symbols used to configure CMock’s C code features in its source
-and header files at compile time.
-
-See [Using Unity & CMock](../../testing-guide/frameworks.md) for
-much more on configuring and making use of these frameworks in your build.
-
-To manage overall command line length, these symbols are only added to
-compilation when a CMock C source file is compiled.
-
-No symbols must be set unless CMock’s defaults are inappropriate for your
-environment and needs.
-
-**Default**: `[]` (empty)
-
-## `:plugins`
-
-To enable CMock’s optional and advanced features available via CMock plugin,
-simply add `:cmock` ↳ `:plugins` to your configuration and specify your desired
-additional CMock plugins as a simple list of the plugin names.
-
-See [CMock’s documentation][cmock-docs] to understand plugin options.
-
-**Default**: `[]` (empty)
-
-## `:unity_helper_path`
-
-A Unity helper is a simple header file used by convention to support your
-specialized test case needs. For example, perhaps you want a Unity assertion
-macro for the contents of a struct used throughout your project. Write the macro
-you need in a Unity helper header file and `#include` that header file in your
-test file.
-
-When a Unity helper is provided to CMock, it takes on more significance, and
-more magic happens. CMock parses Unity helper header files and uses macros of a
-certain naming convention to extend CMock’s handling of mocked parameters.
-
-See the [Unity and CMock documentation](../../testing-guide/frameworks.md) 
-for more details.
-
-`:unity_helper_path` may be a single string or a list. Each value must be a
-relative path from your Ceedling working directory to a Unity helper header file
-(these are typically organized within containing Ceedling `:paths` ↳ `:support`
-directories).
-
-**Default**: `[]` (empty)
-
-## `:includes`
-
-In certain advanced testing scenarios, you may need to inject additional header
-files into generated mocks. The filenames in this list will be transformed into
-`#include` directives created at the top of every generated mock.
-
-If `:unity_helper_path` is in use (see preceding), the filenames at the end of
-any Unity helper file paths will be automatically injected into this list
-provided to CMock.
-
-**Default**: `[]` (empty)
-
-## Notes on Ceedling’s nudges for CMock strict ordering
-
-The preceding settings are tied to other Ceedling settings; hence, why they are
-documented here.
-
-The first setting above, `:enforce_strict_ordering`, defaults to `FALSE` within
-CMock. However, it is set to `TRUE` by default in Ceedling as our way of
-encouraging you to use strict ordering.
-
-Strict ordering is teeny bit more expensive in terms of code generated, test
-execution time, and complication in deciphering test failures. However, it’s
-good practice. And, of course, you can always disable it by overriding the
-value in the Ceedling project configuration file.
-
-[cmock-docs]: https://github.com/ThrowTheSwitch/CMock/blob/master/docs/CMock_Summary.md
-
-<br/><br/>