ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/reference/index.md

@@ -0,0 +1,65 @@
+# Reference
+
+The Reference section is a quick-lookup companion to Ceedling's narrative
+documentation. Where the other sections explain concepts and walk you through
+workflows, these pages collect every command, macro, variable, constant, and
+configuration section into compact, scannable lists.
+
+<div class="grid cards" markdown>
+
+-   :material-console: **[Command Line][command-line]**
+
+    ---
+
+    All application commands and build task syntax.
+
+-   :material-book-open-variant: **[Project Configuration][project-configuration]**
+
+    ---
+
+    Project configuration sections, project loading, and modifying 
+    a project configuration with mixins.
+
+-   :material-pound: **[Test Build Directives][build-directives]**
+
+    ---
+
+    Macros for affecting the build configuration for an individual test file.
+
+-   :material-variable: **[Environment Variables][environment-vars]**
+
+    ---
+
+    Environment variables recognized by Ceedling.
+
+-   :material-pound: **[Partials Macros][partials-macros]**
+
+    ---
+
+    All function selection and static variable access macros used with 
+    [Partials](../testing-guide/partials/index.md)
+
+-   :material-chart-bar: **[Coverage Reporting][coverage-reporting]**
+
+    ---
+
+    All [GCov plugin](../plugins/gcov/index.md) configuration options including 
+    those for advanced reports with GCovr and ReportGenerator.
+
+-   :material-database: **[Global Collections][global-collections]**
+
+    ---
+
+    All globally-accessible Ruby constants assembled at startup.
+
+</div>
+
+[command-line]:          command-line.md
+[project-configuration]: project-configuration.md
+[build-directives]:      build-directives.md
+[environment-vars]:      environment-vars.md
+[partials-macros]:       partials-macros.md
+[global-collections]:    global-collections.md
+[coverage-reporting]:    gcov-plugin.md
+
+<br/><br/>

data/docs/mkdocs/reference/partials-macros.md

