ceedling 1.2.0 → 1.2.2

data/lib/ceedling/release_invoker/release_build_executor.rb

@@ -6,6 +6,7 @@
 # =========================================================================
 
 require 'ceedling/constants'
+require 'ceedling/filename_extension'
 require 'ceedling/release_invoker/release_invoker_types'
 
 # Does the actual work of a release build: compiling objects, linking the
@@ -24,7 +25,8 @@ class ReleaseBuildExecutor
     :file_finder,
     :file_wrapper,
     :file_path_utils,
-    :dependinator
+    :dependinator,
+    :library_resolver
   )
 
   def compile_objects(state)
@@ -44,17 +46,22 @@ class ReleaseBuildExecutor
   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()
+    lib_paths = @library_resolver.search_path_arguments()
+    library_files = @library_resolver.link_files( release_library_entries( libraries ) )
     target    = @configurator.project_release_build_target
 
+    # As with a test link, the object and library lists as meta relink an artifact that a
+    # dropped source or library would otherwise leave holding its code
     @dependinator.register(
       target,
-      files: objects,
-      meta:  { flags: state.link_flags, lib_args: lib_args, lib_paths: lib_paths, tools: [@configurator.tools_release_linker] }
+      files: objects + library_files,
+      meta:  { flags: state.link_flags, lib_args: lib_args, lib_paths: lib_paths, tools: [@configurator.tools_release_linker], objects: objects, libraries: library_files }
     )
     stale = @dependinator.stale?( target )
 
     if stale
+      # A target named by an absolute :output may sit in a directory no build made
+      @file_wrapper.mkdir( File.dirname( target ) )
       @generator.generate_executable_file(
         @configurator.tools_release_linker,
         RELEASE_SYM,
@@ -192,13 +199,7 @@ class ReleaseBuildExecutor
   end
 
   def convert_libraries_to_arguments(libraries)
-    args =
-      (libraries || []) +
-      ((defined? LIBRARIES_SYSTEM) ? LIBRARIES_SYSTEM : []) +
-      ((defined? LIBRARIES_RELEASE) ? LIBRARIES_RELEASE : [])
-
-    args.flatten!
-    args.compact!
+    args = release_library_entries( libraries )
 
     if (defined? LIBRARIES_FLAG)
       args.map! { |v| LIBRARIES_FLAG.gsub(/\$\{1\}/, v) }
@@ -207,12 +208,15 @@ class ReleaseBuildExecutor
     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
+  # The :libraries entries a release links, whatever form each takes, beside the library
+  # files its object list names
+  def release_library_entries(libraries)
+    entries =
+      (libraries || []) +
+      ((defined? LIBRARIES_SYSTEM) ? LIBRARIES_SYSTEM : []) +
+      ((defined? LIBRARIES_RELEASE) ? LIBRARIES_RELEASE : [])
+
+    return entries.flatten.compact
   end
 
   # A release's object list can include precompiled libraries/archives
@@ -221,35 +225,20 @@ class ReleaseBuildExecutor
   # 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}$/
+    library_pattern = /.+#{library_endings()}$/
     sorted_objects = both.group_by { |v| v.match?( library_pattern ) ? :libraries : :objects }
-    libraries = sorted_objects[:libraries] || []
-    objects   = sorted_objects[:objects]   || []
-    return objects, libraries
+    return (sorted_objects[:objects] || []), (sorted_objects[:libraries] || [])
+  end
+
+  # A library type may be named by several extensions at once (.a and .so, say), and a
+  # subproject's by its own
+  def library_endings
+    endings = []
+    endings << FilenameExtension.new( EXTENSION_SUBPROJECTS ).pattern if defined? EXTENSION_SUBPROJECTS
+    endings << FilenameExtension.new( EXTENSION_LIBRARIES ).pattern if defined? EXTENSION_LIBRARIES
+    endings << Regexp.escape( '.LIBRARY' ) if endings.empty?
+    return "(?:#{endings.join( '|' )})"
   end
 
   # States, in one line, how many targets a build step left untouched because nothing

data/lib/ceedling/release_invoker/release_build_planner.rb

@@ -34,15 +34,16 @@ class ReleaseBuildPlanner
   def plan(state, files: nil)
     tailor_release_tools()
 
-    sources =
+    # A link-only name is no source of its own. Placed apart from the sources, one naming
+    # the object a source builds to joins it rather than colliding with it.
+    sources, link_only =
       if files.nil?
-        @configurator.collection_release_build_input +
-          @configurator.collection_release_artifact_extra_link_objects
+        [@configurator.collection_release_build_input, @configurator.collection_release_artifact_extra_link_objects]
       else
-        files.dup
+        [files.dup, []]
       end
 
-    state.objects        = @file_path_utils.form_release_build_objects_filelist( sources )
+    state.objects        = release_objects( sources, link_only )
     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 )
