ceedling 1.1.9 → 1.2.0

data/lib/ceedling/dependencies/dependency_path_normalizer.rb

@@ -0,0 +1,80 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Canonicalizes a path into the identity DependencyTracker uses as a cache key.
+#
+# Path *equality* is platform-dependent: Linux is case-sensitive (`Foo.c` and
+# `foo.c` are different files); macOS (default APFS/HFS+) and Windows (NTFS)
+# are case-insensitive but case-preserving (`Foo.c` and `foo.c` name the same
+# file, but the filesystem remembers whichever casing created it). A target or
+# dependency path can reach this code in whatever casing a caller happened to
+# use (a `#include "Foo.h"` directive vs. an on-disk `foo.h`, or a path
+# assembled from YAML config with inconsistent casing) -- if the cache key
+# doesn't reflect the file's *actual* on-disk casing, a lookup can miss even
+# though the file is genuinely the same one previously tracked.
+#
+# Rather than first detecting "is this filesystem case-insensitive?" as a
+# separate yes/no probe, this class always attempts to recover the real
+# on-disk casing for a path that exists, one directory component at a time,
+# memoizing each directory's listing within this instance (a directory's
+# contents don't change mid-build in the relevant sense, and this avoids
+# re-listing the same directory for every path lookup that shares it). This
+# is a no-op in the case-sensitive case: the exact-case entry is simply what
+# the listing already contains, so resolution finds it immediately. A path
+# that does not exist on disk (or a directory listing that fails, e.g. a
+# permissions error) is returned expanded but otherwise unchanged -- it can't
+# be case-resolved against a filesystem that can't be consulted, and callers
+# already treat a nonexistent dependency as unconditionally stale.
+class DependencyPathNormalizer
+
+  constructor :file_wrapper
+
+  def setup()
+    @directory_listing_cache = {}
+  end
+
+  # Returns the canonical cache-key form of `path`: expanded to an absolute
+  # path and, if it exists, resolved to its real on-disk casing.
+  def normalize(path)
+    expanded = @file_wrapper.get_expanded_path( path )
+    return expanded unless @file_wrapper.exist?( expanded )
+
+    real_case_path( expanded )
+  end
+
+  ### Private ###
+  private
+
+  def real_case_path(path)
+    dir  = @file_wrapper.dirname( path )
+    base = @file_wrapper.basename( path )
+
+    # Reached the filesystem root -- `dirname` of the root is itself.
+    return path if dir == path
+
+    parent = real_case_path( dir )
+    entries = directory_listing( parent )
+
+    # Prefer an exact-case match over a merely case-insensitive one: on a
+    # case-sensitive filesystem where two distinctly-cased entries genuinely
+    # coexist (e.g. `Foo.c` and `foo.c` as two different files), the exact
+    # match is unambiguously the right one -- falling back to a case-
+    # insensitive match is only correct when no exact match exists at all.
+    on_disk_entry = entries.find { |entry| entry == base } || entries.find { |entry| entry.casecmp?( base ) }
+
+    on_disk_entry ? File.join( parent, on_disk_entry ) : path
+  end
+
+  def directory_listing(dir)
+    @directory_listing_cache[dir] ||= begin
+      @file_wrapper.directory_listing( File.join( dir, '*' ) ).map { |entry| @file_wrapper.basename( entry ) }
+    rescue StandardError
+      []
+    end
+  end
+
+end

data/lib/ceedling/dependencies/dependency_tracker.rb

