ceedling 1.2.1 → 1.2.2

data/plugins/gcov/lib/gcovr_thresholds.rb

@@ -0,0 +1,74 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/exceptions'
+
+# Coverage thresholds a gcovr run violated, one message each
+class GcovrThresholdError < CeedlingException
+
+  attr_reader :violations
+
+  def initialize(violations)
+    @violations = violations
+    super( violations.join( "\n" ) )
+  end
+
+end
+
+# Decodes gcovr's exit status and stderr into the :fail_under_* thresholds a run violated.
+# Each violated threshold sets a bit of the exit status and writes a line of its own to
+# stderr. Bit 8 covers both condition and decision coverage, which from gcovr 8.7 may
+# each write a line.
+module GcovrThresholds
+
+  BITS = {
+    2  => { option: :fail_under_line,     label: 'Line',                  kinds: ['line'] },
+    4  => { option: :fail_under_branch,   label: 'Branch',                kinds: ['branch'] },
+    8  => { option: :fail_under_decision, label: 'Condition or decision', kinds: ['condition', 'decision'] },
+    16 => { option: :fail_under_function, label: 'Function',              kinds: ['function'] },
+  }.freeze
+
+  MESSAGE_PATTERN = /^\(?error\)?:?\s+(failed minimum (\w+) coverage.*?)\s*$/i
+
+  # Returns the violation messages, and the exit status bits no configured threshold explains
+  def self.decode(opts:, exitcode:, stderr:)
+    messages = messages_by_kind( stderr )
+    violations = []
+
+    BITS.each do |bit, threshold|
+      next unless (exitcode & bit) == bit && !opts[threshold[:option]].nil?
+
+      violations.concat( violations_for( threshold, opts, messages ) )
+      exitcode &= ~bit
+    end
+
+    return violations, exitcode
+  end
+
+  # gcovr's own messages, grouped by the coverage kind each names. Older gcovr writes them in
+  # lowercase, so the first letter is capitalized, and nothing else is touched.
+  def self.messages_by_kind(stderr)
+    messages = Hash.new { |hash, kind| hash[kind] = [] }
+
+    stderr.to_s.each_line do |line|
+      match = line.match( MESSAGE_PATTERN )
+      messages[match[2].downcase] << match[1].sub( /\A./ ) { |first| first.upcase } if match
+    end
+
+    return messages
+  end
+
+  def self.violations_for(threshold, opts, messages)
+    found = threshold[:kinds].flat_map { |kind| messages[kind] }
+    found = ["#{threshold[:label]} coverage is less than the configured minimum of #{opts[threshold[:option]]}%"] if found.empty?
+
+    return found.map { |message| "Gcovr ⏩️ #{message}" }
+  end
+
+  private_class_method :messages_by_kind, :violations_for
+
+end

data/plugins/gcov/lib/reportgenerator_reportinator.rb

@@ -8,7 +8,7 @@
 require 'benchmark'
 require 'ceedling/constants'
 require 'ceedling/exceptions'
-require 'ceedling/file_path_utils'
+require 'ceedling/filesystem/file_path_utils'
 require 'gcov_reportinator'
 
 class ReportGeneratorReportinator < GcovReportinator

data/plugins/module_generator/lib/module_generator.rb

@@ -110,7 +110,7 @@ class ModuleGenerator < Plugin
 
     @ceedling[:loginator].log(
       'Module Generator :update_svn is deprecated and ignored. Add generated files to source control with your own tools.',
-      Verbosity::COMPLAIN, LogLabels::WARNING
+      Verbosity::COMPLAIN
     )
   end
 
@@ -119,7 +119,7 @@ class ModuleGenerator < Plugin
     project.same_named( files.map { |file| file[:path].to_s } ).each do |planned, existing|
       @ceedling[:loginator].log(
         "Module file `#{planned}` shares its name with #{existing.map { |path| "`#{path}`" }.join( ', ' )}.",
-        Verbosity::COMPLAIN, LogLabels::WARNING
+        Verbosity::COMPLAIN
       )
     end
   end
