ceedling 1.0.0 → 1.1.0

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

@@ -0,0 +1,276 @@
+# `:paths`
+
+**Paths for build tools and building file collections**
+
+Ceedling relies on various path and file collections to do its work. File
+collections are automagically assembled from paths, matching globs / wildcards,
+and file extensions. See [project configuration `:extension`](extension.md).
+
+Entries in `:paths` help create directory-based bulk file collections. The
+`:files` configuration section is available for filepath-oriented tailoring of
+these bulk file collections.
+
+Entries in `:paths` ↳ `:include` also specify search paths for header files.
+
+All of the configuration subsections that follow default to empty lists. In
+YAML, list items can be comma separated within brackets or organized per line
+with a dash. An empty list can only be denoted as `[]`. Typically, you will see
+Ceedling project files use lists broken up per line.
+
+```yaml
+:paths:
+  :support: []    # Empty list (internal default)
+  :source:
+    - files/code  # Typical list format
+
+```
+
+!!! warning "Mixin order controls path list order"
+    If you use Mixins to build up path lists in your project configuration,
+    the merge order of those Mixins will dictate the ordering of your path
+    lists. Particularly given that the search path list built with
+    `:paths` ↳ `:include` you will want to pay attention to ordering issues
+    involved in specifying path lists in Mixins.
+
+## Example `:paths` YAML
+
+!!! note "Path standardization"
+    Ceedling standardizes paths for you. Internally, all paths use forward
+    slash `/` path separators (including on Windows) and trailing path 
+    separators are cleaned up. This should have no impact on your project
+    regardless of platform, but you will see the effects in logging.
+
+### Simple entries
+
+```yaml
+:paths:
+  # All <dirs>/*.<source extension> => test/release compilation input
+  :source:
+    - project/src/            # Resulting source list has just two relative directory paths
+    - project/aux             # (Traversal goes no deeper than these simple paths)
+
+  # All <dirs> => compilation search paths + mock search paths
+  :include:                   # All <dirs> => compilation input
+    - project/src/inc         # Include paths are subdirectory of src/
+    - /usr/local/include/foo  # Header files for a prebuilt library at fully qualified path
+
+  # All <dirs>/<test prefix>*.<source extension> => test compilation input + test suite executables
+  :test:                
+    - ../tests                # Tests have parent directory above working directory
+```
+
+### Common globs with subtractive entries
+
+```yaml
+:paths:
+  :source:              
+    - +:project/src/**    # Recursive glob yields all subdirectories of any depth plus src/
+    - -:project/src/exp   # Exclude experimental code in exp/ from release or test builds
+                          # `+:` is decoration for pretty alignment; only `-:` changes a list
+
+  :include:
+    - +:project/src/**/inc   # Include every subdirectory inc/ beneath src/
+    - -:project/src/exp/inc  # Remove header files subdirectory for experimental code
+```
+
+### Advanced entries with globs and string expansion
+
+```yaml
+:paths:
+  :test:                             
+    - test/**/f???             # Every 4 character "f-series" subdirectory beneath test/
+
+  :my_things:                  # Custom path list
+    - "#{PROJECT_ROOT}/other"  # Inline Ruby string expansion using Ceedling global constant
+```
+
+```yaml
+:paths:
+  :test:                             
+    - test/{foo,b*,xyz}  # Path list will include test/foo/, test/xyz/, and any subdirectories 
+                         # beneath test/ beginning with 'b', including just test/b/
+```
+
+Globs and inline Ruby string expansion can require trial and error to arrive at
+your intended results. Ceedling provides as much validation of paths as is
+practical.
+
+!!! tip "Troubleshooting paths"
+    * Use the `ceedling paths:*` and `ceedling files:*` command line tasks to 
+      verify your settings. (Here `*` is shorthand for `test`, `source`, `include`,
+      etc. Confusing? Sorry.)
+    * `ceedling dumpconfig` can also help your troubleshoot your configuration. 
+      This application command causes Ceedling to fully process your configuration
+      (e.g. Mixins, any string expansion, etc.) and write the result to another 
+      YAML file for your inspection.
+
+## `:paths` ↳ `:test`
+
+All C files containing unit test code.
+
+!!! note "Test suite configuration requirement"
+    `:paths` ↳ `:test` is one of the handful of configuration values that must 
+    be set for a test suite.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:source`
+
+All C files containing release code (code to be tested).
+
+!!! note "Build configuration requirement"
+    `:paths` ↳ `:source` must be set for any build — release build or test suite —
+    to run.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:support`
+
+Any C files you might need to aid your unit testing. For example, on occasion,
+you may need to create a header file containing a subset of function signatures
+matching those elsewhere in your code (e.g. a subset of your OS functions, a
+portion of a library API, etc.). Why? To provide finer grained control over
+mock function substitution or limiting the size of the generated mocks.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:include`
+
+See these two important discussions to fully understand your options for header
+file search paths:
+
+* [Configuring Your Header File Search Paths][header-file-search-paths]
+* [`TEST_INCLUDE_PATH(...)` build directive macro][test-include-path-macro]
+
+[header-file-search-paths]: ../../testing-guide/conventions.md#test-build-search-paths
+[test-include-path-macro]: ../../testing-guide/build-directives.md#test_include_path
+
+This set of paths specifies the locations of your header files. If your header
+files are intermixed with source files, you must duplicate some or all of your
+`:paths` ↳ `:source` entries here.
+
+In its simplest use, your include paths list can be exhaustive. That is, you
+list all path locations where your project’s header files reside in this
+configuration list.
+
+However, if you have a complex project or many, many include paths that create
+problematically long search paths at the compilation command line, you may treat
+your `:paths` ↳ `:include` list as a base, common list. Having established that
+base list, you can then extend it on a test-by-test basis with use of the
+`TEST_INCLUDE_PATH(...)` build directive macro in your test files.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:test_toolchain_include`
+
+System header files needed by the test toolchain — should your compiler be
+unable to find them, finds the wrong system include search path, or you need a
+creative solution to a tricky technical problem.
+
+Note that if you configure your own toolchain in the `:tools` section, this
+search path is largely meaningless to you. However, this is a convenient way
+to control the system include path should you rely on the default [GCC][GCC]
+tools.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:release_toolchain_include`
+
+Same as preceding albeit related to the release toolchain.
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:libraries`
+
+Library search paths. [See `:libraries` section][libraries].
+
+[libraries]: libraries.md
+
+**Default**: `[]` (empty)
+
+## `:paths` ↳ `:<custom>`
+
+Any paths you specify for custom list. List is available to tool configurations
+and/or plugins. Note a distinction — the preceding names are recognized
+internally to Ceedling and the path lists are used to build collections of
+files contained in those paths. A custom list is just that — a custom list of
+paths.
+
+## `:paths` configuration options & notes
+
+1. A path can be absolute (fully qualified) or relative.
+1. A path can include a glob matcher (more on this below).
+1. A path can use [inline Ruby string expansion][inline-ruby-string-expansion].
+1. Subtractive paths are possible and useful. See the documentation below.
+1. Path order beneath a subsection (e.g. `:paths` ↳ `:include`) is preserved
+   when the list is iterated internally or passed to a tool.
+
+## `:paths` Globs
+
+Globs are effectively fancy wildcards. They are not as capable as full regular
+expressions but are easier to use. Various OSs and programming languages
+implement them differently.
+
+For a quick overview, see this [tutorial][globs-tutotrial].
+
+Ceedling supports globs so you can specify patterns of directories without the
+need to list each and every required path.
+
+Ceedling `:paths` globs operate similarly to [Ruby globs][ruby-globs] except
+that they are limited to matching directories within `:paths` entries and not
+also files. In addition, Ceedling adds a useful convention with certain uses of
+the `*` and `**` operators.
+
+Glob operators include the following: `*`, `**`, `?`, `[-]`, `{,}`.
+
+* `*`
+    * When used within a character string, `*` is simply a standard wildcard.
+    * When used after a path separator, `/*` matches all subdirectories of depth
+      1 below the parent path, not including the parent path.
+* `**`: All subdirectories recursively discovered below the parent path, not
+  including the parent path. This pattern only makes sense after a path
+  separator `/**`.
+* `?`: Single alphanumeric character wildcard.
+* `[x-y]`: Single alphanumeric character as found in the specified range.
+* `{x, y, ...}`: Matching any of the comma-separated patterns. Two or more
+  patterns may be listed within the brackets. Patterns may be specific
+  character sequences or other glob operators.
+
+Special conventions:
+
+* If a globified path ends with `/*` or `/**`, the resulting list of
+  directories also includes the parent directory.
+
+[globs-tutotrial]: http://ruby.about.com/od/beginningruby/a/dir2.htm
+[ruby-globs]: https://ruby-doc.org/core-3.0.0/Dir.html#method-c-glob
+
+## Subtractive entries
+
+Globs are super duper helpful when you have many paths to list. But, what if a
+single glob gets you 20 nested paths, but you actually want to exclude 2 of
+those paths?
+
+Must you revert to listing all 18 paths individually? No, my friend, we've got
+you. Behold, subtractive paths.
+
+Put simply, with an optional preceding decorator `-:`, you can instruct Ceedling
+to remove certain directory paths from a collection after it builds that
+collection.
+
+By default, paths are additive. For pretty alignment in your YAML, you may also
+use `+:`, but strictly speaking, it’s not necessary.
+
+Subtractive paths may be simple paths or globs just like any other path entry.
+
+!!! note "Subtractive paths resolve after all mixins merge"
+    The resolution of subtractive paths happens after your full paths lists are
+    assembled. So, if you use `:paths` entries in Mixins to build up your
+    project configuration, subtractive paths will only be processed after the
+    final mixin is merged. That is, you can merge in additive and subtractive
+    paths with Mixins to your heart’s content. The subtractive paths are not
+    removed until all Mixins have been merged.
+
+[GCC]: https://gcc.gnu.org
+[inline-ruby-string-expansion]: ../project-file.md#inline-ruby-string-expansion
+
+<br/><br/>

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

