ceedling 1.1.10 → 1.2.0

data/plugins/module_generator/lib/module_generator_options.rb

@@ -0,0 +1,150 @@
+# =========================================================================
+#   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/exceptions'
+
+# The options Unity's module generator and CMock's skeleton generator need for one
+# module request, built from the project configuration.
+#
+# Paths come from the project's :paths collections. Without a hint, each kind of file
+# goes to its configured :path_src, :path_inc, or :path_tst, else the first path of its
+# collection. With a hint, each goes to the path the hint matches best in its own
+# collection, or to that collection's first path when the hint matches nothing there.
+# A hint that matches nothing in any collection is a mistake and stops the task.
+# Without include paths, headers go where the source goes.
+class ModuleGeneratorOptions
+
+  # The :naming values Unity's module generator accepts, passed to it as given
+  NAMING = %w[bumpy camel snake caps].freeze
+
+  KINDS = %i[src inc tst].freeze
+
+  TEST_GUARDS = %w[ifdef if].freeze
+
+  attr_reader :test_guard
+
+  # `path_finder` returns the path in a list a hint matches best, or nil for no match.
+  # `boilerplate_reader` returns a file's contents, or nil when it does not exist.
+  def initialize(config:, cmock_config:, path_finder:, boilerplate_reader:)
+    @config       = config
+    @cmock_config = cmock_config
+    @path_finder  = path_finder
+    @naming       = naming( config[:module_generator_naming] )
+    @test_guard   = guard_style( config[:module_generator_test_guard] )
+    @boilerplates = boilerplates( boilerplate_reader )
+    @collections  = collections
+    @shared       = shared_options
+  end
+
+  def unity(request)
+    src, inc, tst = paths( request.path_hint )
+    return @shared.merge( pattern: request.pattern, path_src: src, path_inc: inc, path_tst: tst )
+  end
+
+  # The header to read and the CMock options that write its skeleton beside the source.
+  # A subdirectory the name carries applies to both.
+  def stub(request)
+    src, inc, = paths( request.path_hint )
+    subdir    = File.dirname( request.name ).then { |dir| dir == '.' ? nil : dir }
+
+    return {
+      header: File.join( inc, "#{request.name}.h" ),
+      cmock:  @cmock_config.merge( skeleton_path: src, subdir: subdir )
+    }
+  end
+
+  # The header to parse, the test file to write, and what goes into it. A subdirectory
+  # the name carries applies to both paths.
+  def test(request)
+    _, inc, tst = paths( request.path_hint )
+    module_name = File.basename( request.name )
+    subdir      = File.dirname( request.name )
+
+    return {
+      header: File.join( inc, "#{request.name}.h" ),
+      path:   File.join( [tst, (subdir unless subdir == '.'), "#{@shared[:test_prefix]}#{module_name}.c"].compact ),
+      cmock:  @cmock_config,
+      file:   { module_name: module_name, header: "#{module_name}.h", includes: @shared[:includes][:tst],
+                boilerplate: @boilerplates[:tst], test_define: test_define, test_guard: @test_guard }
+    }
+  end
+
+  def test_define = @shared[:test_define]
+
+  private
+
+  def naming(value)
+    return nil if value.nil?
+
+    str = value.to_s
+    return str if NAMING.include?( str )
+
+    raise CeedlingException.new( "Module Generator :naming `#{value}` is not one of #{NAMING.map { |key| ":#{key}" }.join( ', ' )}." )
+  end
+
+  def guard_style(value)
+    guard = (value || :ifdef).to_s
+    return guard if TEST_GUARDS.include?( guard )
+
+    raise CeedlingException.new( "Module Generator :test_guard `#{value}` is not one of #{TEST_GUARDS.map { |key| ":#{key}" }.join( ', ' )}." )
+  end
+
+  # Configured boilerplates, each replaced by the contents of a configured boilerplate file
+  def boilerplates(reader)
+    files = @config[:module_generator_boilerplate_files] || {}
+
+    return KINDS.to_h do |kind|
+      path = files[kind]
+      next [kind, (@config[:module_generator_boilerplates] || {})[kind]] if path.nil?
+
+      contents = reader.call( path )
+      raise CeedlingException.new( "Module Generator boilerplate file `#{path}` does not exist." ) if contents.nil?
+
+      [kind, contents]
+    end
+  end
+
+  def collections
+    source = @config[:collection_paths_source] || []
+    return {
+      src: source,
+      inc: (@config[:collection_paths_include] || []).then { |include| include.empty? ? source : include },
+      tst: @config[:collection_paths_test] || []
+    }
+  end
+
+  # Unity options every request shares. Unity's own Subversion support stays off.
+  def shared_options
+    return {
+      test_prefix:  @config[:project_test_file_prefix],
+      mock_prefix:  @config[:cmock_mock_prefix] || 'Mock',
+      includes:     KINDS.to_h { |kind| [kind, Array( (@config[:module_generator_includes] || {})[kind] )] },
+      boilerplates: @boilerplates,
+      naming:       @naming,
+      update_svn:   false,
+      test_define:  @config[:module_generator_test_define] || 'TEST',
+      test_guard:   @test_guard
+    }
+  end
+
+  # Source, include, and test paths for a hint, or the configured defaults without one
+  def paths(hint)
+    return KINDS.map { |kind| @config[:"module_generator_path_#{kind}"] || @collections[kind].first } if hint.nil?
+
+    return matched_paths( hint )
+  end
+
+  def matched_paths(hint)
+    matches = KINDS.map { |kind| @path_finder.call( hint, @collections[kind] ) }
+    if matches.none?
+      raise CeedlingException.new( "Module path hint `#{hint}` matches no source, include, or test path in the project's :paths." )
+    end
+
+    return KINDS.zip( matches ).map { |kind, match| match || @collections[kind].first }
+  end
+
+end

data/plugins/module_generator/lib/module_generator_project.rb

@@ -0,0 +1,45 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'pathname'
+
+# What the project configuration says about files and defines the Module Generator is
+# about to create or depend on. Its answers become warnings, never refusals.
+class ModuleGeneratorProject
+
+  COLLECTIONS = %i[collection_all_source collection_all_headers collection_all_tests].freeze
+
+  # `test_defines` returns the defines a build gives a test file, resolving per-test
+  # matchers against that file's path exactly as a test build does
+  def initialize(config, test_defines:)
+    @config       = config
+    @test_defines = test_defines
+  end
+
+  # Whether a build of the test file defines the symbol, with or without a value
+  def test_defined?(symbol, test_path)
+    return @test_defines.call( test_path ).any? { |entry| entry.to_s.split( '=', 2 ).first.strip == symbol }
+  end
+
+  # Existing project files elsewhere that share a planned file's name, keyed by the
+  # planned path. A planned file that already exists is not its own duplicate.
+  def same_named(planned)
+    existing = COLLECTIONS.flat_map { |key| @config[key] || [] }
+
+    return planned.each_with_object( {} ) do |path, found|
+      matches = existing.select { |file| same_name_elsewhere?( file, Pathname.new( path ).cleanpath ) }
+      found[path] = matches unless matches.empty?
+    end
+  end
+
+  private
+
+  def same_name_elsewhere?(file, target)
+    return File.basename( file ) == target.basename.to_s && Pathname.new( file ).cleanpath != target
+  end
+
+end

data/plugins/module_generator/lib/module_generator_request.rb

@@ -0,0 +1,83 @@
+# =========================================================================
+#   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/exceptions'
+
+# One module a `module:create`, `module:destroy`, or `module:stub` call names, read
+# from the arguments a user types between the task's brackets.
+#
+# An argument is a module name, optionally preceded by colon-separated path hints
+# (`lab:secret:lair`). The hints join into one path for the path matcher, and a
+# Windows drive letter's own colon stays part of that path. A slash in the name
+# instead names a subdirectory to create.
+#
+# The first argument is always a module. A later argument that spells a pattern sets
+# the pattern for every module in the call. A name carrying the configured test file
+# prefix asks for its test file alone.
+class ModuleGeneratorRequest < Struct.new( :name, :path_hint, :pattern, keyword_init: true )
+
+  PATTERNS = %w[src test dh dih mch mvp].freeze
+
+  # A drive letter's colon, which is part of a path rather than a hint separator
+  DRIVE = /\A[A-Za-z]:(?=[\\\/])/
+
+  def self.parse(args, test_prefix:, patterns: true)
+    args = args.compact.map( &:strip )
+    raise CeedlingException.new( 'The module task names no module.' ) if args.first.to_s.empty?
+
+    names, pattern = patterns ? split_pattern( args ) : [args, nil]
+
+    return names.map do |arg|
+      request = from_argument( arg, pattern )
+      patterns ? request.test_only( test_prefix, arg ) : request
+    end
+  end
+
+  # The module arguments and the one pattern among the arguments after the first
+  def self.split_pattern(args)
+    found, names = args.drop( 1 ).partition { |arg| PATTERNS.include?( arg.downcase ) }
+    raise CeedlingException.new( "The module task takes one pattern, not #{found.join( ', ' )}." ) if found.size > 1
+
+    return [args.take( 1 ) + names, found.first&.downcase]
+  end
+
+  def self.from_argument(arg, pattern)
+    hint, name = split_hint( arg )
+    raise CeedlingException.new( "The module argument `#{arg}` names no module." ) if name.empty?
+
+    return new( name: name, path_hint: hint, pattern: pattern ).freeze
+  end
+
+  # The joined hint, or nil, and the name. A drive letter belongs to the hint when hints
+  # follow it, and to the name otherwise.
+  def self.split_hint(arg)
+    drive = arg[DRIVE].to_s
+    hints = arg.delete_prefix( drive ).split( ':', -1 )
+    name  = hints.pop
+    return [nil, drive + name] if hints.empty?
+
+    hint = drive + hints.reject( &:empty? ).join( '/' )
+    return [hint.empty? ? nil : hint, name]
+  end
+
+  private_class_method :split_pattern, :from_argument, :split_hint
+
+  # This request as a test-only module when its name carries the test file prefix. A
+  # prefix ending in a letter or digit (`Test`) needs a word boundary after it, so
+  # `TestWidget` is a test file while `Testimony` is a module.
+  def test_only(test_prefix, arg)
+    return self unless name.start_with?( test_prefix )
+
+    module_name = name.delete_prefix( test_prefix )
+    return self if test_prefix.match?( /[[:alnum:]]\z/ ) and module_name.match?( /\A[[:lower:][:digit:]]/ )
+
+    raise CeedlingException.new( "The module argument `#{arg}` names no module." ) if module_name.empty?
+
+    return self.class.new( name: module_name, path_hint: path_hint, pattern: 'test' ).freeze
+  end
+
+end

data/plugins/module_generator/lib/module_generator_test_file.rb

@@ -0,0 +1,68 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# The text of a test file holding an ignored test for each function a header declares,
+# for `module:test`.
+#
+# A new file follows the layout Unity's module generator gives a test file. An existing
+# file keeps everything it has and gains tests only for functions it does not yet test.
+# A function counts as tested by any `test_<function>` or `test_<function>_...` test,
+# so a user's own descriptive test names count. New tests go ahead of the file's closing
+# `#endif`, or at its end when it has none.
+class ModuleGeneratorTestFile
+
+  Result = Struct.new( :content, :added )
+
+  def initialize(module_name:, header:, includes:, boilerplate:, test_define:, test_guard:)
+    @module_name = module_name
+    @header      = header
+    @includes    = includes
+    @boilerplate = boilerplate
+    @test_define = test_define
+    @test_guard  = test_guard
+  end
+
+  def render(functions, existing: nil)
+    added = existing.nil? ? functions : functions.reject { |function| tested?( existing, function ) }
+    tests = added.map { |function| test_for( function ) }.join
+
+    return Result.new( existing.nil? ? new_file( tests ) : extend_file( existing, tests ), added )
+  end
+
+  private
+
+  def tested?(content, function)
+    return content.match?( /\bvoid\s+test_#{Regexp.escape( function )}(?:_\w*)?\s*\(/ )
+  end
+
+  def test_for(function)
+    return "\nvoid test_#{function}_NeedToImplement(void)\n{\n    TEST_IGNORE_MESSAGE(\"Need to Implement #{function}\");\n}\n"
+  end
+
+  def new_file(tests)
+    includes = (@includes + [@header]).map { |include| "#include \"#{include}\"\n" }.join
+
+    return "#{boilerplate}##{@test_guard} #{@test_define}\n\n#include \"unity.h\"\n\n#{includes}\n" \
+           "void setUp(void)\n{\n}\n\nvoid tearDown(void)\n{\n}\n#{tests}\n#endif // #{@test_define}\n"
+  end
+
+  def boilerplate
+    return @boilerplate.to_s.empty? ? '' : "#{format( @boilerplate, @module_name )}\n"
+  end
+
+  # New tests go ahead of the last `#endif` and the blank line before it
+  def extend_file(existing, tests)
+    return existing if tests.empty?
+
+    closing = existing.rindex( /^#endif\b/ )
+    return existing + tests if closing.nil?
+
+    head = existing[0...closing].chomp
+    return "#{head}#{tests}\n#{existing[closing..]}"
+  end
+
+end

data/plugins/module_generator/lib/module_generator_unity.rb

@@ -0,0 +1,24 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'generate_module'
+
+# Unity's module generator with the test guard style Ceedling configures. Unity wraps
+# each test file in `#ifdef <test define>`; the `if` guard wraps it in `#if` instead,
+# which coding standards that forbid `#ifdef` require.
+class ModuleGeneratorUnity < UnityModuleGenerator
+
+  TEMPLATE_TST_IF = TEMPLATE_TST.sub( '#ifdef ', '#if ' ).freeze
+
+  def files_to_operate_on(module_name, pattern = nil)
+    files = super
+    return files unless @options[:test_guard] == 'if'
+
+    return files.map { |file| file[:template].equal?( TEMPLATE_TST ) ? file.merge( template: TEMPLATE_TST_IF ) : file }
+  end
+
+end

data/plugins/module_generator/module_generator.rake

@@ -6,63 +6,41 @@
 # =========================================================================
 
 namespace :module do
-  module_root_separator = ":"
+
+  # One request per module a task's arguments name, each carrying only its own hint
+  module_requests = lambda do |args, patterns: true|
+    ModuleGeneratorRequest.parse(
+      [args[:module_path]] + args.extras,
+      test_prefix: @ceedling[:module_generator].test_prefix,
+      patterns:    patterns
+    )
+  end
 
   desc "Generate module (source, header and test files)"
-  task :create, :module_path do |t, args|
-    files = [args[:module_path]] + (args.extras || [])
-    optz = { :module_root_path => "" }
-    ["dh", "dih", "mch", "mvp", "src", "test"].each do |pat|
-      p = files.delete(pat)
-      optz[:pattern] = p unless p.nil?
+  task :create, :module_path do |_t, args|
+    module_requests.call( args ).each do |request|
+      @ceedling[:module_generator].create( request )
     end
+  end
 
-    files.each do |v|
-      module_root_path, module_name = v.split(module_root_separator, 2)
-      if module_name
-        optz[:module_root_path] = module_root_path
-        v = module_name
-      end
-      if (v =~ /^test_?/i)
-        # If the name of the file starts with test, automatically treat it as one
-        @ceedling[:module_generator].create(v.sub(/^test_?/i,''), optz.merge({:pattern => 'test'}))
-      else
-        # Otherwise, go through the normal procedure
-        @ceedling[:module_generator].create(v, optz)
-      end
+  desc "Generate module stubs from header"
+  task :stub, :module_path do |_t, args|
+    module_requests.call( args, patterns: false ).each do |request|
+      @ceedling[:module_generator].stub( request )
     end
   end
 
-  desc "Generate module stubs from header"
-  task :stub, :module_path do |t, args|
-    files = [args[:module_path]] + (args.extras || [])
-    optz = { :module_root_path => "" }
-    files.each do |v|
-      module_root_path, module_name = v.split(module_root_separator, 2)
-      if module_name
-        optz[:module_root_path] = module_root_path
-        v = module_name
-      end
-      # Otherwise, go through the normal procedure
-      @ceedling[:module_generator].stub_from_header(v, optz)
+  desc "Generate module tests from header"
+  task :test, :module_path do |_t, args|
+    module_requests.call( args, patterns: false ).each do |request|
+      @ceedling[:module_generator].test( request )
     end
   end
 
   desc "Destroy module (source, header and test files)"
-  task :destroy, :module_path do |t, args|
-    files = [args[:module_path]] + (args.extras || [])
-    optz = { :destroy => true, :module_root_path => "" }
-    ["dh", "dih", "mch", "mvp", "src", "test"].each do |pat|
-      p = files.delete(pat)
-      optz[:pattern] = p unless p.nil?
-    end
-    files.each do |v|
-      module_root_path, module_name = v.split(module_root_separator, 2)
-      if module_name
-        optz[:module_root_path] = module_root_path
-        v = module_name
-      end
-      @ceedling[:module_generator].create(v, optz)
+  task :destroy, :module_path do |_t, args|
+    module_requests.call( args ).each do |request|
+      @ceedling[:module_generator].destroy( request )
     end
   end
 

data/plugins/report_build_warnings_log/config/defaults.yml

@@ -8,5 +8,8 @@
 
 ---
 :report_build_warnings_log:
-  :filename: warnings.log
+  :filename: warnings   # Base name of each report; its extension is the report type's own
+  :reports: []          # Any of :text, :sarif, :json; none is :text alone
+  :patterns: []   # Regular expressions replacing the default match of any line mentioning "warning"
+  :excludes: []   # Regular expressions dropping matched warnings, context included
 ...

data/plugins/report_build_warnings_log/lib/report_build_warnings_log.rb

@@ -1,36 +1,39 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-24 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
 
-require 'ceedling/plugins/plugin'
+require 'ceedling/plugins/report_log_writer_plugin'
 require 'ceedling/constants'
+require 'set'
+require 'warning_collector'
+require 'warning_reports'
+require 'version'
+
+class ReportBuildWarningsLog < ReportLogWriterPlugin
 
-class ReportBuildWarningsLog < Plugin
-  
   # `Plugin` setup()
   def setup
-    # Create structure of @warnings hash with default values
-    @warnings = Hash.new() do |h,k|
-      # k => :context
-      h[k] = {
-        collection: [],
-      }
-    end
+    super
 
-    # Ceedling can run with multiple threads, provide a lock to use around @warnings
-    @mutex = Mutex.new()
+    # Each build context that ran a build step, with its warnings. A plain Hash, so
+    # merely reading an absent context never adds it.
+    @warnings = Hash.new
 
-    # Get default (default.yml) / user-set log filename in project configuration
-    @log_filename = @ceedling[:configurator].report_build_warnings_log_filename
+    configurator = @ceedling[:configurator]
 
-    # Convenient instance variable references
-    @file_wrapper = @ceedling[:file_wrapper]
-    @loginator = @ceedling[:loginator]
-    @reportinator = @ceedling[:reportinator]
+    # The configured reports, each written as the configured filename with its own extension
+    @basename = WarningReports.basename( configurator.report_build_warnings_log_filename )
+    @reports  = WarningReports.load( configurator.report_build_warnings_log_reports, version: Ceedling::Version::TAG )
+
+    # Optional patterns replace the default warning match, and excludes drop matches
+    @collector   = WarningCollector.new(
+      patterns: WarningCollector.compile( configurator.report_build_warnings_log_patterns, setting: ':report_build_warnings_log ↳ :patterns' ),
+      excludes: WarningCollector.compile( configurator.report_build_warnings_log_excludes, setting: ':report_build_warnings_log ↳ :excludes' )
+    )
   end
 
   # `Plugin` build step hook
@@ -76,62 +79,51 @@ class ReportBuildWarningsLog < Plugin
   # `Plugin` build step hook
   def post_build(_timestamp_s)
     # Write collected warnings to log(s)
-    write_logs( @warnings, @log_filename )
+    write_logs
   end
 
   # `Plugin` build step hook
   def post_error(_timestamp_s)
     # Write collected warnings to log(s)
-    write_logs( @warnings, @log_filename )
+    write_logs
   end
 
   ### Private ###
 
   private
 
-  # Extract warning messages and store to hash in thread-safe manner
+  # Stores each warning in the output, with its context, once per build context. A
+  # header's warning repeated by every file including it is stored the first time. A
+  # context is stored even without warnings, as a structured report still covers it.
   def process_output(context, output, hash)
-    # If $stderr/$stdout does not contain "warning", bail out
-    return if !(output =~ /warning/i)
+    warnings = @collector.warnings( output )
 
-    # Store warning message
     @mutex.synchronize do
-      hash[context][:collection] << output
+      entry = (hash[context] ||= { collection: [], seen: Set.new })
+      warnings.each do |warning|
+        entry[:collection] << warning if entry[:seen].add?( @collector.identity( warning ) )
+      end
     end
   end
 
-  # Walk warnings hash and write contents to log file(s)
-  def write_logs( warnings, filename )
-    msg = @reportinator.generate_heading( "Running Warnings Report" )
-    @loginator.log( msg )
-
-    if warnings.empty?
-      @loginator.log( "Build produced no warnings.\n" )
-      return
-    end
-
-    warnings.each do |context, hash|
-      log_filepath = form_log_filepath( context, filename )
-
-      msg = @reportinator.generate_progress( "Generating artifact #{log_filepath}" )
-      @loginator.log( msg )
-
-      File.open( log_filepath, 'w' ) do |f|
-        hash[:collection].each { |warning| f << warning }
+  # Writes each configured report for each build context. A report that skips a context
+  # without warnings leaves nothing to write when no context has any.
+  def write_logs
+    flush_log(
+      heading: 'Running Warnings Report',
+      empty_message: 'Build produced no warnings.',
+      empty: -> { reports_for_contexts.empty? }
+    ) do
+      reports_for_contexts.each do |context, report, warnings|
+        write_artifact( artifact_filepath( context, "#{@basename}.#{report.extension}" ), report.render( context, warnings ) )
       end
     end
-
-    # White space at command line after progress messages
-    @loginator.log( '' )
   end
 
-  def form_log_filepath(context, filename)
-    path = File.join( PROJECT_BUILD_ARTIFACTS_ROOT, context.to_s )
-    filepath = File.join(path, filename)
-
-    # Ensure containing artifact directory exists
-    @file_wrapper.mkdir( path )
-
-    return filepath
+  def reports_for_contexts
+    return @warnings.flat_map do |context, entry|
+      @reports.filter_map { |report| [context, report, entry[:collection]] if report.write_empty? or entry[:collection].any? }
+    end
   end
+
 end