@@ -52,6 +53,13 @@ class ReleaseBuildPlanner
 
   private
 
+  def release_objects(sources, link_only)
+    objects = @file_path_utils.form_release_build_objects_filelist( sources ).to_a
+    return objects if link_only.empty?
+
+    return (objects + @file_path_utils.form_release_build_objects_filelist( link_only ).to_a).uniq
+  end
+
   # 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
@@ -73,7 +81,7 @@ class ReleaseBuildPlanner
     when '.a'
       compiler[:arguments] << '-fPIC' unless compiler[:arguments].include?('-fPIC')
       linker[:executable] = 'ar'
-      linker[:arguments]  = ['rcs', '${2}', '${1}']
+      linker[:arguments]  = ['rcs', '"${2}"', '"${1}"']
     end
   end
 

data/lib/ceedling/reportinator.rb

@@ -129,10 +129,9 @@ 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. 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.
+    # If filename is the module name, don't add the module label. A test's name is
+    # its path from the project root (e.g. `test/adc/TestFoo`), so only its 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

data/lib/ceedling/setupinator.rb

@@ -7,6 +7,29 @@
 
 class Setupinator
 
+  # Configurator steps that fill out the configuration from user configuration and defaults,
+  # in the order they run:
+  #  - Unity and CMock values that tie vendor tool configurations together
+  #  - The Partials configuration reference for dependency-tracker meta
+  #  - Test runner generation settings
+  #  - Exceptions, enabled automagically by CMock settings
+  #  - Environment variables again, before configuration that may reference them by inline
+  #    Ruby string expansion
+  #  - Paths, flags, and defines expanded, then paths standardized
+  #  - Unity helpers, included in mocks by their standardized filenames
+  COMPLETION_STEPS = %i[populate_unity_config populate_cmock_config populate_partials_config populate_test_runner_generation_config
+    populate_exceptions_config eval_environment_variables eval_paths eval_flags eval_defines standardize_paths populate_cmock_helpers].freeze
+
+  # Configurator settings taken from the command line, each by its application
+  # configuration key: test case filters, whether the requested tasks build tests or a
+  # release (which decides what build/vendor needs), and forced test re-execution
+  COMMAND_LINE_SETTINGS = { include_test_case: :include_test_case, exclude_test_case: :exclude_test_case,
+    test_build_tasks: :test_build_tasks?, release_build_tasks: :release_build_tasks?, force_test_rerun: :force_test_rerun }.freeze
+
+  # The application objects setup uses, taken from the object hash rather than a DIY
+  # constructor, which validates aspects of setup
+  COLLABORATORS = %i[configurator loginator reportinator plugin_manager plugin_reportinator test_runner_manager].freeze
+
   attr_reader :config_hash
 
   def setup
@@ -26,32 +49,40 @@ class Setupinator
   def ceedling=(value)
     # Capture application objects hash as instance variable
     @ceedling = value