@@ -133,7 +133,7 @@ class ModuleGenerator < Plugin
       @ceedling[:loginator].log(
         "Generated test `#{path}` is wrapped in `##{options.test_guard} #{define}`, but its build does not " \
         "define #{define}. Add it under :defines ↳ :test, or the test compiles to nothing.",
-        Verbosity::COMPLAIN, LogLabels::WARNING
+        Verbosity::COMPLAIN
       )
     end
   end

data/plugins/report_tests_teamcity_stdout/lib/report_tests_teamcity_stdout.rb

@@ -39,18 +39,13 @@ class ReportTestsTeamcityStdout < Plugin
   def pre_test(test)
     return if !@output_enabled
 
-    # Generate a new Flow ID and store it in test hash
+    # Generate a new Flow ID and open the test's suite. A suite is named for its test,
+    # which tells same-named tests in different directories apart.
     @mutex.synchronize do
       @flowid_count += 1
-      @suites[test] = { :flowid => @flowid_count }
-    end
+      @suites[test] = { :flowid => @flowid_count, :name => escape( @ceedling[:file_path_utils].form_test_name( test ) ) }
 
-    # Generate first TeamCity service message
-    @mutex.synchronize do
-      teamcity_service_message(
-        "testSuiteStarted name='#{File.basename(test, '.*')}'",
-        @suites[test][:flowid]
-      )
+      teamcity_service_message( "testSuiteStarted name='#{@suites[test][:name]}'", @suites[test][:flowid] )
     end
   end
 
@@ -58,103 +53,81 @@ class ReportTestsTeamcityStdout < Plugin
   def post_test_fixture_execute(arg_hash)
     return if !@output_enabled
 
-    flowId = nil
-    test_key = arg_hash[:test_filepath]
-
-    # Get unique Flow ID
-    @mutex.synchronize do
-      flowId = @suites[test_key][:flowid]
-    end
+    flowId = @mutex.synchronize { @suites[arg_hash[:test_filepath]][:flowid] }
 
     # Gather test results for this test executable
     results = @ceedling[:plugin_reportinator].assemble_test_results( [arg_hash[:result_file]] )
-
-    # Apportion total run time of test executable equally to each test case within it.
-    duration_ms = results[:total_time] * 1000.0
-    avg_duration = (duration_ms / [1, results[:counts][:passed] + results[:counts][:failed]].max).round
+    duration = average_duration( results )
 
     context = arg_hash[:context]
 
-    # Handle test case successes within the test executable
-    results[:successes].each do |success|
-      filepath = File.join( success[:source][:dirname], File.basename( success[:source][:basename], '.*' ) )
+    report_successes( results[:successes], context, flowId, duration )
+    report_failures( results[:failures], context, flowId, duration )
+    report_ignores( results[:ignores], context, flowId )
+  end
 
-      # puts(success)
-      success[:collection].each do |test|
-        _test = test[:test]
-
-        # Create Java-like name per TeamCity convention `package_or_namespace.ClassName.TestName`
-        #  ==> `context.TestFilepath.TestCaseName`
-        teamcity_service_message(
-          "testStarted name='#{context}.#{filepath}.#{_test}'",
-          flowId
-        )
-
-        teamcity_service_message(
-          "testFinished name='#{context}.#{filepath}.#{_test}' duration='#{avg_duration}'",
-          flowId
-        )
-      end
+  # `Plugin` build step hook
+  def post_test(test)
+    return if !@output_enabled
+
+    @mutex.synchronize do
+      teamcity_service_message(
+        "testSuiteFinished name='#{@suites[test][:name]}'",
+        @suites[test][:flowid]
+      )
     end
+  end
 
-    # Handle test case failures within the test executable
-    results[:failures].each do |failure|
-      failure[:collection].each do |test|
-        filepath = File.join( failure[:source][:dirname], File.basename( failure[:source][:basename], '.*' ) )
+  ### Private
 
-        _test = test[:test]
-        _message = test[:message]
+  private
 
-        teamcity_service_message(
-          "testStarted name='#{context}.#{filepath}.#{_test}'",
-          flowId
-        )
+  # Total run time of a test executable, apportioned equally to each test case within it, in ms
+  def average_duration(results)
+    duration_ms = results[:total_time] * 1000.0
 
