ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/configuration/which-ceedling.md

@@ -0,0 +1,77 @@
+# Which Ceedling
+
+In certain scenarios you may need to run a different version of Ceedling.
+Typically, Ceedling developers need this ability. But, it could come in
+handy in certain advanced Continuous Integration build scenarios or some
+sort of version behavior comparison.
+
+It’s not uncommon in Ceedling development work to have the last production 
+gem installed while modifying the application code in a locally cloned 
+repository. Or, you may be bouncing between local versions of Ceedling to
+troubleshoot changes.
+
+Which Ceedling handling gives you options on what gets run.
+
+## Background
+
+Ceedling is usually packaged and installed as a Ruby Gem. This gem ends
+up installed in an appropriate place by the `gem` package installer.
+Inside the gem installation is the entire Ceedling project. The `ceedling`
+command line launcher lives in `bin/` while the Ceedling application lives
+in `lib/`. The code in `/bin` manages lots of startup details and base
+configuration. Ultimately, it then launches the main application code from
+`lib/`.
+
+The features and conventions controlling _which ceedling_ dictate which
+application code the `ceedling` command line handler launches.
+
+!!! note "Ceedling development in `bin/`"
+    Working on the code in Ceedling’s `bin/` and need to run it while a gem is 
+    installed? You must take the additional step of specifying the path to the 
+    `ceedling` launcher in your filesystem.
+
+    In Unix-like systems:
+    `> my/ceedling/changes/bin/ceedling <args>`.
+
+    On Windows systems:
+    `> ruby my\ceedling\changes\bin\ceedling <args>`.
+
+## Options and precedence
+
+When Ceedling starts up, it evaluates a handful of conditions to determine
+which Ceedling location to launch.
+
+The following are evaluated in order:
+
+1. Environment variable `WHICH_CEEDLING`. If this environment variable is
+   set, its value is used.
+1. Configuration entry `:project` ↳ `:which_ceedling`. If this is set,
+   its value is used.
+1. The path `vendor/ceedling`. If this path exists in your working 
+   directory — typically because of a `--local` vendored installation at
+   project creation — its contents are used to launch Ceedling.
+1. If none of the above exist, the `ceedling` launcher defaults to using
+   the `lib/` directory next to the `bin/` directory from which the 
+   `ceedling` launcher is running. In the typical case this is the default 
+   gem installation.
+
+!!! note "Configuration entry (2) does not make sense in some scenarios"
+    When running `ceedling new`, `ceedling examples`, or `ceedling example` 
+    there is no project file to read. Similarly, `ceedling upgrade` does not 
+    load a project file; it merely works with the directory structure and 
+    contents of a project. In these cases, the environment variable is your
+    only option to set which Ceedling to launch.
+
+## Settings
+
+The environment variable and configuration entry for _Which Ceedling_ can
+contain two values:
+
+1. The value `gem` indicates that the command line `ceedling` launcher 
+   should run the application packaged alongside it in `lib/` (these 
+   paths are typically found in the gem installation location).
+1. A relative or absolute path in your file system. Such a path should 
+   point to the top-level directory that contains Ceedling’s `bin/` and 
+   `lib/` sub-directories.
+
+<br/><br/>

data/docs/mkdocs/development/index.md

@@ -0,0 +1,50 @@
+# Development
+
+## Community & Contributing
+
+<div class="grid cards" markdown>
+
+-   :material-scale-balance: **[Code of Conduct][code-of-conduct]**
+
+    ---
+
+    The ThrowTheSwitch community follows a shared code of conduct.
+    Please familiarize yourself with it before participating.
+
+-   :material-source-pull: **[Contributing][contributing]**
+
+    ---
+
+    Guidelines for contributing to this project — be it code, reviews,
+    documentation, or issue reports.
+
+</div>
+
+## Projects
+
+<div class="grid cards" markdown>
+
+-   :material-hammer-wrench: **[Ceedling Dev Workflow][dev-workflow]**
+
+    ---
+
+    Install Ceedling for development, run the self-test suite, work with
+    the documentation tooling, and understand code layout.
+
+-   :material-puzzle-edit: **[Plugin Development Guide][plugin-dev]**
+
+    ---
+
+    Create custom Ceedling plugins using configuration, programmatic hook
+    methods, or Rake tasks. Covers architecture, conventions, and all
+    available build step hooks.
+
+</div>
+
+
+[plugin-dev]:       plugins/index.md
+[code-of-conduct]:  https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/CODE_OF_CONDUCT.md
+[contributing]:     https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/CONTRIBUTING.md
+[dev-workflow]:     workflow.md
+
+<br/><br/>

data/docs/mkdocs/development/plugins/configuration.md