-
-    # Get our dependencies from object hash rather than DIY constructor
-    # This is a shortcut / validates aspects of our setup
-    @configurator         = value[:configurator]
-    @loginator            = value[:loginator]
-    @reportinator         = value[:reportinator]
-    @plugin_manager       = value[:plugin_manager]
-    @plugin_reportinator  = value[:plugin_reportinator]
-    @test_runner_manager  = value[:test_runner_manager]
+    COLLABORATORS.each { |name| instance_variable_set( "@#{name}", value[name] ) }
   end
 
 
   # Load up all the constants and accessors our rake files, objects, & external scripts will need.
+  # Each numbered step's order matters.
   def do_setup( app_cfg )
     @config_hash = app_cfg[:project_config]
 
-    ##
-    ## 1. Miscellaneous handling and essential configuration prep
-    ##
+    apply_command_line( app_cfg )                                      # 1.
+    prepare_essential_configuration()                                  # 1.
+    plugins_paths_hash = handle_base_configuration( app_cfg )          # 2.
+    handle_plugins( plugins_paths_hash )                               # 3.
+    assemble_defaults( plugins_paths_hash )                            # 4.
+    complete_configuration( app_cfg )                                  # 5.
+    validate_final_configuration()                                     # 6.
+
+    # 7. Partially flatten config + build Configurator accessors and globals
+    @configurator.build( app_cfg[:ceedling_lib_path], app_cfg[:logging_path], config_hash, :environment )
+
+    load_plugins()                                                     # 8.
+  end
+
+
+### Private
+
+private
 
-    # Set special purpose test case filters (from command line)
-    @configurator.include_test_case = app_cfg[:include_test_case]
-    @configurator.exclude_test_case = app_cfg[:exclude_test_case]
+  ##
+  ## 1. Miscellaneous handling and essential configuration prep
+  ##
 
-    # Set special purpose forced test re-execution (from command line)
-    @configurator.force_test_rerun = app_cfg[:force_test_rerun]
+  def apply_command_line(app_cfg)
+    COMMAND_LINE_SETTINGS.each { |setting, key| @configurator.public_send( "#{setting}=", app_cfg[key] ) }
 
     # Verbosity handling
     @configurator.set_verbosity()
@@ -59,7 +90,9 @@ class Setupinator
     # Logging configuration
     @loginator.set_logfile( app_cfg[:log_filepath] )
     @configurator.project_logging = @loginator.project_logging
+  end
 
+  def prepare_essential_configuration
     log_step( 'Validating configuration contains minimum required sections', heading: false )
 
     # Complain early about anything essential that's missing
@@ -68,39 +101,44 @@ class Setupinator
     # Merge any needed runtime settings into user configuration
     @configurator.merge_ceedling_runtime_config( config_hash, CEEDLING_RUNTIME_CONFIG.deep_clone )
 
-    if config_hash[:project][:use_partials]
-      log_step( 'Processing Partials configuration', heading: false, verbosity: Verbosity::NORMAL )
-      # Set configuration settings derived from enabling partials
-      @configurator.set_partials_derived_config( config_hash )
-    end
+    return unless config_hash[:project][:use_partials]
+
+    log_step( 'Processing Partials configuration', heading: false, verbosity: Verbosity::NORMAL )
+    # Set configuration settings derived from enabling partials
+    @configurator.set_partials_derived_config( config_hash )
+  end
 
-    ##
-    ## 2. Handle basic configuration
-    ##
+  ##
+  ## 2. Handle basic configuration
+  ##
 
+  def handle_base_configuration(app_cfg)
     log_step( 'Base configuration handling', heading: false )
 
     # Evaluate environment vars before plugin configurations that might reference with inline Ruby string expansion
     @configurator.eval_environment_variables( config_hash )
 
     # Standardize paths and add to Ruby load paths