@@ -0,0 +1,405 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'time'
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+
+# A pure query module for content-hash-based rebuild staleness -- not a build
+# scheduler. Ceedling's existing Rake-based, multithreaded, conditionally-
+# branching build steps already encode ordering via task prerequisites; this
+# class only answers, at the moment an existing build step considers whether
+# to run, "has anything this target depends on changed since it last built
+# successfully?" Cascading rebuilds fall out of Ceedling's existing task
+# graph, not from anything in here.
+#
+# Usage, once per target within a single Ceedling invocation:
+#   tracker.register(target, files: [...], meta: {...})   # may be called more than once; additive
+#   if tracker.stale?(target)
+#     ... run the real build step ...
+#     tracker.register(target, outputs: [...])             # optional; files the step produced
+#     tracker.mark_fresh(target)
+#   end
+#   tracker.flush   # once, after all targets for this invocation are processed
+#
+# `meta` is an arbitrary, caller-supplied Hash folded into one canonicalized,
+# hashed blob alongside the file-content hashes -- compilation/link flags,
+# `-D` defines, include/search paths, toolchain version strings, and status
+# booleans (coverage on/off, MC/DC on/off, release vs. debug, ...). A target
+# is stale if any of: it was never registered, it doesn't exist on disk, its
+# own content hash changed, its meta hash changed, any dependency's content
+# hash changed, or any dependency no longer exists.
+#
+# `outputs` are files a step produces beside its target and later trusts, such as
+# cached results. A fresh target vouches for the outputs recorded with it, so a
+# recorded output that is missing or altered makes the target stale too. Only a
+# regular file counts as present, for a target, a dependency or an output alike.
+#
+# Every filesystem touch goes through the injected FileWrapper (and ENV access
+# through SystemWrapper), so every code path here is exercisable in specs
+# without creating a single real file.
+class DependencyTracker
+
+  DEBUG_TIERS = { none: 0, meta: 1, full: 2 }.freeze unless const_defined?(:DEBUG_TIERS, false)
+
+  # Tier 2 (:full) captures raw dependency file content per target, per build --
+  # a single huge generated header could otherwise blow up the cache file
+  # silently. Content beyond this size is recorded as truncated (with its real
+  # size) rather than either silently dropped or silently included in full.
+  DEBUG_FULL_CAPTURE_SIZE_CAP = 1_048_576 unless const_defined?(:DEBUG_FULL_CAPTURE_SIZE_CAP, false) # 1 MiB
+
+  constructor(
+    :file_wrapper,
+    :system_wrapper,
+    :loginator,
+    :dependency_hasher,
+    :dependency_path_normalizer,
+    :dependency_cache_store,
+    :gcc_dependency_parser,
+    :dependency_debug_tree,
+    :dependency_differ
+  )
+
+  def setup()
+    @mutex = Mutex.new
+    @store_path = nil
+    @debug_root = nil
+    @debug_tier = DEBUG_TIERS[:none]
+    @relationships = {}
+    @cache = { 'entries' => {} }
+  end
+
+  # Must be called once before any other method. Loads (and validates) any
+  # existing cache at `store_path`. `debug_tier` (:none, :meta, or :full)
+  # defaults to the `CEEDLING_DEP_DEBUG` environment variable when not given
+  # explicitly, matching Ceedling's existing convention of environment
+  # variables acting as an override for otherwise-code-driven settings (see
+  # Loginator's `CEEDLING_DECORATORS` handling) -- and falls back to :none for
+  # anything unset or unrecognized, since these tiers are meant to be opt-in,
+  # temporary debugging aids, never a silently-active default.
+  #
+  # Any cache entries dropped while loading (malformed, or their target
+  # deleted from disk -- see DependencyCacheStore#load) have their
+  # DependencyDebugTree data pruned too, so the debug tree never outlives
+  # the cache entries it exists to explain.
+  def open(store_path:, debug_tier: nil)
+    @store_path = store_path
+    @debug_root = debug_root_for( store_path )
+    @debug_tier = resolve_debug_tier( debug_tier )
+
+    @mutex.synchronize do
+      @relationships = {}
+      @cache = @dependency_cache_store.load( @store_path )
+      ( @cache['pruned'] || [] ).each { |target| @dependency_debug_tree.prune( @debug_root, target ) }
+    end
+  end
+
+  # Registers `target`'s dependency files and/or meta. Additive: calling this
+  # more than once for the same target unions the file lists (deduplicated)
+  # and shallow-merges the meta hashes (later calls win on conflicting keys)
+  # rather than replacing the prior registration -- so a target's
+  # dependencies can be accumulated incrementally across multiple calls (e.g.
+  # one call for its own source file plus explicit config, another from
+  # `register_gcc_deps_file`/`register_gcc_deps_string` for its discovered
+  # header dependencies) without each caller needing to know and resupply
+  # everything a previous caller already established.
+  #
+  # `outputs` accumulate the same way. A step registers them once it has produced
+  # them, before `mark_fresh` records their hashes.
+  def register(target, files: [], meta: {}, outputs: [])
+    ensure_open!
+
+    key = @dependency_path_normalizer.normalize( target )
+    file_keys = Array( files ).map { |file| @dependency_path_normalizer.normalize( file ) }
+    output_keys = Array( outputs ).map { |output| @dependency_path_normalizer.normalize( output ) }
+
+    @mutex.synchronize do
+      existing = @relationships[key] || empty_relationship()
+      @relationships[key] = {
+        files:   (existing[:files] + file_keys).uniq,
+        meta:    existing[:meta].merge( meta ),
+        outputs: (existing[:outputs] + output_keys).uniq
+      }
+    end
+  end
+
+  # Parses gcc `-M`/`-MM`/`-MMD` Makefile-dialect dependency content and
+  # additively registers each target it discovers (see `register`) with its
+  # parsed dependencies. `meta` is applied identically to every target found
+  # in `content`.
+  def register_gcc_deps_string(content, meta: {})
+    ensure_open!
+
+    @gcc_dependency_parser.parse( content ).each do |target, deps|
+      register( target, files: deps, meta: meta )
+    end
+  end
+
+  # As `register_gcc_deps_string`, but reads `filepath` (e.g. a `.d` file
+  # produced by gcc's `-MF`) via the injected FileWrapper first.
+  def register_gcc_deps_file(filepath, meta: {})
+    ensure_open!
+    register_gcc_deps_string( @file_wrapper.read( filepath ), meta: meta )
+  end
+
+  # Pure query -- never mutates the cache. `target` is stale if:
+  # - it was never registered this run,
+  # - it does not exist on disk as a regular file,
+  # - there is no prior cache entry for it,
+  # - its own content hash no longer matches the cache entry,
+  # - its meta hash no longer matches the cache entry,
+  # - any registered dependency no longer exists, or its content hash no
+  #   longer matches the cache entry, or
+  # - any output recorded in the cache entry no longer exists, or its content
+  #   hash no longer matches.
+  #
+  # Outputs come from the cache entry rather than this run's registrations, so a
+  # step need not know its outputs before asking.
+  def stale?(target)
+    ensure_open!
+
+    key = @dependency_path_normalizer.normalize( target )
+    rel = @mutex.synchronize { @relationships[key] }
+    return true if rel.nil?
+    return true unless regular_file?( key )
+
+    entry = @mutex.synchronize { @cache['entries'][key] }
+    return true if entry.nil?
+    return true if entry['self_hash'] != @dependency_hasher.hash_of_file( key )
+    return true if entry['meta_hash'] != @dependency_hasher.hash_of_meta( rel[:meta] )
+    return true unless rel[:files].all? { |dep| matches?( dep, entry.dig( 'deps', dep ) ) }
+
+    !( entry['outputs'] || {} ).all? { |output, digest| matches?( output, digest ) }
+  end
+
+  # Records `target` (and its currently-registered dependencies, meta, and outputs)
+  # as fresh -- called by a build step after it successfully (re)builds `target`.
+  # A dependency or output that isn't currently a regular file is simply omitted
+  # from the recorded hashes (rather than raising); the next `stale?` call already
+  # treats a missing dependency as stale on its own.
+  #
+  # When a debug tier is active, this also writes a DependencyDebugTree
+  # snapshot for `target` (tier :meta+: canonicalized meta; tier :full:
+  # target content too) and, at tier :full, for every currently-registered
+  # dependency (content only -- a dependency has no meta of its own). These
+  # snapshots are what `diagnose` later diffs live content against; nothing
+  # is embedded in the JSON cache entry itself.
+  def mark_fresh(target)
+    ensure_open!
+
+    key = @dependency_path_normalizer.normalize( target )
+    rel = @mutex.synchronize { @relationships[key] } || empty_relationship()
+
+    # A target isn't guaranteed to exist -- e.g. a caller conditionally writes one of two
+    # mutually exclusive outcome files -- so this mirrors `stale?`'s own presence check
+    # before ever hashing the target. `hashes_of` extends the same tolerance to each
+    # dependency and output.
+    self_hash = regular_file?( key ) ? @dependency_hasher.hash_of_file( key ) : nil
+    entry = {
+      'self_hash' => self_hash,
+      'meta_hash' => @dependency_hasher.hash_of_meta( rel[:meta] ),
+      'deps'      => hashes_of( rel[:files] )
+    }
+
+    # Only a target with outputs carries the key, so every other entry is unchanged
+    outputs = hashes_of( rel[:outputs] )
+    entry['outputs'] = outputs unless outputs.empty?
+
+    capture_debug_snapshots( key, self_hash, rel ) if @debug_tier > DEBUG_TIERS[:none]
+
+    @mutex.synchronize { @cache['entries'][key] = entry }
+  end
+
+  # Explicit cache-busting: drops any cache entry for `target`, so the next
+  # `stale?` call for it returns true regardless of hashes. Does not affect
+  # this run's `register`ed relationships for `target`.
+  def invalidate(target)
+    ensure_open!
+    key = @dependency_path_normalizer.normalize( target )
+    @mutex.synchronize { @cache['entries'].delete( key ) }
+  end
+
+  # Persists the current cache state to `store_path`. Intended to be called
+  # once per Ceedling invocation, after all targets have been processed.
+  #
+  # `prune: true` additionally drops any cache entry whose target was *not*
+  # `register`ed at some point during this run, both from what gets
+  # persisted and from in-memory state. This is opt-in and off by default
+  # because it is only correct when the caller knows this run's
+  # registrations represent the complete, current set of targets -- e.g. a
+  # real `test:all`/`release` run, never a partial build of a single file
+  # (`ceedling test:some_file.c`), which would otherwise wipe cache entries
+  # for every target the partial build simply didn't touch. Contrast with
+  # the always-on, always-safe pruning `DependencyCacheStore#load` already
+  # does for targets provably deleted from disk, which cannot misfire this
+  # way regardless of build completeness.
+  def flush(prune: false)
+    ensure_open!
+
+    entries = @mutex.synchronize do
+      if prune
+        dropped = @cache['entries'].keys.reject { |target| @relationships.key?( target ) }
+        @cache['entries'].select! { |target, _entry| @relationships.key?( target ) }
+        dropped.each { |target| @dependency_debug_tree.prune( @debug_root, target ) }
+      end
+      @cache['entries'].dup
+    end
+
+    @dependency_cache_store.persist( @store_path, entries )
+  end
+
+  # Explains why `target` is (or was last found to be) stale: which of
+  # self/meta/dependencies changed, and -- to whatever extent a prior
+  # DependencyDebugTree snapshot is available to compare against (see
+  # `mark_fresh`) -- an actual diff for each. Always runs (no debug tier
+  # required): with no snapshots ever captured, it still reports *which*
+  # checks failed, just without diff detail, each annotated with why no
+  # diff could be produced. Writes the result to the debug tree as
+  # `diagnosis.yml` under `target`'s own mirrored directory, and also
+  # returns it directly for programmatic use (e.g. specs).
+  #
+  # Does not require `target` to currently be stale -- calling it on a
+  # fresh target just reports everything as unchanged.
+  def diagnose(target)
+    ensure_open!
+
+    key = @dependency_path_normalizer.normalize( target )
+    rel = @mutex.synchronize { @relationships[key] }
+    entry = @mutex.synchronize { @cache['entries'][key] }
+
+    diagnosis = { 'target' => key, 'diagnosed_at' => Time.now.utc.iso8601 }
+
+    if rel.nil?
+      diagnosis['reason'] = 'never registered this run'
+    elsif !regular_file?( key )
+      diagnosis['reason'] = 'target does not exist on disk'
+    elsif entry.nil?
+      diagnosis['reason'] = 'no prior cache entry (never marked fresh)'
+    else
+      diagnosis['self'] = diagnose_self( key, entry )
+      diagnosis['meta'] = diagnose_meta( key, rel, entry )
+      diagnosis['antecedents'] = rel[:files].map { |dep| diagnose_dependency( dep, entry ) }
+      diagnosis['outputs'] = ( entry['outputs'] || {} ).map { |output, digest| diagnose_output( output, digest ) }
+    end
+
+    @dependency_debug_tree.write_diagnosis( @debug_root, key, diagnosis )
+    diagnosis
+  end
+
+  ### Private ###
+  private
+
+  def ensure_open!
+    return unless @store_path.nil?
+    raise CeedlingException.new( 'DependencyTracker#open must be called before use.' )
+  end
+
+  def resolve_debug_tier(explicit)
+    tier = explicit || env_debug_tier()
+    DEBUG_TIERS.fetch( tier, DEBUG_TIERS[:none] )
+  end
+
+  def env_debug_tier
+    value = @system_wrapper.env_get( 'CEEDLING_DEP_DEBUG' )
+    return :none if value.nil? || value.strip.empty?
+    value.strip.downcase.to_sym
+  end
+
+  # Debug tree root, derived from `store_path` rather than a separate
+  # parameter -- `.dep_cache.json` -> `.dep_cache_debug/`, alongside it.
+  def debug_root_for(store_path)
+    dir  = @file_wrapper.dirname( store_path )
+    base = @file_wrapper.basename( store_path, @file_wrapper.extname( store_path ) )
+    File.join( dir, "#{base}_debug" )
+  end
+
+  def capture_debug_snapshots(key, self_hash, rel)
+    meta = @debug_tier >= DEBUG_TIERS[:meta] ? @dependency_hasher.canonicalize( rel[:meta] ) : nil
+    content = @debug_tier >= DEBUG_TIERS[:full] ? captured_content( key ) : {}
+
+    @dependency_debug_tree.write_snapshot( @debug_root, key, hash: self_hash, meta: meta, **content )
+
+    return unless @debug_tier >= DEBUG_TIERS[:full]
+
+    rel[:files].each do |dep|
+      next unless regular_file?( dep )
+      @dependency_debug_tree.write_snapshot( @debug_root, dep, hash: @dependency_hasher.hash_of_file( dep ), **captured_content( dep ) )
+    end
+  end
+
+  def captured_content(path)
+    content = @file_wrapper.read( path )
+    if content.bytesize > DEBUG_FULL_CAPTURE_SIZE_CAP
+      { truncated: true, size: content.bytesize }
+    else
+      { content: content }
+    end
+  end
+
+  def diagnose_self(key, entry)
+    current_hash = @dependency_hasher.hash_of_file( key )
+    changed = entry['self_hash'] != current_hash
+    result = { 'changed' => changed }
+    return result unless changed
+
+    snapshot = @dependency_debug_tree.read_snapshot( @debug_root, key )
+    current_content = regular_file?( key ) ? @file_wrapper.read( key ) : nil
+    result.merge( @dependency_differ.diff_content( snapshot, current_content ) )
+  end
+
+  def diagnose_meta(key, rel, entry)
+    current_meta_hash = @dependency_hasher.hash_of_meta( rel[:meta] )
+    changed = entry['meta_hash'] != current_meta_hash
+    result = { 'changed' => changed }
+    return result unless changed
+
+    snapshot = @dependency_debug_tree.read_snapshot( @debug_root, key )
+    old_meta = snapshot && snapshot['meta']
+    new_meta = @dependency_hasher.canonicalize( rel[:meta] )
+    result.merge( @dependency_differ.diff_meta( old_meta, new_meta ) )
+  end
+
+  def diagnose_dependency(dep, entry)
+    return { 'path' => dep, 'missing' => true } unless regular_file?( dep )
+
+    current_hash = @dependency_hasher.hash_of_file( dep )
+    changed = entry.dig( 'deps', dep ) != current_hash
+    result = { 'path' => dep, 'changed' => changed }
+    return result unless changed
+
+    snapshot = @dependency_debug_tree.read_snapshot( @debug_root, dep )
+    result.merge( @dependency_differ.diff_content( snapshot, @file_wrapper.read( dep ) ) )
+  end
+
+  # Outputs keep no debug snapshot, so a diagnosis reports only that one changed
+  def diagnose_output(output, digest)
+    return { 'path' => output, 'missing' => true } unless regular_file?( output )
+
+    { 'path' => output, 'changed' => digest != @dependency_hasher.hash_of_file( output ) }
+  end
+
+  def empty_relationship()
+    { files: [], meta: {}, outputs: [] }
+  end
+
+  # A directory is never a dependency or output, however a `.d` file came to name one
+  def regular_file?(path)
+    @file_wrapper.exist?( path ) && !@file_wrapper.directory?( path )
+  end
+
+  # Whether `path` is still a regular file with the content hashed as `digest`
+  def matches?(path, digest)
+    regular_file?( path ) && digest == @dependency_hasher.hash_of_file( path )
+  end
+
+  def hashes_of(paths)
+    paths.each_with_object( {} ) do |path, hashes|
+      hashes[path] = @dependency_hasher.hash_of_file( path ) if regular_file?( path )
+    end
+  end
+
+end

