ceedling 1.1.10 → 1.2.0

data/docs/mkdocs/plugins/command-hooks.md

@@ -1,268 +0,0 @@
-# Command Hooks
-
-Easily run command line tools and scripts at various points in a Ceedling build.
-
-## Plugin Overview
-
-This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling’s programmatic `Plugin` code hooks to easily managed tool definitions. 
-
-## Setup
-
-To use this plugin, it must be enabled:
-
-```yaml
-:plugins:
-  :enabled:
-    - command_hooks
-```
-
-## Configuration
-
-### Overview
-
-To connect utilties or scripts to build step hooks, Ceedling tools must be defined.
-
-A Ceedling tool is just a YAML blob that gathers together a handful of settings and values that tell Ceedling how to build and execute a command line. Your tool can be a command line utility, a script, etc.
-
-Example Ceedling tools follow. When enabled, this plugin ensures any tools you define are executed by the corresponding build step hook they are organized beneath. The configurtion of enabled hooks and tools happens in a top-level `:command_hooks:` block within your project configuration. One or more tools can be attached to a build step hook.
-
-### Tool lists
-
-A command hook can execute one or more tools.
-
-If only a single tool is needed, its hash keys and value can be organized as a YAML sub-hash beneath the hook key. Alternatively, a single tool can exist as the only entry in a YAML list.
-
-If multiple tools are needed, they must be organized as entries in a YAML list.
-
-See the commented examples below.
-
-### Tool definitions
-
-Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See the [`:tools` configuration reference][tools-doc] to understand how to craft your argument list and other tool options.
-
-This plugin passes one or two runtime parameters for use in a hook’s tool argument list depending on the hook. These parameters are referenced with Ceedling tool argument expansion identifiers `${1}`, `${2}`, etc. Wherever you place `${1}` or `${2}` in your tool argument list, they expand in the command line Ceedling constructs with the parameters this plugin provides for that build step hook. The list of build step hooks below documents which parameters are available for each hook.
-
-Each tool may optionally include a `:name` — a simple nickname used in log and error messages. If omitted, the plugin forms a default name from the hook’s key (e.g. `pre_mock_generate`). For a hook configured with a list of tools, the default name additionally includes the tool’s position in the list (e.g. `post_link_execute_0`, `post_link_execute_1`). See the commented examples below.
-
-[tools-doc]: ../configuration/reference/tools.md
-
-### Hook logging
-
-In addition to the standard Ceedling tool definition elements, a hook configuration entry may optionally include a `:logging` setting.
-
-`:logging` may be set to `TRUE` or `FALSE`. An omitted setting is equivalent to `FALSE`.
-
-When logging is enabled and logging conditions are appropriate, any output from the hook tool will be logged to the console with a brief header identifying the hook.
-
-* Explicit command hook output logging only occurs at verbosity levels Normal and Obnoxious.
-* Debug logging naturally displays hook output as part of normal tool execution logging. It is not duplicated by hook logging.
-* At Normal verbosity, blank hook output is not logged at all; Obnoxious verbosity will display blank output as `<empty>`.
-
-### Command Hooks example configuration YAML
-
-```yaml
-:command_hooks:
-  # Hook called every time a mock is generated
-  # Who knows what my_script.py does -- sky is the limit
-  :pre_mock_generate:
-    # This tool is organized as a sub-hash beneath the command hook key
-    :executable: python
-    :name: 'mock prep script' # Explicit nickname used in log/error messages
-    :arguments:
-      - my_script.py
-      - --some-arg
-      - ${1} # Replaced with the filepath of the header file that will be mocked
-    :logging: TRUE # Log any tool output to console
-      
-  # Hook called for each linking operation
-  # Here, we are performing two tasks for the same build step hook, converting a
-  # binary executable to S-record format and, then, archiving with other artifacts.
-  # Neither tool below is given a :name -- the plugin defaults them to
-  # "post_link_execute_0" and "post_link_execute_1"
-  :post_link_execute:
-    # These tools are organized in a YAML list beneath the command hook key
-    - :executable: objcopy.exe
-      :arguments:
-        - ${1} # Replaced with the filepath to the linker’s binary artifact output
-        - output.srec
-        - --strip-all
-    - :executable: 
-      :arguments: tar.exe
-        - -acf
-        - awesome_build.zip
-        - ${1} # Replaced with the filepath to the linker’s binary artifact output
-        - memory_report.txt
-```
-
-## Available Build Step Hooks
-
-Define any of the following entries within a top-level `:command_hooks:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps.
-
-Some hooks are called for every file-related operation for which the hook is named. Other hooks are triggered by the single build step for which the hook is named.
-
-As an example, consider a Ceedling project with ten test files and seventeen mocks. The command line `ceedling test:all` would trigger:
-
-* 1 occurrence of the `:pre_build` hook.
-* 1 occurrence of the `:pre_test_build` hook.
-* 10 occurrences of the `:pre_test` and `:post_test` hooks.
-* 17 occurrences of the `:pre_mock_generate` and `:post_mock_generate` hooks.
-* 10 occurrences of the `:pre_test_runner_generate` and `:post_test_runner_generate` hooks.
-* 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity’s source, CMock’s source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
-* 10 occurrences of the `:pre_link` and `:post_link` hooks for test executable creation.
-* 10 occurrences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
-* 1 occurrence of the `:post_test_build` hook.
-* 1 occurrence of the `:post_build` hook unless a build error occurred (`:post_error` would be called instead).
-
-### `:pre_build`
-
-Called once just before Ceedling executes any tasks.
-
-The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_build` value can be used to compute the total build duration.
-
-### `:post_build`
-
-Called once just before Ceedling terminates after a successful build.
-
-The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_build` value can be used to compute the total build duration.
-
-### `:post_error`
-
-Called once just after any build failure and just before Ceedling terminates.
-
-The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds at the moment the error is handled.
-
-### `:pre_test`
-
-Called just before each test begins its build pipeline and just after all context for that build has been gathered.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-### `:post_test`
-
-Called just after each test completes its build and execution.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-### `:pre_test_build`
-
-Called once just before the full test build pipeline begins (before any individual test’s configure, preprocess, compile, link, or execute steps).
-
-Two parameters are available to a tool when the hook is called:
-
-* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
-* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `post_test_build` value can be used to compute the total test build duration.
-
-### `:post_test_build`
-
-Called once just after the full test build pipeline completes or terminates (including on error).
-
-Two parameters are available to a tool when the hook is called:
-
-* `${1}` — the build context as a string (e.g. `"test"`, `"gcov"`).
-* `${2}` — a floating-point stopwatch value in seconds. This value and the corresponding `pre_test_build` value can be used to compute the total test build duration.
-
-### `:pre_release_build`
-
-Called once just before a release build begins.
-
-The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `post_release_build` value can be used to compute the total release build duration.
-
-### `:post_release_build`
-
-Called once just after a release build finishes or terminates (including on error).
-
-The parameter available to a tool (`${1}`) when the hook is called is a floating-point stopwatch value in seconds. This value and the corresponding `pre_release_build` value can be used to compute the total release build duration.
-
-### `:pre_mock_preprocess`
-
-If mocks are enabled and preprocessing is in use, this is called just before each header file to be mocked is preprocessed.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
-
-See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
-
-[preprocessing]: ../testing-guide/conventions.md#test-preprocessing
-
-### `:post_mock_preprocess`
-
-If mocks are enabled and preprocessing is in use, this is called just after each header file to be mocked is preprocessed.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
-
-### `:pre_mock_generate`
-
-If mocks are enabled, this is called just before each header file to be mocked is processed by mock generation.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
-
-### `:post_mock_generate`
-
-If mocks are enabled, this is called just after each mock generation.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
-
-### `:pre_test_preprocess`
-
-If preprocessing is in use, this is called just before each test file is preprocessed before runner generation.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
-
-### `:post_test_preprocess`
-
-If preprocessing is in use, this is called just after each test file is preprocessed.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-See [_Conventions & Behaviors_][preprocessing] for details on how Ceedling preprocessing operates.
-
-### `:pre_runner_generate`
-
-Called just before each test file is processed by test runner generation.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-### `:post_runner_generate`
-
-Called just after each test runner is generated.
-
-The parameter available to a tool (`${1}`) when the hook is called is the test’s filepath.
-
-### `:pre_compile_execute`
-
-Called just before each C or assembly file is compiled.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the file to be compiled.
-
-### `:post_compile_execute`
-
-Called just after each file compilation.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the input file that was compiled.
-
-### `:pre_link_execute`
-
-Called just before any binary artifact—test or release—is linked.
-
-The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact’s filepath.
-
-### `:post_link_execute`
-
-Called just after a binary artifact is linked.
-
-The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact’s filepath.
-
-### `:pre_test_fixture_execute`
-
-Called just before each test is executed in its corresponding test fixture.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact to be executed by the fixture.
-
-### `:post_test_fixture_execute`
-
-Called just after each test’s fixture is executed and test results are collected.
-
-The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact that was executed by the fixture.
-
-<br/><br/>

data/docs/mkdocs/plugins/compile-commands-json-db.md

@@ -1,42 +0,0 @@
-# JSON Compilation Database
-
-Language Server Protocol (LSP) support for Clang tooling.
-
-## Background
-
-Syntax highlighting and code completion are hard. Historically each editor or IDE has implemented their own and then competed amongst themselves to offer the best experience for developers. Good syntax highlighting can be so valuable as to outweigh the consideration of alternate editors. If implementing sytnax highlighting and related features in a tool is hard for one language — and it is — imagine doing it for dozens of them. Further, on the flip side, imagine the complexities involved for a developer working with multiple languages at once.
-
-In June of 2016, Microsoft with Red Hat and Codenvy got together to create the [Language Server Protocol (LSP)][lsp-microsoft] ([community site][lsp-community]). The idea was simple. By standardizing, any conforming IDE or editor would only need to support LSP instead of custom plugins for each language. In turn, the backend code that performs syntax highlighting and similar features can be written once and used by any IDE that supports LSP. Today, [Many editors support LSP][lsp-tools].
-
-[lsp-microsoft]: https://microsoft.github.io/language-server-protocol/
-[lsp-community]: https://langserver.org/
-[lsp-tools]: https://microsoft.github.io/language-server-protocol/implementors/tools/
-
-## Plugin Overview
-
-For C and C++ projects, perhaps the most popular LSP server is the [`clangd`][clangd] backend. In order to provide features like _go to definition_, `clangd` needs to understand how to build a project so that it can discover all the pieces to the puzzle. Because of the various flavors of builds Ceedling supports and especially because of the complexities of test suite builds, components of a build can easily go missing from the view of `clangd`.
-
-This plugin gives `clangd` — or any tool that understands a [JSON compilation database][json-compilation-database] — full visibility into a Ceedling build.
-
-Once enabled, this plugin generates the database as `<build root>/artifacts/compile_commands.json` for each new build. Tools that understand JSON Compilation Database files can then process it to make their features fully available to you.
-
-[clangd]: https://clangd.llvm.org
-[json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
-
-## Setup
-
-Enable the plugin in your Ceedling project file by adding `compile_commands_json_db` to the list of enabled plugins.
-
-``` YAML
-:plugins:
-  :enabled:
-    - compile_commands_json_db
-```
-
-## Configuration
-
-There is no additional configuration necessary to run this plugin.
-
-`clangd` will search your build directory for the JSON compilation database, but in some instances on Unix-asbed platforms it can be easier and necessary to symlink the file into the root directory of your project (e.g. `ln -s ./build/artifacts/compile_commands.json .`).
-
-<br/><br/>

data/docs/mkdocs/plugins/cppcheck.md

@@ -1,377 +0,0 @@
-# Cppcheck
-
-Adds Ceedling tasks to execute Cppcheck static analysis, helping detect
-undefined behavior, dangerous code patterns, and style issues across your
-project or individual files.
-
-## Plugin overview
-
-The Cppcheck plugin integrates [Cppcheck](https://cppcheck.sourceforge.io)
-static analysis into Ceedling, facilitating automated code quality checks as
-part of your development workflow. It provides two analysis modes:
-
-- **Whole project analysis**: By running `ceedling cppcheck:all`, all project
-source files will be analyzed with all checks enabled (`--enable=all`) and
-configurable reports can be generated in multiple formats.
-- **Single file analysis**: By running `ceedling cppcheck:<filename>`, an
-individual source file will be analyzed using the checks configured in the
-`:enable_checks` list (defaults to `style`).
-
-The plugin supports extensive Cppcheck configuration options such as platform,
-language standard, preprocessor defines, include/exclude paths, and suppression
-management. It also integrates with advanced features like MISRA addons, custom
-check levels, library configuration files, and regular expression rules. All of
-these can be configured in your `project.yml` file.
-
-The plugin can produce reports in HTML, SARIF, text, and XML (v2 and v3)
-formats, all stored under the build artifacts directory.
-
-It also suppoprts using a project file (such as `compile_commands.json` or a
-Cppcheck GUI project), in which case, the plugin delegates source and include
-path discovery to Cppcheck rather than using Ceedling's own file collection.
-
-## Setup
-
-Enable the plugin by adding `cppcheck` to the enabled plugins list in your
-`project.yml` file:
-
-```yaml
-:plugins:
-  :enabled:
-    - cppcheck
-```
-
-## Configuration
-
-Add `cppcheck` section to your `project.yml` specifying configuration options.
-e.g:
-
-```yaml
-:cppcheck:
-  :reports:
-    - html
-  :addons:
-    - misra
-```
-
-### Reports
-
-Four types of reports are available:
-
-- html
-- sarif
-- text
-- xml (v2 and v3)
-
-They can be enabled by listing them on the `:reports` list:
-
-```yaml
-:cppcheck:
-  :reports:
-    - text
-    - html
-```
-
-#### HTML
-
-HTML title can be configured:
-
-```yaml
-:cppcheck:
-  :html_title: Awesome Project
-```
-
-*Notes:*
-
-- This report requires the `cppcheck-htmlreport` tool to be available.
-- This report implies the `xml` report.
-
-#### Sarif
-
-Artifact file can be configured:
-
-```yaml
-:cppcheck:
-  :sarif_artifact_filename: CppcheckResults.sarif
-```
-
-#### Text
-
-Artifact file and output format can be configured:
-
-```yaml
-:cppcheck:
-  :text_artifact_filename: CppcheckResults.txt
-  :template: gcc
-```
-
-`:template` can be any of the ones included with Cppcheck or custom format string.
-
-#### XML
-
-Artifact file and XML version can be configured:
-
-```yaml
-:cppcheck:
-  :xml_artifact_filename: CppcheckResults.xml
-  :xml_report_version: 2
-```
-
-### Import project file
-
-You can import some project files and build configurations into Cppcheck.
-Some of compatible files are:
-
-- Cppcheck GUI project (\*.cppcheck)
-- Compile Commands (compile_commands.json)
-- Visual Studio projects (\*.vcxproj, \*.sln)
-
-```yaml
-:cppcheck:
-  :project: path/to/compile_commands.json
-```
-
-*Note: If configured, Cppcheck won't look for sources and includes paths from*
-*_Ceedling_ configuration files.*
-
-### Preprocessor defines
-
-#### Define
-
-```yaml
-:cppcheck:
-  :defines:
-    - A
-    - B
-    - C=1
-```
-
-#### Undefine
-
-```yaml
-:cppcheck:
-  :undefines:
-    - A
-    - B
-    - C
-```
-
-*Note: By default `TEST` is undefined so the analysis is performed against production code.*
-
-### Includes
-
-Force inclusion of files before checked files.
-
-```yaml
-:cppcheck:
-  :includes:
-    - file1.h
-    - file2.h
-```
-
-### Excludes
-
-Exclude files from the analysis.
-
-```yaml
-:cppcheck:
-  :excludes:
-    - file1.c
-    - file2.c
-```
-
-### Platform
-
-Specify platform to use for the analysis, can be any of the ones included with
-Cppcheck, e.g.: unix64, or the path of the platform XML file.
-
-```yaml
-:cppcheck:
-  :platform: unix64
-```
-
-### Standard
-
-Specify C/C++ language standard.
-
-```yaml
-:cppcheck:
-  :standard: c99
-```
-
-### Check level
-
-Specify the check level to be used.
-
-- *normal*
-- *exhaustive*
-
-```yaml
-:cppcheck:
-  :check_level: exhaustive
-```
-
-### Addons
-
-Addons to be run.
-
-```yaml
-:cppcheck:
-  :addons:
-    - misra
-    - path/to/addon.py
-```
-
-#### MISRA with rule texts file
-
-Locate your rules text file or copy it to your project.
-e.g.: `<your-project>/misra.txt` and create the addon file `misra.json` inside
-your project:
-
-##### **`misra.json`**
-```json
-{
-	"script": "misra",
-	"args": ["--rule-texts=misra.txt"]
-}
-```
-
-Enable the addon:
-
-```yaml
-:cppcheck:
-  :addons:
-    - misra.json
-```
-
-### Checks
-
-Enable additional checks.
-Default is *style*.
-
-```yaml
-:cppcheck:
-  :enable_checks:
-    - performance
-    - portability
-```
-
-*Note: These are only used for single file analysis.*
-*Whole project analysis always enable all checks.*
-
-Disable individual checks:
-
-```yaml
-:cppcheck:
-  :disable_checks:
-    - style
-    - information
-```
-
-### Suppressions
-
-#### Inline
-
-Inline suppressions are disabled by default, they can be enabled with:
-
-```yaml
-:cppcheck:
-  :inline_suppressions: true
-```
-
-#### List files
-
-Suppressions files can be used by giving the search paths and/or files in the
-`:paths` and `:files` sections of  your `project.yml` respectively.
-e.g.:
-
-```yaml
-:paths:
-  :cppcheck:
-    - suppressions/
-    - source/*/suppressions/
-
-:files:
-  :cppcheck:
-    - suppressions.xml
-```
-
-Both XML and text files are supported, and for the latter, the file extension
-can be configured. The default is `.txt`.
-e.g.:
-
-```yaml
-:extension:
-  :cppcheck: .txt
-```
-
-The files that will ultimately be used can be verified with:
-
-```shell
-$ ceedling files:cppcheck
-```
-
-#### Command line
-
-Command line suppressions can also be added:
-
-```yaml
-:cppcheck:
-  :suppressions:
-    - memleak:src/file1.cpp
-    - exceptNew:src/file1.cpp
-```
-
-### Library configuration
-
-Add library configuration files:
-
-```yaml
-:cppcheck:
-  :libraries:
-    - lib1.cfg
-    - lib2.cfg
-```
-
-### Rules
-
-Regular expression rules:
-
-```yaml
-:cppcheck:
-  :rules:
-    - if \( p \) { free \( p \) ; }
-```
-
-### Extra options
-
-For things not covered above, add extra command line options:
-
-```yaml
-:cppcheck:
-  :options:
-    - --max-configs=<limit>
-    - --suppressions-list=<file>
-```
-
-## Usage
-
-### Analyze whole project
-
-Run analysis for all project sources:
-
-```shell
-$ ceedling cppcheck:all
-```
-
-*Note: Analysis is run with* all *checks enabled.*
-
-### Analyze single file
-
-Run analysis for single source file:
-
-```shell
-$ ceedling cppcheck:<filename>
-```
-
-*Note: Analysis will run with the checks in [`:enable_checks`](#checks) list enabled.*