ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/plugins/module-generator.md

@@ -1,267 +0,0 @@
-# Module Generator
-
-This plugin adds a pair of new commands to Ceedling allowing you to generate or remove 
-module skeletons according to predefined templates.
-
-## Overview
-With a single call, Ceedling can generate a source, header, and test file for a new 
-module. If given a pattern, it can even create a series of submodules to support 
-specific design patterns. Finally, it can just as easily remove related modules, 
-avoiding the need to delete each individually.
-
-Let's say, for example, that you want to create a single module named `MadScience`.
-
-```sh
-ceedling module:create[MadScience]
-```
-
-It says we're speaking to the module plugin, and we want to create a new module. The
-name of that module is between the brackets. It will keep this case, unless you have
-specified a different default (see configuration). It will create three files:
-`MadScience.c`, `MadScience.h`, and `TestMadScience.c`. *NOTE* that it is important that
-there are no spaces between the brackets. We know, it's annoying... but it's the rules.
-
-## Patterns
-
-You can also create an entire pattern of files. To do that, just add a second argument
-to the pattern ID. Something like this:
-
-```sh
-ceedling module:create[SecretLair,mch]
-```
-
-In this example, we'd create 9 files total: 3 headers, 3 source files, and 3 test files. These
-files would be named `SecretLairModel`, `SecretLairConductor`, and `SecretLairHardware`. Isn't
-that nice?
-
-The module generator understands the following patterns:
-
-- `src` -- generate only a source file
-- `test` -- generate only a test file
-- `dh` -- generate 6 files for the driver-hardware pattern
-- `dih` -- generate 9 files for the driver-interrupt-hardware pattern
-- `mch` -- generate 9 files for the model-conductor-hardware pattern
-- `mvp` -- generate 9 files for the model-view-presenter pattern
-
-## Paths
-
-The directories found in the project `:paths:` are reused. You can also specify an alternative default generation path using: 
-
-```yaml
-:module_generator:
-  :path_src: src/
-  :path_inc: src/
-  :path_tst: test/
-```
-
-But what if I don't want it to place my new files in the default location?
-
-It can do that too! You can give it a hint as to where to find your files. The pattern matching
-here is fairly basic, but it is usually sufficient. It works perfectly if your directory structure
-matches a common pattern. For example, let's say you issue this command:
-
-```sh
-ceedling module:create[lab:SecretLair,mch]
-```
-
-Say your directory structure looks like this:
-
-```yaml
-:paths:
-  :source:
-    - lab/src
-    - lair/src
-    - other/src
-  :test:
-    - lab/test
-    - lair/test
-    - other/test
-```
-
-In this case, the `lab:` hint would make the module generator guess you want your files here:
-
-- source files: `lab/src` (because it's a close match)
-- include files: `lab/src` (because no include paths were listed)
-- test files: `lab/test` (because it's a close match)
-
-Instead, if your directory structure looks like this:
-
-```yaml
-:paths:
-  :source:
-    - src/**   #this might contain subfolders lab, lair, and other
-  :include:
-    - inc/**   #again, this might contain subfolders lab, lair, other, and shared
-  :test:
-    - test
-```
-
-In this case, the `lab:` hint would make the module generator guess you want your files here:
-
-- source files: `src/lab` (because it's a close match)
-- include files: `inc/lab` (because it's a close match)
-- test files: `test` (because there wasn't a close match, and this was the first entry on our list)
-
-You can see that more complicated structures will have files placed in the wrong place from time to
-time... no worries... you can move the file after it's created... but if your project has any kind of 
-consistent structure, the guessing engine does a good job of making it work.
-
-A few more quick notes about the path-matching:
-
-1. You can give multiple ordered hints that map roughly to folder nesting! `lab:secret:lair` will 
-   happily match to put `lair.c` in a folder like `my/lab/secret/`.
-
-2. If the matcher isn't given any path information or it finds multiple equally good candidates, 
-   it will always guess in the order you have the paths listed in your project.yml file
-
-3. If the matcher completely fails to find a good candidate, it will return an error, allowing you
-   to rectify the situation.
-
-4. What path is "first" when you're using `**` pattern in your `:paths:` specifications? The parent
-   folder is used first, then its children alphabetically, and so on. This is important when 
-   considering where files (or especially subfolders... see below) will be generated.
-
-### Adding to Paths
-
-In addition to the pattern matching above, you can add slashes (`/`) to your filename specification.
-When a slash is used instead of a colon (`:`), it will stop using pattern matching and assume the
-subdirectory is supposed to be there. If the subdir is NOT there, it will automatically add it.
-
-Let's try an example with our previous path specification:
-
-```yaml
-:paths:
-  :source:
-    - src/**   #this might contain subfolders lab, lair, and other
-  :include:
-    - inc/**   #again, this might contain subfolders lab, lair, other, and shared
-  :test:
-    - test
-```
-
-Then, use the following command:
-
-```sh
-ceedling module:create[newlab/SecretLair]
-```
-
-This will create the following 3 files:
-
-- `src/newlab/SecretLair.c`
-- `inc/newlab/SecretLair.h`
-- `test/newlab/TestSecretLair.c`
-
-Technically, you can start with a colon and specify part of a path, then use a slash
-to specify the remainder of the path to use. In most circumstances, this should work... however
-it suffers from the same potential issues as the matcher above, with the added joy of creating 
-new subdirectories for you without asking. 
-
-It's important to note the module generator doesn't care if these new subdirectories are covered 
-by the current path specification. This allows you to create the files before updating the
-`project.yml` file if desired, but it also means you might accidentally think you've created
-a file that Ceedling can see, when it can't. 
-
-## Stubbing
-
-Similarly, you can create stubs for all functions in a header file just by making a single call
-to your handy `stub` feature, like this:
-
-```sh
-ceedling module:stub[SecretLair]
-```
-
-This call will look in `SecretLair.h` and will generate a file `SecretLair.c` that contains a stub
-for each function declared in the header! Even better, if `SecretLair.c` already exists, it will
-add only new functions, leaving your existing calls alone so that it doesn't cause any problems.
-
-## Configuration
-
-Enable the plugin in your project.yml by adding `module_generator`
-to the list of enabled plugins.
-
-Then, like much of Ceedling, you can just run as-is with the defaults, or you can override those
-defaults for your own needs. For example, new source and header files will be automatically
-placed in the `src/` folder while tests will go in the `test/` folder. That's great if your project
-follows the default ceedling structure... but what if you have a different structure?
-
-```yaml
-:module_generator:
-  :naming: :bumpy
-  :includes: 
-    - :src: []
-    - :inc: []
-    - :tst: []
-  :boilerplates:
-    - :src: ""
-    - :inc: ""
-    - :tst: ""
-```
-
-Now I've redirected the location where modules are going to be generated.
-
-### Includes
-
-You can make it so that all of your files are generated with a standard include list. This is done
-by adding to the `:includes` array. For example:
-
-```yaml
-:module_generator:
-  :includes:
-    :tst:
-      - defs.h
-      - board.h
-    :src:
-      - board.h
-```
-
-### Boilerplates
-
-You can specify the actual boilerplate used for each of your files. This is the handy place to
-put that corporate copyright notice (or maybe a copyleft notice, if that's your preference?)
-
-Notice there is a separate template for source files, include files, and test files. Also, 
-your boilerplates can optionally contain `%1$s` which will inject the filename into that spot.
-
-```yaml
-:module_generator:
-  :boilerplates: 
-    :src: |
-      /***************************
-      * %1$s
-      * This file is Awesome.
-      * That is All.
-      ***************************/
-    :inc: |
-      /***************************
-      * Header. Woo.             *
-      ***************************/
-    :tst: |
-      /***************************
-      * My Awesome Test For %1$s
-      ***************************/
-```
-
-### Test Defines
-
-You can specify the "#ifdef TEST" at the top of the test files with a custom define.
-This example will put a "#ifdef CEEDLING_TEST" at the top of the test files.  
-
-```yaml
-:module_generator:
-  :test_define: CEEDLING_TEST
-```
-
-### Naming Convention
-
-Finally, you can force a particular naming convention. Even if someone calls the generator
-with something like `MyNewModule`, if they have the naming convention set to `:caps`, it will
-generate files like `MY_NEW_MODULE.c`. This keeps everyone on your team behaving the same way.
-
-Your options for `:naming:` are as follows:
-
-    - `:bumpy` - BumpyFilesLooksLikeSo
-    - `:camel` - camelFilesAreSimilarButStartLow
-    - `:snake` - snake_case_is_all_lower_and_uses_underscores
-    - `:caps`  - CAPS_FEELS_LIKE_YOU_ARE_SCREAMING
-
-<br/><br/>

data/docs/mkdocs/plugins/report-build-warnings-log.md

@@ -1,42 +0,0 @@
-# Build Warnings Log
-
-Capture build process warnings from command tools to a plain text log file.
-
-## Overview
-
-This plugin captures warning messages output by command line tools throughout a
-build. At the end of a build, any collected warning messages are written to one 
-or more plain text log files.
-
-Warning messages are collected for all compilation-related builds and
-differentiated by build context — `test`, `release`, or plugin-modified build 
-(e.g. `gcov`).
-
-Ceedling warning messages or warning messages from code generation will not
-appear in log files; warnings are only collected from build step command line
-tools for the predefined build steps of preprocessing, compilation, and
-linking.
-
-Log files are written to `<build root>/artifacts/<context>/`.
-
-## Setup
-
-Enable the plugin in your Ceedling project file:
-
-```yaml
-:plugins:
-  :enabled:
-    - report_build_warnings_log
-```
-
-## Configuration
-
-To change the default filename of `warning.log`, add your desired filename to
-your configuration file using `:report_build_warnings_log:` ↳ `:filename`.
-
-```yaml
-:report_build_warnings_log:
-  :filename: more_better_filename.ext
-```
-
-<br/><br/>

data/docs/mkdocs/plugins/report-tests-gtestlike-stdout.md

@@ -1,98 +0,0 @@
-# GTest-like Console Report
-
-Prints to the console ($stdout) test suite results in a GTest-like format.
-
-## Plugin Overview
-
-This plugin is intended to be used in place of the more commonly used "pretty" 
-test report plugin. Like its sibling, this plugin ollects raw test results from
-the individual test executables of your test suite and presents them in a more 
-readable summary form — specifically the GoogleTest format.
-
-This plugin is most useful when using an IDE or working with a CI system that
-understands the GTest console logging format.
-
-## Setup
-
-Enable the plugin in your Ceedling project by adding 
-`report_tests_gtestlike_stdout` to the list of enabled plugins instead of any 
-other `report_tests_*_stdout` plugin.
-
-```YAML
-:plugins:
-  :enabled:
-    - report_tests_gtestlike_stdout
-```
-
-## Configuration
-
-No additional configuration is needed once the plugin is enabled.
-
-## Plugin Output
-
-### Ceedling mapped to GoogleTest reporting elements
-
-Ceedling's conventions and output map to GTest format as the following:
-
-* A Ceedling test file — ultimately an individual test executable — is a GTest 
-  _test case_.
-* A Ceedling test case (a.k.a. unit test) is a GTest _test_.
-* Execution time is collected for each Ceedling test executable, not each 
-  Ceedling test case. As such, the test report includes only execution time for
-  each GTest _test case_. Individual test execution times are reported as 0 ms.
-
-GoogleTest generates reporting output incrementally. Ceedling produces test 
-results incrementally as well, but its plugin reporting structure does not 
-collect and format statistics until the end of a build. This plugin duplicates
-the tense of the wording in a GTest report, but it is unintentionally somewhat 
-misleading.
-
-### Example output (snippet)
-
-The GTest format is verbose. It lists all tests with success and failure results.
-
-The example output below shows the header and footer of test results for a suite 
-of 49 Ceedling tests in 18 test files but only includes logging for 6 tests.
-
-```sh
- > ceedling test:all
-```
-
-```
-[==========] Running 49 tests from 18 test cases.
-[----------] Global test environment set-up.
- 
- ...
-
-[----------] 4 tests from test/TestUsartModel.c
-[ RUN      ] test/TestUsartModel.c.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting
-[       OK ] test/TestUsartModel.c.testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting (0 ms)
-[ RUN      ] test/TestUsartModel.c.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately
-[       OK ] test/TestUsartModel.c.testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately (0 ms)
-[ RUN      ] test/TestUsartModel.c.testShouldReturnErrorMessageUponInvalidTemperatureValue
-[       OK ] test/TestUsartModel.c.testShouldReturnErrorMessageUponInvalidTemperatureValue (0 ms)
-[ RUN      ] test/TestUsartModel.c.testShouldReturnWakeupMessage
-[       OK ] test/TestUsartModel.c.testShouldReturnWakeupMessage (0 ms)
-[----------] 4 tests from test/TestUsartModel.c (1277 ms total)
-[----------] 1 tests from test/TestMain.c
-[ RUN      ] test/TestMain.c.testMainShouldCallExecutorInitAndContinueToCallExecutorRunUntilHalted
-[       OK ] test/TestMain.c.testMainShouldCallExecutorInitAndContinueToCallExecutorRunUntilHalted (0 ms)
-[----------] 1 tests from test/TestMain.c (1351 ms total)
-[----------] 1 tests from test/TestModel.c
-[ RUN      ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit
-test/TestModel.c(21): error: Function TaskScheduler_Init() called more times than expected.
- Actual:   FALSE
- Expected: TRUE
-[  FAILED  ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit (0 ms)
-[----------] 1 tests from test/TestModel.c (581 ms total)
-
-[----------] Global test environment tear-down.
-[==========] 49 tests from 18 test cases ran.
-[  PASSED  ] 48 tests.
-[  FAILED  ] 1 tests, listed below:
-[  FAILED  ] test/TestModel.c.testInitShouldCallSchedulerAndTemperatureFilterInit
-
- 1 FAILED TESTS
-```
-
-<br/><br/>

data/docs/mkdocs/plugins/report-tests-ide-stdout.md

@@ -1,63 +0,0 @@
-# IDE Test Suite Console Report
-
-Prints to the console ($stdout) test suite results with a test failure filepath and line number format understood by nearly any IDE.
-
-## Plugin Overview
-
-This plugin is intended to be used in place of the more commonly used "pretty" 
-test report plugin. Like its sibling, this plugin ollects raw test results from
-the individual test executables of your test suite and presents them in a more 
-readable summary form.
-
-The format of test results produced by this plugin is identical to its prettier
-sibling with one key difference — test failures are listed in such a way that 
-filepaths, line numbers, and test case function names can be easily parsed by 
-a typical IDE. The formatting of test failure messages uses a simple, defacto 
-standard of a sort recognized almost universally.
-
-The end result is that test failures in your IDE's build window can become 
-links that jump directly to failing test cases.
-
-## Setup
-
-Enable the plugin in your project.yml by adding `report_tests_ide_stdout` to 
-the list of enabled plugins instead of any other `report_tests_*_stdout` 
-plugin.
-
-```YAML
-:plugins:
-  :enabled:
-    - report_tests_ide_stdout
-```
-
-## Configuration
-
-No additional configuration is needed once the plugin is enabled.
-
-## Example Output
-
-```sh
- > ceedling test:Model
-```
-
-```
--------------------
-FAILED TEST SUMMARY
--------------------
-test/TestModel.c:21:testInitShouldCallSchedulerAndTemperatureFilterInit: "Function TaskScheduler_Init() called more times than expected."
-
---------------------
-OVERALL TEST SUMMARY
---------------------
-TESTED:  1
-PASSED:  0
-FAILED:  1
-IGNORED: 0
-
----------------------
-BUILD FAILURE SUMMARY
----------------------
- • Unit test failures.
-```
-
-<br/><br/>