-        # Create Java-like name per TeamCity convention `package_or_namespace.ClassName.TestName`
-        #  ==> `context.TestFilepath.TestCaseName`
-        _message = 
-          "testFailed name='#{context}.#{filepath}.#{_test}' " + 
-          "message='#{escape(_message)}' " +
-          "details='File: #{failure[:source][:file]} Line: #{test[:line]}'"
+    return (duration_ms / [1, results[:counts][:passed] + results[:counts][:failed]].max).round
+  end
 
-        teamcity_service_message( _message, flowId )
+  def report_successes(successes, context, flowId, duration)
+    successes.each do |success|
+      success[:collection].each do |test|
+        name = test_name( context, success[:source], test[:test] )
 
-        teamcity_service_message(
-          "testFinished name='#{context}.#{filepath}.#{_test}' duration='#{avg_duration}'",
-          flowId
-        )
+        teamcity_service_message( "testStarted name='#{name}'", flowId )
+        teamcity_service_message( "testFinished name='#{name}' duration='#{duration}'", flowId )
       end
     end
+  end
 
-    # Handle ignored tests
-    results[:ignores].each do |ignored|
-      ignored[:collection].each do |test|
-        filepath = File.join( ignored[:source][:dirname], File.basename( ignored[:source][:basename], '.*' ) )
-        _test = test[:test]
-
-        service_message = "testIgnored name='#{context}.#{filepath}.#{_test}'"
+  def report_failures(failures, context, flowId, duration)
+    failures.each do |failure|
+      failure[:collection].each do |test|
+        name = test_name( context, failure[:source], test[:test] )
+        details = escape( "File: #{failure[:source][:file]} Line: #{test[:line]}" )
 
-        teamcity_service_message( service_message, flowId )
+        teamcity_service_message( "testStarted name='#{name}'", flowId )
+        teamcity_service_message( "testFailed name='#{name}' message='#{escape( test[:message] )}' details='#{details}'", flowId )
+        teamcity_service_message( "testFinished name='#{name}' duration='#{duration}'", flowId )
       end
     end
-
   end
 
-  # `Plugin` build step hook
-  def post_test(test)
-    return if !@output_enabled
-
-    @mutex.synchronize do
-      teamcity_service_message(
-        "testSuiteFinished name='#{File.basename(test, '.*')}'",
-        @suites[test][:flowid]
-      )
+  def report_ignores(ignores, context, flowId)
+    ignores.each do |ignored|
+      ignored[:collection].each do |test|
+        teamcity_service_message( "testIgnored name='#{test_name( context, ignored[:source], test[:test] )}'", flowId )
+      end
     end
   end
 
-  ### Private
+  # A Java-like name per TeamCity convention `package_or_namespace.ClassName.TestName`
+  #  ==> `context.TestFilepath.TestCaseName`, escaped
+  def test_name(context, source, test)
+    filepath = File.join( source[:dirname], File.basename( source[:basename], '.*' ) )
 
-  private
+    return escape( "#{context}.#{filepath}.#{test}" )
+  end
 
   def escape(string)
     # https://www.jetbrains.com/help/teamcity/service-messages.html#Escaped+Values

data/plugins/sanitize/lib/sanitize_records.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'ceedling/constants'
+require 'ceedling/build_log_writer'
 require 'sanitize_constants'
 require 'sanitize_reports'
 
@@ -20,7 +21,7 @@ class SanitizeRecords
     @loginator    = loginator
     @reports      = reports
     @records      = []
-    @logged_tests = []
+    @log_writer   = BuildLogWriter.new( file_wrapper: file_wrapper )
     @written      = []
     @mutex        = Mutex.new
   end
@@ -101,11 +102,7 @@ class SanitizeRecords
 
   # A build's first report for a test replaces the last build's log, and later ones follow it
   def write_log(log, findings)
-    first = @mutex.synchronize { !@logged_tests.include?( log ) && @logged_tests << log }
-    text  = findings.map( &:text ).join( "\n" )
-
-    @file_wrapper.mkdir( File.dirname( log ) )
-    @file_wrapper.write( log, first ? text : "\n#{text}", first ? 'w' : 'a' )
+    @log_writer.write( log, findings.map( &:text ).join( "\n" ), separator: "\n" )
   end
 
   def pluralize(count, word)

data/plugins/valgrind/lib/valgrind.rb

