ceedling 1.1.9 → 1.2.0

data/lib/ceedling/{tasks_tests.rake → rakefiles/tests/tasks_tests.rake}

@@ -13,59 +13,50 @@ end
 
 namespace TEST_SYM do
 
-  TOOL_COLLECTION_TEST_TASKS = {
-    :test_compiler  => TOOLS_TEST_COMPILER,
-    :test_assembler => TOOLS_TEST_ASSEMBLER,
-    :test_linker    => TOOLS_TEST_LINKER,
-    :test_fixture   => TOOLS_TEST_FIXTURE
-  }
-
   desc "Run all unit tests (also just 'test' works)."
   task :all => [:prepare] do
-    @ceedling[:test_invoker].setup_and_invoke(
-      tests:COLLECTION_ALL_TESTS,
-      options:{:force_run => true, :build_only => false}.merge(TOOL_COLLECTION_TEST_TASKS))
+    @ceedling[:test_invoker].setup_and_invoke(tests: COLLECTION_ALL_TESTS, options: [:refresh_dependencies])
   end
 
-  desc "Run single test ([*] test or source file name, no path)."
+  desc "Run single test ([*] test or source file name, with optional path)."
   task :* do
     message = "Oops! '#{TEST_ROOT_NAME}:*' isn't a real task. " +
-              "Use a real test or source file name (no path) in place of the wildcard.\n" +
-              "Example: `ceedling #{TEST_ROOT_NAME}:foo.c`"
+              "Use a real test or source file name in place of the wildcard, " +
+              "adding as much of its path as needed to identify one file among any same-named tests.\n" +
+              "Example: `ceedling #{TEST_ROOT_NAME}:foo.c` or `ceedling #{TEST_ROOT_NAME}:unit/foo.c`"
 
     @ceedling[:loginator].log( message, Verbosity::ERRORS )
   end
 
   desc "Just build tests without running."
   task :build_only => [:prepare] do
-    @ceedling[:test_invoker].setup_and_invoke(tests:COLLECTION_ALL_TESTS, options:{:build_only => true}.merge(TOOL_COLLECTION_TEST_TASKS))
+    @ceedling[:test_invoker].setup_and_invoke(tests: COLLECTION_ALL_TESTS, options: [:build_only])
   end
 
   desc "Run tests by matching regular expression pattern."