data/lib/ceedling/dependencies/dependinator.rb

@@ -0,0 +1,65 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Ceedling-specific adapter between the build pipeline and the generic,
+# application-agnostic DependencyTracker -- owns the tracker's lifecycle
+# (where its cache file lives, when it's opened and flushed) so pipeline
+# code only ever deals in build verbs, never cache mechanics.
+class Dependinator
+
+  CACHE_FILENAME = 'dep_cache.json'.freeze unless const_defined?(:CACHE_FILENAME, false)
+
+  constructor :dependency_tracker
+
+  # Builds the cache file path for a given pipeline identifier (:test, :release, a
+  # plugin's own symbol, ...). Public and callable without an instance so any
+  # caller -- a pipeline invoker, a spec, a future plugin -- can compute or inspect
+  # the path an identifier resolves to. Every identifier lands in the same,
+  # already-unconditionally-created directory, distinguished by filename alone, so
+  # a new pipeline needs no build-path scaffolding of its own to get an isolated
+  # cache -- just a unique identifier.
+  def self.cache_store_path(identifier)
+    File.join( PROJECT_BUILD_DEPENDENCIES_CACHE_PATH, ".#{identifier}.#{CACHE_FILENAME}" )
+  end
+
+  # `identifier` isolates one pipeline's cache from another's -- sharing a single
+  # cache file between, say, test and release builds would make a full test:all
+  # run's pruning flush (see `flush`) silently evict every cached release entry,
+  # and vice versa, since pruning drops anything not registered in the current run.
+  def open(identifier: :test)
+    @dependency_tracker.open( store_path: self.class.cache_store_path( identifier ) )
+  end
+
+  def register(target, files: [], meta: {}, outputs: [])
+    @dependency_tracker.register( target, files: files, meta: meta, outputs: outputs )
+  end
+
+  def register_gcc_deps_file(filepath, meta: {})
+    @dependency_tracker.register_gcc_deps_file( filepath, meta: meta )
+  end
+
+  def stale?(target)
+    @dependency_tracker.stale?( target )
+  end
+
+  def mark_fresh(target)
+    @dependency_tracker.mark_fresh( target )
+  end
+
+  def invalidate(target)
+    @dependency_tracker.invalidate( target )
+  end
+
+  # `refresh_dependencies` is a full-run signal, set only by `test:all` (tasks_tests.rake):
+  # only a run that touched every test target may safely prune cache entries
+  # for targets it didn't see this time -- a partial build (a single test
+  # file, `test:pattern`, `test:path`, `test:build_only`) must not.
+  def flush(refresh_dependencies: false)
+    @dependency_tracker.flush( prune: refresh_dependencies )
+  end
+
+end