@@ -0,0 +1,164 @@
+---
+toc_depth: 3
+---
+
+# Plugin Option 1: Configuration
+
+The configuration option, surprisingly enough, provides Ceedling configuration
+values. Configuration plugin values can supplement or override project
+configuration values.
+
+Not long after Ceedling plugins were developed the `option:` feature was added
+to Ceedling to merge in secondary configuration files. This feature is
+typically a better way to manage multiple configurations and in many ways
+supersedes a configuration plugin.
+
+That said, a configuration plugin is more capable than the `option:` feature and
+can be appropriate in some circumstances. Further, Ceedling's configuration
+plugin abilities are often a great way to provide configuration to
+programmatic `Plugin` subclasses (Ceedling plugins options #2).
+
+## Three flavors of configuration plugins exist
+
+1. **YAML defaults.** The data of a simple YAML file is incorporated into
+   Ceedling's configuration defaults during startup.
+1. **Programmatic (Ruby) defaults.** Ruby code creates a configuration hash 
+   that Ceedling incorporates into its configuration defaults during startup. 
+   This provides the greatest flexibility in creating configuration values.
+1. **YAML configurations.** The data of a simple YAML file is incorporated into
+   Ceedling's configuration much like your project configuration file.
+
+## Example configuration plugin layout
+
+Project configuration file:
+
+```yaml
+:plugins:
+  :load_paths:
+    - support/plugins
+  :enabled:
+    - zoom_zap
+```
+
+Ceedling project directory structure:
+
+(Third flavor of configuration plugin shown.)
+
+```
+project/
+├── project.yml
+└── support/
+    └── plugins/
+        └── zoom_zap/
+            └── config/
+                └── zoom_zap.yml
+```
+
+## Ceedling configuration build & use
+
+Configuration is developed at startup by assembling defaults, collecting 
+user-configured settings, and then populating any missing values with defaults.
+
+Defaults:
+
+1. Ceedling loads its own defaults separately from your project configuration
+1. Supporting framework defaults such as for CMock are populated into (1)
+1. Any plugin defaults are merged with (2).
+
+Final project configuration:
+
+1. Your project file is loaded and any mixins merged
+1. Supporting framework settings that depend on project configuration are populated
+1. Plugin configurations are merged with the result of (1) and (2)
+1. Defaults are populated into your project configuration
+1. Path standardization, string replacement, and related occur throughout the final 
+   configuration
+
+Merging means that existing simple configuration values are replaced or, in the 
+case of containers such as lists and hashes, values are added to. If no such 
+key/value pairs already exist, they are simply inserted into the configuration. 
+
+Populating means inserting a configuration value if none already exists. As an 
+example, if Ceedling finds no compiler defined for test builds in your project
+configuration, it populates your configuration with its own internal tool definition.
+
+A plugin may implement its own code to extract custom configuration from
+the Ceedling project file. See the built-in plugins for examples. For instance, the
+[Beep plugin](../../plugins/beep.md) makes use of a top-level `:beep` section in project 
+configuration. In such cases, it's typically wise to make use of a plugin's option for 
+defining default values. Configuration handling code is greatly simplified if values are 
+guaranteed to exist in some form. This eliminates a great deal of presence checking
+and related code.
+
+## Configuration Plugin Flavors
+
+### Configuration Plugin Flavor A: YAML Defaults
+
+Naming and location convention: `<plugin_name>/config/defaults.yml`
+
+Configuration values are defined inside a YAML file just as the Ceedling project
+configuration file.
+
+Keys and values are defined in Ceedling's "base" configuration along with all
+default values Ceedling loads at startup. If a particular key/value pair is
+already set at the time the plugin attempts to set it, it will not be
+redefined.
+
+YAML values are static apart from Ceedling's ability to perform string
+substitution at configuration load time (see the [configuration reference][string-expansion] for more).
+Programmatic Ruby defaults (next section) are more flexible but more
+complicated.
+
+```yaml
+# Any valid YAML is appropriate
+:key:
+  :value: <setting>
+```
+
+### Configuration Plugin Flavor B: Programmatic (Ruby) Defaults
+
+Naming and location convention: `<plugin_name>/config/defaults_<plugin_name>.rb`
+
+Configuration values are defined in a Ruby hash returned by a "naked" function
+`get_default_config()` in a Ruby file. The Ruby file is loaded and evaluated at
+Ceedling startup. It can contain anything allowed in a Ruby script file but
+must contain the accessor function. The returned hash's top-level keys will
+live in Ceedling's configuration at the same level in the configuration
+hierarchy as a Ceedling project file's top-level keys ('top-level' refers to
+the left-most keys in the YAML, not to how "high" the keys are towards the top
+of the file).
+
+Keys and values are defined in Ceedling's "base" configuration along with all
+default values Ceedling loads at startup. If a particular key/value pair is
+already set at the time the plugin attempts to set it, it will not be
+redefined.
+
+This configuration option is more flexible than that documented in the previous
+section as full Ruby execution is possible in creating the defaults hash.
+
+### Configuration Plugin Flavor C: YAML Values
+
+Naming and location convention: `<plugin_name>/config/<plugin_name>.yml`
+
+Configuration values are defined inside a YAML file just as the Ceedling project
+configuration file.
+
+Keys and values are defined in Ceedling's "base" configuration along with all
+default values Ceedling loads at startup. If a particular key/value pair is
+already set at the time the plugin attempts to set it, it will not be
+redefined.
+
+YAML values are static apart from Ceedling's ability to perform string
+substitution at configuration load time (see the [configuration reference][string-expansion] for more).
+Programmatic Ruby defaults (next section) are more flexible but more
+complicated.
+
+```yaml
+# Any valid YAML is appropriate
+:key:
+  :value: <setting>
+```
+
+[string-expansion]: ../../configuration/project-file.md#inline-ruby-string-expansion
+
+<br/><br/>