@@ -0,0 +1,60 @@
+# `:plugins`
+
+**Ceedling extensions**
+
+See the section below dedicated to plugins for more information. This section
+pertains to enabling plugins in your project configuration.
+
+Ceedling includes a number of [built-in plugins][ceedling-plugins].
+
+!!! tip "Handy-dandy Command Hooks plugin for custom needs"
+    Many users find the handy-dandy [Command Hooks plugin][command-hooks]
+    is often enough to meet their custom needs. This plugin allows you to 
+    connect your own scripts and command line tools to Ceedling build steps.
+
+For documentation on creating your own custom plugins, see the
+[Plugin Development Guide][custom-plugins].
+
+## Example `:plugins` YAML
+
+```yaml
+:plugins:
+  :load_paths:
+    - project/tools/ceedling/plugins  # Home to your collection of plugin directories.
+    - project/support                 # Home to some ruby code your custom plugins share.
+  :enabled:
+    - report_tests_pretty_stdout      # Nice test results at your command line.
+    - our_custom_code_metrics_report  # You created a plugin to scan all code to collect 
+                                      # line counts and complexity metrics. Its name is a
+                                      # subdirectory beneath the first `:load_path` entry.
+```
+
+## `:load_paths`
+
+Base paths to search for plugin subdirectories or extra Ruby functionality.
+
+Ceedling maintains the Ruby load path for its built-in plugins. This list of
+paths allows you to add your own directories for custom plugins or simpler
+Ruby files referenced by your Ceedling configuration options elsewhere.
+
+**Default**: `[]` (empty)
+
+## `:enabled`
+
+List of plugins to be used — a plugin's name is identical to the subdirectory
+that contains it.
+
+**Default**: `[]` (empty)
+
+Plugins can provide a variety of added functionality to Ceedling. In general
+use, it's assumed that at least one reporting plugin will be used to format
+test results (usually `report_tests_pretty_stdout`).
+
+If no reporting plugins are specified, Ceedling will print to `$stdout` the
+(quite readable) raw test results from all test fixtures executed.
+
+[custom-plugins]: ../../development/plugins/index.md
+[ceedling-plugins]: ../../plugins/index.md
+[command-hooks]: ../../plugins/command-hooks.md
+
+<br/><br/>

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

