ceedling 1.1.9 → 1.2.0

data/lib/ceedling/test_invoker/mock_locator.rb

@@ -0,0 +1,49 @@
+# =========================================================================
+#   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/test_invoker/test_pipeline_helpers'
+
+# Where a test's mocks come from and where they go. A mock's real header resolves
+# against the test's search paths, and the mock is written to a directory below the
+# test's mock root mirroring that header's location. Stand-ins, mock search paths, and
+# the real mock must all agree on that directory, so every stage locates mocks here.
+class MockLocator
+
+  include TestPipelineHelpers
+
+  constructor :configurator, :include_pathinator, :file_finder, :file_path_utils
+
+  # The headers a test's mocks resolve against: those on its search paths, in search
+  # order, without its own mock directories, which hold mocks rather than real headers
+  def header_collection(search_paths, mock_search_paths = [])
+    return @include_pathinator.ordered_header_files( search_paths - mock_search_paths )
+  end
+
+  # A mock's real header and the subdirectory mirroring its location. `complain` sets
+  # what a missing header does: :error raises, and :ignore gives [nil, nil].
+  def locate(include, collection:, complain: :error)
+    return @file_finder.resolve_mock( include.filepath, collection: collection, complain: complain )
+  end
+
+  # Each mock's mirrored directory below `mocks_root`, once each. A Partial mock has no
+  # real header and lives in the root itself, and a mock whose missing header the caller
+  # tolerates has no directory.
+  def directories(includes, mocks_root:, collection:, complain: :error)
+    dirs = includes.filter_map do |include|
+      next if mock_partial?( include )
+
+      source, subdir = locate( include, collection: collection, complain: complain )
+      next if source.nil?
+
+      @file_path_utils.form_mock_output_path( mocks_root, subdir )
+    end
+
+    return dirs.uniq
+  end
+
+end

data/lib/ceedling/test_invoker/partials_manager.rb

