ceedling 1.1.6 → 1.1.8

data/plugins/gcov/lib/gcov.rb

@@ -40,11 +40,19 @@ class Gcov < Plugin
       )
     end
 
-    # Validate configuration and tools while building Reportinators
-    @reportinators = build_reportinators( 
-      @project_config[:gcov_utilities],
-      @reports_enabled
-    )
+    # #1252 -- Validate `:gcov ↳ :utilities` config (cheap, no external tool needed) and
+    # build the console summary Reportinator (needs no external tool of its own) here,
+    # eagerly, since `setup()` runs for every build this plugin is merely *enabled* for,
+    # not only real `gcov:` builds. Deliberately NOT building the gcovr/ReportGenerator
+    # Reportinators here -- doing so validates gcovr/ReportGenerator are installed
+    # (see their own constructors), which would make either a hard dependency of any
+    # build at all (e.g. plain `test:all`) rather than only a real `gcov:` build. See
+    # generate_coverage_reports, which builds (and so validates) them lazily, only once
+    # post_build already knows a gcov: task actually ran.
+    validate_utilities_config( @project_config[:gcov_utilities] )
+    @console_reportinator = summaries_enabled?( @project_config ) ?
+      ConsoleReportinator.new( @ceedling, @project_config ) : nil
+    @reportinators = nil
 
     # Convenient instance variable references
     @configurator = @ceedling[:configurator]
@@ -62,16 +70,12 @@ class Gcov < Plugin
 
     @mutex = Mutex.new()
 
-    # Validate MC/DC configuration against GCC version (only incurs gcc --version when :mcdc: TRUE)
-    if @project_config[:gcov_mcdc]
-      gcc_version = get_gcc_version()
-      if gcc_version.major < 14
-        raise CeedlingException.new(
-          ":gcov ↳ :mcdc ➡️ Modified condition/decision coverage requires GCC 14 or higher " \
-          "(found #{gcc_version.major}.#{gcc_version.minor})"
-        )
-      end
-    end
+    # See validate_mcdc_gcc_version! below for why this isn't checked eagerly here --
+    # setup() runs for every build this plugin is merely *enabled* for, not only real
+    # gcov: builds. Shelling out to `gcc --version` here would make GCC-version
+    # validation (and a build-breaking exception on too-old a GCC) fire even for builds
+    # that never touch :mcdc at all, e.g. plain `test:all`.
+    @mcdc_gcc_checked = false
   end
 
   # Called within class and also externally by plugin Rakefile
@@ -171,6 +175,8 @@ class Gcov < Plugin
 
       # Compile all non-assembly files with coverage; gcovr --exclude filters non-production files from reports
       if File.extname(source) != EXTENSION_ASSEMBLY
+        validate_mcdc_gcc_version!
+
         arg_hash[:tool] = TOOLS_GCOV_COMPILER
         arg_hash[:msg] = @reportinator.generate_module_progress(
           operation: "Compiling with coverage",
@@ -184,6 +190,8 @@ class Gcov < Plugin
 
   def pre_link_execute(arg_hash)
     if arg_hash[:context] == GCOV_SYM
+      validate_mcdc_gcc_version!
+
       @cli_gcov_task = true
       arg_hash[:tool] = TOOLS_GCOV_LINKER
       arg_hash[:flags] += ['-fcondition-coverage'] if @project_config[:gcov_mcdc]
@@ -214,7 +222,7 @@ class Gcov < Plugin
         results: results
       }
 
-      verbosity = (results[:counts][:failed] > 0) ? Verbosity::ERRORS : Verbosity::NORMAL
+      verbosity = @plugin_reportinator.test_results_floor_verbosity
 
       # Print unit test suite results
       @plugin_reportinator.run_test_results_report( hash, verbosity )
@@ -257,6 +265,15 @@ class Gcov < Plugin
   def generate_coverage_reports()
     return if not @reports_enabled
 