@@ -152,7 +152,7 @@ class Valgrind < Plugin
 
     test_name = arg_hash[:test_name]
     path      = report_filepath( test_name )
-    return unless @file_wrapper.exist?( path )
+    return unless report_written?( path )
 
     cause = ValgrindReport.first_error( @file_wrapper.read( path ), xml: xml_report_enabled? )
     return if cause.nil?
@@ -230,7 +230,14 @@ class Valgrind < Plugin
     return xml_report_enabled? ? xml_filepath( test_name ) : log_filepath( test_name )
   end
 
-  # Assembles the full Valgrind argument list for one test.
+  # Valgrind wrote the report moments ago in another process, so a miss is retried before
+  # it is believed
+  def report_written?(path)
+    return @file_wrapper.exist_with_retry?( path )
+  end
+
+  # Assembles the full Valgrind argument list for one test, making the directories its
+  # reports go in. A nested test's reports sit in subdirectories, and Valgrind makes none.
   #
   # Suppression files lead so a user's own :arguments entries can still override
   # anything they set. `${1}` is the test executable substitution token and is always
@@ -240,15 +247,15 @@ class Valgrind < Plugin
 
     arguments = Array( config[:valgrind_suppressions] ).map { |file| "--suppressions=\"#{file}\"" }
 
-    arguments << "--log-file=\"#{log_filepath( test_name )}\""
+    arguments << "--log-file=\"#{@file_wrapper.mkdir_for( log_filepath( test_name ) )}\""
 
     if xml_report_enabled?
       arguments << '--xml=yes'
-      arguments << "--xml-file=\"#{xml_filepath( test_name )}\""
+      arguments << "--xml-file=\"#{@file_wrapper.mkdir_for( xml_filepath( test_name ) )}\""
     end
 
     arguments += Array( config[:valgrind_arguments] )
-    arguments << '${1}'
+    arguments << '"${1}"'
 
     return arguments
   end
@@ -260,11 +267,11 @@ class Valgrind < Plugin
   def count_errors(test_name)
     path = report_filepath( test_name )
 
-    unless @file_wrapper.exist?( path )
+    unless report_written?( path )
       # A silent skip here reads exactly like a clean result. It is not one. The
       # memory error status of this test is unknown.
       msg = "Valgrind wrote no report for #{test_name} at #{path}. Memory error status is unknown."
-      @loginator.log( msg, Verbosity::COMPLAIN, LogLabels::WARNING )
+      @loginator.log( msg, Verbosity::COMPLAIN )
       return nil
     end
 

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

@@ -4586,7 +4586,8 @@ for more details.</p>
 <p><code>:unity_helper_path</code> may be a single string or a list. Each value must be a
 relative path from your Ceedling working directory to a Unity helper header file
 (these are typically organized within containing Ceedling <code>:paths</code> ↳ <code>:support</code>
-directories).</p>
+directories). A test build compiles the source file beside each helper header,
+of the same name, when one exists.</p>
 <p><strong>Default</strong>: <code>[]</code> (empty)</p>
 <h2 id="includes"><code>:includes</code></h2>
 <p>In certain advanced testing scenarios, you may need to inject additional header

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

@@ -4673,8 +4673,13 @@ builds.</p>
 <p><strong>Default</strong>: <code>[]</code> (empty)</p>
 <h2 id="files-options-notes"><code>:files</code> options &amp; notes</h2>
 <ol>