data/lib/ceedling/dependencies/gcc_dependency_parser.rb

@@ -0,0 +1,86 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Parses gcc's `-M`/`-MM`/`-MMD` Makefile-dialect dependency output into a plain
+# `{ target => [dep, dep, ...] }` mapping. Pure string processing -- no filesystem
+# access, so it works identically whether the content came from a real `.d` file
+# or an in-memory string handed to it directly (e.g. from a test, or a caller
+# that already has the content in hand).
+#
+# Handles:
+# - Backslash-newline line continuations (`\` at end of line joins with the next).
+# - Multiple targets in one blob, including `-MP` phony no-prerequisite targets
+#   (`some_header.h:` with nothing after the colon).
+# - Multiple targets sharing one prerequisite list on a single logical line
+#   (`a.o b.o: common.h`), valid Make syntax though gcc rarely emits it directly.
+# - Escaped spaces in paths (`\ ` -> literal space), as gcc emits for paths
+#   containing spaces.
+# - Windows drive-letter paths (`C:\foo\bar.h`): the drive-letter colon is not
+#   mistaken for the target/prerequisite separator because a real separator
+#   colon must be followed by whitespace or end-of-line, while a drive-letter
+#   colon is immediately followed by `\` or `/`.
+class GccDependencyParser
+
+  # A logical line's target/prerequisite separator: a colon immediately
+  # followed by whitespace or end-of-line. A colon immediately followed by
+  # `\` or `/` (a Windows drive letter) does not match and is skipped over.
+  SEPARATOR_RE = /\A(.*?):(?=[ \t]|\z)[ \t]*(.*)\z/ unless const_defined?(:SEPARATOR_RE, false)
+
+  # A token is a maximal run of "escaped character" or "non-whitespace"
+  # sequences -- this keeps an escaped space (`\ `) glued to its token instead
+  # of splitting on it as a token boundary.
+  TOKEN_RE = /(?:\\.|\S)+/ unless const_defined?(:TOKEN_RE, false)
+
+  # Parses `content` (a String) and returns `{ target => [dep, ...] }`.
+  # Returns `{}` for nil/blank content. Never raises on malformed input --
+  # lines that don't contain a recognizable target/prerequisite separator are
+  # skipped rather than treated as an error, since a `.d` file may have been
+  # truncated by an interrupted build or hand-edited.
+  def parse(content)
+    targets = {}
+    return targets if content.nil?
+
+    join_line_continuations( content ).each_line do |line|
+      line = line.strip
+      next if line.empty?
+
+      m = line.match( SEPARATOR_RE )
+      next if m.nil?
+
+      target_tokens = tokenize( m[1] )
+      dep_tokens    = tokenize( m[2] )
+
+      target_tokens.each do |target|
+        (targets[target] ||= []).concat( dep_tokens )
+      end
+    end
+
+    targets.transform_values { |deps| deps.uniq }
+  end
+
+  ### Private ###
+  private
+
+  def join_line_continuations(content)
+    content.gsub( /\\\r?\n/, ' ' )
+  end
+
+  def tokenize(text)
+    return [] if text.nil?
+    text.scan( TOKEN_RE ).map { |token| unescape( token ) }
+  end
+
+  # gcc escapes only spaces and `#` (Makefile comment character) with a
+  # backslash in its dependency output. Backslashes are otherwise significant
+  # and literal -- most notably as Windows path separators (`C:\proj\foo.c`)
+  # -- so only these two specific escapes are unescaped; any other backslash
+  # is left exactly as-is.
+  def unescape(token)
+    token.gsub( /\\([ #])/ ) { $1 }
+  end
+
+end

data/lib/ceedling/encodinator.rb

@@ -7,20 +7,32 @@
 
 # Patch the string class so that we have a nice shortcut for cleaning string encodings
 class String
+  # Clean up any oddball characters in an otherwise ASCII document. Hoisted to a
+  # frozen constant rather than rebuilt on every clean_encoding call -- a fresh
+  # Hash literal every call was a measurable, needless allocation back when the
+  # two highest-volume callers (ParsingParcels#code_lines_with_num,
+  # PreprocessinatorReconstructor#_scan_expansion_for_file) each called this
+  # per line; both now clean a whole buffer once instead, but the remaining
+  # per-line fallback-path callers (e.g. CPreprocessorConditionals#process_directive)
+  # still benefit. Only :replace varies by caller (default '' vs. e.g. '_' from
+  # defineinator.rb), so the common, default-safe_char case reuses this
+  # constant untouched; a non-default safe_char still allocates one small
+  # merged Hash, same as before.
+  DEFAULT_CLEAN_ENCODING_OPTIONS = {
+    :invalid           => :replace,  # Replace invalid byte sequences
+    :undef             => :replace,  # Replace anything not defined in ASCII
+    :replace           => '',        # Use a safe character for those replacements
+    :universal_newline => true       # Always break lines with \n
+  }.freeze
+
   def clean_encoding(safe_char = '')
     begin
-      # Clean up any oddball characters in an otherwise ASCII document
-      encoding_options = {
-        :invalid           => :replace,  # Replace invalid byte sequences
-        :undef             => :replace,  # Replace anything not defined in ASCII
-        :replace           => safe_char, # Use a safe character for those replacements
-        :universal_newline => true       # Always break lines with \n
-      }
-    
+      encoding_options = safe_char.empty? ? DEFAULT_CLEAN_ENCODING_OPTIONS : DEFAULT_CLEAN_ENCODING_OPTIONS.merge(:replace => safe_char)
+
       return self.encode("ASCII", **encoding_options).encode('UTF-8', **encoding_options)
-    rescue 
+    rescue
       raise "String contains characters that can't be represented in standard ASCII / UTF-8."
-    end 
-    self 
+    end
+    self
   end
 end