data/docs/mkdocs/development/plugins/index.md

@@ -0,0 +1,84 @@
+---
+toc_depth: 2
+---
+
+# Developing Plugins for Ceedling
+
+This guide walks you through the process of creating custom plugins for
+[Ceedling](https://github.com/ThrowTheSwitch/Ceedling).
+
+It is assumed that the reader has a working installation of Ceedling and some
+basic usage experience, *i.e.* project creation/configuration and running tasks.
+
+Some experience with Ruby and Rake will be helpful but not absolutely required.
+You can learn the basics as you go — often by looking at other, existing 
+Ceedling plugins or by simply searching for code examples online.
+
+## Development Roadmap & Notes
+
+(See Ceedling's _[release notes](https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/ReleaseNotes.md)_ for more.)
+
+* Ceedling 1.0 marks the beginning of moving all of Ceedling away from relying
+  on Rake. New, Rake-based plugins should not be developed. Rake dependencies
+  among built-in plugins will be refactored as the transition occurs.
+* Ceedling's entire plugin architecture will be overhauled in future releases.
+  The current structure is too dependent on Rake and provides both too little
+  and too much access to Ceedling's core.
+* Certain aspects of Ceedling's plugin structure have developed organically.
+  Consistency, coherence, and usability may not be high — particularly for 
+  build step hook argument hashes and test results data structures used in 
+  programmatic plugins.
+* Because of iterating on Ceedling's core design and features, documentation
+  here may not always be perfectly up to date.
+
+---
+
+## Custom Plugins Overview
+
+Ceedling plugins extend Ceedling without modifying its core code. They are
+implemented in YAML and the Ruby programming language and are loaded by 
+Ceedling at runtime.
+
+Plugins provide the ability to customize the behavior of Ceedling at various
+stages of a build — preprocessing, compiling, linking, building, testing, and
+reporting.
+
+See the [`:plugins` configuration reference][plugins-config] for details of operation
+and the [plugins overview][plugins-directory] for a directory of built-in plugins.
+
+## Plugin Conventions & Architecture
+
+Plugins are enabled and configured from within a Ceedling project's YAML
+configuration file (`:plugins` section).
+
+Conventions & requirements:
+
+* Plugin configuration names, the containing directory names, and filenames 
+  must:
+    * All match (i.e. identical names)
+    * Be snake_case (lowercase with connecting underscores).
+* Plugins must be organized in a containing directory (the name of the plugin
+  as used in the project configuration `:plugins` ↳ `:enabled` list is its 
+  containing directory name).
+* A plugin's containing directory must be located in a Ruby load path. Load
+  paths may be added to a Ceedling project using the `:plugins` ↳ `:load_paths`
+  list.
+* Rake plugins place their Rakefiles in the root of the containing plugin 
+  directory.
+* Programmatic plugins must contain either or both `config/` and `lib/`
+  subdirectories within their containing directories.
+* Configuration plugins must place their files within a `config/` subdirectory
+  within the plugin's containing directory.
+
+Ceedling provides 3 options to customize its behavior through a plugin. Each
+strategy is implemented with source files conforming to location and naming
+conventions. These approaches can be combined.
+
+1. Configuration (YAML & Ruby)
+1. `Plugin` subclass (Ruby)
+1. Rake tasks (Ruby)
+
+[plugins-config]: ../../configuration/reference/plugins.md
+[plugins-directory]: ../../plugins/index.md
+
+<br/><br/>