ceedling 1.0.1 → 1.1.0

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

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

@@ -0,0 +1,198 @@
+# 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’
+
+Please consult YAML documentation for the finer points of format
+and to understand details of our YAML-based configuration file.
+
+We recommend [Wikipedia’s entry on YAML](http://en.wikipedia.org/wiki/Yaml)
+for this. A few highlights from that reference page:
+
+* 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.
+
+* Repeated nodes are initially denoted by an ampersand (`&`) and
+  thereafter referenced with an asterisk (`*`). These are known as
+  anchors and aliases in YAML speak.
+
+## 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

@@ -0,0 +1,35 @@
+# `:cexception`
+
+**Configure CException’s features**
+
+## Exmaple `: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

@@ -0,0 +1,106 @@
+# `: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].
+
+## Exmaple `: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/>