-    plugins_paths_hash = @configurator.prepare_plugins_load_paths( app_cfg[:ceedling_plugins_path], config_hash )
+    return @configurator.prepare_plugins_load_paths( app_cfg[:ceedling_plugins_path], config_hash )
+  end
 
-    ##
-    ## 3. Plugin Handling
-    ##
+  ##
+  ## 3. Plugin Handling
+  ##
 
+  def handle_plugins(plugins_paths_hash)
     log_step( 'Plugin Handling' )
 
-    # Plugin handling
     @configurator.discover_plugins( plugins_paths_hash, config_hash )
     @configurator.merge_config_plugins( config_hash )
     @configurator.populate_plugins_config( plugins_paths_hash, config_hash )
+  end
 
-    ##
-    ## 4. Collect and apply defaults to user configuration
-    ##
+  ##
+  ## 4. Collect and apply defaults to user configuration
+  ##
 
+  def assemble_defaults(plugins_paths_hash)
     log_step( 'Assembling Default Settings' )
 
     # Assemble defaults
@@ -111,37 +149,20 @@ class Setupinator
 
     # Set any missing essential or plugin values in configuration with assembled default values
     @configurator.populate_with_defaults( config_hash, defaults_hash )
+  end
 
-    ##
-    ## 5. Fill out / modify remaining configuration from user configuration + defaults
-    ##
+  ##
+  ## 5. Fill out / modify remaining configuration from user configuration + defaults
+  ##
 
+  def complete_configuration(app_cfg)
     log_step( 'Completing Project Configuration' )
 
-    # Populate Unity configuration with values to tie vendor tool configurations together
-    @configurator.populate_unity_config( config_hash )
-
-    # Populate CMock configuration with values to tie vendor tool configurations together
-    @configurator.populate_cmock_config( config_hash )
-
-    # Populate Partials configuration reference for dependency-tracker meta
-    @configurator.populate_partials_config( config_hash )
-
-    # Configure test runner generation
-    @configurator.populate_test_runner_generation_config( config_hash )
-
-    # Automagically enable use of exceptions based on CMock settings
-    @configurator.populate_exceptions_config( config_hash )
-
-    # Evaluate environment vars again before subsequent configurations that might reference with inline Ruby string expansion
-    @configurator.eval_environment_variables( config_hash )
-
-    # Standardize values and expand inline Ruby string substitutions
-    @configurator.eval_paths( config_hash )
-    @configurator.eval_flags( config_hash )
-    @configurator.eval_defines( config_hash )
-    @configurator.standardize_paths( config_hash )
+    COMPLETION_STEPS.each { |step| @configurator.public_send( step, config_hash ) }
+    complete_tools_and_runners( app_cfg )
+  end
 
+  def complete_tools_and_runners(app_cfg)
     # Fill out any missing tool config value
     @configurator.populate_tools_config( config_hash )
 
@@ -159,57 +180,44 @@ class Setupinator
     # Configure test runner build & runtime options
     @test_runner_manager.configure_build_options( config_hash )
     @test_runner_manager.configure_runtime_options( app_cfg[:include_test_case], app_cfg[:exclude_test_case] )
+  end
 
-    ##
-    ## 6. Validate configuration
-    ##
+  ##
+  ## 6. Validate configuration
+  ##
 
+  def validate_final_configuration
     log_step( 'Validating final project configuration', heading: false )
 
     @configurator.validate_final( config_hash )
+  end
 
-    ##
-    ## 7. Flatten configuration + process it into globals and accessors
-    ##
-
-    # Skip logging this step as the end user doesn't care about this internal preparation
-
-    # Partially flatten config + build Configurator accessors and globals
-    @configurator.build( app_cfg[:ceedling_lib_path], app_cfg[:logging_path], config_hash, :environment )
-
-    ##
-    ## 8. Final plugins handling
-    ##
+  ##
+  ## 8. Final plugins handling
+  ##
 