-  task :pattern, [:regex] => [:prepare] do |t, args|
+  task :pattern, [:regex] => [:prepare] do |_t, args|
     matches = []
 
     COLLECTION_ALL_TESTS.each { |test| matches << test if (test =~ /#{args.regex}/) }
 
     if (matches.size > 0)
-      @ceedling[:test_invoker].setup_and_invoke(tests:matches, options:{:force_run => false}.merge(TOOL_COLLECTION_TEST_TASKS))
+      @ceedling[:test_invoker].setup_and_invoke(tests: matches, options: [])
     else
       @ceedling[:loginator].log( "Found no tests matching pattern /#{args.regex}/", Verbosity::ERRORS )
     end
   end
 
   desc "Run tests whose test path contains [dir] or [dir] substring."
-  task :path, [:dir] => [:prepare] do |t, args|
+  task :path, [:dir] => [:prepare] do |_t, args|
     matches = []
 
-    COLLECTION_ALL_TESTS.each { |test| matches << test if File.dirname(test).include?(args.dir.gsub(/\\/, '/')) }
+    COLLECTION_ALL_TESTS.each { |test| matches << test if File.dirname(test).include?(args.dir.tr("\\", '/')) }
 
     if (matches.size > 0)
-      @ceedling[:test_invoker].setup_and_invoke(tests:matches, options:{:force_run => false}.merge(TOOL_COLLECTION_TEST_TASKS))
+      @ceedling[:test_invoker].setup_and_invoke(tests: matches, options: [])
     else
       @ceedling[:loginator].log( "Found no tests including the given path or path component", Verbosity::ERRORS )
     end
   end
 
 end
-

data/lib/ceedling/rakefiles/tests/tasks_tests_generate.rake

@@ -0,0 +1,55 @@
+# =========================================================================
+#   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/constants'
+
+namespace GEN_SYM do
+
+  task :mocks => [:prepare] do
+    Rake.application['gen:mocks:all'].invoke
+  end
+
+  # A single `namespace GEN_SYM do` level, not one nested per gen: sub-namespace --
+  # see rules_release.rake's own identical reasoning: RakeTaskRegistry resolves a
+  # task's semantic tags from its *nearest* enclosing namespace, so nesting one
+  # level deeper than necessary here would make gen: tasks resolve to "mocks"/
+  # "test_runner" instead of "gen" itself, going unrecognized as test/build tasks.
+  desc "Generate mocks for every test without further building or running."
+  task 'mocks:all' => [:prepare] do
+    @ceedling[:test_invoker].setup_and_invoke(tests: COLLECTION_ALL_TESTS, options: [:mocking])
+  end
+
+  desc "Generate mocks for single test ([*] test or source file name, with optional path)."
+  task 'mocks:*' do
+    message = "Oops! '#{GENERATE_MOCKS_TASK_ROOT}*' isn't a real task. " +
+              "Use a real test or source file name in place of the wildcard, " +
+              "adding as much of its path as needed to identify one file among any same-named tests.\n" +
+              "Example: `ceedling #{GENERATE_MOCKS_TASK_ROOT}foo.c` or `ceedling #{GENERATE_MOCKS_TASK_ROOT}unit/foo.c`"
+
+    @ceedling[:loginator].log( message, Verbosity::ERRORS )
+  end
+
+  task :test_runner => [:prepare] do
+    Rake.application['gen:test_runner:all'].invoke
+  end
+
+  desc "Generate up through test runners for every test without further building or running."
+  task 'test_runner:all' => [:prepare] do
+    @ceedling[:test_invoker].setup_and_invoke(tests: COLLECTION_ALL_TESTS, options: [:test_runner])
+  end
+
+  desc "Generate up through test runner for a single test ([*] test or source file name, with optional path)."
+  task 'test_runner:*' do
+    message = "Oops! '#{GENERATE_TEST_RUNNER_TASK_ROOT}*' isn't a real task. " +
+              "Use a real test or source file name in place of the wildcard, " +
+              "adding as much of its path as needed to identify one file among any same-named tests.\n" +
+              "Example: `ceedling #{GENERATE_TEST_RUNNER_TASK_ROOT}foo.c` or `ceedling #{GENERATE_TEST_RUNNER_TASK_ROOT}unit/foo.c`"
+
+    @ceedling[:loginator].log( message, Verbosity::ERRORS )
+  end
+
+end

data/lib/ceedling/release_invoker/README.md

@@ -0,0 +1,35 @@
+# The Release Build Pipeline
+
+A release build compiles and links exactly one artifact from a flat list of objects, using compile/assemble/link inputs that are resolved once and shared alike by every object, rather than the test pipeline's model of many independent, per-file records.
+
+That one difference in shape -- one artifact instead of many independent test files -- is what makes the release pipeline so much smaller than the test pipeline: there's nothing here analogous to a `Testable`, no per-item struct at all, and no dedicated stage-sequencing class, because there's no per-item variation across a run for one to manage. Where the test pipeline earns its `TestPipelineManager` and its four independently composable stop-point flags by fanning out over N test files with real conditional structure between them, a release build is a fixed handful of steps every single time.
+
+## The pipeline's shape
+
+Three classes divide the work:
+
+- **`ReleaseInvoker`** owns the whole run, lifecycle and sequencing both. It fires the `pre_release_build`/`post_release_build` plugin hooks, opens and flushes the dependency cache around the run, catches and logs any exception raised anywhere in the pipeline rather than letting it propagate, and calls the four steps below directly, in order. There's no separate pipeline-manager class the way the test pipeline has `TestPipelineManager`, precisely because there's no stop-point or conditional stage-skipping here for a dedicated class to own.
+- **`ReleaseBuildPlanner`** decides *what* to build: the object list, and the compile/assemble/link flags, defines, and search paths every one of those objects will share alike. It never invokes a tool and never talks to the dependency tracker -- it only figures out the plan.
+- **`ReleaseBuildExecutor`** does the actual work the plan calls for: compiling objects, linking the artifact, and copying the result into place. It's the only one of the three that invokes a tool or talks to the dependency tracker.
+
+## `ReleaseState`
+
+`ReleaseState` is the release pipeline's one state object, playing the same role `PipelineState` plays for the test pipeline -- except that since there's exactly one artifact here, not N independent ones, it holds both the flat object list and the shared, once-resolved compile/link inputs every object uses alike, rather than a collection of many separate per-item records. It carries the object list, the compile/assemble/link flags, defines, and search paths the planner resolves once, and `executable_rebuilt`. That last field is carried on the struct rather than re-derived later for exactly the same reason `Testable#executable_rebuilt` is on the test side: by the time anything downstream would ask "was this just rebuilt?", the dependency tracker has already been told the executable is fresh, so asking it again would always answer "no."
+
+## The four steps, in order
+
+**Planning** is `ReleaseBuildPlanner#plan`. It resolves the full object list (every configured release source plus any extra link-only objects), tailors the compiler/linker tool configuration for a shared-library or static-archive target if the project is still using Ceedling's own default release tools, and resolves the flags, defines, and search paths every object compiled in this run will use alike.
+
+**Building objects** is `ReleaseBuildExecutor#compile_objects`, which compiles or assembles every object in the plan's list in parallel, each independently checked against the dependency tracker so only what's actually stale gets rebuilt.
+
+**Building the release artifact** is `ReleaseBuildExecutor#link`. It separates any precompiled libraries or archives out of the object list, formats them (and any project-configured system or release-only libraries) as linker arguments, and links the executable if the dependency tracker reports it stale -- recording whether a real link just happened for the next step to use.
+
+**Collecting artifacts** is `ReleaseBuildExecutor#artifactinate`, which copies the built executable, its map file, and any project-configured extra artifacts into the release artifacts directory -- but only when linking actually just happened; otherwise there's nothing new to collect.
+
+## The single-file compile-check mode
+
+The release pipeline has exactly one way to run less than the full sequence, and it's a parameter, not a set of flags the way the test pipeline's stop-points are: `ReleaseInvoker#setup_and_invoke` accepts an optional `files:` argument, and when it's a single-element Array rather than `nil`, planning and object-building still run against that one file, but linking and artifact-collection are skipped entirely. This is what backs the ad hoc `release:compile:<file>`/`release:assemble:<file>` Rake tasks, which exist so a project can compile one file in isolation -- to check it for syntax or compile errors during development -- without linking anything or touching the artifacts directory. Where the test pipeline's stop-points are several independently composable Symbols answering "how far should this run go," the release pipeline only ever answers a single yes-or-no question: is this a real, full release build, or a scoped single-file compile check?
+
+## Shared vocabulary with the test pipeline
+
+A handful of things carry over directly from the test pipeline's own conventions, worth knowing if you've read that pipeline's README first: `Batchinator`'s `#build_step` (for step framing) and `#exec` (for parallel per-object compilation) are the exact same collaborator, used the same way; the `Dependinator` register/`stale?`/`mark_fresh` pattern for deciding what actually needs (re)doing is identical; `executable_rebuilt`, as already mentioned, is the same carried-rather-than-requeried pattern under the same name; and both pipelines' classes are wired together through the same `constructor`-gem dependency-injection convention.

data/lib/ceedling/release_invoker/release_build_executor.rb

@@ -0,0 +1,263 @@
+# =========================================================================
+#   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/constants'
+require 'ceedling/release_invoker/release_invoker_types'
+
+# Does the actual work of a release build: compiling objects, linking the
+# artifact, and copying it into place -- the only class in this subsystem
+# that invokes tools or talks to the dependency tracker.
+class ReleaseBuildExecutor
+
+  include ReleaseInvokerTypes
+
+  constructor(
+    :configurator,
+    :loginator,
+    :reportinator,
+    :batchinator,
+    :generator,
+    :file_finder,
+    :file_wrapper,
+    :file_path_utils,
+    :dependinator
+  )
+
+  def compile_objects(state)
+    skipped = 0
+
+    @batchinator.exec(workload: :compile, things: state.objects) do |object|
+      compiled = compile_release_component( object: object, state: state )
+      # Worker threads share `skipped` -- a bare `+= 1` here is a read-modify-write
+      # across threads and can silently lose an increment under MRI's GVL, same as
+      # the test pipeline's own equivalent counter (test_build_executor.rb).
+      state.lock.synchronize { skipped += 1 } unless compiled
+    end
+
+    log_skip_summary( task: "compilation", count: skipped, noun: "objects" )
+  end
+
+  def link(state)
+    objects, libraries = sort_objects_and_libraries( state.objects )
+    lib_args  = convert_libraries_to_arguments( libraries )
+    lib_paths = get_library_paths_to_arguments()
+    target    = @configurator.project_release_build_target
+
+    @dependinator.register(
+      target,
+      files: objects,
+      meta:  { flags: state.link_flags, lib_args: lib_args, lib_paths: lib_paths, tools: [@configurator.tools_release_linker] }
+    )
+    stale = @dependinator.stale?( target )
+
+    if stale
+      @generator.generate_executable_file(
+        @configurator.tools_release_linker,
+        RELEASE_SYM,
+        objects,
+        state.link_flags,
+        target,
+        @configurator.project_release_build_map,
+        lib_args,
+        lib_paths
+      )
+
+      @dependinator.mark_fresh( target )
+    else
+      msg = @reportinator.generate_progress( "Skipping linking for #{File.basename( target )}" )
+      @loginator.log( msg, Verbosity::OBNOXIOUS )
+    end
+
+    log_skip_summary( task: "linking", count: (stale ? 0 : 1), noun: "executables" )
+
+    # #artifactinate relies on this rather than a second `stale?` call -- by
+    # now `mark_fresh` above (when `stale` was true) has already updated the
+    # cache entry to match the executable's current state, so a fresh
+    # `stale?` query would always answer false.
+    state.executable_rebuilt = stale
+  end
+
+  def artifactinate(state)
+    artifacts = [
+      @configurator.project_release_build_target,
+      @configurator.project_release_build_map,
+      @configurator.release_build_artifacts
+    ].flatten
+
+    unless state.executable_rebuilt
+      log_skip_summary( task: "artifact collection", count: artifacts.size, noun: "artifacts" )
+      return
+    end
+
+    artifacts.each do |file|
+      # `file` was just linked/generated by this same build -- exist_with_retry? rides
+      # out it briefly not yet being visible right after that shell-out exits.
+      @file_wrapper.cp( file, @configurator.project_release_artifacts_path ) if @file_wrapper.exist_with_retry?( file )
+    end
+  end
+
+  private
+
+  # Compile a single C or assembly source file into an object file. Returns
+  # whether a real compile actually happened, so the caller can report how
+  # many objects across the whole build needed nothing done.
+  def compile_release_component(object:, state:)
+    source       = @file_finder.find_build_input_file( filepath: object, context: RELEASE_SYM )
+    dependencies = @file_path_utils.form_release_dependencies_filepath( object )
+
+    if !@configurator.extension_assembly.match?( source )
+      flags = state.compile_flags
+      stale = register_and_check_object_staleness( object: object, source: source, dependencies: dependencies, flags: flags, defines: state.defines, search_paths: state.search_paths, tool: @configurator.tools_release_compiler )
+
+      return log_compile_skip( source: source ) unless stale
+
+      # A source mirrored into its own subdirectory needs that subdirectory (and its
+      # dependencies-file counterpart) to actually exist before the compiler can write there.
+      # Object and dependency paths can nest arbitrarily deep depending on where the source
+      # itself lives; only the flat top-level build roots are pre-created via `directory()`
+      # tasks, not every mirrored subdirectory beneath them.
+      @file_wrapper.mkdir( File.dirname( object ) )
+      @file_wrapper.mkdir( File.dirname( dependencies ) )
+
+      @generator.generate_object_file_c(
+        tool:         @configurator.tools_release_compiler,
+        module_name:  File.basename( source ).ext(),
+        context:      RELEASE_SYM,
+        source:       source,
+        object:       object,
+        search_paths: state.search_paths,
+        flags:        flags,
+        defines:      state.defines,
+        list:         @file_path_utils.form_release_build_list_filepath( object ),
+        dependencies: dependencies
+      )
+    else
+      flags = state.assemble_flags
+      stale = register_and_check_object_staleness( object: object, source: source, dependencies: dependencies, flags: flags, defines: state.defines, search_paths: state.search_paths, tool: @configurator.tools_release_assembler )
+
+      return log_compile_skip( source: source ) unless stale
+
+      @file_wrapper.mkdir( File.dirname( object ) )
+      @file_wrapper.mkdir( File.dirname( dependencies ) )
+
+      @generator.generate_object_file_asm(
+        tool:         @configurator.tools_release_assembler,
+        module_name:  File.basename( source ).ext(),
+        context:      RELEASE_SYM,
+        source:       source,
+        object:       object,
+        search_paths: state.search_paths,
+        flags:        flags,
+        defines:      state.defines,
+        list:         @file_path_utils.form_release_build_list_filepath( object ),
+        dependencies: dependencies
+      )
+    end
+
+    # A real (re)compile just happened -- register_gcc_deps_file again to pick
+    # up the freshly-written `.d` file's current header set (only produced for
+    # C compiles; a no-op call for assembly, whose tool has no -MMD/-MF) before
+    # recording this target's new baseline. exist_with_retry? rides out the file
+    # briefly not yet being visible right after the shell-out exits.
+    @dependinator.register_gcc_deps_file( dependencies ) if @file_wrapper.exist_with_retry?( dependencies )
+    @dependinator.mark_fresh( object )
+
+    true
+  end
+
+  # Reports that a single object file needed no recompiling, at a verbosity
+  # meant for readers who want every target accounted for individually
+  # rather than just the batch total.
+  def log_compile_skip(source:)
+    msg = @reportinator.generate_progress( "Skipping compilation for #{File.basename( source )}" )
+    @loginator.log( msg, Verbosity::OBNOXIOUS )
+    false
+  end
+
+  # Registers `object`'s antecedents (its source file, plus whatever headers
+  # gcc's `-MMD -MF` discovered on the *previous* successful compile, if any)
+  # and reports whether it needs (re)building. The previous run's `.d` file is
+  # the only header list available before this run's compile has happened --
+  # if headers changed, that's exactly what makes this stale. Nothing has just
+  # written that file, so one look suffices: a clean build has none, and a missed
+  # one leaves the object stale, forcing a recompile.
+  def register_and_check_object_staleness(object:, source:, dependencies:, flags:, defines:, search_paths:, tool:)
+    @dependinator.register( object, files: [source], meta: { flags: flags, defines: defines, search_paths: search_paths, tools: [tool] } )
+    @dependinator.register_gcc_deps_file( dependencies ) if @file_wrapper.exist?( dependencies )
+    @dependinator.stale?( object )
+  end
+
+  def convert_libraries_to_arguments(libraries)
+    args =
+      (libraries || []) +
+      ((defined? LIBRARIES_SYSTEM) ? LIBRARIES_SYSTEM : []) +
+      ((defined? LIBRARIES_RELEASE) ? LIBRARIES_RELEASE : [])
+
+    args.flatten!
+    args.compact!
+
+    if (defined? LIBRARIES_FLAG)
+      args.map! { |v| LIBRARIES_FLAG.gsub(/\$\{1\}/, v) }
+    end
+
+    return args
+  end
+
+  def get_library_paths_to_arguments()
+    paths = (defined? PATHS_LIBRARIES) ? (PATHS_LIBRARIES || []).clone : []
+    if (defined? LIBRARIES_PATH_FLAG)
+      paths.map! { |v| LIBRARIES_PATH_FLAG.gsub(/\$\{1\}/, v) }
+    end
+    return paths
+  end
+
+  # A release's object list can include precompiled libraries/archives
+  # alongside plain compiled objects (via :libraries ↳ :release or extra
+  # link-only entries) -- these need to reach the linker as -l-style
+  # arguments rather than as ordinary link inputs, so they're split out here
+  # by file extension before linking.
+  def sort_objects_and_libraries(both)
+    # A library type may be named by several extensions at once (.a and .so, say), so its
+    # regex alternation is built from however many are configured -- one entry needs no
+    # alternation at all, several are joined into one. Enumerable is the test rather than
+    # Array specifically, since a library-type extension is a FilenameExtension by the time
+    # it reaches here, not a raw Array, even though both are iterable the same way.
+    extension = if ((defined? EXTENSION_SUBPROJECTS) && (defined? EXTENSION_LIBRARIES))
+      extension_libraries = if (EXTENSION_LIBRARIES.is_a? Enumerable)
+                              EXTENSION_LIBRARIES.to_a.join(")|(?:\\")
+                            else
+                              EXTENSION_LIBRARIES
+                            end
+      "(?:\\#{EXTENSION_SUBPROJECTS})|(?:\\#{extension_libraries})"
+    elsif (defined? EXTENSION_SUBPROJECTS)
+      "\\#{EXTENSION_SUBPROJECTS}"
+    elsif (defined? EXTENSION_LIBRARIES)
+      if (EXTENSION_LIBRARIES.is_a? Enumerable)
+        "(?:\\#{EXTENSION_LIBRARIES.to_a.join(")|(?:\\")})"
+      else
+        "\\#{EXTENSION_LIBRARIES}"
+      end
+    else
+      "\\.LIBRARY"
+    end
+    # Compile once rather than once per entry in `both`
+    library_pattern = /.+#{extension}$/
+    sorted_objects = both.group_by { |v| v.match?( library_pattern ) ? :libraries : :objects }
+    libraries = sorted_objects[:libraries] || []
+    objects   = sorted_objects[:objects]   || []
+    return objects, libraries
+  end
+
+  # States, in one line, how many targets a build step left untouched because nothing
+  # about them needed attention this run. Silent when nothing was skipped, so a full
+  # rebuild's output isn't cluttered with zero counts.
+  def log_skip_summary(task:, count:, noun:, reason: "nothing changed")
+    msg = @reportinator.generate_skip_summary( task: task, count: count, noun: noun, reason: reason )
+    @loginator.log( msg ) unless msg.nil?
+  end
+
+end

data/lib/ceedling/release_invoker/release_build_planner.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
+# =========================================================================
+
+require 'ceedling/constants'
+require 'ceedling/defaults'
+require 'ceedling/release_invoker/release_invoker_types'
+
+# Determines what a release build needs: the object list and the compile/
+# assemble/link inputs every one of those objects shares alike. No tool
+# invocation and no dependency-tracker registration happens here -- that's
+# ReleaseBuildExecutor's concern; this class only figures out the plan.
+class ReleaseBuildPlanner
+
+  include ReleaseInvokerTypes
+
+  constructor(
+    :configurator,
+    :loginator,
+    :reportinator,
+    :flaginator,
+    :defineinator,
+    :file_path_utils,
+    :file_wrapper
+  )
+
+  # files: nil for a full release build (every configured release source, plus
+  # extra link-only objects); an Array of one filepath to scope down to a
+  # single object, as the ad hoc release:compile:<file>/release:assemble:<file>
+  # tasks do.
+  def plan(state, files: nil)
+    tailor_release_tools()
+
+    sources =
+      if files.nil?
+        @configurator.collection_release_build_input +
+          @configurator.collection_release_artifact_extra_link_objects
+      else
+        files.dup
+      end
+
+    state.objects        = @file_path_utils.form_release_build_objects_filelist( sources )
+    state.compile_flags   = @flaginator.flag_down( context: RELEASE_SYM, operation: OPERATION_COMPILE_SYM )
+    state.assemble_flags  = @flaginator.flag_down( context: RELEASE_SYM, operation: OPERATION_ASSEMBLE_SYM )
+    state.link_flags      = @flaginator.flag_down( context: RELEASE_SYM, operation: OPERATION_LINK_SYM )
+    state.defines         = @defineinator.defines( subkey: RELEASE_SYM )
+    state.search_paths    = @configurator.collection_paths_include
+  end
+
+  private
+
+  # Shared libraries and static archives need compiler/linker argument tags
+  # (-fPIC, -shared, or swapping the linker for `ar` outright) that a plain
+  # executable target doesn't -- derived once per build from the release
+  # target's own file extension, mutating the resolved tool config in place
+  # exactly as gcc's own default release tools expect to be used. Skipped
+  # entirely for a project that's already configured its own compiler tool
+  # (a custom :tools ↳ :release_compiler means these Ceedling-authored
+  # defaults-only tags would be presumptuous to apply).
+  def tailor_release_tools()
+    compiler = @configurator.tools_release_compiler
+    linker   = @configurator.tools_release_linker
+
+    return unless compiler[:executable] == DEFAULT_RELEASE_COMPILER_TOOL[:executable]
+
+    case File.extname( @configurator.project_release_build_target )
+    when '.so'
+      compiler[:arguments] << '-fPIC' unless compiler[:arguments].include?('-fPIC')
+      linker[:arguments] << '-shared' unless linker[:arguments].include?('-shared')
+    when '.a'
+      compiler[:arguments] << '-fPIC' unless compiler[:arguments].include?('-fPIC')
+      linker[:executable] = 'ar'
+      linker[:arguments]  = ['rcs', '${2}', '${1}']
+    end
+  end
+
+end

data/lib/ceedling/release_invoker/release_invoker.rb

@@ -0,0 +1,78 @@
+# =========================================================================
+#   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/constants'
+require 'ceedling/release_invoker/release_invoker_types'
+
+# Thin entry point for a release build -- lifecycle, error handling, and
+# dependency-cache open/flush live here; ReleaseBuildPlanner/ReleaseBuildExecutor
+# do the actual work. There's no dedicated pipeline-manager class the way
+# TestInvoker has TestPipelineManager: a release build has no stop-points or
+# conditional stage-skipping to validate or gate, just a fixed handful of
+# steps, so sequencing them directly here is proportionate.
+class ReleaseInvoker
+
+  include ReleaseInvokerTypes
+
+  constructor(
+    :application,
+    :plugin_manager,
+    :dependinator,
+    :loginator,
+    :batchinator,
+    :release_build_planner,
+    :release_build_executor
+  )
+
+  # files: nil for a full release build; an Array of one filepath to scope down
+  # to a single object -- the ad hoc release:compile:<file>/release:assemble:<file>
+  # tasks, which exist to let a project compile one file in isolation without
+  # linking or touching artifacts, e.g. for quick syntax/compile-error checking
+  # during development.
+  def setup_and_invoke(files: nil)
+    timestamp_s = SystemWrapper.time_stopwatch_s()
+    @plugin_manager.pre_release_build( timestamp_s )
+
+    @dependinator.open( identifier: :release )
+
+    state = ReleaseState.new()
+
+    begin
+      @batchinator.build_step( "Determining Objects to be Built", heading: false ) do
+        @release_build_planner.plan( state, files: files )
+      end
+
+      @batchinator.build_step( "Building Objects" ) do
+        @release_build_executor.compile_objects( state )
+      end
+
+      if files.nil?
+        @batchinator.build_step( "Building Release Artifact" ) do
+          @release_build_executor.link( state )
+        end
+
+        @batchinator.build_step( "Collecting Artifacts", heading: false ) do
+          @release_build_executor.artifactinate( state )
+        end
+      end
+
+    rescue StandardError => ex
+      @application.register_build_failure
+
+      @loginator.log( ex.message, Verbosity::ERRORS, LogLabels::EXCEPTION )
+      @loginator.log_debug_backtrace( ex )
+    ensure
+      # Only a run that touched every release target (the full `release` task,
+      # not a single-file compile:/assemble: task) may safely prune cache
+      # entries for targets it didn't see this time -- mirrors TestInvoker's
+      # own :refresh_dependencies precedent for test:all vs. a partial build.
+      @dependinator.flush( refresh_dependencies: files.nil? )
+      @plugin_manager.post_release_build( SystemWrapper.time_stopwatch_s() )
+    end
+  end
+
+end

data/lib/ceedling/release_invoker/release_invoker_types.rb

@@ -0,0 +1,40 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+module ReleaseInvokerTypes
+
+  # Carries all state for a single release build invocation. Unlike TestInvokerTypes'
+  # PipelineState/Testable pair, there's exactly one artifact here, not N independent
+  # ones, so this one struct holds both the flat build plan and the shared,
+  # once-resolved compile/link inputs every object uses alike.
+  ReleaseState = Struct.new(
+    :objects,           # Array<String> — object filepaths to compile/link; each
+                         # object's real source is resolved at compile time via
+                         # FileFinder, mirroring TestBuildExecutor#stage_build_objects
+    :compile_flags, :assemble_flags, :link_flags,
+    :defines,
+    :search_paths,
+    :executable_rebuilt, # Boolean — set by ReleaseBuildExecutor#link, read by
+                          # #artifactinate to decide whether to copy the artifact.
+                          # Carried here rather than re-querying the dependency
+                          # tracker: by then the executable has already been marked
+                          # fresh (if it was rebuilt), so a fresh staleness query
+                          # would always answer false regardless of what happened.
+    :lock,               # Mutex for thread-safe shared-counter writes
+    keyword_init: true
+  ) do
+    def initialize(**kwargs)
+      kwargs[:objects] ||= []
+      # Defaulted here, unlike PipelineState's explicit-at-call-site convention --
+      # ReleaseState has exactly one construction site, so there's no risk of a
+      # caller forgetting to supply it.
+      kwargs[:lock] ||= Mutex.new
+      super(**kwargs)
+    end
+  end unless const_defined?(:ReleaseState, false)
+
+end

data/lib/ceedling/reportinator.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'unicode/display_width'
+require 'ceedling/constants'
 
 ##
 # Pretifies reports
@@ -128,11 +129,26 @@ class Reportinator
     # Sanitze -- ensure it's a string and strip any filename extension
     _module_name = module_name.to_s().ext('')
 
-    # If filename is the module name, don't add the module label
-    label = (File.basename(filename).ext('') == _module_name) ? '' : "#{_module_name}::"
+    # If filename is the module name, don't add the module label. A module name
+    # mirroring its file's path below a configured root (e.g. `adc/TestFoo`) is
+    # still the same module as far as this comparison is concerned, so only its
+    # own last segment is weighed against filename's bare basename.
+    label = (File.basename(filename).ext('') == File.basename(_module_name)) ? '' : "#{_module_name}::"
     return generate_progress("#{operation} #{label}#{filename}")
   end
 
+  # States, in one line, how many targets a build step left untouched because
+  # nothing about them needed attention this run -- shared by every build stage
+  # that skips individual targets (test and release alike), so this wording and
+  # its singular/plural handling live in exactly one place. Returns nil when
+  # nothing was skipped, so a full rebuild's output isn't cluttered with zero
+  # counts; callers only log when a message comes back.
+  def generate_skip_summary(task:, count:, noun:, reason: "nothing changed")
+    return nil if count == 0
+    singular_noun = noun.sub(/s$/, '')
+    generate_progress( "Skipping #{task} for #{count} #{count == 1 ? singular_noun : noun} (#{reason})" )
+  end
+
   def generate_config_walk(keys, depth=0)
     # :key ↳ :key ↳ :key