+    # #1252 -- Lazily build (and so validate the external tools of) the gcovr/
+    # ReportGenerator Reportinators only now: this method only runs from post_build
+    # (automatic reporting) or the standalone `gcov:report` task (manual reporting,
+    # mutually exclusive with automatic per :gcov_report_task) -- either way, only
+    # once a real gcov: task is confirmed to have already run. See setup()'s own
+    # comment for why this can't happen any earlier. `||=` just guards against ever
+    # rebuilding (and so re-validating) on a hypothetical repeat call.
+    @reportinators ||= build_reportinators( @project_config[:gcov_utilities] )
+
     @reportinators.each do |reportinator|
       # Create the artifacts output directory.
       @file_wrapper.mkdir( reportinator.artifacts_path ) if reportinator.artifacts_path
@@ -312,16 +329,10 @@ class Gcov < Plugin
     return sources - tested_sources
   end
 
-  def build_reportinators(config, enabled)
-    reportinators = []
-
-    # Instantiate console summary reportinator if summaries enabled
-    @console_reportinator = summaries_enabled?(@project_config) ?
-      ConsoleReportinator.new(@ceedling, @project_config) : nil
-
-    # Do not instantiate file reportinators (and tool validation) unless reports enabled
-    return reportinators if (!enabled)
-
+  # Fail fast at plugin setup if :utilities holds an unrecognized name (e.g. a typo) --
+  # cheap, config-shape-only validation, so this stays eager even though the actual
+  # Reportinators it names are built lazily (see build_reportinators, generate_coverage_reports).
+  def validate_utilities_config(config)
     config.each do |reportinator|
       if not GCOV_UTILITY_NAMES.map(&:upcase).include?( reportinator.upcase )
         options = GCOV_UTILITY_NAMES.map{ |utility| "'#{utility}'" }.join(', ')
@@ -329,6 +340,14 @@ class Gcov < Plugin
         raise CeedlingException.new(msg)
       end
     end
+  end
+
+  # #1252 -- Deliberately not called from setup(); see its own comment and
+  # generate_coverage_reports, the only caller. Constructing GcovrReportinator/
+  # ReportGeneratorReportinator validates gcovr/ReportGenerator are installed, so this
+  # can only run once a real gcov: task is confirmed to have run.
+  def build_reportinators(config)
+    reportinators = []
 
     # Run reports using gcovr
     if utility_enabled?( config, GCOV_UTILITY_NAME_GCOVR )
@@ -345,6 +364,25 @@ class Gcov < Plugin
     return reportinators
   end
 
+  # Lazily validates :mcdc against the installed GCC version -- called from every
+  # gcov-context build hook that could otherwise emit -fcondition-coverage (compile,
+  # link), memoized so `gcc --version` runs at most once regardless of how many source
+  # files or hooks fire before it. See setup()'s own comment for why this isn't checked
+  # eagerly there.
+  def validate_mcdc_gcc_version!
+    return if @mcdc_gcc_checked
+    @mcdc_gcc_checked = true
+    return unless @project_config[:gcov_mcdc]
+
+    gcc_version = get_gcc_version()
+    if gcc_version.major < 14
+      raise CeedlingException.new(
+        ":gcov ↳ :mcdc ➡️ Modified condition/decision coverage requires GCC 14 or higher " \
+        "(found #{gcc_version.major}.#{gcc_version.minor})"
+      )
+    end
+  end
+
   def get_gcc_version()
     command = @tool_executor.build_command_line( TOOLS_GCOV_GCC_VERSION, [])
 

data/plugins/gcov/lib/gcovr_reportinator.rb

@@ -50,6 +50,31 @@ class GcovrReportinator < GcovReportinator
         "(found #{@gcovr_version.major}.#{@gcovr_version.minor})"
       )
     end