+  def load_plugins
     # Detailed logging already happend for plugin processing
     log_step( 'Loading Plugins' )
 
     @configurator.insert_rake_plugins( @configurator.rake_plugins )
-    
+
     # Merge in any environment variables that plugins specify after the main build
     @plugin_manager.load_programmatic_plugins( @configurator.programmatic_plugins, @ceedling ) do |env|
       # Evaluate environment vars that plugins may have added
       @configurator.eval_environment_variables( env )
       @configurator.build_supplement( config_hash, env )
     end
-    
+
     # Inject dependencies for plugin needs
     @plugin_reportinator.set_system_objects( @ceedling )
   end
 
-
-### Private
-
-private
-
   # Neaten up a build step with progress message and some scope encapsulation
   def log_step(msg, heading: true, verbosity: Verbosity::OBNOXIOUS )
-    @loginator.lazy( verbosity ) do 
-      if heading
-        @reportinator.generate_heading( @loginator.decorate( msg, LogLabels::CONSTRUCT ) )
-      else # Progress message
-        "\n" + @reportinator.generate_progress( @loginator.decorate( msg, LogLabels::CONSTRUCT ) )
-      end
+    @loginator.lazy( verbosity ) do
+      decorated = @loginator.decorate( msg, LogLabels::CONSTRUCT )
+      heading ? @reportinator.generate_heading( decorated ) : "\n" + @reportinator.generate_progress( decorated )
     end
   end
 

data/lib/ceedling/test_context_extractor.rb

@@ -7,9 +7,10 @@
 
 require 'ceedling/exceptions'
 require 'ceedling/partials/partials'
-require 'ceedling/file_path_utils'
+require 'ceedling/filesystem/file_path_utils'
 require 'ceedling/generators/generator_test_runner' # From lib/ not vendor/unity/auto
 require 'ceedling/encodinator'
+require 'ceedling/filesystem/project_paths'
 
 class TestContextExtractor
 
@@ -304,9 +305,12 @@ class TestContextExtractor
     end
   end
 
+  # Each path is recorded in the one spelling collections use, so its headers are never
+  # collected a second time under another
   def ingest_build_directive_include_paths(filepath, include_paths)
     return if include_paths.empty?
 
+    include_paths = include_paths.map { |path| ProjectPaths.canonical( path ) }
     key = form_file_key( filepath )
 
     @lock.synchronize do

data/lib/ceedling/test_invoker/PIPELINE.md

@@ -23,14 +23,14 @@ The seven stage classes never call each other. `TestPipelineManager` alone seque
 Three collaborators hold logic more than one stage needs, so the stages cannot drift apart:
 
 - **`TestSearchPaths`** composes a test's search paths in the order the compiler searches them, and sets a test's mock search paths (stages 2, 3, and 4).
-- **`MockLocator`** resolves a mock's real header and the directory mirroring it below the test's mock root (stages 2, 4, and 5).
+- **`MockLocator`** resolves a mock's real header and places the mock: its directory below the test's mock root, the folder and root CMock writes it by, and the directory its `#include` as written reaches it from (stages 2, 4, 5, and 10).
 - **`StandinHeaderinator`** places stand-in headers for mocks and Partials (stage 4).
 
 ## `PipelineState` and `Testable`
 
 `PipelineState` exists once for the whole run, and a `Testable` exists once per test file. Between them they hold everything a stage reads or writes:
 