@@ -0,0 +1,333 @@
+# `:project`: Global project settings
+
+!!! warning "`:project` settings will be reorganized"
+    In future versions of Ceedling, test-specific and release-specific build
+    settings presently organized beneath `:project` will likely be renamed and
+    migrated to the `:test_build` and `:release_build` sections.
+
+## Example `:project` YAML
+
+```yaml
+:project:
+  :nane: "Acme Smartomatic"
+  :build_root: project_awesome/build
+  :use_exceptions: FALSE
+  :use_test_preprocessor: :all
+  :release_build: TRUE
+  :compile_threads: :auto
+```
+
+## `:name`
+
+Optional project name that, if present, adds a new first line to build logging 
+output with the project name.
+
+Example YAML:
+```yaml
+:project:
+  :name: "Q-36 Space Modulator"
+```
+
+Example first logging line:
+```
+🌱 Q-36 SPACE MODULATOR
+```
+
+## `:build_root`
+
+Top level directory into which generated path structure and files are placed.
+
+!!! note "Build configuration requirement"
+    This is one of the handful of configuration values that must be set for 
+    any project. `:project` ↳ `:build_root` must be set for any build — release 
+    build or test suite — to run.
+
+**Default**: (none)
+
+## `:default_tasks`
+
+A list of default build / plugin tasks Ceedling should execute if none are
+provided at the command line.
+
+!!! note "Build & plugin tasks only"
+    Build & plugin tasks include tasks such as `test:all` and `clobber`. 
+    `:default_tasks` does not support application commands (e.g. `dumpconfig`) 
+    or command line flags (e.g. `--verbosity`).
+    
+    See the documentation [on using the command line][command-line]
+    to understand the distinction between application commands and build & 
+    plugin tasks.
+
+[command-line]: ../../getting-started/command-line.md
+
+Example YAML:
+```yaml
+:project:
+  :default_tasks:
+    - clobber
+    - test:all
+    - release
+```
+**Default**: `['test:all']`
+
+## `:use_mocks`
+
+Configures the build environment to make use of CMock. Note that if you do not
+use mocks, there's no harm in leaving this setting as its default value.
+
+**Default**: TRUE
+
+## `:use_partials`
+
+Enables Ceedling Partials. [Partials][partials] allow you to test and mock
+inaccessible functions and variables in the C code under test without rewriting
+your source code.
+
+[partials]: ../../testing-guide/partials/index.md
+
+**Default**: FALSE
+
+## `:use_test_preprocessor`
+
+This option allows Ceedling to work with test files that contain tricky
+conditional compilation statements (e.g. `#ifdef`) as well as mockable header
+files containing conditional preprocessor directives and/or macros.
+
+See the [documentation on test preprocessing][test-preprocessing] for more.
+
+!!! note
+    With any preprocessing enabled, the `gcc` & `cpp` tools must exist in an
+    accessible system search path.
+
+[test-preprocessing]: ../../testing-guide/conventions.md#test-preprocessing
+
+* `:none` disables preprocessing.
+* `:all` enables preprocessing for all mockable header files and test C files.
+* `:mocks` enables only preprocessing of header files that are to be mocked.
+* `:tests` enables only preprocessing of your test files.
+
+**Default**: `:none`
+
+## `:test_file_prefix`
+
+Ceedling collects test files by convention from within the test file search
+paths. The convention includes a unique name prefix and a file extension
+matching that of source files.
+
+Why not simply recognize all files in test directories as test files? By using
+the given convention, we have greater flexibility in what we do with C files in
+the test directories.
+
+**Default**: "test_"
+
+## `:release_build`
+
+When enabled, a release Rake task is exposed. This configuration option requires
+a corresponding release compiler and linker to be defined (`gcc` is used as the
+default).
+
+Ceedling is primarily concerned with facilitating the complicated mechanics of
+automating unit tests. The same mechanisms are easily capable of building a
+final release binary artifact (i.e. non test code — the thing that is your
+final working software that you execute on target hardware). That said, if you
+have complicated release builds, you should consider a traditional build tool
+for these. Ceedling shines at executing test suites.
+
+More release configuration options are available in the `:release_build` section.
+
+**Default**: FALSE
+
+## `:compile_threads`
+
+A value greater than one enables parallelized build steps. Ceedling creates a
+number of threads up to `:compile_threads` for build steps. These build steps
+execute batched operations including but not limited to mock generation, code
+compilation, and running test executables.
+
+Particularly if your build system includes multiple cores, overall build time
+will drop considerably as compared to running a build with a single thread.
+
+Tuning the number of threads for peak performance is an art more than a
+science. A special value of `:auto` instructs Ceedling to query the host
+system's number of virtual cores. To this value it adds a constant of 4. This
+is often a good value sufficient to "max out" available resources without
+overloading available resources.
+
+`:compile_threads` is used for all release build steps and all test suite build
+steps except for running the test executables that make up a test suite. See
+next section for more.
+
+**Default**: 1
+
+## `:test_threads`
+
+The behavior of and values for `:test_threads` are identical to
+`:compile_threads` with one exception.
+
+`test_threads:` specifically controls the number of threads used to run the
+test executables comprising a test suite.
+
+Why the distinction from `:compile_threads`? Some test suite builds rely not on
+native executables but simulators running cross-compiled code. Some simulators
+are limited to running only a single instance at a time. Thus, with this and
+the previous setting, it becomes possible to parallelize nearly all of a test
+suite build while still respecting the limits of certain simulators depended
+upon by test executables.
+
+**Default**: 1
+
+## `:which_ceedling`
+
+This is an advanced project option primarily meant for development work on
+Ceedling itself. This setting tells the code that launches the Ceedling
+application where to find the code to launch.
+
+This entry can be either a directory path or `gem`.
+
+See the section [Which Ceedling](../which-ceedling.md) for full details.
+
+**Default**: `gem`
+
+## `:use_backtrace`
+
+When a test executable encounters a ☠️ **Segmentation Fault** or other crash
+condition, the executable immediately terminates and no further details for test
+suite reporting are collected.
+
+But, fear not. You can bring your dead unit tests back to life.
+
+By default, in the case of a crash, Ceedling reruns the test executable for
+each test case using a special mode to isolate that test case. In this way
+Ceedling can iteratively identify which test cases are causing the crash or
+exercising release code that is causing the crash. Ceedling then assembles the
+final test reporting results from these individual test case runs.
+
+You have three options for this setting, `:none`, `:simple`, or `:gdb`.
+
+### `:none`
+`:none` will simply cause a test report to list each test case as failed
+due to a test executable crash.
+
+Sample Ceedling run output with backtrace `:none`:
+
+```
+👟 Executing
+------------
+Running TestUsartModel.out...
+☠️ ERROR: Test executable `TestUsartModel.out` seems to have crashed
+
+-------------------
+FAILED TEST SUMMARY
+-------------------
+[test/TestUsartModel.c]
+  Test: testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting
+  At line (24): "Test executable crashed"
+
+  Test: testCrash
+  At line (37): "Test executable crashed"
+
+  Test: testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately
+  At line (44): "Test executable crashed"
+
+  Test: testShouldReturnErrorMessageUponInvalidTemperatureValue
+  At line (50): "Test executable crashed"
+
+  Test: testShouldReturnWakeupMessage
+  At line (56): "Test executable crashed"
+
+-----------------------
+❌ OVERALL TEST SUMMARY
+-----------------------
+TESTED:  5
+PASSED:  0
+FAILED:  5
+IGNORED: 0
+```
+
+### `:simple`
+`:simple` causes Ceedling to re-run each test case in the test executable
+individually to identify and report the problematic test case(s). This is
+the default option and is described above.
+
+Sample Ceedling run output with backtrace `:simple`:
+
+```
+👟 Executing
+------------
+Running TestUsartModel.out...
+☠️ ERROR: Test executable `TestUsartModel.out` seems to have crashed
+
+-------------------
+FAILED TEST SUMMARY
+-------------------
+[test/TestUsartModel.c]
+  Test: testCrash
+  At line (37): "Test case crashed >> Segmentation fault (core dumped)"
+
+-----------------------
+❌ OVERALL TEST SUMMARY
+-----------------------
+TESTED:  5
+PASSED:  4
+FAILED:  1
+IGNORED: 0
+```
+
+### `:gdb`
+`:gdb` uses the [`gdb`][gdb] debugger to identify and report the troublesome
+line of code triggering the crash. If this option is enabled, but `gdb` is
+not available to Ceedling, project configuration validation will terminate
+with an error at startup.
+
+With `gdb` in use, Ceedling will provide a brief crash summary from details
+extracted from the `gdb` report. Ceedling will attempt to surface in the 
+summary the offending line of code or failing `assert()` from the report.
+
+The full `gdb` report is captured to a log file, and the log filepath is 
+provided in the crash summary. The log filepath will comprise the containing 
+test executable as a subdirectory and the name of the crashing test case 
+function as the filename.
+
+Sample Ceedling run output with backtrace `:gdb`:
+
+```
+👟 Executing
+------------
+Running TestUsartModel.out...
+☠️ ERROR: Test executable `TestUsartModel.out` seems to have crashed
+
+-------------------
+FAILED TEST SUMMARY
+-------------------
+[test/TestUsartModel.c]
+  Test: testCrash
+  At line (40): "Test case crashed >> [SIGSEGV] Segmentation fault
+                `uint32_t i = *null_ptr;`
+                (build/logs/test/TestUsartModel/testCrash.gdb.log)"
+
+-----------------------
+❌ OVERALL TEST SUMMARY
+-----------------------
+TESTED:  5
+PASSED:  4
+FAILED:  1
+IGNORED: 0
+```
+
+**_Notes:_**
+
+1. The default of `:simple` only works in an environment capable of using
+   command line arguments (passed to the test executable). If you are targeting
+   a simulator with your test executable binaries, `:simple` is unlikely to
+   work for you. In the simplest case, you may simply fall back to `:none`.
+   With some work and using Ceedling's various features, much more sophisticated
+   options are possible.
+1. The `:gdb` option currently only supports the native build platform. That is,
+   the `:gdb` backtrace option cannot handle backtrace for cross-compiled code
+   or any sort of simulator-based test fixture.
+
+[gdb]: https://www.sourceware.org/gdb/
+
+**Default**: `:simple`
+
+<br/><br/>