ceedling 1.1.9 → 1.2.0

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

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

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