@@ -0,0 +1,79 @@
+# Partials Macros Reference
+
+!!! note "Documentation convention"
+    `*` is a stand-in or wildcard to refer to all variations of a particular macro type.
+
+---
+
+## Partial directive macros
+
+!!! tip
+    For detailed usage guidance, conventions, and examples, see [Partial Directive Macros](../testing-guide/partials/directives.md).
+
+### Module selection macros
+
+#### Test Partials macros
+
+These macros expand to a string literal that names a generated header
+file to be used with `#include`. `#include "ceedling.h"` must precede
+their use.
+
+* **`TEST_PARTIAL_ALL_MODULE(module)`**<br/>Select all functions in the module to be testable by Partial.
+* **`TEST_PARTIAL_PUBLIC_MODULE(module)`**<br/>Select all public (non-`static`, non-`inline`) functions in the module to be testable by Partial.
+* **`TEST_PARTIAL_PRIVATE_MODULE(module)`**<br/>Select all private (`static` and `inline`) functions in the module to be testable by Partial.
+* **`TEST_PARTIAL_MODULE(module)`**<br/>Begin with an empty function set to be testable by Partial; functions must be added explicitly via `TEST_PARTIAL_CONFIG`.
+
+`TEST_PARTIAL_*` macros expand to an implementation header filename.
+
+#### Mock Partials macros
+
+* **`MOCK_PARTIAL_ALL_MODULE(module)`**<br/>Select all functions in the module to be mockable by Partial.
+* **`MOCK_PARTIAL_PUBLIC_MODULE(module)`**<br/>Select all public (non-`static`, non-`inline`) functions in the module to be mockable by Partial.
+* **`MOCK_PARTIAL_PRIVATE_MODULE(module)`**<br/>Select all private (`static` and `inline`) functions in the module to be mockable by Partial.
+* **`MOCK_PARTIAL_MODULE(module)`**<br/>Begin with an empty function set to be mockable by Partial; functions must be added explicitly via `MOCK_PARTIAL_CONFIG`.
+
+`MOCK_PARTIAL_*` macros expand to a mockable interface header filename.
+
+### Function list configuration macros
+
+These macros are statements (not to be used with `#include` directives) 
+that refine the set of functions selected by the use of any module selection 
+macro above.
+
+* **`TEST_PARTIAL_CONFIG(module, func...)`**<br/>Add or subtract functions from the test Partial’s function set.
+* **`MOCK_PARTIAL_CONFIG(module, func...)`**<br/>Add or subtract functions from the mock Partial’s function set.
+
+### Function list addition and subtraction
+
+!!! tip
+    For the full rules on which additions and subtractions are valid with 
+    each `*_MODULE` variant, see
+    [Partial directive macros](../testing-guide/partials/directives.md#partials-function-list-configuration-macros).
+
+* Prefix a function name with `-` (`-func`) to exclude it from the Partial.
+* Use no prefix or `+` (`+func`) to include it.
+
+A function explicitly added to one side is automatically removed from the 
+complementary Partial to prevent duplicate symbol linker errors.
+
+---
+
+## Promoted static variable access
+
+!!! tip
+    For the full explanation of how Ceedling promotes function-scoped `static` 
+    variables to module scope and when to use this macro, see
+    [Accessing Static Variables](../testing-guide/partials/variables.md).
+
+**`PARTIAL_LOCAL_VAR(function_name, variable_name)`**
+
+Access a function-scoped `static` variable that Ceedling has promoted to
+module scope in a generated Partial. The macro expands to the promoted
+identifier `partial_<function_name>_<variable_name>`.
+
+- Defined in `ceedling.h`; requires `#include "ceedling.h"` above its use
+- Both arguments must be literal C identifiers — not strings or runtime values
+- Can appear anywhere a variable name is legal: expressions, assertions,
+  assignments
+
+<br/><br/>

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

@@ -0,0 +1,46 @@
+# Project Configuration Reference
+
+Ceedling's project configuration is assembled from one or more sources and
+merged into a single in-memory data structure before any build begins. The
+base configuration comes from a YAML project file. That base can be extended
+by [Mixins](../configuration/reference/mixins.md) — additional YAML files
+merged in after the base is loaded. Mixins can be specified from the command
+line, via environment variables, or from within the project file using the
+`:mixins:` section listed below.
+
+For the full details on how loading and merging work — including the search
+order for the default project file and all Mixin sources — see
+[Loading Configuration](../configuration/loading.md). For the environment
+variables that influence configuration loading, see
+[Environment Variables](../configuration/environment-vars.md).
+
+For conceptual overview and project file conventions, see
+[Configuration](../configuration/index.md).
+
+## Configuration sections
+
+Each top-level key in your project YAML file corresponds to one configuration
+section. All sections are optional; Ceedling supplies defaults for anything
+left unset.
+
+| Section | Description |
+|---|---|
+| **[`:project`](../configuration/reference/project.md)** | Build root, build modes, version info, and global project switches |
+| **[`:mixins`](../configuration/reference/mixins.md)** | Load and merge additional YAML configuration files into the base project configuration |
+| **[`:test_build`](../configuration/reference/test-build.md)** | Test-specific build options: assembly support, mock generation, preprocessor use, and more |
+| **[`:release_build`](../configuration/reference/release-build.md)** | Release artifact build options and output settings |
+| **[`:paths`](../configuration/reference/paths.md)** | Source, test, include, support, library, and vendor path globs |
+| **[`:files`](../configuration/reference/files.md)** | Explicit file inclusion and exclusion overrides |
+| **[`:environment`](../configuration/reference/environment.md)** | Set and export environment variables from within the project configuration |
+| **[`:extension`](../configuration/reference/extension.md)** | File extension strings for source, header, object, binary, and other file types |
+| **[`:defines`](../configuration/reference/defines.md)** | Per-context, per-file preprocessor symbol definitions |
+| **[`:flags`](../configuration/reference/flags.md)** | Compiler, linker, assembler, and preprocessor flags per build context |
+| **[`:libraries`](../configuration/reference/libraries.md)** | Test and release libraries plus linker search paths |
+| **[`:unity`](../configuration/reference/unity.md)** | Unity test framework configuration (defines, helper file paths, etc.) |
+| **[`:cmock`](../configuration/reference/cmock.md)** | CMock mock generation configuration |
+| **[`:test_runner`](../configuration/reference/test-runner.md)** | Test runner generation configuration |
+| **[`:cexception`](../configuration/reference/cexception.md)** | CException configuration |
+| **[`:plugins`](../configuration/reference/plugins.md)** | Enable built-in plugins and configure custom plugin load paths |
+| **[`:tools`](../configuration/reference/tools.md)** | Define or override compiler, linker, and other tool invocations |
+
+<br/><br/>

data/docs/mkdocs/snapshot/assets/project.yml

@@ -0,0 +1,404 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+---
+:project:
+  :name: "Example Project"
+
+  # how to use ceedling. If you're not sure, leave this as `gem` and `?`
+  :which_ceedling: gem
+  :ceedling_version: '?'
+
+  # optional features. If you don't need them, keep them turned off for performance
+  :use_mocks: TRUE
+  :use_test_preprocessor: :none  # options are :none, :mocks, :tests, or :all
+  :use_backtrace: :simple        # options are :none, :simple, or :gdb
+
+  # tweak the way ceedling handles automatic tasks
+  :build_root: build
+  :test_file_prefix: test_
+  :default_tasks:
+    - test:all
+
+  # performance options. If your tools start giving mysterious errors, consider 
+  # dropping this to 1 to force single-tasking
+  :test_threads: 8
+  :compile_threads: 8
+
+  # enable release build (more details in release_build section below)
+  :release_build: FALSE
+
+# Specify where to find mixins and any that should be enabled automatically
+:mixins:
+  :enabled: []
+  :load_paths: []
+
+# further details to configure the way Ceedling handles test code
+:test_build:
+  :use_assembly: FALSE
+
+# further details to configure the way Ceedling handles release code
+:release_build:
+  :output: MyApp.out
+  :use_assembly: FALSE
+  :artifacts: []
+
+# Plugins are optional Ceedling features which can be enabled. Ceedling supports
+# a variety of plugins which may effect the way things are compiled, reported, 
+# or may provide new command options. Refer to the readme in each plugin for 
+# details on how to use it.
+:plugins:
+  :load_paths: []
+  :enabled:
+    #- beep                           # beeps when finished, so you don't waste time waiting for ceedling
+    - module_generator                # handy for quickly creating source, header, and test templates
+    #- gcov                           # test coverage using gcov. Requires gcc, gcov, and a coverage analyzer like gcovr
+    #- cppcheck                       # static analysis using cppcheck. Requires cppcheck to be installed
+    #- valgrind                       # memory analysis using valgrind. Requires valgrind to be installed (Linux only)
+    #- bullseye                       # test coverage using bullseye. Requires bullseye for your platform
+    #- command_hooks                  # write custom actions to be called at different points during the build process
+    #- compile_commands_json_db       # generate a compile_commands.json file
+    #- dependencies                   # automatically fetch 3rd party libraries, etc.
+    #- fake_function_framework        # use FFF instead of CMock
+
+    # Report options (You'll want to choose one stdout option, but may choose multiple stored options if desired)
+    #- report_build_warnings_log
+    #- report_tests_gtestlike_stdout
+    #- report_tests_ide_stdout
+    #- report_tests_log_factory
+    - report_tests_pretty_stdout
+    #- report_tests_raw_output_log
+    #- report_tests_teamcity_stdout
+
+# Specify which reports you'd like from the log factory
+:report_tests_log_factory:
+  :reports:
+    - json 
+    - junit 
+    - cppunit 
+    - html 
+
+# override the default extensions for your system and toolchain
+:extension:
+  #:header: .h
+  #:source: .c
+  #:assembly: .s
+  #:dependencies: .d
+  #:object: .o
+  :executable: .out
+  #:testpass: .pass
+  #:testfail: .fail
+
+# This is where Ceedling should look for your source and test files.
+# see documentation for the many options for specifying this.
+:paths:
+  :test:
+    - +:test/**
+    - -:test/support
+  :source:
+    - src/**
+  :include:
+    - src/** # In simple projects, this entry often duplicates :source
+  :support:
+    - test/support
+  :libraries: []
+
+# You can even specify specific files to add or remove from your test
+# and release collections. Usually it's better to use paths and let
+# Ceedling do the work for you!
+:files:
+  :test: []
+  :source: []
+
+# Compilation symbols to be injected into builds
+# See documentation for advanced options:
+#  - Test name matchers for different symbols per test executable build
+#  - Referencing symbols in multiple lists using advanced YAML
+#  - Specifiying symbols used during test preprocessing
+:defines:
+  :test:
+    - TEST # Simple list option to add symbol 'TEST' to compilation of all files in all test executables
+  :release: []
+
+  # Enable to inject name of a test as a unique compilation symbol into its respective executable build. 
+  :use_test_definition: FALSE 
+
+# Configure additional command line flags provided to tools used in each build step
+# :flags:
+#   :release:
+#     :compile:         # Add '-Wall' and '--02' to compilation of all files in release target
+#       - -Wall
+#       - --O2
+#   :test:
+#     :compile:
+#       '(_|-)special': # Add '-pedantic' to compilation of all files in all test executables with '_special' or '-special' in their names
+#         - -pedantic
+#       '*':            # Add '-foo' to compilation of all files in all test executables
+#         - -foo
+
+# Configuration Options specific to CMock. See CMock docs for details
+:cmock:
+  # Core configuration
+  :plugins:                        # What plugins should be used by CMock?
+    - :ignore
+    - :callback
+  :verbosity:  2                   # the options being 0 errors only, 1 warnings and errors, 2 normal info, 3 verbose
+  :when_no_prototypes:  :warn      # the options being :ignore, :warn, or :erro
+
+  # File configuration
+  :skeleton_path:  ''              # Subdirectory to store stubs when generated (default: '')
+  :mock_prefix:  'mock_'           # Prefix to append to filenames for mocks
+  :mock_suffix:  ''                # Suffix to append to filenames for mocks
+
+  # Parser configuration
+  :strippables:  ['(?:__attribute__\s*\([ (]*.*?[ )]*\)+)']
+  :attributes:
+     - __ramfunc
+     - __irq
+     - __fiq
+     - register
+     - extern
+  :c_calling_conventions:
+     - __stdcall
+     - __cdecl
+     - __fastcall
+  :treat_externs:  :exclude        # Options being :include or :exclude
+  :treat_inlines:  :exclude        # Options being :include or :exclude
+  #:inline_function_patterns:      # When :treat_inlines is :include this list overrides default patterns: ["static inline", "inline static", "inline"]
+  #  - INLINE                      # Indicates `INLINE` (a macro) should be used to recognize inline functions
+
+  # Type handling configuration
+  #:unity_helper_path: ''          # specify a string of where to find a unity_helper.h file to discover custom type assertions
+  :treat_as:                       # optionally add additional types to map custom types
+    uint8:    HEX8
+    uint16:   HEX16
+    uint32:   UINT32
+    int8:     INT8
+    bool:     UINT8
+  #:treat_as_array:  {}            # hint to cmock that these types are pointers to something
+  #:treat_as_void:  []             # hint to cmock that these types are actually aliases of void
+  :memcmp_if_unknown:  true        # allow cmock to use the memory comparison assertions for unknown types
+  :when_ptr:  :compare_data        # hint to cmock how to handle pointers in general, the options being :compare_ptr, :compare_data, or :smart
+
+  # Mock generation configuration
+  :weak:  ''                       # Symbol to use to declare weak functions
+  :enforce_strict_ordering: true   # Do we want cmock to enforce ordering of all function calls?
+  :fail_on_unexpected_calls: true  # Do we want cmock to fail when it encounters a function call that wasn't expected?
+  :callback_include_count: true    # Do we want cmock to include the number of calls to this callback, when using callbacks?
+  :callback_after_arg_check: false # Do we want cmock to enforce an argument check first when using a callback?
+  #:includes: []                   # You can add additional includes here, or specify the location with the options below
+  #:includes_h_pre_orig_header: [] 
+  #:includes_h_post_orig_header: []
+  #:includes_c_pre_header:  []
+  #:includes_c_post_header:  []
+  #:array_size_type:  []            # Specify a type or types that should be used for array lengths
+  #:array_size_name:  'size|len'    # Specify a name or names that CMock might automatically recognize as the length of an array
+  :exclude_setjmp_h:  false        # Don't use setjmp when running CMock. Note that this might result in late reporting or out-of-order failures.
+
+# Configuration options specific to Unity. 
+:unity:
+  :defines:
+    - UNITY_EXCLUDE_FLOAT
+
+# You can optionally have ceedling create environment variables for you before
+# performing the rest of its tasks.
+:environment: []
+# :environment:
+#   # List enforces order allowing later to reference earlier with inline Ruby substitution
+#   - :var1: value
+#   - :var2: another value
+#   - :path:            # Special PATH handling with platform-specific path separators
+#     - #{ENV['PATH']}  # Environment variables can use inline Ruby substitution
+#     - /another/path/to/include
+
+# LIBRARIES
+# These libraries are automatically injected into the build process. Those specified as
+# common will be used in all types of builds. Otherwise, libraries can be injected in just
+# tests or releases. These options are MERGED with the options in supplemental yaml files.
+:libraries:
+  :placement: :end
+  :flag: "-l${1}"
+  :path_flag: "-L ${1}"
+  :system: []    # for example, you might list 'm' to grab the math library
+  :test: []
+  :release: []
+
+################################################################
+# PLUGIN CONFIGURATION
+################################################################
+
+# Add -gcov to the plugins list to make sure of the gcov plugin
+# You will need to have gcov and gcovr both installed to make it work.
+# For more information on these options, see docs in plugins/gcov
+:gcov:
+  :summaries: TRUE                # Enable simple coverage summaries to console after tests
+  :report_task: FALSE             # Disabled dedicated report generation task (this enables automatic report generation)
+  :utilities:
+    - gcovr           # Use gcovr to create the specified reports (default).
+    #- ReportGenerator # Use ReportGenerator to create the specified reports.
+  :reports: # Specify one or more reports to generate.
+    # Make an HTML summary report.
+    - HtmlBasic
+    # - HtmlDetailed
+    # - Text
+    # - Cobertura
+    # - SonarQube
+    # - JSON
+    # - HtmlInline
+    # - HtmlInlineAzure
+    # - HtmlInlineAzureDark
+    # - HtmlChart
+    # - MHtml
+    # - Badges
+    # - CsvSummary
+    # - Latex
+    # - LatexSummary
+    # - PngChart
+    # - TeamCitySummary
+    # - lcov
+    # - Xml
+    # - XmlSummary
+  :gcovr:
+    # :html_artifact_filename: TestCoverageReport.html
+    # :html_title: Test Coverage Report
+    :html_medium_threshold: 75
+    :html_high_threshold: 90
+    # :html_absolute_paths: TRUE
+    # :html_encoding: UTF-8
+
+# :cppcheck:
+#   :reports:
+#     - text     # plain text report (default)
+#     # - xml    # XML report for tool integration
+#     # - sarif  # SARIF report for GitHub/VS Code integration
+#     # - html   # HTML report (requires cppcheck-htmlreport)
+#   :enable_checks: []
+#   :platform: ''
+#   :standard: ''
+
+# :module_generator:
+#   :naming: :snake #options: :bumpy, :camel, :caps, or :snake
+#   :includes:
+#     :tst: []
+#     :src: []
+#   :boilerplates:
+#     :src: ""
+#     :inc: ""
+#     :tst: ""
+
+# :dependencies:
+#   :libraries:
+#     - :name: WolfSSL
+#       :source_path:   third_party/wolfssl/source
+#       :build_path:    third_party/wolfssl/build
+#       :artifact_path: third_party/wolfssl/install
+#       :fetch:
+#         :method: :zip
+#         :source: \\shared_drive\third_party_libs\wolfssl\wolfssl-4.2.0.zip
+#       :environment:
+#         - CFLAGS+=-DWOLFSSL_DTLS_ALLOW_FUTURE
+#       :build:
+#         - "autoreconf -i"
+#         - "./configure --enable-tls13 --enable-singlethreaded"
+#         - make
+#         - make install
+#       :artifacts:
+#         :static_libraries:
+#           - lib/wolfssl.a
+#         :dynamic_libraries:
+#           - lib/wolfssl.so
+#         :includes:
+#           - include/**
+
+# :command_hooks:
+#   :pre_mock_preprocess:
+#   :post_mock_preprocess:
+#   :pre_test_preprocess:
+#   :post_test_preprocess:
+#   :pre_mock_generate:
+#   :post_mock_generate:
+#   :pre_runner_generate:
+#   :post_runner_generate:
+#   :pre_compile_execute:
+#   :post_compile_execute:
+#   :pre_link_execute:
+#   :post_link_execute:
+#   :pre_test_fixture_execute:
+#   :post_test_fixture_execute:
+#   :pre_test:
+#   :post_test:
+#   :pre_release:
+#   :post_release:
+#   :pre_build:
+#   :post_build:
+#   :post_error:
+
+################################################################
+# TOOLCHAIN CONFIGURATION
+################################################################
+
+#:tools:
+# Ceedling defaults to using gcc for compiling, linking, etc.
+# As [:tools] is blank, gcc will be used (so long as it's in your system path)
+# See documentation to configure a given toolchain for use
+# :tools:
+#   :test_compiler: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_linker: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_assembler: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_fixture: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_includes_preprocessor: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_file_preprocessor: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :test_file_preprocessor_directives: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :release_compiler: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :release_linker: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :release_assembler: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+#   :release_dependencies_generator: 
+#     :executable:
+#     :arguments: []
+#     :name: 
+#     :optional: FALSE
+...