-<li>A path can be absolute (fully qualified) or relative.</li>
-<li>A path can include a glob matcher (more on this below).</li>
+<li>A path can be absolute (fully qualified) or relative. A relative path is relative to
+   the working directory, where you run <code>ceedling</code>.</li>
+<li><code>~</code> at the start of a path names your home directory.</li>
+<li>A path can include a glob matcher (more on this below). A glob based above the build
+   root, such as <code>+:**/*.c</code>, adds nothing from it.</li>
+<li>An entry within the build root adds from it with a warning, but no entry adds a file
+   from the directories Ceedling and its plugins create there, or from the mocks directory.</li>
 <li>A path can use <a href="../project-file.html#inline-ruby-string-expansion">inline Ruby string expansion</a>.</li>
 <li>Subtractive paths prepended with a <code>-:</code> decorator are possible and useful.
    See the documentation below.</li>
@@ -4708,7 +4713,8 @@ that they ignore directory paths. Only filepaths are recognized.</p>
 <h2 id="subtractive-files-entries">Subtractive <code>:files</code> entries</h2>
 <p>Tailoring a file collection includes adding to it but also subtracting from it.</p>
 <p>Put simply, with an optional preceding decorator <code>-:</code>, you can instruct Ceedling
-to remove certain file paths from a collection after it builds that collection.</p>
+to remove certain file paths from a collection after it builds that collection.
+A subtractive entry that names no file logs a warning, except below the build root.</p>
 <p>By default, paths are additive. For pretty alignment in your YAML, you may also
 use <code>+:</code>, but strictly speaking, it’s not necessary.</p>
 <p>Subtractive paths may be simple paths or globs just like any other path entry.</p>

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

@@ -4528,14 +4528,32 @@ command line argument will be <code>-lm</code>.</p>
 <p><strong>Default</strong>: <code>-l${1}</code> (GCC format)</p>
 <h2 id="path_flag"><code>:path_flag</code></h2>
 <p>Command line argument format for adding a library search path.</p>
-<p>Library search paths may be added to your project with <code>:paths</code> ↳ <code>:libraries</code>.</p>
+<p>Library search paths may be added to your project with <code>:paths</code> ↳ <code>:libraries</code>.
+Each directory those entries collect becomes one argument, as for any <code>:paths</code> 
+entry. A glob names each directory it matches, and a <code>-:</code> entry removes 
+directories. An entry that collects no existing directory adds no argument.</p>
 <p><strong>Default</strong>: <code>-L "${1}"</code> (GCC format)</p>
 <h2 id="libraries-notes"><code>:libraries</code> notes</h2>
 <ul>
-<li>If you've specified your own link step, you are going to want to add <code>${4}</code> to
+<li>
+<p>A <a href="../../getting-started/builds.html#delta-build-special-cases">delta build</a>
+  relinks when a library file entry in <code>:libraries</code> changes names or paths.
+  A library Ceedling cannot find, such as one internal to your toolchain’s
+  search paths, is not tracked. Ceedling looks for named libraries within 
+  <code>:paths</code> ↳ <code>:libraries</code>:</p>
+<ul>
+<li>A bare name such as <code>m</code> as <code>libm.a</code>, <code>libm.so</code>, and the other typical 
+  names toolchains use.</li>
+<li>An entry such as <code>:libm.a</code> as that exact filename.</li>
+<li>And a full filepath as itself.</li>
+</ul>
+</li>
+<li>
+<p>If you've specified your own link step, you are going to want to add <code>${4}</code> to
   your argument list in the position where library files should be added to the
   command line. For <code>gcc</code>, this is often at the very end. Other tools may vary.
-  See the <code>:tools</code> section for more.</li>
+  See the <code>:tools</code> section for more.</p>
+</li>
 </ul>
 <p><br/><br/></p>
 

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

@@ -4831,7 +4831,19 @@ files contained in those paths. A custom list is just that — a custom list of
 paths.</p>
 <h2 id="paths-configuration-options-notes"><code>:paths</code> configuration options &amp; notes</h2>
 <ol>
-<li>A path can be absolute (fully qualified) or relative.</li>
+<li>A path can be absolute (fully qualified) or relative. A relative path is relative to
+   the working directory, where you run <code>ceedling</code>, not to your project file’s
+   directory. For a project file named with <code>--project</code> from another directory, write
+   its paths relative to that other directory.</li>
+<li><code>~</code> at the start of a path names your home directory. <code>~user</code> is a directory named
+   <code>~user</code>.</li>
+<li>A path reached through a symlink names the place the symlink leads to, so two
+   entries reaching one directory collect it once. Directories found below an entry
+   keep the spelling they are found by, as an <code>#include</code> reaches them.</li>
+<li>An entry based above the build root, such as <code>./**</code> or <code>../**</code>, collects nothing
+   from it. An entry within the build root collects from it with a warning, but no entry
+   collects from the directories Ceedling and its plugins create, such as <code>test/</code>,
+   <code>release/</code>, <code>vendor/</code>, and <code>artifacts/</code> below the build root, or the mocks directory.</li>
 <li>A path can include a glob matcher (more on this below).</li>
 <li>A path can use <a href="../project-file.html#inline-ruby-string-expansion">inline Ruby string expansion</a>.</li>
 <li>Subtractive paths are possible and useful. See the documentation below.</li>
@@ -4883,6 +4895,17 @@ collection.</p>
 <p>By default, paths are additive. For pretty alignment in your YAML, you may also
 use <code>+:</code>, but strictly speaking, it’s not necessary.</p>
 <p>Subtractive paths may be simple paths or globs just like any other path entry.</p>
+<p>A subtractive entry removes the directories it names and every directory below them.
+An additive entry naming one of those directories more closely keeps it:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">:paths</span><span class="p">:</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">  </span><span class="nt">:source</span><span class="p">:</span>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/**</span>
+<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-:src/legacy</span><span class="w">       </span><span class="c1"># Removes src/legacy/ and every directory below it...</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">src/legacy/keep</span><span class="w">    </span><span class="c1"># ...except src/legacy/keep/, which this entry names</span>
+</code></pre></div>
+<p>A subtractive entry that names nothing logs a warning, so a mistyped entry does 
+not pass unnoticed. Below the build root, where nothing exists before a first
+build, it passes without a word.</p>
 <div class="admonition warning">
 <p class="admonition-title">Quote the whole entry, decoration included</p>
 <p>YAML keeps quote marks that begin partway through a value as part of the
@@ -4890,11 +4913,11 @@ value. Quoting only the path leaves quote marks in the path, and
 Ceedling rejects the entry. Quote an entry whenever it holds <code>#{…}</code>
 <a href="../project-file.html#inline-ruby-string-expansion">inline Ruby string expansion</a>, because YAML
 otherwise reads the <code>#</code> as the start of a comment.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="c1"># Correct</span>
-<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">"-:#{ENV['SRC_ROOT']}/vendor/legacy"</span>
-<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a>
-<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="c1"># Incorrect -- the quote marks become part of the path</span>
-<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-:"#{ENV['SRC_ROOT']}/vendor/legacy"</span>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="c1"># Correct</span>
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">"-:#{ENV['SRC_ROOT']}/vendor/legacy"</span>
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>
+<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="c1"># Incorrect -- the quote marks become part of the path</span>
+<a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-:"#{ENV['SRC_ROOT']}/vendor/legacy"</span>
 </code></pre></div>
 </div>
 <div class="admonition note">

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

@@ -4743,6 +4743,13 @@ output with the project name.</p>
 </code></pre></div></p>
 <h2 id="build_root"><code>:build_root</code></h2>
 <p>Top level directory into which generated path structure and files are placed.</p>
+<p><code>ceedling clobber</code> empties the build root’s test and release trees, so Ceedling refuses a
+build root that is empty, the project directory, or a directory above it.</p>
+<p>An entry based above the build root, such as the <code>:paths</code> entry <code>../**</code> or the <code>:files</code>
+glob <code>+:**/*.c</code>, collects nothing from it. A <code>:paths</code> or <code>:files</code> entry within the build
+root, such as one naming generated code in <code>build/gen</code>, collects from it with a warning.
+No entry collects from the directories Ceedling and its plugins create there, such as
+<code>test/</code>, <code>release/</code>, <code>vendor/</code>, and <code>artifacts/</code>.</p>
 <div class="admonition note">
 <p class="admonition-title">Build configuration requirement</p>
 <p>This is one of the handful of configuration values that must be set for 