-- **Identity**: a `Testable`'s `filepath` and `name`, set in the first stage and never changed.
+- **Identity**: a `Testable`'s `filepath` and `name`, set in the first stage and never changed. The name is the test's path from the project root without its extension (`FilePathUtils#form_test_name`), unique in every build, and it keys `PipelineState#testables` and places every per-test directory. A path outside the project writes each `..` as `_up_`, so no name reaches outside the build directory. `FileFinder` maps a name back to its test file exactly, never by search.
 - **Paths and preprocessing scratch state**: where this test's build output, mocks, Partials, and preprocessed files live, and the bookkeeping preprocessing needs along the way. These stay plain Hashes because their keys are sparse and conditional. A project with mocking disabled has no `:mocks` path at all, which a Hash tolerates better than a struct field with no meaningful default.
 - **Flags, defines, and search paths**: the compiler, linker, and preprocessor arguments resolved once per test and reused by every stage that runs a tool. `mock_search_paths` holds the part of `search_paths` that points at this test's mirrored mock directories (see [Mock search paths](#mock-search-paths)), so a stage can take them back out when it needs the ordering without them.
 - **Generated-content records**: `runner` (a `RunnerInfo`), each resolved mock in `mocks` (a `MockDetails`), and `partials` (a `TestablePartials`, holding a config map and the two lists of module names Partials generation has produced so far). These have a fixed shape every instance shares, which is what a struct is for: a mistyped field name fails loudly instead of silently doing nothing.
@@ -55,8 +55,8 @@ Stages 2 and 3 run before stage 4, so anything they derive from the `#include`s
 
 **Context collection (stages 1-4)** finds out what a test needs, without generating or compiling anything.
 
-- **Stage 1** creates each test's build directories and its `Testable`.
-- **Stage 2** scans the test file as text: its `#include`s, its include path build directives (cached between runs), and its Partials configuration. With test preprocessing off, it also scans `TEST_SOURCE_FILE()` directives and test case names, since nothing later will. It checks that the test uses mocks or Partials only where the project enables them, and it collects the test's first mock search paths from the text-scan list.
+- **Stage 1** names each test, creates its build directories, and creates its `Testable`. It first stops a build that includes a test whose name another test maps onto, which only two paths differing in extension alone, or a path outside the project mapping onto a real `_up_` or `_abs_` directory, can cause.
+- **Stage 2** scans the test file as text: its `#include`s, its include path build directives (cached between runs), and its Partials configuration. With test preprocessing off, it also scans `TEST_SOURCE_FILE()` directives and test case names, since nothing later will, and checks this test's `TEST_SOURCE_FILE()` entries. It checks that the test uses mocks or Partials only where the project enables them, and it collects the test's first mock search paths from the text-scan list.
 - **Stage 3** resolves the flags, defines, and search paths every later tool call for this test uses.
 - **Stage 4** runs only with test preprocessing on. It extracts the test file's `#include`s through the real preprocessor in three passes, described below, ends by replacing the text-scan list with the reconciled one, and narrows the mock search paths to the mocks that remain.
 
@@ -66,9 +66,9 @@ Stages 2 and 3 run before stage 4, so anything they derive from the `#include`s
 
 **Mocks (stages 9-10)** run only when the project uses mocks and this run has any. A transform flattens every test's planned mocks into one list, as the Partials transform does. Stage 9, with mock preprocessing on (`:mocks` or `:all`), preprocesses each header to be mocked. Stage 10 generates each mock's source and header with CMock, into a directory that mirrors its real header's location below the test's mock root. The `:mocking` stop point ends the run here.
 
-Two same-named headers mocked by directory stay distinct through `:cmock` ↳ `:mock_name_include_folder`, on by default. CMock names a mock's include guard and lifecycle functions by the folder its `#include` names, and the runner names its calls by the same `#include`, so the two always agree. `TestBuildExecutor#mock_folder_and_path` hands CMock that folder. When the folder ends the mirrored directory, the mock stays there. An `#include` spelling more path than the mirror holds puts its mock at the written path below the test's mock root instead, which the root search path still reaches.
+Two same-named headers mocked by directory stay distinct through `:cmock` ↳ `:mock_name_include_folder`, on by default. CMock names a mock's include guard and lifecycle functions by the folder its `#include` names, and the runner names its calls by the same `#include`, so the two always agree. `MockLocator#placement` decides where each mock goes, and generation, the planner's mock sources, the stand-ins, and the mock search paths all use it. When the folder ends the header's mirrored subdirectory, the mock stays in the mirrored directory. An `#include` spelling more path than the mirror holds puts its mock at the written path below the test's mock root instead, and one climbing with `..` stays below the mock root with an `_up_` directory for each `..`. The directory the `#include` as written reaches the mock from joins the mock search paths.
 