@@ -0,0 +1,426 @@
+# =========================================================================
+#   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/test_invoker/test_pipeline_helpers'
+
+class PartialsManager
+
+  include TestPipelineHelpers
+
+  constructor(
+    :configurator,
+    :loginator,
+    :reportinator,
+    :batchinator,
+    :preprocessinator,
+    :partializer,
+    :generator,
+    :dependinator,
+    :file_path_utils
+  )
+
+  # Stage 6: Preprocess partial header files for extract-and-generate pass.
+  def stage_preprocess_partial_headers(state)
+    preprocess_partials(
+      items:                  state.partials_headers,
+      kind:                   'header',
+      noun:                   'headers',
+      preserve_macros_method: :preprocess_partial_header_file_preserve_macros,
+      expand_macros_method:   :preprocess_partial_header_expand_macros
+    )
+  end
+
+  # Stage 7: Preprocess partial source files for extract-and-generate pass.
+  def stage_preprocess_partial_sources(state)
+    preprocess_partials(
+      items:                  state.partials_sources,
+      kind:                   'source',
+      noun:                   'sources',
+      preserve_macros_method: :preprocess_partial_source_file_preserve_macros,
+      expand_macros_method:   :preprocess_partial_source_expand_macros
+    )
+  end
+
+  # Stage 8: Extract and generate partial implementation and interface files.
+  #
+  # Extraction and validation below always run in full, for every partial, every
+  # invocation -- pure in-memory C parsing from whatever `config` already holds,
+  # cheap regardless of whether stages 6/7 did real preprocessing work or recalled
+  # it. `testable.partials.tests`/`.mocks` are rebuilt from that in-memory result
+  # every run too, since stage 14 reads those lists to decide compile sources
+  # regardless of whether anything on disk actually changed.
+  #
+  # The three disk writes below -- types header, implementation, interface -- are
+  # each independently optional (a module with no type/aggregate defs never gets
+  # a types header at all; implementation/interface are separately gated on
+  # extraction succeeding) and each gets its own DependencyTracker target rather
+  # than one combined target the way stage 6's three preprocessing passes share
+  # one: a target that's sometimes legitimately never written would never read
+  # back as fresh.
+  def stage_generate_partials(state)
+    directives_only = @configurator.test_build_preprocess_directives_only_available
+
+    partials = []
+    state.testables.each do |_, testable|
+      next if testable.partials.configs.empty?
+      testable.partials.configs.each do |_, config|
+        partials << { config: config, testable: testable }
+      end
+    end
+
+    skipped_types      = 0
+    skipped_impl       = 0
+    skipped_interface  = 0
+
+    @batchinator.exec(workload: :compile, things: partials) do |partial|
+      config   = partial[:config]
+      testable = partial[:testable]
+      name     = testable.name
+
+      module_contents = @partializer.extract_module_contents(
+        name,
+        config,
+        fallback: !directives_only
+      )
+
+      @partializer.validate_config(
+        c_module: module_contents, config: config, name: name, fallback: !directives_only
+      )
+
+      @partializer.sanitize( module_contents )
+
+      # Antecedents mirror stages 6/7's own targets for this same module's header/source --
+      # Partial generation's actual inputs (the preprocessed content those stages produce or
+      # recall) are already fully covered by the same file+flags/defines/search_paths.
+      # A declaration-only Partial (a prototype with no matching definition) has no source
+      # file to find, leaving config.source.filepath legitimately nil -- compact it out
+      # before it reaches path normalization, which expects real paths only.
+      antecedent_files = [config.header.filepath, config.source.filepath].compact
+
+      # The real header's guard is spoofed deliberately in every generated file, and the types
+      # header carries the dependencies its extracted types name. Both are inputs to generation,
+      # so both ride in the staleness meta below -- a changed guard or a changed include list
+      # has to invalidate what was generated from the previous ones.
+      module_include_guard = @partializer.extract_module_include_guard( config.header.filepath )
+      types_header_includes = @partializer.remap_types_header_includes(
+        name:     config.module,
+        includes: (config.source.includes + config.header.includes),
+        partials: testable.partials.configs,
+        test:     name
+      )
+
+      antecedent_meta  = {
+        flags:        testable.preprocess_flags,
+        defines:      testable.preprocess_defines,
+        search_paths: testable.search_paths,
+        # No shell tool runs in this stage -- Partial generation is pure Ruby (below) --
+        # so there's nothing to add here beyond the whole :partials config.
+        tools:        [],
+        partials:     @configurator.get_partials_config,
+        include_guard: module_include_guard,
+        types_includes: types_header_includes.map( &:to_s )
+      }
+
+      # Generated once and shared by the implementation and interface headers below (via
+      # their own includes lists), so a module tested and mocked in the same test file gets
+      # exactly one C definition of each of its typedefs and aggregate types. Nothing to
+      # write (and therefore nothing to track) when the module has no typedefs or aggregate
+      # definitions -- recompute the bare filename the same deterministic way
+      # GeneratorPartials#generate_types would have, purely so the includes-remapping below
+      # still knows what to #include.
+      types_header = nil
+      if !module_contents.type_definitions.empty? || !module_contents.aggregate_definitions.empty?
+        types_header = @file_path_utils.form_partial_types_header_filename( config.module )
+        target       = File.join( testable.paths[:partials], types_header )
+
+        @dependinator.register( target, files: antecedent_files, meta: antecedent_meta )
+
+        if @dependinator.stale?( target )
+          @generator.generate_partial_types(
+            name:          name,
+            partial:       config.module,
+            c_module:      module_contents,
+            output_path:   testable.paths[:partials],
+            includes:      types_header_includes,
+            include_guard: module_include_guard
+          )
+          @dependinator.mark_fresh( target )
+        else
+          msg = @reportinator.generate_module_progress(
+            operation:   'Skipping Partial types generation for',
+            module_name: name,
+            filename:    config.module
+          )
+          @loginator.log( msg, Verbosity::OBNOXIOUS )
+          state.lock.synchronize { skipped_types += 1 }
+        end
+      end
+
+      implementation = @partializer.extract_implementation_functions(
+        test:        name,
+        partial:     config.module,
+        definitions: module_contents.function_definitions,
+        config:      config
+      )
+
+      interface = @partializer.extract_interface_functions(
+        test:         name,
+        partial:      config.module,
+        definitions:  module_contents.function_definitions,
+        declarations: module_contents.function_declarations,
+        config:       config
+      )
+
+      @partializer.validate_extracted_functions(
+        name:      name,
+        partial:   config.module,
+        impl:      implementation,
+        interface: interface
+      )
+
+      arg_hash = {
+        test:                 name,
+        partial:              config.module,
+        function_definitions: implementation,
+        c_module:             module_contents,
+        header_includes:      @partializer.remap_implementation_header_includes(
+                                name:         config.module,
+                                includes:     (config.source.includes + config.header.includes),
+                                partials:     testable.partials.configs,
+                                types_header: types_header,
+                                test:         name
+                              ),
+        source_includes:      @partializer.remap_implementation_source_includes(
+                                name:     config.module,
+                                includes: (config.source.includes + config.header.includes),
+                                partials: testable.partials.configs,
+                                test:     name
+                              ),
+        input_filepath:       config.source.filepath,
+        output_path:          testable.paths[:partials],
+        include_guard:        module_include_guard
+      }
+
+      unless implementation.nil?
+        # The same call writes a header alongside the source, so the source vouches for it
+        # as an output. A modified or deleted header then regenerates both.
+        target        = File.join( testable.paths[:partials], @file_path_utils.form_partial_implementation_source_filename( config.module ) )
+        header_target = File.join( testable.paths[:partials], @file_path_utils.form_partial_implementation_header_filename( config.module ) )
+
+        @dependinator.register( target, files: antecedent_files, meta: antecedent_meta, outputs: [header_target] )
+
+        if @dependinator.stale?( target )
+          @generator.generate_partial_implementation( **arg_hash )
+          @dependinator.mark_fresh( target )
+        else
+          msg = @reportinator.generate_module_progress(
+            operation:   'Skipping Partial implementation generation for',
+            module_name: name,
+            filename:    config.module
+          )
+          @loginator.log( msg, Verbosity::OBNOXIOUS )
+          state.lock.synchronize { skipped_impl += 1 }
+        end
+
+        state.lock.synchronize { testable.partials.tests << config.module }
+      end
+
+      arg_hash = {
+        test:                  name,
+        partial:               config.module,
+        function_declarations: interface,
+        includes:              @partializer.remap_interface_header_includes(
+                                 name:         config.module,
+                                 includes:     (config.source.includes + config.header.includes),
+                                 partials:     testable.partials.configs,
+                                 types_header: types_header,
+                                 test:         name
+                               ),
+        c_module:              module_contents,
+        input_filepath:        config.header.filepath,
+        output_path:           testable.paths[:partials],
+        include_guard:         module_include_guard
+      }
+
+      unless interface.nil?
+        target = File.join( testable.paths[:partials], @file_path_utils.form_partial_interface_header_filename( config.module ) )
+
+        @dependinator.register( target, files: antecedent_files, meta: antecedent_meta )
+
+        if @dependinator.stale?( target )
+          @generator.generate_partial_interface( **arg_hash )
+          @dependinator.mark_fresh( target )
+        else
+          msg = @reportinator.generate_module_progress(
+            operation:   'Skipping Partial interface generation for',
+            module_name: name,
+            filename:    config.module
+          )
+          @loginator.log( msg, Verbosity::OBNOXIOUS )
+          state.lock.synchronize { skipped_interface += 1 }
+        end
+
+        state.lock.synchronize { testable.partials.mocks << config.module }
+      end
+    end
+
+    log_skip_summary( task: "Partial types generation", count: skipped_types, noun: "types headers" )
+    log_skip_summary( task: "Partial implementation generation", count: skipped_impl, noun: "implementations" )
+    log_skip_summary( task: "Partial interface generation", count: skipped_interface, noun: "interfaces" )
+  end
+
+  private
+
+  # Shared body for stages 6 and 7 -- a partial's header and source files go through
+  # identical preprocessing, differing only in which of `state.partials_headers`/
+  # `state.partials_sources` supplies the work and which Preprocessinator methods
+  # `kind` (a header or a source) is actually preprocessed by.
+  #
+  # A partial file's three preprocessing passes below (directives-only generation,
+  # preserve-macros preprocessing, full-expansion) all derive from the same
+  # antecedent file and the same preprocess flags/defines/search paths, so they're
+  # stale or fresh together as a single unit -- one DependencyTracker target per
+  # file per test covers all three.
+  #
+  # Settling every target's staleness in its own sequential pass first (cheap, no
+  # subprocess work) is what lets the three parallel batches below each just check
+  # `details.stale` instead of duplicating the register/stale? call three times
+  # over. On a stale target, all three passes run and populate `config` as they do
+  # today. On a fresh target, the two preprocessed output filepaths are recomputed
+  # the same deterministic way the preprocessor methods themselves compute them,
+  # and `config.includes` is recalled from the on-disk list a prior stale run wrote
+  # -- so `config` ends up populated identically either way, and stage 8 (which
+  # reads only `config`) needs no knowledge of which path produced it.
+  def preprocess_partials(items:, kind:, noun:, preserve_macros_method:, expand_macros_method:)
+    directives_only = @configurator.test_build_preprocess_directives_only_available
+    skipped = 0
+
+    items.each do |details|
+      config   = details.config
+      testable = details.testable
+      name     = testable.name
+
+      target = @file_path_utils.form_preprocessed_file_filepath( config.filepath, name )
+
+      @dependinator.register(
+        target,
+        files: [config.filepath],
+        meta:  dependency_meta(
+          flags: testable.preprocess_flags, defines: testable.preprocess_defines, search_paths: testable.search_paths,
+          tools: [
+            @configurator.tools_test_file_directives_only_preprocessor,
+            @configurator.tools_test_bare_includes_preprocessor,
+            @configurator.tools_test_file_full_preprocessor
+          ],
+          partials: @configurator.get_partials_config
+        )
+      )
+
+      details.preprocessed_target = target
+      details.stale               = @dependinator.stale?( target )
+
+      if details.stale
+        msg = @reportinator.generate_module_progress(
+          operation:   "Preprocessing partial #{kind} for",
+          module_name: name,
+          filename:    File.basename( config.filepath )
+        )
+        @loginator.log( msg )
+      else
+        msg = @reportinator.generate_module_progress(
+          operation:   "Skipping partial #{kind} preprocessing for",
+          module_name: name,
+          filename:    File.basename( config.filepath )
+        )
+        @loginator.log( msg, Verbosity::OBNOXIOUS )
+        skipped += 1
+
+        config.directives_only_filepath = target
+        config.includes                 = @preprocessinator.load_includes_list( test: name, filepath: config.filepath )
+        config.full_expansion_filepath  = @file_path_utils.form_preprocessed_file_full_expansion_filepath( config.filepath, name )
+      end
+    end
+
+    log_skip_summary( task: "partial #{kind} preprocessing", count: skipped, noun: noun )
+
+    # Generate directive-only preprocessor output if available
+    @batchinator.exec(workload: :compile, things: items) do |details|
+      next unless details.stale
+
+      config   = details.config
+      testable = details.testable
+      name     = testable.name
+
+      arg_hash = {
+        filepath:      config.filepath,
+        test:          name,
+        flags:         testable.preprocess_flags,
+        include_paths: testable.search_paths,
+        vendor_paths:  vendor_search_paths(),
+        defines:       testable.preprocess_defines
+      }
+
+      details.directives_only_filepath = @preprocessinator.generate_directives_only_output( **arg_hash )
+    end if directives_only
+
+    # Preprocess and assemble files
+    @batchinator.exec(workload: :compile, things: items) do |details|
+      next unless details.stale
+
+      config                   = details.config
+      testable                 = details.testable
+      name                     = testable.name
+      directives_only_filepath = details.directives_only_filepath
+
+      arg_hash = {
+        test:                     name,
+        filepath:                 config.filepath,
+        directives_only_filepath: directives_only_filepath,
+        fallback:                 directives_only_fallback?( directives_only, directives_only_filepath ),
+        flags:                    testable.preprocess_flags,
+        include_paths:            testable.search_paths,
+        vendor_paths:             vendor_search_paths(),
+        defines:                  testable.preprocess_defines
+      }
+
+      config.directives_only_filepath, config.includes = @preprocessinator.public_send( preserve_macros_method, **arg_hash )
+    end
+
+    # Full-preprocess files for expanded signature extraction.
+    @batchinator.exec(workload: :compile, things: items) do |details|
+      next unless details.stale
+
+      config   = details.config
+      testable = details.testable
+      name     = testable.name
+
+      arg_hash = {
+        filepath:      config.filepath,
+        test:          name,
+        flags:         testable.preprocess_flags,
+        include_paths: testable.search_paths,
+        vendor_paths:  vendor_search_paths(),
+        defines:       testable.preprocess_defines
+      }
+
+      config.full_expansion_filepath = @preprocessinator.public_send( expand_macros_method, **arg_hash )
+
+      # A skipped run recalls the includes list and full expansion this run wrote, so the
+      # preprocessed target vouches for both
+      @dependinator.register(
+        details.preprocessed_target,
+        outputs: [
+          @file_path_utils.form_preprocessed_includes_list_filepath( config.filepath, name ),
+          @file_path_utils.form_preprocessed_file_full_expansion_filepath( config.filepath, name )
+        ]
+      )
+      @dependinator.mark_fresh( details.preprocessed_target )
+    end
+  end
+
+end