@@ -4855,9 +4862,11 @@ upon by test executables.</p>
 <p><strong>Default</strong>: 1</p>
 <h2 id="which_ceedling"><code>:which_ceedling</code></h2>
 <p>This is an advanced project option primarily meant for development work on
-Ceedling itself. This setting tells the code that launches the Ceedling
-application where to find the code to launch.</p>
-<p>This entry can be either a directory path or <code>gem</code>.</p>
+Ceedling itself. This setting selects the Ceedling installation that runs
+your project’s commands. The <code>ceedling</code> command you run hands each command off to
+that installation’s own launcher.</p>
+<p>This entry can be either a directory path or <code>gem</code>. A relative path is
+relative to your working directory.</p>
 <p>See the section <a href="../which-ceedling.html">Which Ceedling</a> for full details.</p>
 <p><strong>Default</strong>: <code>gem</code></p>
 <h2 id="use_backtrace"><code>:use_backtrace</code></h2>
@@ -4941,9 +4950,10 @@ with an error at startup.</p>
 extracted from the <code>gdb</code> report. Ceedling will attempt to surface in the 
 summary the offending line of code or failing <code>assert()</code> from the report.</p>
 <p>The full <code>gdb</code> report is captured to a log file, and the log filepath is 
-provided in the crash summary. The log filepath will comprise the containing 
-test executable as a subdirectory and the name of the crashing test case 
-function as the filename.</p>
+provided in the crash summary. The log filepath comprises the <a href="../../testing-guide/conventions.html#test-names-build-output">test’s name</a>,
+its path from your project’s root, as a subdirectory plus the name of the crashing 
+test case function as the filename. A build that logs a test case’s crash replaces 
+that log; a log holds only the latest crash.</p>
 <div class="admonition warning">
 <p class="admonition-title">macOS: a working <code>gdb</code> can stop attaching to processes</p>
 <p>macOS restricts which debuggers may attach to a process. A Homebrew <code>gdb</code>