-**Test file preprocessing and runners (stages 11-13)** work on the test file itself. Stages 11 and 12 run only with test preprocessing on. Stage 11 preprocesses the test file and extracts its `TEST_SOURCE_FILE()` directives from the result. Stage 12 parses test case names from that output. Stage 13 always runs and generates the Unity test runner, from the preprocessed test file when there is one and the original otherwise. The `:test_runner` stop point ends the run here.
+**Test file preprocessing and runners (stages 11-13)** work on the test file itself. Stages 11 and 12 run only with test preprocessing on. Stage 11 preprocesses the test file, extracts its `TEST_SOURCE_FILE()` directives from the result, and checks them. Each test checks only its own entries, once, under its own name. Stage 12 parses test case names from that output. Stage 13 always runs and generates the Unity test runner, from the preprocessed test file when there is one and the original otherwise. The `:test_runner` stop point ends the run here.
 
 Each of these stages is skipped when nothing its output is built from has changed, which takes in more than the test file. Stage 11's full expansion reads every header the test reaches, so the project headers named in its line markers are among stage 11's dependencies, as they are for stage 4's second pass. Editing the macro in a header that enables a test case therefore reruns stage 11. When stage 11 is skipped, its `TEST_SOURCE_FILE()` directives are recalled from a cache. Stages 12 and 13 check one runner target. It depends on the test file, the file test case names are parsed from, the runner and Unity configuration, and the test's mock and include lists. With test preprocessing, those lists come from stage 4's reconciliation, so a header that changes which mocks a test has regenerates its runner although the test file is unchanged.
 
@@ -110,7 +110,7 @@ Pass 1 places stand-ins whether its list was just extracted or recalled from cac
 
 ### Mock search paths
 
-A mock is generated into a directory mirroring its real header's location, and the compiler finds it only if that directory is on the search path. C's `#include` resolution has no recursive search path. So each test's search paths carry one mirrored directory per mock, after the flat mock root, and `mock_search_paths` records which entries those are.
+A mock is generated into a directory mirroring its real header's location, and the compiler finds it only if that directory is on the search path. C's `#include` resolution has no recursive search path. So each test's search paths carry each mock's directory, and the directory its `#include` reaches it from when that differs, after the flat mock root. `mock_search_paths` records which entries those are.
 
 Where the paths come from follows which `#include` list drives the build:
 
@@ -120,6 +120,8 @@ Where the paths come from follows which `#include` list drives the build:
 
 Every stage that resolves a mock's header does so through `MockLocator`, against the test's search paths minus its `mock_search_paths`, so stages 2, 4, and 5 resolve each mock identically.
 
+Resolving needs every header on those search paths, in search order. `IncludePathinator#ordered_header_files` builds that list from each search path's own listing. A directory outside the build root keeps its listing for the whole test build: the build never writes there, and every stage asks for the same directories for every test. A directory under the build root, such as a mock or Partials directory, is listed on every call, since the build fills it as it runs. Stage 5 builds the list once per test and shares it across the test's mocks. `TestInvoker` forgets the listings at the start of each test build, after the `pre_test_build` hook.
+
 ## Stop points
 
 A run can stop early by including one of four mutually exclusive Symbols in `PipelineState#options`. Each names a different place to stop, so supplying more than one is rejected.

data/lib/ceedling/test_invoker/mock_locator.rb

@@ -6,6 +6,8 @@
 # =========================================================================
 
 require 'ceedling/constants'
