ceedling 1.2.0 → 1.2.2

data/bin/launchinator.rb

@@ -0,0 +1,69 @@
+# =========================================================================
+#   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/exceptions'
+require 'ceedling/installation'
+require 'ceedling/handoff'
+
+# Runs each command in the installation it selects. Another installation's own launcher
+# replaces this process. The launcher's own installation continues here.
+class Launchinator
+
+  constructor :installation_selector, :loginator
+
+  # Selects which Ceedling runs a command and points app_cfg's paths at it, without handing off
+  def resolve(env:, app_cfg:, config: {}, detect_vendor: true)
+    return @installation_selector.select( env:env, config:config, app_cfg:app_cfg, detect_vendor:detect_vendor )
+  end
+
+  # Hands off to another selected installation and never returns. Otherwise returns the
+  # rakefile to load in this process. A process a launcher already handed off to says so
+  # and never hands off again.
+  def launch(env:, app_cfg:, config: {}, detect_vendor: true)
+    target = resolve( env:env, app_cfg:app_cfg, config:config, detect_vendor:detect_vendor )
+    return proceed( target:target, app_cfg:app_cfg )
+  end
+
+  # As #launch, for a target already selected through #resolve
+  def proceed(target:, app_cfg:)
+    launcher = Installation.new( app_cfg[:launcher_root_path] )
+
+    if Handoff.received?( app_cfg[:handoff], own:launcher )
+      @loginator.log( Handoff.received_message( app_cfg[:handoff], own:launcher ), Verbosity::COMPLAIN, LogLabels::NOTICE )
+    elsif target != launcher
+      hand_off( target, launcher, app_cfg[:argv] )
+    end
+
+    return target.rakefile_path
+  end
+
+  private
+
+  def hand_off(target, launcher, argv)
+    validate_runnable( target )
+
+    @loginator.log( Handoff.handing_off_message( launcher:launcher, target:target ), Verbosity::COMPLAIN, LogLabels::NOTICE )
+    Handoff.exec( target:target, launcher:launcher, argv:argv, loginator:@loginator )
+  end
+
+  # An installation that cannot run on its own would fail in a way that hides why
+  def validate_runnable(target)
+    if !File.exist?( target.bin_path )
+      raise CeedlingException.new( "Cannot hand off to #{target.describe()}: it has no launcher at #{target.bin_path}" )
+    end
+
+    return if !target.missing_builtin_mixins?
+
+    raise CeedlingException.new(
+      "#{target.describe()} cannot run on its own: it lacks #{Installation::BUILTIN_MIXINS_DIR}/, which `--local` " +
+      "vendoring left out from Ceedling 1.1.0 through 1.2.1. Re-vendor it with `ceedling upgrade <project path>`, " +
+      "then run this command again."
+    )
+  end
+
+end

data/bin/mixin_resolvinator.rb

@@ -22,26 +22,14 @@ class MixinResolvinator
     #  - Empty load paths
     return [], [] if _mixins.nil?
 
-    # Build list of load paths
     # Configured load paths are higher in search path ordering
     load_paths = _mixins[:load_paths] || []
+    enabled    = (_mixins[:enabled] || []).clone # A copy of the configuration section
 
-    # Get list of mixins
-    enabled = _mixins[:enabled] || []
-    enabled = enabled.clone # Ensure it's a copy of configuration section
-
-    # Handle any inline Ruby string expansion, then standardize Windows backslashes --
-    # cmdline and env var mixin paths already go through standardize_paths elsewhere,
-    # so config :mixins section paths need the same treatment for consistency.
-    load_paths.each do |load_path|
-      load_path.replace( @ruby_expandinator.expand( load_path, source: ":mixins ↳ :load_paths" ) )
-      load_path.replace( @path_validator.standardize_paths( load_path ).first )
-    end
-
-    enabled.each do |mixin|
-      mixin.replace( @ruby_expandinator.expand( mixin, source: ":mixins ↳ :enabled" ) )
-      mixin.replace( @path_validator.standardize_paths( mixin ).first )
-    end
+    # Command line and environment variable mixin paths are standardized elsewhere, so
+    # :mixins section paths are too, after any inline Ruby string expansion
+    prepare_in_place( load_paths, ":mixins ↳ :load_paths" )
+    prepare_in_place( enabled, ":mixins ↳ :enabled" )
 
     # Remove the :mixins section of the configuration
     config.delete( :mixins )