+
+    # --decisions requires gcovr 6+; --fail-under-decision (which depends on --decisions)
+    # is a distinct, later addition requiring gcovr 7+ -- confirmed directly against real
+    # gcovr 6.0, which rejects --fail-under-decision outright as an unrecognized argument.
+    # Raised here, upfront, rather than left to surface as gcovr's own opaque CLI error or
+    # silently dropped -- either of which would leave a configured coverage threshold
+    # quietly never actually checked.
+    gcovr_opts = @config[GCOVR_SETTING_PREFIX.to_sym] || {}
+
+    if !gcovr_opts[:fail_under_decision].nil? && !min_version?( @gcovr_version, 7, 0 )
+      raise CeedlingException.new(
+        ":gcov ↳ :gcovr ↳ :fail_under_decision ➡️ requires gcovr 7 or higher " \
+        "(found #{@gcovr_version.major}.#{@gcovr_version.minor})"
+      )
+    end
+
+    # --decisions was introduced in gcovr 5.1, not 6.0 -- confirmed directly against
+    # gcovr's own changelog and a real gcovr 5.1/5.0 install (5.1 accepts --decisions
+    # and proceeds; 5.0 rejects it outright as unrecognized).
+    if gcovr_opts[:decisions] && !min_version?( @gcovr_version, 5, 1 )
+      raise CeedlingException.new(
+        ":gcov ↳ :gcovr ↳ :decisions ➡️ requires gcovr 5.1 or higher " \
+        "(found #{@gcovr_version.major}.#{@gcovr_version.minor})"
+      )
+    end
   end
 
   # Generate the gcovr report(s) specified in the options.
@@ -94,9 +119,18 @@ class GcovrReportinator < GcovReportinator
     args += "--gcov-filter \"#{gcovr_opts[:gcov_filter]}\" " unless gcovr_opts[:gcov_filter].nil?
     args += "--gcov-exclude \"#{gcovr_opts[:gcov_exclude]}\" " unless gcovr_opts[:gcov_exclude].nil?
     args += "--exclude-directories \"#{gcovr_opts[:exclude_directories]}\" " unless gcovr_opts[:exclude_directories].nil?
-    args += "--branches " if gcovr_opts[:branches]
-    args += "--sort-uncovered " if gcovr_opts[:sort_uncovered]
-    args += "--sort-percentage " if gcovr_opts[:sort_percentage]
+    # gcovr 7.0 deprecated --branches/--sort-uncovered/--sort-percentage in favor of
+    # these renamed equivalents (still functional, but warn, below 7.0); use whichever
+    # form the detected gcovr_version actually expects.
+    if gcovr_opts[:branches]
+      args += (min_version?(gcovr_version, 7, 0) ? "--txt-metric branch " : "--branches ")
+    end
+    if gcovr_opts[:sort_uncovered]
+      args += (min_version?(gcovr_version, 7, 0) ? "--sort uncovered-number " : "--sort-uncovered ")
+    end
+    if gcovr_opts[:sort_percentage]
+      args += (min_version?(gcovr_version, 7, 0) ? "--sort uncovered-percent " : "--sort-percentage ")
+    end
     args += "--print-summary " if gcovr_opts[:print_summary]
     args += "--gcov-executable \"#{gcovr_opts[:gcov_executable]}\" " unless gcovr_opts[:gcov_executable].nil?
     args += "--exclude-unreachable-branches " if gcovr_opts[:exclude_unreachable_branches]
@@ -112,6 +146,14 @@ class GcovrReportinator < GcovReportinator
       args += "--merge-mode-functions \"#{gcovr_opts[:merge_mode_function]}\" " unless gcovr_opts[:merge_mode_function].nil?
     end
 
+    # --fail-under-decision is a no-op to gcovr without --decisions also present (that's
+    # what actually turns decision-coverage analysis on) -- :fail_under_decision implies
+    # it automatically so the threshold option can never be configured into silently
+    # failing outright. initialize already guarantees gcovr 6+ whenever either is set
+    # (7+ specifically whenever :fail_under_decision is set), matching this method's own
+    # 6+ gate above.
+    args += "--decisions " if gcovr_opts[:decisions] || !gcovr_opts[:fail_under_decision].nil?
+
     [:fail_under_line,
      :fail_under_branch,
      :fail_under_decision,
@@ -122,18 +164,24 @@ class GcovrReportinator < GcovReportinator
       next if gcovr_opts[opt].nil?
 
       value = gcovr_opts[opt]
-      
+
       # Value sanity checks for :fail_under_* settings
       if opt.to_s =~ /fail_/
         if not value.is_a? Integer
           raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} ➡️ '#{value}' must be an integer")
