ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/plugins/cppcheck.md

@@ -0,0 +1,377 @@
+# 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.*

data/{plugins/dependencies/README.md → docs/mkdocs/plugins/dependencies.md}

@@ -1,18 +1,17 @@
-ceedling-dependencies
-=====================
+# Dependencies
 
-Plugin for supporting release dependencies. It's rare for an embedded project to
+Plugin for supporting release dependencies. It’s rare for an embedded project to
 be built completely free of other libraries and modules. Some of these may be
 standard internal libraries. Some of these may be 3rd party libraries. In either
-case, they become part of the project's ecosystem.
+case, they become part of the project’s ecosystem.
 
 This plugin is intended to make that relationship easier. It allows you to specify
 a source for dependencies. If required, it will automatically grab the appropriate
 version of that dependency.
 
-Most 3rd party libraries have a method of building already in place. While we'd
+Most 3rd party libraries have a method of building already in place. While we’d
 love to convert the world to a place where everything downloads with a test suite
-in Ceedling, that's not likely to happen anytime soon. Until then, this plugin
+in Ceedling, that’s not likely to happen anytime soon. Until then, this plugin
 will allow the developer to specify what calls Ceedling should make to oversee
 the build process of those third party utilities. Are they using Make? CMake? A
 custom series of scripts that only a mad scientist could possibly understand? No
@@ -22,7 +21,7 @@ will make it happen whenever it notices that the output artifacts are missing.
 Output artifacts? Sure! Things like static and dynamic libraries, or folders
 containing header files that might want to be included by your release project.
 
-So how does all this magic work?
+## So how does all this magic work?
 
 First, you need to add the Dependencies plugin to your list of enabled plugins. Then, we'll 
 add a new comfiguration section called `:dependencies`. There, you can list as many 
