ceedling 1.0.1 → 1.1.0

data/docs/{CeedlingUpgrade.md → mkdocs/project/upgrade.md}

@@ -37,12 +37,14 @@ features?
 The other choice, of course, is to update it. To do so, we open a command prompt and address ceedling 
 from *outside* the project. For example, let's say we have the following structure:
 
- - projects
-    - myproject
-        - project.yml
-        - src
-        - tgt
-        - vendor
+```
+projects/
+└── myproject/
+    ├── project.yml
+    ├── src/
+    ├── tgt/
+    └── vendor/
+```
 
 In this case, we'd want to be in the `projects` directory. At that point, we can ask Ceedling to
 update our project.
@@ -80,4 +82,4 @@ If you have custom plugins installed to your project, the plugin architecture ha
 revisions and it may or may not be compatible at this time. Again, this is a problem which should
 not exist soon.
 
-
+<br/><br/>

data/docs/mkdocs/reference/build-directives.md

@@ -0,0 +1,37 @@
+# Test Build Directive Macros Reference
+
+For detailed usage guidance, purpose explanations, and examples for these
+macros, see [Test Build Directive Macros](../testing-guide/build-directives.md).
+
+Both macros are defined in `unity.h` and evaluate to empty strings at compile
+time — they serve only as text markers for Ceedling's scanner. `#include "unity.h"`
+must appear above their use in a test file.
+
+!!! warning "Incompatible with conditional preprocessor blocks"
+    `TEST_SOURCE_FILE()` and `TEST_INCLUDE_PATH()` cannot be enclosed in
+    `#ifdef` or other conditional compilation preprocessor statements. See
+    [preprocessing gotchas](../testing-guide/conventions.md#preprocessing-gotchas)
+    for details.
+
+## `TEST_SOURCE_FILE("filepath")`
+
+Inject a specific source file into a test executable's build. Use this when
+a source file has no corresponding header file that Ceedling can discover by
+convention, or when you need to explicitly include an assembly file (`.s`) in
+a test build that has assembly support enabled.
+
+- Argument: a filepath string using forward slashes
+- The file must exist within Ceedling's source file collection
+- Multiple uses per test file are allowed, one per line
+
+## `TEST_INCLUDE_PATH("path")`
+
+Add a header search path to an individual test executable's compiler
+invocation. This supplements — it does not replace — the `:paths` ↳ `:include`
+entries from your project file.
+
+- Argument: a path string using forward slashes
+- Paths are relative to the working directory from which `ceedling` is executed
+- Multiple uses per test file are allowed, one per line
+
+<br/><br/>

data/docs/mkdocs/reference/command-line.md

@@ -0,0 +1,323 @@
+# Command Line Reference
+
+See [_Getting started: The command line_](../getting-started/command-line.md)
+for:
+
+- A conceptual overview of how application commands and build & plugin 
+  tasks work together.
+- Quick-start command line examples.
+- In-depth details for each of the reference entries below (each heading
+  links back to richer documentation).
+
+!!! note "Documentation convention"
+    The `*` used in this reference is a stand-in for:
+
+    * One of several available options
+    * A matching string (e.g. test filename)
+    * A regex
+
+## Application commands
+
+!!! tip "Detailed command line help at the, well, command line"
+    Ceedling provides robust help for application commands.
+    Execute `ceedling help` for a summary view of all application commands.
+    Execute `ceedling help <command>` for detailed help.
+
+    Because the built-in command line help is thorough, the following 
+    reference includes brief entries.
+
+---
+
+### [`ceedling [no arguments]`](../getting-started/command-line.md#ceedling-no-arguments)
+
+Runs the default build tasks. Unless set in the project file, Ceedling 
+uses a default task of `test:all`. To override this behavior, set your 
+own default tasks in the project file (see later section). 
+
+---
+
+### [`ceedling <tasks...>`](../getting-started/command-line.md#ceedling-tasks)
+
+Runs the named build tasks (i.e. `ceedling test:all`). Various option flags
+exist to control project configuration loading, verbosity levels, 
+logging, test task filters, etc.
+
+See [next section](#build-plugin-tasks) to understand the build & plugin 
+tasks this application command is able to execute. Run `ceedling help build` 
+to understand all the command line flags that work with build & plugin tasks.
+
+---
+
+### [`ceedling build <tasks...>`](../getting-started/command-line.md#ceedling-build-tasks)
+
+`ceedling build` is a verbose alias for the preceding. `build` is optional 
+(i.e. `ceedling test:all` is equivalent to `ceedling build test:all`).
+
+---
+
+### [`ceedling check`](../getting-started/command-line.md#ceedling-check)
+
+Process project configuration for validity and to check for any warnings
+or automated overrides. No builds occur. Various option flags exist to 
+control project configuration loading and configuration manipulation.
+
+---
+
+### [`ceedling dumpconfig`](../getting-started/command-line.md#ceedling-dumpconfig-filepath-sections)
+
+Process project configuration and write final result to a YAML file. 
+Various option flags exist to control project configuration loading,
+configuration manipulation, and configuration sub-section extraction.
+
+---
+
+### [`ceedling environment`](../getting-started/command-line.md#ceedling-environment)
+
+Lists project related environment variables:
+
+* All environment variable names and string values added to your 
+  environment from within Ceedling and through the `environment`
+  section of your configuration. This is especially helpful in 
+  verifying the evaluation of any string replacement expressions in
+  your `environment` config entries.
+* All existing Ceedling-related environment variables set before you
+  ran Ceedling from the command line.
+
+---
+
+### [`ceedling example`](../getting-started/command-line.md#ceedling-example-name-dest)
+
+Extracts an example project from within Ceedling to your local 
+filesystem. The available examples are listed with 
+`ceedling examples`. Various option flags control whether the example
+contains vendored Ceedling and/or a documentation bundle.
+
+---
+
+### [`ceedling examples`](../getting-started/command-line.md#ceedling-examples)
+
+Lists the available examples within Ceedling. To extract an example,
+use `ceedling example`.
+
+---
+
+### [`ceedling help`](../getting-started/command-line.md#ceedling-help-command)
+
+  Displays summary help for all application commands and detailed help 
+  for each command. `ceedling help` also loads your project 
+  configuration (if available) and lists all build tasks from it. 
+  Various option flags control what project configuration is loaded.
+
+---
+
+### [`ceedling new`](../getting-started/command-line.md#ceedling-new-dest)
+
+  Creates a new project structure. Various option flags control whether 
+  the new project contains vendored Ceedling, a documentation bundle,
+  and/or a starter project configuration file.
+
+---
+
+### [`ceedling upgrade`](../getting-started/command-line.md#ceedling-upgrade-path)
+
+  Upgrade vendored installation of Ceedling for an existing project 
+  along with any locally installed documentation bundles.
+
+---
+
+### [`ceedling version`](../getting-started/command-line.md#ceedling-version)
+
+Displays version information for Ceedling and its components. Version 
+output for Ceedling includes the Git Commit short SHA in Ceedling’s 
+build identifier and Ceedling’s path of origin.
+
+```
+🌱 Welcome to Ceedling!
+
+  Ceedling => #.#.#-<Short SHA>
+  ----------------------
+  <Ceedling install path>
+
+  Build Frameworks
+  ----------------------
+       CMock => #.#.#
+       Unity => #.#.#
+  CException => #.#.#
+```
+
+If the short SHA information is unavailable such as in local 
+development, the SHA is omitted. The source for this string is 
+generated and captured in the Ruby Gem at the time of Ceedling’s 
+automated build in CI.
+
+## Build & plugin tasks
+
+Build task are loaded from your project configuration. Unlike 
+application commands that are fixed, build tasks vary depending on your
+project configuration and the files within your project structure.
+
+Ultimately, build & plugin tasks are executed by the
+[`build` application command](#ceedling-build-tasks)
+(but the `build` keyword can be omitted — see above).
+
+!!! warning "Quotes in shell command line parsing"
+    Quotes may be necessary around any tasks using bracket notation or that
+    can make use of wildcards or regexes. Your shell will likely need quotes
+    to distinguish the parameter’s characters from shell command line
+    operators.
+
+---
+
+### [`ceedling paths:*`](../getting-started/command-line.md#ceedling-paths)
+
+* `ceedling paths:header`
+* `ceedling paths:source`
+* `ceedling paths:support`
+* `ceedling paths:test`
+
+List all paths collected from `paths` entries in your YAML config
+file where `*` is the name of any section contained in `paths`. This
+task is helpful in verifying the expansion of path wildcards / globs
+specified in the `paths` section of your config file.
+
+---
+
+### [`ceedling files:*`](../getting-started/command-line.md#ceedling-files)
+
+* `ceedling files:header`
+* `ceedling files:source`
+* `ceedling files:support`
+* `ceedling files:test`
+* `ceedling files:assembly`
+
+List all files and file counts collected from the relevant search
+paths specified by the `paths` entries of your YAML config file.
+
+The `files:assembly` task will only be available if assembly support 
+is enabled in the [`:release_build`](../configuration/reference/release-build.md) 
+or [`:test_build`](../configuration/reference/test-build.md)
+sections of your configuration file.
+
+---
+
+### [`ceedling test:all`](../getting-started/command-line.md#ceedling-testall)
+
+Run all unit tests.
+
+---
+
+### [`ceedling test:build_only`](../getting-started/command-line.md#ceedling-testbuild_only)
+
+Build the entire test suite but do not execute it. This is a simple 
+validation of code and configuration via your toolchain.
+
+---
+
+### [`ceedling test:*`](../getting-started/command-line.md#ceedling-test)
+
+Execute the named test file or the named source file that has an
+accompanying test. No path. Examples: `ceedling test:foo`, `ceedling 
+test:foo.c` or `ceedling test:test_foo.c`
+
+#### [`ceedling test:* --test-case=<test_case_name>`](../getting-started/command-line.md#ceedling-test-test-casetest_case_name)
+Execute individual test cases which match `test_case_name`.
+
+For instance, if you have a test file _test_gpio.c_ containing the following 
+test cases (test cases are simply `void test_name(void)`).
+
+- `test_gpio_start`
+- `test_gpio_configure_proper`
+- `test_gpio_configure_fail_pin_not_allowed`
+
+… and you want to run only _configure_ tests, you can call:
+
+`ceedling test:gpio --test-case=configure`
+
+!!! note
+    Test case matching is on sub-strings. `--test_case=configure` matches on
+    the test cases including the word _configure_, naturally. 
+    `--test-case=gpio` would match all three test cases.
+
+#### [`ceedling test:* --exclude_test_case=<test_case_name>`](../getting-started/command-line.md#ceedling-test-exclude_test_casetest_case_name)
+Execute test cases which do not match `test_case_name`.
+
+For instance, if you have file test_gpio.c with defined 3 tests:
+
+- `test_gpio_start`
+- `test_gpio_configure_proper`
+- `test_gpio_configure_fail_pin_not_allowed`
+
+… and you want to run only start tests, you can call:
+
+`ceedling test:gpio --exclude_test_case=configure`
+
+!!! note
+    Exclude matching follows the same sub-string logic as discussed in the
+    preceding section.
+
+---
+
+### [`ceedling test:pattern[*]`](../getting-started/command-line.md#ceedling-testpattern)
+
+Execute any tests whose name and/or path match the regular expression
+pattern (case sensitive). Example: `ceedling "test:pattern[(I|i)nit]"` 
+will execute all tests named for initialization testing.
+
+---
+
+### [`ceedling test:path[*]`](../getting-started/command-line.md#ceedling-testpath)
+
+Execute any tests whose path contains the given string (case
+sensitive). Example: `ceedling test:path[foo/bar]` will execute all tests
+whose path contains foo/bar.
+
+Both directory separator characters `/` and `\` are valid.
+
+---
+
+### [`ceedling release`](../getting-started/command-line.md#ceedling-release)
+
+Build all source into a release artifact (if the release build option
+is configured).
+
+---
+
+### [`ceedling release:compile:*`](../getting-started/command-line.md#ceedling-releasecompile)
+
+Sometimes you just need to compile a single file dagnabit.
+
+Example: `ceedling release:compile:foo.c`
+
+---
+
+### [`ceedling release:assemble:*`](../getting-started/command-line.md#ceedling-releaseassemble)
+
+Sometimes you just need to assemble a single file doggonit. Example:
+`ceedling release:assemble:foo.s`
+
+---
+
+### [`ceedling summary`](../getting-started/command-line.md#ceedling-summary)
+
+If plugins are enabled, this task will execute the summary method of
+any plugins supporting it. This task is intended to provide a quick
+roundup of build artifact metrics without re-running any part of the
+build.
+
+---
+
+### [`ceedling clean`](../getting-started/command-line.md#ceedling-clean)
+
+Deletes all toolchain binary artifacts (object files, executables),
+test results, and any temporary files. Clean produces no output at the
+command line unless verbosity has been set to an appreciable level.
+
+---
+
+### [`ceedling clobber`](../getting-started/command-line.md#ceedling-clobber)
+
+Extends clean task’s behavior to also remove generated files: test
+runners, mocks, preprocessor output. Clobber produces no output at the
+command line unless verbosity has been set to an appreciable level.
+
+<br/><br/>

data/docs/mkdocs/reference/environment-vars.md

@@ -0,0 +1,60 @@
+# Environment Variables Reference
+
+See [Getting Started → Environment Variables](../configuration/environment-vars.md)
+for context on when and why to use these variables.
+
+## Project configuration
+
+### `CEEDLING_PROJECT_FILE`
+
+Points Ceedling at your project configuration file. This is
+[one of several options](../configuration/loading.md) for specifying the
+project file location.
+
+### `CEEDLING_MIXIN_#`
+
+Environment variables named `CEEDLING_MIXIN_#` — where `#` is any positive
+integer — specify filepaths to mixin YAML files to be merged into your base
+project configuration. Multiple mixin environment variables are merged in
+ascending numeric order (e.g. `CEEDLING_MIXIN_1` before `CEEDLING_MIXIN_5`
+before `CEEDLING_MIXIN_99`).
+
+See [_Loading Configuration_](../configuration/mixins.md#environment-variables)
+for the full details on Mixin environment variables.
+
+## Console output — `CEEDLING_DECORATORS`
+
+Forces Ceedling's console logging decorators (fancy Unicode characters, emoji,
+and color) on or off.
+
+!!! warning "`CEEDLING_DECORATORS` cannot be set with `:environment`"
+    Ceedling's logger must load before any environment variables are processed 
+    in your project configuration. As such, `CEEDLING_DECORATORS` can only be set 
+    in your environment before Ceedling runs.
+
+By default, Ceedling makes an educated guess as to which platforms can best
+support decorators. Some platforms (we're looking at you, Windows) do not
+typically have default font support in their terminals for these features. So,
+by default this feature is disabled on problematic platforms while enabled on
+others.
+
+Set `CEEDLING_DECORATORS` to `true` (`1`) to force decorators on, or `false`
+(`0`) to force them off.
+
+Example with decorators enabled:
+
+```
+-----------------------
+❌ OVERALL TEST SUMMARY
+-----------------------
+TESTED:  6
+PASSED:  5
+FAILED:  1
+IGNORED: 0
+```
+
+If you find a monospaced font that provides emojis, etc. and works with Windows'
+command prompt, you can (1) Install the font (2) change your command prompt's
+font (3) set `CEEDLING_DECORATORS` to `true`.
+
+<br/><br/>