-        elsif (value < 0) || (value > 100)
-          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} ➡️ '#{value}' must be an integer percentage 0 – 100")
+        elsif (value < 1) || (value > 100)
+          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} ➡️ '#{value}' must be an integer percentage 1 – 100")
         end
       end
-      
-      # If the YAML key has a value, trasnform key into command line argument with value and concatenate
-      args += "--#{opt.to_s.gsub('_','-')} #{value} " unless value.nil?
+
+      # :source_encoding/:object_directory are quoted (unlike the already-validated,
+      # always-integer :fail_under_* values) so a value containing a space doesn't
+      # break the constructed command line.
+      if [:source_encoding, :object_directory].include?(opt)
+        args += "--#{opt.to_s.gsub('_','-')} \"#{value}\" " unless value.nil?
+      else
+        args += "--#{opt.to_s.gsub('_','-')} #{value} " unless value.nil?
+      end
     end
 
     return args
@@ -327,7 +375,7 @@ class GcovrReportinator < GcovReportinator
   # configuration must come from the gcovr configuration file itself.
   IGNORED_WHEN_CONFIG_FILE_SET = [
     :report_include, :report_exclude, :gcov_filter, :gcov_exclude, :exclude_directories,
-    :branches, :sort_uncovered, :sort_percentage, :print_summary, :gcov_executable,
+    :branches, :decisions, :sort_uncovered, :sort_percentage, :print_summary, :gcov_executable,
     :exclude_unreachable_branches, :exclude_throw_branches, :use_gcov_files, :gcov_ignore_parse_errors,
     :keep, :delete, :threads, :merge_mode_function,
     :fail_under_line, :fail_under_branch, :fail_under_decision, :fail_under_function,
@@ -379,7 +427,12 @@ class GcovrReportinator < GcovReportinator
       _opts[:report_exclude] = excludes unless excludes.empty?
     end
 
-    _opts[:mcdc] = true if opts[:gcov_mcdc]
+    # No :mcdc-specific gcovr flag to set here -- GCC's own condition/MC-DC data flows
+    # into gcovr's reports unconditionally, in every format, regardless of --decisions
+    # (confirmed directly: gcovr's Condition-labeled HTML/JSON content is byte-identical
+    # with and without --decisions; that flag only adds its own separate, additive
+    # Decision data alongside it). :mcdc's own gcovr-version floor is still enforced in
+    # initialize -- there's just nothing more for gcovr's own CLI args to do here.
 
     return _opts
   end
@@ -387,22 +440,29 @@ class GcovrReportinator < GcovReportinator
 
   # Build a combined Python regex for gcovr's `--exclude` flag covering all
   # non-production file categories: test files, support files, and generated/framework files.
+  # Path/prefix values are config-driven, so they're Regexp-escaped -- interpolated raw, a
+  # metacharacter (e.g. a literal '.') in a project's own path would silently over- or
+  # under-match.
   def build_report_exclusions
     data = build_exclusion_data
     patterns = []
 
+    test_prefix    = Regexp.escape(data[:test_prefix].to_s)
+    build_root     = Regexp.escape(data[:build_root].to_s)
+    src_extension  = Regexp.escape(data[:src_extension].to_s)
+
     data[:test_paths].each do |path|
       # Test files (e.g. test_foo.c)
-      patterns << ".*#{path}.*/#{data[:test_prefix]}.+\\#{data[:src_extension]}$"
+      patterns << ".*#{Regexp.escape(path)}.*/#{test_prefix}.+\\#{src_extension}$"
     end
 
     # Support files (e.g. helpers, stubs, fixtures) — never production source
     data[:support_paths].each do |path|
-      patterns << ".*#{path}/.+\\#{data[:src_extension]}$"
+      patterns << ".*#{Regexp.escape(path)}/.+\\#{src_extension}$"
     end
 
     # Any generated files for tests or vendored framework C source files below the root of the build directory
-    patterns << ".*#{data[:build_root]}/.+\\#{EXTENSION_CORE_SOURCE}$"
+    patterns << ".*#{build_root}/.+\\#{EXTENSION_CORE_SOURCE}$"
 
     return patterns
   end
@@ -505,59 +565,43 @@ class GcovrReportinator < GcovReportinator
 
   # Output to console a human-friendly message on certain coverage failure exit codes.
   # Prefers the actual gcovr error text from stderr; falls back to descriptive strings.
-  # Perform the logic on whether to raise an exception
+  # gcovr's composite exit code bit-ORs every violated :fail_under_* threshold together --
+  # every violated bit is collected and reported, not just whichever is checked first.
   def gcovr_exec_exception?(opts, exitcode, boom, shell_result=nil)
+    violations = []
 
     # Special handling of exit code 2 with --fail-under-line
     if ((exitcode & 2) == 2) and !opts[:fail_under_line].nil?
       fallback = "Line coverage is less than the configured minimum of #{opts[:fail_under_line]}%"
-      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
-      if boom
-        raise CeedlingException.new(msg)
-      else
-        @loginator.log( msg, Verbosity::COMPLAIN )
-        # Clear bit in exit code
-        exitcode &= ~2
-      end
+      violations << "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
+      exitcode &= ~2
     end
 
     # Special handling of exit code 4 with --fail-under-branch
     if ((exitcode & 4) == 4) and !opts[:fail_under_branch].nil?
       fallback = "Branch coverage is less than the configured minimum of #{opts[:fail_under_branch]}%"
-      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
-      if boom
-        raise CeedlingException.new(msg)
-      else
-        @loginator.log( msg, Verbosity::COMPLAIN )
-        # Clear bit in exit code
-        exitcode &= ~4
-      end
+      violations << "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
+      exitcode &= ~4
     end
 
     # Special handling of exit code 8 with --fail-under-decision
     if ((exitcode & 8) == 8) and !opts[:fail_under_decision].nil?
       fallback = "Decision coverage is less than the configured minimum of #{opts[:fail_under_decision]}%"
-      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
-      if boom
-        raise CeedlingException.new(msg)
-      else
-        @loginator.log( msg, Verbosity::COMPLAIN )
-        # Clear bit in exit code
-        exitcode &= ~8
-      end
+      violations << "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
+      exitcode &= ~8
     end
 
     # Special handling of exit code 16 with --fail-under-function
     if ((exitcode & 16) == 16) and !opts[:fail_under_function].nil?
       fallback = "Function coverage is less than the configured minimum of #{opts[:fail_under_function]}%"
-      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
-      if boom
-        raise CeedlingException.new(msg)
-      else
-        @loginator.log( msg, Verbosity::COMPLAIN )
-        # Clear bit in exit code
-        exitcode &= ~16
-      end
+      violations << "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
+      exitcode &= ~16
+    end
+
+    if boom
+      raise CeedlingException.new( violations.join("\n") ) unless violations.empty?
+    else
+      violations.each { |msg| @loginator.log( msg, Verbosity::COMPLAIN ) }
     end
 
     # A non-zero exit code is a problem

data/plugins/gcov/lib/reportgenerator_reportinator.rb

@@ -128,7 +128,9 @@ class ReportGeneratorReportinator < GcovReportinator
 
   # Get the ReportGenerator options from the project options.
   def collect_reportgenerator_opts(opts)
-    _opts = opts[REPORT_GENERATOR_SETTING_PREFIX.to_sym]
+    # dup prevents repeated calls from accumulating mutations on the shared opts hash --
+    # mirrors GcovrReportinator#collect_gcovr_opts' identical guard and rationale.
+    _opts = opts[REPORT_GENERATOR_SETTING_PREFIX.to_sym].dup
 
     # Auto-generate -filefilters: exclusion patterns for test paths and the build root.
     # These exclude test files and all generated/framework files from coverage reports.
@@ -275,17 +277,19 @@ class ReportGeneratorReportinator < GcovReportinator
   # Build filename-fragment patterns for the .gcno scan exclusion regex.
   # Excludes test files, generated mocks, and test runners from gcov processing.
   # The '.*' suffix handles source extensions embedded in .gcno filenames (e.g. test_foo.c.gcno).
+  # test_prefix/mock_prefix are config-driven, so they're Regexp-escaped -- unescaped, a
+  # metacharacter in either (e.g. a literal '.') would silently over- or under-match.
   def build_gcno_exclusions
     data = build_exclusion_data
     # Use [^\/\\]* (no path separators) rather than .* to match filenames only.
     # Ceedling names build output dirs after test files (e.g. build/gcov/out/test_foo/),
     # so .* would greedily match test_foo/bar.c and exclude ALL production sources.
     [
-      "#{data[:test_prefix]}[^\\/\\\\]*",  # test_foo.gcno
-      "#{data[:mock_prefix]}[^\\/\\\\]*",  # MockBar.gcno
-      "[^\\/\\\\]*_runner[^\\/\\\\]*",     # test_foo_runner.gcno
-      File.basename(UNITY_C_FILE, '.*'),   # unity.gcno
-      File.basename(CMOCK_C_FILE, '.*')    # cmock.gcno
+      "#{Regexp.escape(data[:test_prefix].to_s)}[^\\/\\\\]*",  # test_foo.gcno
+      "#{Regexp.escape(data[:mock_prefix].to_s)}[^\\/\\\\]*",  # MockBar.gcno
+      "[^\\/\\\\]*_runner[^\\/\\\\]*",                          # test_foo_runner.gcno
+      Regexp.escape(File.basename(UNITY_C_FILE, '.*')),        # unity.gcno
+      Regexp.escape(File.basename(CMOCK_C_FILE, '.*'))         # cmock.gcno
     ]
   end
 

data/plugins/valgrind/lib/valgrind.rb

@@ -101,7 +101,7 @@ class Valgrind < Plugin
         results: results
       }
 