@@ -63,13 +62,10 @@ it! In the end, it'll look something like this:
           - include/**
 ```
 
-Let's take a deeper look at each of these features.
-
-The Starting Dash & Name
-------------------------
+## Starting Dash & Name
 
 Yes, that opening dash tells the dependencies plugin that the rest of these fields
-belong to our first dependency. If we had a second dependency, we'd have another
+belong to our first dependency. If we had a second dependency, we’d have another
 dash, lined up with the first, and followed by all the fields indented again.
 
 By convention, we use the `:name` field as the first field for each tool. Ceedling
@@ -79,25 +75,24 @@ it easier for us to see the name of each dependency with starting dash.
 The name field is only used to print progress while we're running Ceedling. You may
 call the name of the field whatever you wish.
 
-Working Paths
--------------
+## Working Paths
 
 All paths are collected under `:dependencies` ↳ `:paths`. The `:source` field allows us 
-to specify where the source code for each of our dependencies is stored. By default, it's
+to specify where the source code for each of our dependencies is stored. By default, it’s
 the same as the `:fetch` path, which is where source will be fetched TO when fetching the 
 dependency from elsewhere. All commands to build this dependency will be executed from
 the `:source` location. Temporary data will be placed in the `:build` location. Unless you're
-using one of Ceedling's built-in builders, you'll need to learn where the tool you're using to
-build places it's built artifacts , and list that here. Finally, the output
+using one of Ceedling’s built-in builders, you'll need to learn where the tool you're using to
+build places it’s built artifacts , and list that here. Finally, the output
 artifacts will be referenced to this location. You override this by specifying a `:artifact`
 path. In summary:
 
- - `:paths`
-   - `:fetch` -- where things are fetched to (defaults to `build/deps/depname/`)
-   - `:source` -- where we trigger builds (defaults to `:fetch`)
-   - `:build` -- where we have the produced build files (defaults to `<:fetch>/build`)
-   - `:deploy` -- where any produced library files should be copied (defaults to same as release executable)
-   - `:artifact` -- where output libraries can be found (defaults to `:build`)
+- `:paths`
+    - `:fetch` -- where things are fetched to (defaults to `build/deps/depname/`)
+    - `:source` -- where we trigger builds (defaults to `:fetch`)
+    - `:build` -- where we have the produced build files (defaults to `<:fetch>/build`)
+    - `:deploy` -- where any produced library files should be copied (defaults to same as release executable)
+    - `:artifact` -- where output libraries can be found (defaults to `:build`)
 
 If the dependency is directly included in your project (you've specified `:none` as the
 `:method` for fetching), then `:source` should be where your Ceedling can find the
@@ -106,20 +101,19 @@ source for your dependency in you repo.
 All artifacts are relative to the appropriate `:artifact` path. So if there are multiple 
 include dirs, choose the highest level and make the rest relative from there. 
 
-Fetching Dependencies
----------------------
+## Fetching Dependencies
 
 The `:dependencies` plugin supports the ability to automatically fetch your dependencies
 for you... using some common methods of fetching source. This section contains only a
 couple of fields:
 
 - `:method` -- This is the method that this dependency is fetched.
-  - `:none` -- This tells Ceedling that the code is already included in the project.
-  - `:zip` -- This tells Ceedling that we want to unpack a zip file to our source path.
-  - `:gzip` -- This tells Ceedling that we want to unpack a gzip file to our source path.
-  - `:git` -- This tells Ceedling that we want to clone a git repo to our source path.
-  - `:svn` -- This tells Ceedling that we want to checkout a subversion repo to our source path.
-  - `:custom` -- This tells Ceedling that we want to use a custom command or commands to fetch the code.
+    - `:none` -- This tells Ceedling that the code is already included in the project.
+    - `:zip` -- This tells Ceedling that we want to unpack a zip file to our source path.
+    - `:gzip` -- This tells Ceedling that we want to unpack a gzip file to our source path.
+    - `:git` -- This tells Ceedling that we want to clone a git repo to our source path.
+    - `:svn` -- This tells Ceedling that we want to checkout a subversion repo to our source path.
+    - `:custom` -- This tells Ceedling that we want to use a custom command or commands to fetch the code.
 - `:source` -- This is the path or url to fetch code when using the `:zip`, `:gzip` or `:git` method.
 - `:tag`/`:branch` -- This is the specific tag or branch that you wish to retrieve (`:git` only, optional).
 - `:hash` -- This is the specific SHA1 hash you want to fetch (`:git` only, optional and triggers a deep clone).
@@ -128,11 +122,10 @@ couple of fields:
 
 Some notes:
 
-The `:source` location for fetching a `:zip` or `:gzip` file is relative to the `:paths` ↳ `:source`
+* The `:source` location for fetching a `:zip` or `:gzip` file is relative to the `:paths` ↳ `:source`
 folder. 
 
-Environment Variables
----------------------
+## Environment Variables
 
 Many build systems support customization through environment variables. By specifying
 an array of environment variables, the Dependencies plugin will customize the shell environment 
@@ -144,7 +137,7 @@ within a specific dependency’s configuration is only for the shell environment
 that dependency. The format and abilities of the two `:environment` configuration sections are
 also different.
 
-Environment variables may be specified in three ways. Let's look at one of each:
+Environment variables may be specified in three ways. Let’s look at one of each:
 
 ```yaml
 :dependencies:
@@ -156,7 +149,7 @@ Environment variables may be specified in three ways. Let's look at one of each:
 ```
 
 In the first example, you see the most straightforward method. The environment variable
-`ARCHITECTURE` is set to the value `ARM9`. That's it. Simple.
+`ARCHITECTURE` is set to the value `ARM9`. That’s it. Simple.
 
 The next two options modify an existing symbol. In the first one, we use `+=`, which tells
 Ceedling to add the define `ADD_AWESOMENESS` to the environment variable `CFLAGS`. The second
@@ -170,11 +163,10 @@ If we had been modifying `PATH` instead, we might have had to use a `:` on a unu
 Windows.
 
 Second, removing an argument will have no effect on the argument if that argument isn't found
-precisely. It's case sensitive and the entire string must match. If symbol doesn't already exist,
+precisely. It’s case sensitive and the entire string must match. If symbol doesn't already exist,
 it WILL after executing this command... however it will be assigned to nothing.
 
-Building Dependencies
----------------------
+## Building Dependencies
 
 The heart of the `:dependencies` plugin is the ability for you, the developer, to specify the
 build process for each of your dependencies. You will need to have any required tools installed
@@ -184,12 +176,11 @@ The steps are specified as an array of strings. Ceedling will execute those step
 specified, moving from step to step unless an error is encountered. By the end of the process,
 the artifacts should have been created by your process... otherwise an error will be produced.
 
-Artifacts
----------
+## Artifacts
 
 These are the outputs of the build process. There are there types of artifacts. Any dependency
 may have none or some of these. Calling out these files tells Ceedling that they are important.
-Your dependency's build process may produce many other files... but these are the files that
+Your dependency’s build process may produce many other files... but these are the files that
 Ceedling understands it needs to act on.
 
 ### `static_libraries`
@@ -213,7 +204,7 @@ to produce them.
 ### `includes`
 
 Often when libraries are built, the same process will output a collection of includes so that
-your release code knows how to interact with that library. It's the public API for that library.
+your release code knows how to interact with that library. It’s the public API for that library.
 By specifying the directories that will contain these includes (don't specify the files themselves,
 Ceedling only needs the directories), Ceedling is able to automatically add these to its internal
 include list. This allows these files to be used while building your release code, as well we making
@@ -221,12 +212,11 @@ them mockable during unit testing.
 
 ### `source`
 
-It's possible that your external dependency will just produce additional C files as its output.
+It’s possible that your external dependency will just produce additional C files as its output.
 In this case, Ceedling is able to automatically add these to its internal source list. This allows
 these files to be used while building your release code.
 
-Tasks
-=====
+## Tasks
 
 Once configured correctly, the `:dependencies` plugin should integrate seamlessly into your
 workflow and you shouldn't have to think about it. In the real world, that doesn't always happen.
@@ -259,7 +249,7 @@ build directory... just in case you clobbered them.
 ### `paths:include`
 
 Maybe you want to verify that all the include paths are correct. If you query Ceedling with this
-request, it will list all the header file paths that it's found, including those produced by
+request, it will list all the header file paths that it’s found, including those produced by
 dependencies.
 
 ### `files:include`
@@ -267,8 +257,7 @@ dependencies.
 Maybe you want to take that query further and actually get a list of ALL the header files
 Ceedling has found, including those belonging to your dependencies.
 
-Custom Tools
-============
+## Custom Tools
 
 You can optionally specify a compiler, assembler, and linker, just as you would a release build:
 
@@ -318,4 +307,4 @@ source and/or assembly files into the specified library:
         - THESE_GET_USED_DURING_COMPILATION
 ```
 
-Happy Testing!
+<br/><br/>