@@ -66,25 +54,7 @@ class MixinResolvinator
 
   # Validate mixins list
   def validate_mixins(mixins:, load_paths:, source:, yaml_extensions:)
-    validated = true
-
-    mixins.each do |mixin|
-      # Validate mixin filepaths
-      if @path_validator.filepath?( mixin )
-        if !@file_wrapper.exist?( mixin )
-          @loginator.log( "Cannot find mixin at #{mixin}", Verbosity::ERRORS )
-          validated = false
-        end
-
-      # Otherwise, validate that mixin name can be found in load paths
-      elsif mixin_filepath( mixin, load_paths, yaml_extensions ).nil?
-        filenames = yaml_extensions.map { |extension| "'#{mixin}#{extension}'" }.join( ' or ' )
-        @loginator.log( "#{source} '#{mixin}' cannot be found in mixin load paths as #{filenames}", Verbosity::ERRORS )
-        validated = false
-      end
-    end
-
-    return validated
+    return mixins.map { |mixin| mixin_found?( mixin, load_paths, source, yaml_extensions ) }.all?
   end
 
 
@@ -114,6 +84,26 @@ class MixinResolvinator
 
   private
 
+  # Expands and standardizes each of `paths`, keeping each String the configuration holds
+  def prepare_in_place(paths, source)
+    paths.each { |path| path.replace( @path_validator.standardize_paths( @ruby_expandinator.expand( path, source: source ) ).first ) }
+  end
+
+  # A mixin filepath must exist, and a mixin name must be found in the load paths
+  def mixin_found?(mixin, load_paths, source, yaml_extensions)
+    if @path_validator.filepath?( mixin )
+      return true if @file_wrapper.exist?( mixin )
+
+      @loginator.log( "Cannot find mixin at #{mixin}", Verbosity::ERRORS )
+      return false
+    end
+    return true unless mixin_filepath( mixin, load_paths, yaml_extensions ).nil?
+
+    filenames = yaml_extensions.map { |extension| "'#{mixin}#{extension}'" }.join( ' or ' )
+    @loginator.log( "#{source} '#{mixin}' cannot be found in mixin load paths as #{filenames}", Verbosity::ERRORS )
+    return false
+  end
+
   # The first existing file named for the mixin, searching each load path in turn for each
   # extension
   def mixin_filepath(mixin, load_paths, yaml_extensions)

data/bin/objects.yml

@@ -55,6 +55,19 @@ cli_handler:
     - path_validator
     - rake_task_registry
     - actionator
+    - launchinator
+    - loginator
+
+launchinator:
+  compose:
+    - installation_selector
+    - loginator
+
+installation_selector:
+  compose:
+    - file_wrapper
+    - config_walkinator
+    - path_validator
     - loginator
 
 cli_helper:

data/bin/path_validator.rb

@@ -5,44 +5,27 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+require 'ceedling/filesystem/project_paths'
+
 class PathValidator
 
   constructor :file_wrapper, :loginator
 
+  # Logs why each of `paths` fails as a `type` (:filepath or :directory), and whether none did
   def validate(paths:, source:, type: :filepath)
-    validated = true
-
-    paths.each do |path|
-      # Error out on empty paths
-      if path.empty?
-        validated = false
-        @loginator.log( "#{source} contains an empty path", Verbosity::ERRORS )
-        next
-      end
-
-      # Error out if path is not a directory / does not exist
-      if (type == :directory) and !@file_wrapper.directory?( path )
-        validated = false
-        @loginator.log( "#{source} '#{path}' does not exist as a directory in the filesystem", Verbosity::ERRORS )
-      end
-
-      # Error out if filepath does not exist
-      if (type == :filepath) and !@file_wrapper.exist?( path )
-        validated = false
-        @loginator.log( "#{source} '#{path}' does not exist in the filesystem", Verbosity::ERRORS )
-      end
-    end
+    problems = paths.filter_map { |path| path_problem( path, type ) }
+    problems.each { |problem| @loginator.log( "#{source} #{problem}", Verbosity::ERRORS ) }
 
-    return validated
+    return problems.empty?
   end
 
-  # Ensure any Windows backslashes are converted to Ruby path forward slashes.
-  # Returns new values in the same order as the arguments given, rather than
-  # mutating the caller's own String objects in place.
+  # Each path spelled as configuration spells it (ProjectPaths.standardize): forward slashes,
+  # `~` as the home directory, no trailing separator. Returns new values in the same order as
+  # the arguments given, rather than mutating the caller's own String objects in place.
   def standardize_paths( *paths )
     paths.map do |path|