-      verbosity = (results[:counts][:failed] > 0) ? Verbosity::ERRORS : Verbosity::NORMAL
+      verbosity = @plugin_reportinator.test_results_floor_verbosity
 
       # Print unit test suite results
       @plugin_reportinator.run_test_results_report( hash, verbosity )

data/site-local/configuration/project-file.html

@@ -1684,6 +1684,34 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label="Some YAML Learnin’">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#yaml-highlights-overview" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        YAML highlights &amp; overview
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#yaml-anchors-aliases-and-extensions" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        YAML anchors, aliases, and extensions
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4102,6 +4130,34 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label="Some YAML Learnin’">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#yaml-highlights-overview" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        YAML highlights &amp; overview
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#yaml-anchors-aliases-and-extensions" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        YAML anchors, aliases, and extensions
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -4241,10 +4297,20 @@
 example of a complete project configuration.</p>
 </div>
 <h2 id="some-yaml-learnin">Some YAML Learnin’</h2>
-<p>Please consult YAML documentation for the finer points of format
-and to understand details of our YAML-based configuration file.</p>
 <p>We recommend <a href="http://en.wikipedia.org/wiki/Yaml">Wikipedia’s entry on YAML</a>
-for this. A few highlights from that reference page:</p>
+and <a href="https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet">educative.io’s advanced YAML cheatsheet</a>
+for a simple overview of YAML and its syntax sufficient for 
+understanding your Ceedling project configuration.</p>
+<div class="admonition tip">
+<p class="admonition-title"><code>ceedling dumpconfig</code> to verify your YAML</p>
+<p>Ceedling provides a means to export the final result of YAML
+processing for your inspection via <a href="../getting-started/command-line.html#ceedling-dumpconfig-filepath-sections"><code>dumpconfig</code></a>.
+Dump output includes the resolution of advanced YAML features and 
+Ceedling’s own manipulations. This is a good way to troubleshoot 
+your project configuration.</p>
+</div>
+<h3 id="yaml-highlights-overview">YAML highlights &amp; overview</h3>
+<p>A few points from the preceding references:</p>
 <ul>
 <li>
 <p>YAML streams are encoded using the set of printable Unicode