+require 'ceedling/filesystem/build_subpath'
+require 'ceedling/filesystem/path_matcher'
 require 'ceedling/test_invoker/test_pipeline_helpers'
 
 # Where a test's mocks come from and where they go. A mock's real header resolves
@@ -16,6 +18,11 @@ class MockLocator
 
   include TestPipelineHelpers
 
+  # Where a mock is written (`directory`), the `folder` and `root` CMock writes it by (CMock
+  # writes below its root at the folder), and the directory the #include as written reaches
+  # the mock from (`reach`), which a search path must name
+  MockPlacement = Struct.new( :folder, :directory, :root, :reach, keyword_init: true )
+
   constructor :configurator, :include_pathinator, :file_finder, :file_path_utils
 
   # The headers a test's mocks resolve against: those on its search paths, in search
@@ -40,10 +47,61 @@ class MockLocator
       source, subdir = locate( include, collection: collection, complain: complain )
       next if source.nil?
 
-      @file_path_utils.form_mock_output_path( mocks_root, subdir )
+      search_directories( placement( mocks_root: mocks_root, subdir: subdir, include_path: include.filepath ) )
+    end
+
+    return dirs.flatten.uniq
+  end
+
+  # A mock's directory, and the directory its #include as written reaches it from
+  def search_directories(placement)
+    return [placement.directory, placement.reach].uniq
+  end
+
+  # Where a mock of the header mirrored at `subdir` is written, for the #include that
+  # names it as `include_path`.
+  #
+  # CMock names a mock's guard and lifecycle functions by the folder its #include names, and
+  # the runner names its calls by the same #include, so the folder reaches CMock as written.
+  # A folder that ends the mirrored subdirectory keeps that directory. One spelling more
+  # path than the mirror holds places the mock at the written path below the mock root. One
+  # that climbs stays below the mock root too: each `..` it begins with becomes an `_up_`
+  # directory, and the #include reaches the mock from that many levels deeper still.
+  # Without :mock_name_include_folder no folder is passed, and CMock names by filename
+  # alone, writing into the mock's directory itself.
+  def placement(mocks_root:, subdir:, include_path:)
+    written = written_folder( include_path )
+    spot    = written.nil? ? mirrored_spot( mocks_root, subdir ) : written_spot( mocks_root, subdir.to_s, written )
+    folder  = @configurator.cmock_mock_name_include_folder ? written : nil
+
+    return MockPlacement.new( folder: folder, directory: spot[:directory], root: (folder ? spot[:reach] : spot[:directory]), reach: spot[:reach] )
+  end
+
+  private
+
+  # The folder of a mock's #include as written, without a leading ./, or nil for none
+  def written_folder(include_path)
+    folder = File.dirname( include_path.to_s ).sub( %r{\A(?:\./)+}, '' )
+    return (folder.empty? || folder == '.') ? nil : folder
+  end
+
+  def mirrored_spot(mocks_root, subdir)
+    directory = @file_path_utils.form_mock_output_path( mocks_root, subdir )
+    return { directory: directory, reach: directory }
+  end
+
+  # The mock's directory for a #include written with `written`, and the directory that
+  # folder leads down or climbs from to it
+  def written_spot(mocks_root, subdir, written)
+    if subdir == written or subdir.end_with?( "/#{written}" )
+      return { directory: File.join( mocks_root, subdir ), reach: File.join( mocks_root, subdir.delete_suffix( written ) ).chomp( '/' ) }
     end
 
-    return dirs.uniq
+    segments = PathMatcher.resolve_relative( written, anchor: '' ).split( '/' )
+    climbs   = segments.take_while { |segment| segment == '..' }.length
+    ups      = [BuildSubpath::PARENT_SEGMENT] * climbs
+
+    return { directory: File.join( mocks_root, *ups, *segments.drop( climbs ) ), reach: File.join( mocks_root, *ups, *ups ) }
   end
 
 end