@@ -4969,7 +4979,7 @@ build. To restore <code>:gdb</code> backtraces, re-codesign <code>gdb</code> fol
 <a id="__codelineno-6-10" name="__codelineno-6-10" href="#__codelineno-6-10"></a>  Test: testCrash
 <a id="__codelineno-6-11" name="__codelineno-6-11" href="#__codelineno-6-11"></a>  At line (40): "Test case crashed &gt;&gt; [SIGSEGV] Segmentation fault
 <a id="__codelineno-6-12" name="__codelineno-6-12" href="#__codelineno-6-12"></a>                `uint32_t i = *null_ptr;`
-<a id="__codelineno-6-13" name="__codelineno-6-13" href="#__codelineno-6-13"></a>                (build/logs/test/TestUsartModel/testCrash.gdb.log)"
+<a id="__codelineno-6-13" name="__codelineno-6-13" href="#__codelineno-6-13"></a>                (build/logs/test/test/TestUsartModel/testCrash.gdb.log)"
 <a id="__codelineno-6-14" name="__codelineno-6-14" href="#__codelineno-6-14"></a>
 <a id="__codelineno-6-15" name="__codelineno-6-15" href="#__codelineno-6-15"></a>-----------------------
 <a id="__codelineno-6-16" name="__codelineno-6-16" href="#__codelineno-6-16"></a>❌ OVERALL TEST SUMMARY

data/site-local/configuration/reference/release-build.html

@@ -4444,6 +4444,8 @@ precedence.</p>
 <em>&lt;build path&gt;/artifacts/release/</em>. Ceedling sets the default artifact 
 file extension to that as is explicitly specified in the <code>:extension</code>
 section or as is system specific otherwise.</p>
+<p>An absolute path, or one beginning with <code>~</code>, names the release itself. Its
+map file sits beside it.</p>
 <p><strong>Default</strong>: <code>project.exe</code> or <code>project.out</code></p>
 <h2 id="use_assembly"><code>:use_assembly</code></h2>
 <p>This option causes Ceedling to enable an assembler tool and add any

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

@@ -5074,6 +5074,15 @@ the name quoted, add escaped quotes in the YAML:</p>
 <li>
 <p><code>:arguments</code> - List (array of strings) of command line arguments and
     substitutions (required).</p>
+<div class="admonition tip">
+<p class="admonition-title">Quote the paths your tools name</p>
+<p>Ceedling runs each tool’s command line through your system’s shell, which
+reads a space, an apostrophe, and other characters in a path as part of
+the command. Wrap each path argument in escaped quotes, as Ceedling’s
+own tools do, for example <code>"-c \"${1}\""</code>. Quoting protects most
+characters. On Linux and macOS, a path holding <code>"</code>, <code>$</code>, a backtick, or
+<code>\</code> can still break a command.</p>
+</div>
 </li>
 <li>
 <p><code>:name</code> - Simple name (i.e. "nickname") of tool beyond its executable name.