ceedling 1.1.9 → 1.2.0

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

@@ -1,404 +0,0 @@
-# =========================================================================
-#   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
-...

data/docs/mkdocs/snapshot/examples/cipher_quest/README.md

@@ -1,210 +0,0 @@
-# Ceedling Cipher Quest Project
-
-A small field-text toolkit for the discerning intelligence agent. Cipher Quest
-encodes messages, decodes intercepted communications, and analyzes text — but
-only if you tell it which tools to pack.
-
-This example project illustrates:
-
-- **Test builds and release builds of the same project** using Ceedling
-- **Per-test-file symbol definitions** via the `:defines` matcher section in
-  `project.yml`
-- **Conditional compilation** with `#ifdef` to enable/disable feature modules
-- **Release build variants** driven by mixins — the project file itself has no
-  release symbols; each variant is supplied externally
-- **A compile-time `#error`** that prevents building a featureless release binary
-
-This project is limited to string manipulation and relies solely on basic 
-assertions for its test suite (i.e. no mocks or Partials).
-
----
-
-## Project Structure
-
-```
-cipher_quest/
-├── project.yml          # Ceedling configuration
-├── mixin/               # Release build variant mixins
-│   ├── release_rot13.yml
-│   ├── release_caesar.yml
-│   ├── release_analyze.yml
-│   └── release_full.yml
-├── src/
-│   ├── main.c           # CLI entry point (NOT unit tested)
-│   ├── text_utils.c/.h  # Core string utilities (always compiled)
-│   ├── cipher.c/.h      # Cipher operations (CIPHER_ROT13 / CIPHER_CAESAR)
-│   └── analyzer.c/.h    # Text analysis (ANALYZER_ENABLED)
-└── test/
-    ├── TestTextUtils.c      # Tests core utilities — needs only TEST
-    ├── TestCipherRot13.c    # Tests ROT13    — needs TEST + CIPHER_ROT13
-    ├── TestCipherCaesar.c   # Tests Caesar   — needs TEST + CIPHER_CAESAR
-    └── TestAnalyzer.c       # Tests analysis — needs TEST + ANALYZER_ENABLED
-```
-
----
-
-## Feature Symbols
-
-| Symbol             | Enables                              |
-|--------------------|--------------------------------------|
-| `CIPHER_ROT13`     | ROT13 encode/decode                  |
-| `CIPHER_CAESAR`    | Caesar cipher encrypt/decrypt        |
-| `ANALYZER_ENABLED` | Character count, frequency, palindrome detection |
-
-Both `CIPHER_ROT13` and `CIPHER_CAESAR` can be defined simultaneously.
-If none of the three symbols is defined at compile time, `main.c` raises
-a `#error` to prevent building a binary that can't do anything useful.
-
----
-
-## Test Build
-
-Run all unit tests (no feature symbols needed beyond `TEST`, which Ceedling
-applies automatically via the `'*'` matcher in `project.yml`):
-
-```sh
-ceedling test:all
-```
-
-Each test file that exercises a conditionally compiled feature gets its
-own symbol via the `:defines` matcher in `project.yml`:
-
-```yaml
-:defines:
-  :test:
-    '*':
-      - TEST
-    :TestCipherRot13:
-      - CIPHER_ROT13
-    :TestCipherCaesar:
-      - CIPHER_CAESAR
-    :TestAnalyzer:
-      - ANALYZER_ENABLED
-```
-
-This means each test executable sees only the symbols it needs. The ROT13
-tests compile `cipher.c` with `CIPHER_ROT13` defined; the Caesar tests
-compile it with `CIPHER_CAESAR`; neither affects the other.
-
-You can also run a single test file:
-
-```sh
-ceedling test:TestCipherRot13
-ceedling test:TestAnalyzer
-```
-
-Or all tests matching a pattern:
-
-```sh
-ceedling test:pattern[Cipher]
-```
-
----
-
-## Release Build
-
-The `:defines: :release:` section in `project.yml` is intentionally empty.
-A plain `ceedling release` will **fail** at the compilation of `main.c` with
-a descriptive error:
-
-```
-error: "cipher_quest: No feature defined. An agent needs tools. ..."
-```
-
-To build a release binary, supply one or more feature symbols via a mixin.
-
----
-
-Below is example help output produced by running the executable with no
-command line arguments. This executable was a result of a release build 
-with `CIPHER_ROT13` defined.
-
-```shell
-> build/release/cipher_quest.out
-
-Usage: cipher_quest <command> [args...]
-
-Core commands (always available):
-  reverse <text>             Reverse the characters
-  upper <text>               Convert to uppercase
-  lower <text>               Convert to lowercase
-  trim <text>                Strip leading/trailing whitespace
-  palindrome <text>          Simple palindrome check (exact characters)
-  wordcount <text>           Count words
-
-Cipher: ROT13
-  rot13 <text>               Encode or decode (ROT13 is its own inverse)
-```
-
-### Using a mixin file (optional `@` sigil)
-
-```sh
-# ROT13 variant
-ceedling release --mixin=@mixin/release_rot13.yml
-
-# Caesar cipher variant
-ceedling release --mixin=@mixin/release_caesar.yml
-
-# Analysis variant
-ceedling release --mixin=@mixin/release_analyze.yml
-
-# Full-featured: All capabilities enabled
-ceedling release --mixin=@mixin/release_full.yml
-```
-
-Mixin files are simple YAML fragments that merge into the project
-configuration. For example, `mixin/release_rot13.yml` contains:
-
-```yaml
-:defines:
-  :release:
-    - CIPHER_ROT13
-```
-
-Ceedling deep-merges this with `project.yml`, adding `CIPHER_ROT13` to the
-release compilation flags without modifying the base project file.
-
-### Using inline YAML mixin (`=` sigil)
-
-Rather than referencing a file, YAML can be supplied directly on the command
-line using the `=` sigil prefix. Quote the value to protect YAML special
-characters (colons, brackets, spaces) from shell interpretation:
-
-```sh
-# ROT13 variant
-ceedling release --mixin "=defines: {release: [CIPHER_ROT13]}"
-
-# Caesar cipher variant
-ceedling release --mixin "=defines: {release: [CIPHER_CAESAR]}"
-
-# All features enabled
-ceedling release --mixin "=defines: {release: [CIPHER_ROT13, CIPHER_CAESAR, ANALYZER_ENABLED]}"
-```
-
-Multiple `--mixin` values can be combined and are processed left-to-right:
-
-```sh
-ceedling release --mixin @mixin/release_rot13.yml --mixin "=project: {build_root: ci_build}"
-```
-
----
-
-## Example Session
-
-```sh
-# Build and run with ROT13 enabled
-ceedling release --mixin=mixin/release_rot13.yml
-./build/release/cipher_quest.out rot13 "Attack at dawn"
-# => Nggnpx ng qnja
-
-./build/release/cipher_quest.out rot13 "Nggnpx ng qnja"
-# => Attack at dawn
-
-# Build with all features and try the analyzer
-ceedling release --mixin=mixin/release_full.yml
-./build/release/cipher_quest.out ispalindrome "A man a plan a canal Panama"
-# => Yes, it is a palindrome.
-
-./build/release/cipher_quest.out caesar 13 "Hello, World!"
-# => Uryyb, Jbeyq!
-```