@@ -4279,12 +4345,16 @@ for this. A few highlights from that reference page:</p>
   punctuation can generally be represented without needing
   to be enclosed in quotes.</p>
 </li>
-<li>
-<p>Repeated nodes are initially denoted by an ampersand (<code>&amp;</code>) and
-  thereafter referenced with an asterisk (<code>*</code>). These are known as
-  anchors and aliases in YAML speak.</p>
-</li>
 </ul>
+<h3 id="yaml-anchors-aliases-and-extensions">YAML anchors, aliases, and extensions</h3>
+<p>YAML provides several “shortcuts” for referencing and modifying blocks
+of YAML so you can avoid duplication. This is advanced YAML and 
+well beyond the scope of Ceedling documentation. However, know that
+Ceedling’s YAML parser is entirely capable of handling these advanced 
+aspects of YAML.</p>
+<p>See this <a href="https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#anchors">cheatsheet entry</a> 
+and <a href="https://blog.daemonl.com/2016/02/yaml.html">this guide</a>
+for much more on these powerful but finicky features.</p>
 <h2 id="notes-on-project-file-structure">Notes on Project File Structure</h2>
 <ul>
 <li>

data/site-local/configuration/reference/cexception.html

@@ -2344,10 +2344,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-cmock-yaml" class="md-nav__link">
+  <a href="#example-cmock-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :cmock YAML
+        Example :cmock YAML
       
     </span>
   </a>