data/lib/ceedling/test_invoker/standin_headerinator.rb

@@ -0,0 +1,136 @@
+# =========================================================================
+#   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/includes/includes'
+require 'ceedling/test_invoker/test_pipeline_helpers'
+
+# Stand-in headers: files placed where a test's mocks and Partials will be generated, so
+# the preprocessor finds something at each of their #includes before stage 8 or stage 10
+# writes the real file. A stand-in sits exactly where the real file will. A test build
+# that never reaches those stages, such as a :sources_only run, keeps only the stand-in,
+# which is all it needs.
+#
+# A mock's stand-in includes the mock's real header, as the generated mock will, so a
+# macro that header defines is visible through the stand-in. A Partial's is blank.
+class StandinHeaderinator
+
+  include TestPipelineHelpers
+
+  # The first line of every stand-in, which tells one apart from a real mock
+  MARKER = '// Ceedling stand-in header'
+
+  # The first line of the blank stand-ins earlier versions wrote (FileWrapper#write_blank_file)
+  BLANK_MARKER = '// Ceedling intentionally blank file'
+
+  MARKER_READ_LENGTH = 64
+
+  constructor :configurator, :loginator, :reportinator, :file_wrapper, :file_path_utils, :mock_locator
+
+  # Places a stand-in for each mock and Partial among `includes`, and gives the mirrored
+  # directories of the ordinary mocks, the mock search paths these includes call for.
+  #
+  # A real mock or Partial from an earlier run is left alone, as is a mock's stand-in that
+  # is already current. Mock generation tracks the file at a mock's path as an input, so
+  # rewriting it would invalidate the mock for nothing. A mock's stand-in that is out of
+  # date, such as a blank one from an earlier version, is rewritten.
+  #
+  # `complain` sets what a mock without a real header does: :error raises, and :ignore
+  # places nothing for it.
+  def place(testable, includes, complain: :error)
+    mocks     = Includes.filter( includes, /^#{@configurator.cmock_mock_prefix}/ )
+    mock_dirs = place_mocks( testable, mocks, complain )
+    place_partials( testable, Includes.filter( includes, /^#{PARTIAL_FILENAME_PREFIX}/ ) )
+
+    return mock_dirs.uniq
+  end
+
+  private
+
+  # A Partial mock is Ceedling's own generated content with no real header, so its
+  # stand-in follows its own #include's path. An ordinary mock's stand-in mirrors its
+  # real header's directory, as the real mock will.
+  def place_mocks(testable, mocks, complain)
+    collection = @mock_locator.header_collection( testable.search_paths, testable.mock_search_paths )
+
+    return mocks.filter_map do |include|
+      if mock_partial?( include )
+        write( testable.name, @file_path_utils.form_mock_header_filepath( testable.name, include.filepath ), include )
+        next
+      end
+
+      place_mock( testable, include, collection, complain )
+    end
+  end
+
+  # Gives the mock's mirrored directory, or nil when its missing header is tolerated or
+  # the test has no mock root
+  def place_mock(testable, include, collection, complain)
+    source, subdir = @mock_locator.locate( include, collection: collection, complain: complain )
+    return nil if source.nil?
+
+    mock_dir = subdir.empty? ? testable.name : File.join( testable.name, subdir )
+    write_mock( testable.name, @file_path_utils.form_mock_header_filepath( mock_dir, include.filename ), include, source )
+
+    return nil if testable.paths[:mocks].nil?
+
+    return @file_path_utils.form_mock_output_path( testable.paths[:mocks], subdir )
+  end
+
+  # A Partial's generated #include names whatever directory its module was named by, and
+  # the stand-in sits where that #include points
+  def place_partials(testable, partials)
+    partials.each do |include|
+      write( testable.name, @file_path_utils.form_partial_header_filepath( testable.name, include.filepath ), include )
+    end
+  end
+
+  def write(test, filepath, include)
+    return if @file_wrapper.exist?( filepath )
+
+    log_placement( test, include )
+    @file_wrapper.mkdir( File.dirname( filepath ) )
+    @file_wrapper.write_blank_file( filepath )
+  end
+
+  def write_mock(test, filepath, include, header)
+    contents = "#{MARKER}\n#{header_include( header )}\n"
+    return if current?( filepath, contents )
+
+    log_placement( test, include )
+    @file_wrapper.mkdir( File.dirname( filepath ) )
+    @file_wrapper.write( filepath, contents )
+  end
+
+  # The line CMock opens a mock with: its :orig_header_include_fmt around the header's name.
+  # Ceedling hands CMock no folder, so the name is the header's own.
+  def header_include( header )
+    format = @configurator.get_cmock_config[:orig_header_include_fmt] || '#include "%s"'
+    return format.gsub( '%s', File.basename( header ) )
+  end
+
+  # A file that is not a stand-in, such as a real mock, counts as current. Only its first
+  # line is read to tell, since a real mock can be large.
+  def current?(filepath, contents)
+    return false unless @file_wrapper.exist?( filepath )
+
+    start = @file_wrapper.read( filepath, MARKER_READ_LENGTH ).to_s
+    return true unless start.start_with?( MARKER, BLANK_MARKER )
+
+    return @file_wrapper.read( filepath ) == contents
+  end
+
+  def log_placement(test, include)
+    msg = @reportinator.generate_module_progress(
+      operation:   'Generating stand-in header for',
+      module_name: test,
+      filename:    include.filename
+    )
+    @loginator.log( msg, Verbosity::DEBUG )
+  end
+
+end