-      next path if path.nil? or path.empty?
-      path.tr( "\\", '/' )
+      next path if path.nil? or path.strip.empty?
+      ProjectPaths.standardize( path )
     end
   end
 
@@ -52,4 +35,17 @@ class PathValidator
     return (!File.extname( str ).empty?) || (str.include?( File::SEPARATOR ))
   end
 
-end
+  ### Private ###
+
+  private
+
+  # Why `path` fails as a `type`, or nil
+  def path_problem(path, type)
+    return 'contains an empty path' if path.empty?
+    return "'#{path}' does not exist as a directory in the filesystem" if (type == :directory) and !@file_wrapper.directory?( path )
+    return "'#{path}' does not exist in the filesystem" if (type == :filepath) and !@file_wrapper.exist?( path )
+
+    return nil
+  end
+
+end

data/bin/versionator.rb

@@ -7,7 +7,7 @@
 
 require 'exceptions'
 require 'constants'  # Filename constants
-require 'version'    # Import Ceedling constant symbols from lib/version.rb
+require 'ceedling/installation'
 
 ## Definitions
 ##  TAG: <#.#.#> version string used to package the software bundle
@@ -15,66 +15,65 @@ require 'version'    # Import Ceedling constant symbols from lib/version.rb
 
 class Versionator
 
+  # Vendored framework headers and the prefix of their version macros
+  FRAMEWORK_HEADERS = {
+    'UNITY'      => File.join( 'unity', 'src', 'unity.h' ),
+    'CMOCK'      => File.join( 'cmock', 'src', 'cmock.h' ),
+    'CEXCEPTION' => File.join( 'c_exception', 'lib', 'CException.h' )
+  }.freeze
+
   attr_reader :ceedling_tag, :ceedling_build, :ceedling_install_path
   attr_reader :unity_tag, :cmock_tag, :cexception_tag
 
   def initialize(ceedling_root_path, ceedling_vendor_path=nil)
-
-    ##
-    ## Ceedling version info
-    ##
-
     @ceedling_install_path = ceedling_root_path.clone()
+    @ceedling_tag = read_tag( ceedling_root_path )
+    @ceedling_build = read_build( ceedling_root_path )
 
-    # Set Ceedling tag
-    @ceedling_tag = Ceedling::Version::TAG
+    # Framework versions are gathered only when asked for
+    read_framework_tags( ceedling_vendor_path ) unless ceedling_vendor_path.nil?
+  end
 
-    # Create Ceedling build string
-    # Lookup the Ceedling Git commit SHA if it exists as simple text file in the root of the codebase
-    ceedling_commit_sha_filepath = File.join( ceedling_root_path, GIT_COMMIT_SHA_FILENAME )
-    @ceedling_build = 
-      if File.exist?( ceedling_commit_sha_filepath )
-        # Ingest text from commit SHA file and clean it up
-        sha = File.read( ceedling_commit_sha_filepath ).strip()
-        # <TAG>-<SHA>
-        "#{@ceedling_tag}-#{sha}"
-      else
-        # <TAG>
-        @ceedling_tag
-      end
+  private
 
-    ##
-    ## Build frameworks version info
-    ##
+  # The tag comes from the installation's own lib/version.rb, never from a loaded constant
+  def read_tag(root_path)
+    installation = Installation.new( root_path )
+    tag = installation.version
+    return tag unless tag.nil?
 
-    # Do no framework version gathering if it's not asked for
-    return if ceedling_vendor_path.nil?
+    raise CeedlingException.new( "Could not read a Ceedling version from #{File.join( installation.root, Installation::VERSION_FILE )}" )
+  end
 
-    # Create _tag accessors in the Versionator object
+  # <TAG>-<SHA> when the installation carries a commit SHA file, otherwise <TAG>
+  def read_build(root_path)
+    sha_filepath = File.join( root_path, GIT_COMMIT_SHA_FILENAME )
+    return @ceedling_tag unless File.exist?( sha_filepath )
 
-    # Anonymous hash to iterate through complementary vendor projects
-    { 'UNITY'      => File.join( 'unity', 'src', 'unity.h' ),
-      'CMOCK'      => File.join( 'cmock', 'src', 'cmock.h' ),
-      'CEXCEPTION' => File.join( 'c_exception', 'lib', 'CException.h' )
-    }.each_pair do |name, path|
-      filename = File.join( ceedling_vendor_path, path )
+    return "#{@ceedling_tag}-#{File.read( sha_filepath ).strip()}"
+  end
 