@@ -4046,10 +4046,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-cmock-yaml" class="md-nav__link">
+  <a href="#example-cmock-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :cmock YAML
+        Example :cmock YAML
       
     </span>
   </a>
@@ -4155,7 +4155,7 @@
 
 <h1 id="cexception"><code>:cexception</code></h1>
 <p><strong>Configure CException’s features</strong></p>
-<h2 id="exmaple-cmock-yaml">Exmaple <code>:cmock</code> YAML</h2>
+<h2 id="example-cmock-yaml">Example <code>:cmock</code> YAML</h2>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">:cexception</span><span class="p">:</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w">  </span><span class="nt">:defines</span><span class="p">:</span>
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w">    </span><span class="c1"># Enables CException `#include`ing CExceptionConfig.h</span>

data/site-local/configuration/reference/cmock.html

@@ -2288,10 +2288,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-cmock-yaml" class="md-nav__link">
+  <a href="#example-cmock-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :cmock YAML
+        Example :cmock YAML
       
     </span>
   </a>
@@ -4112,10 +4112,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-cmock-yaml" class="md-nav__link">
+  <a href="#example-cmock-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :cmock YAML
+        Example :cmock YAML
       
     </span>
   </a>
@@ -4290,7 +4290,7 @@
 <p>Ceedling sets values for a subset of CMock settings. All CMock options are
 available to be set, but only those options set by Ceedling in an automated
 fashion are documented below. See <a href="https://github.com/ThrowTheSwitch/CMock/blob/master/docs/CMock_Summary.md">CMock documentation</a>.</p>
-<h2 id="exmaple-cmock-yaml">Exmaple <code>:cmock</code> YAML</h2>
+<h2 id="example-cmock-yaml">Example <code>:cmock</code> YAML</h2>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">:cmock</span><span class="p">:</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w">  </span><span class="nt">:when_no_prototypes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">:warn</span>
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w">  </span><span class="nt">:enforce_strict_ordering</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">TRUE</span>

data/site-local/configuration/reference/unity.html

@@ -2260,10 +2260,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-unity-yaml" class="md-nav__link">
+  <a href="#example-unity-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :unity YAML
+        Example :unity YAML
       
     </span>
   </a>
@@ -4057,10 +4057,10 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exmaple-unity-yaml" class="md-nav__link">
+  <a href="#example-unity-yaml" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Exmaple :unity YAML
+        Example :unity YAML
       
     </span>
   </a>
@@ -4177,7 +4177,7 @@
 
 <h1 id="unity"><code>:unity</code></h1>
 <p><strong>Configure Unity’s features</strong></p>
-<h2 id="exmaple-unity-yaml">Exmaple <code>:unity</code> YAML</h2>
+<h2 id="example-unity-yaml">Example <code>:unity</code> YAML</h2>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">:unity</span><span class="p">:</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w">  </span><span class="nt">:defines</span><span class="p">:</span>
 <a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">UNITY_INT_WIDTH=16</span><span class="w">   </span><span class="c1"># 16 bit processor without support for 32 bit instructions</span>