-      # Actually look up the vendor project version number components
-      version = [0,0,0]
+  # Sets @unity_tag, @cmock_tag and @cexception_tag from each header's version macros
+  def read_framework_tags(vendor_path)
+    FRAMEWORK_HEADERS.each_pair do |name, path|
+      filepath = File.join( vendor_path, path )
+      instance_variable_set( "@#{name.downcase}_tag", read_framework_tag( name, filepath ) )
+    end
+  end
 
-      begin
-        File.readlines( filename ).each do |line|
-          ['VERSION_MAJOR', 'VERSION_MINOR', 'VERSION_BUILD'].each_with_index do |field, i|
-            m = line.match(/#{name}_#{field}\s+(\d+)/)
-            version[i] = m[1] unless (m.nil?)
-          end
-        end
-      rescue
-        raise CeedlingException.new( "Could not collect version information for vendor component ⏩️ #{filename}" )
-      end
+  def read_framework_tag(name, filepath)
+    lines = File.readlines( filepath )
+  rescue StandardError
+    raise CeedlingException.new( "Could not collect version information for vendor component ⏩️ #{filepath}" )
+  else
+    return framework_version( name, lines )
+  end
 
-      # Set the version tag accessor directly instead of building and evaling a string
-      instance_variable_set("@#{name.downcase}_tag", version.join('.'))
-    end
+  # MAJOR.MINOR.BUILD from the header's last definition of each macro, 0 for any missing
+  def framework_version(name, lines)
+    return ['VERSION_MAJOR', 'VERSION_MINOR', 'VERSION_BUILD'].map do |field|
+      matches = lines.filter_map { |line| line.match( /#{name}_#{field}\s+(\d+)/ ) }
+      matches.empty? ? '0' : matches.last[1]
+    end.join( '.' )
   end
 end

data/ceedling.gemspec

@@ -80,27 +80,31 @@ Ceedling projects start with a YAML configuration file. A variety of conventions
   s.files        += Dir['vendor/unity/auto/**/*.rb']
   s.files        += Dir['vendor/unity/src/**/*.[ch]']
 
-  s.files        += Dir['**/*']
-  # Dir['**/*'] above sweeps the working tree, so anything a local run leaves behind
-  # would otherwise be packaged into a release.
+  # The working tree, less the top-level directories never packaged. The walk never
+  # descends into them: Bundler evaluates this file on every `bundle exec`, and a
+  # retained system test project below specout/ can nest past Windows' path limit,
+  # which makes the glob itself raise. A retained project also nests a vendored Ceedling
+  # deep enough to exceed the tar name limit (Gem::Package::TooLongFileName).
   #
-  # System test artifacts are the worst of it. `rake spec:system:debug:*` retains whole
-  # deployed projects under specout/, which both bloats the gem and breaks packaging
-  # outright, since a retained project nests a vendored Ceedling deep enough to exceed
-  # the tar name limit (Gem::Package::TooLongFileName).
+  #   build     Local build output
+  #   site-web  Hosted/versioned docs site -- not needed offline
+  #   specout   Retained system test artifacts and run logs
+  #   tools     Dev tooling the Rakefile above shells out to
+  unpackaged = %w[build site-web specout tools]
+  s.files += Dir['*'].reject { |entry| unpackaged.include?( entry ) }.flat_map { |entry| [entry, *Dir["#{entry}/**/*"]] }
+
+  # The walk above still sweeps the rest of the working tree, so anything a local run
+  # leaves behind there would otherwise be packaged into a release.
   #
-  # Build output matters for a second reason. Running the examples or the plugin example
-  # projects locally fills their build/ directories with object files and executables,
-  # and shipping compiled binaries in a release gem is exactly what trips the security
+  # Build output matters most. Running the examples or the plugin example projects
+  # locally fills their build/ directories with object files and executables, and
+  # shipping compiled binaries in a release gem is exactly what trips the security
   # scanners described in docs/SECURITY.md. `build` is matched as a whole path segment
   # on purpose: each vendored submodule ships a `meson.build` file, and a substring test
   # would silently drop all three.
   s.files.reject! do |f|
-    f.start_with?('site-web/') ||                        # Hosted/versioned docs site -- not needed offline
-    f == 'tools' || f.start_with?('tools/') ||            # Dev tooling the Rakefile above shells out to
     f == 'docs/mkdocs' || f.start_with?('docs/mkdocs/') ||  # Raw docs source -- site-local/ is the built artifact the gem actually serves
-    f == 'specout' || f.start_with?('specout/') ||        # Retained system test artifacts and run logs
-    f == 'build' || f.start_with?('build/') || f.include?('/build/') ||  # Local build output
+    f.include?('/build/') ||                              # Local build output
     f.match?(/\.(cdx|spdx)\.json\z/) ||                   # Generated SBOMs -- release assets, not gem contents
     # Upstream fff's own test apparatus. Ceedling needs fff.h from this tree and
     # nothing else, and these three directories are 1.2 MB that no Ceedling code path
@@ -118,7 +122,7 @@ Ceedling projects start with a YAML configuration file. A variety of conventions
     f == 'plugins/fff/vendor/fff/buildandtest'
   end
 
-  # Dir['**/*'] cannot see dotfiles, and a few are required for the spec suites that
+  # The walk above cannot see dotfiles, and a few are required for the spec suites that
   # ship with this gem to run at all. Those suites exist to support certification
   # self-testing, driven by separate tooling against the versioned gem, which is also
   # why spec/, Gemfile, and Gemfile.lock are packaged rather than trimmed out.

data/docs/BreakingChanges.md

@@ -6,9 +6,78 @@ These breaking changes are complemented by three other documents:
 1. 🪵 **[Changelog](Changelog.md)** for a structured list of additions, fixes, changes, and removals.
 1. 🐛 **[Known Issues](KnownIssues.md)** for a list of presently known problems and limitations.
 
+A release has a section only if it breaks something. Each section lists what changed in that release alone, so upgrading across several releases means reading each section between them.
+
+---
+
+# [1.2.2] — 2026-10-31
+
+## Test build output is organized by each test’s path from the project root
+
+A test’s build output, results, and logs are organized by its name, and a test is now named by its path from the project root without its extension. Before 1.2.2, the name was its path below its test root, so two tests could mistakenly share one. `test/unit/test_calc.c` was named `unit/test_calc` and is now `test/unit/test_calc`. A test directly in its root gains a directory: `test/test_calc.c` logs to `build/artifacts/valgrind/test/test_calc.log`, not `build/artifacts/valgrind/test_calc.log`.
+
+Update anything that reads per-test output by path:
+
+1. Scripts that collect Valgrind, sanitizer, raw output, or gdb backtrace logs. A glob such as `build/artifacts/valgrind/*.log` no longer reaches them; use `build/artifacts/valgrind/**/*.log`.
+1. Tools that read results, runners, or objects from `build/test/` directly.
+1. TeamCity suite names, which now carry the same path (e.g. `test/TestUsartModel`).
+
+The first build after upgrading rebuilds everything once. Run `ceedling clobber` to remove the output left in the old layout. Until then, any coverage reports also read the old coverage data.
+
+## Build files are placed by each source’s path from the project root
+
+An object, preprocessed file, or dependencies file now sits below its build directory at its source’s path from the project root. Before 1.2.2, it sat at the source’s path below its `:paths` root, or flat. In a test, `src/drivers/uart.c` builds to `build/test/out/<test name>/src/drivers/uart.o`, not `build/test/out/<test name>/drivers/uart.o`. A release builds it to `build/release/out/src/drivers/uart.o`. Each `..` in a path outside the project becomes `_up_`, and a file of the running Ceedling installation outside the project sits below `_ceedling_`. Mocks, runners, and vendored framework objects keep their places.
+
+The first build after upgrading recompiles each moved object once. Run `ceedling clobber` to remove objects left in the old layout. Until then, coverage reports also include the old coverage data.
+
+## A `-:` `:paths` entry removes the directories below it
+
+A `-:` entry in `:paths` used to remove only the directory it named. It now also removes every directory below that directory. An additive entry naming one of those directories more closely keeps it, as `+:src/legacy/keep` does beside `-:src/legacy`. A project that relied on subdirectories surviving a `-:` entry must name them in entries of their own.
+
+## A build root holding the project is refused
+
+`:project` ↳ `:build_root` can no longer be empty, the project directory, or a directory above it. `clobber` empties the build root’s test and release trees, so with `:build_root: .` it deleted the project’s own `test/` directory. Configuration now stops with an error naming the problem.
+
+A `:paths` or `:files` entry within the build root, such as one naming generated code in `build/gen`, still collects from it, with a warning. No entry collects from the directories Ceedling and its plugins create, such as `test/`, `release/`, `vendor/`, and `artifacts/` below the build root, or the mocks directory. A project that named one of them in `:paths` or `:files` loses those files from its collections.
+
+## `-L` arguments name the directories `:paths` ↳ `:libraries` collects
+
+Linker `-L` arguments used to repeat `:paths` ↳ `:libraries` entries exactly as written. They now name the directories those entries collect, as any `:paths` entry does. A glob names each directory it matches, a `-:` entry removes directories, and an entry that collects no existing directory adds no argument.
+
+## `TEST_SOURCE_FILE()` entries are checked without test preprocessing
+
+With `:project` ↳ `:use_test_preprocessor` set to `:none` or `:mocks`, a `TEST_SOURCE_FILE()` entry naming a file that doesn’t exist, or that isn’t a source file, was previously silently dropped. A build now stops with an error naming the entry and its test file, as it already did with test preprocessing.
+
+Without test preprocessing, Ceedling reads these entries as text and does not evaluate `#if`. An entry inside an `#if` branch that is off is checked too, so it must name a real file.
+
+## A project that selects another installation runs entirely in it
+
+A project can select another Ceedling installation through `:project` ↳ `:which_ceedling`, the `WHICH_CEEDLING` environment variable, or a `vendor/ceedling/` copy. Before 1.2.2, the `ceedling` command you ran parsed the command line and loaded that installation’s application into its own process. Now that installation’s own launcher runs the command, in a new process.
+
+1. The selected installation parses the command line itself. An older one rejects commands and options added after its release.
+1. `new`, `example`, `examples`, `docs`, and `help` run in the installation `WHICH_CEEDLING` or a `vendor/ceedling/` copy selects, not in the `ceedling` command you ran. A `--local` copy carries no documentation bundle, so `docs` exports the documentation of the `ceedling` command you ran instead, with a notice.
+1. Both sides of a hand-off log a notice at warning verbosity. It names both installations and their versions.
+1. A project vendored by Ceedling 1.1.0 through 1.2.1 lacks Unity’s built-in mixins, so its copy cannot run on its own. The `ceedling` command you run stops with advice to re-vendor it with `ceedling upgrade`.
+
+## `upgrade` no longer finds its source in `vendor/ceedling/`
+
+`ceedling upgrade PATH` copies the Ceedling you run or the installation `WHICH_CEEDLING` names into the project at `PATH`. It no longer selects a `vendor/ceedling/` directory it finds in the working directory, which inside a `--local` project was the very copy it was replacing.
+
+## `version` reads your project file
+
+`ceedling version` reads your project file when one is available, as `build` does, and reports the installation the project selects. For a project that selects another installation, it lists `Ceedling Launcher =>` and `Ceedling App =>` instead of a single `Ceedling =>` line. A tool that parses `version` for the project’s Ceedling should read `Ceedling App =>` when present.
+
+## Impacts on third-party plugins by file and path code moved to `lib/ceedling/filesystem/`
+
+Ceedling plugin development currently makes no guarantees about the location and interface of internal Ceedling resources. And, it is unlikely that custom plugins would rely on the reorganized filesystem handling code to begin with.
+
+Ceedling’s file and path code now sits in `lib/ceedling/filesystem/`. A plugin that requires one of these files directly must name its new path, such as `require 'ceedling/filesystem/file_path_utils'` in place of `require 'ceedling/file_path_utils'`. A require of an old path fails with a `LoadError`. Where an older Ceedling gem is installed, Ruby can instead load that gem’s copy of the file, and the build fails with an unrelated error such as `wrong number of arguments`. Plugins that reach these objects through `@ceedling[:file_wrapper]` and the like need no change. A plugin that names the new paths no longer loads in Ceedling 1.2.1 or earlier.
+
+The moved files are `project_paths`, `build_subpath`, `path_spellings`, `path_exclusions`, `path_mirror`, `path_matcher`, `destination_collision`, `file_path_utils`, `file_path_collection_utils`, `file_finder`, `file_finder_helper`, `file_wrapper`, and `file_system_wrapper`.
+
 ---
 
-# [1.2.0] — Prerelease
+# [1.2.0] — 2026-10-21
 
 ## Mocks included through a folder are named by that folder