ceedling 0.9.0 → 1.0.1

data/lib/ceedling/test_invoker_helper.rb

@@ -0,0 +1,347 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/exceptions'
+
+class TestInvokerHelper
+
+  constructor :configurator,
+              :loginator,
+              :build_batchinator,
+              :task_invoker,
+              :test_context_extractor,
+              :include_pathinator,
+              :preprocessinator,
+              :defineinator,
+              :flaginator,
+              :file_finder,
+              :file_path_utils,
+              :file_wrapper,
+              :generator,
+              :test_runner_manager
+
+  def setup()
+    # Alias for brevity
+    @batchinator = @build_batchinator
+  end
+
+  def process_project_include_paths()
+    @include_pathinator.validate_test_build_directive_paths()
+    headers = @include_pathinator.validate_header_files_collection()
+    @include_pathinator.augment_environment_header_files( headers )
+  end
+
+  def extract_include_directives(arg_hash)
+    # Run test file through preprocessor to parse out include statements and then collect header files, mocks, etc.
+    includes = @preprocessinator.preprocess_includes( **arg_hash )
+
+    # Store the include statements we found
+    @test_context_extractor.ingest_includes( arg_hash[:filepath], includes )
+  end
+
+  def validate_build_directive_source_files(test:, filepath:)
+    sources = @test_context_extractor.lookup_build_directive_sources_list(filepath)
+
+    ext_message = @configurator.extension_source
+    if @configurator.test_build_use_assembly
+      ext_message += " or #{@configurator.extension_assembly}"
+    end
+
+    sources.each do |source|
+      valid_extension = true
+
+      # Only C files in test build
+      if not @configurator.test_build_use_assembly
+        valid_extension = false if @file_wrapper.extname(source) != @configurator.extension_source      
+      # C and assembly files in test build
+      else
+        ext = @file_wrapper.extname(source)
+        valid_extension = false if (ext != @configurator.extension_assembly) and (ext != @configurator.extension_source)
+      end
+
+      if not valid_extension
+        error = "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} is not a #{ext_message} source file"
+        raise CeedlingException.new(error)
+      end
+
+      if @file_finder.find_build_input_file(filepath: source, complain: :ignore, context: TEST_SYM).nil?
+        error = "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} cannot be found in the source file collection"
+        raise CeedlingException.new(error)
+      end
+    end
+  end
+
+  def search_paths(filepath, subdir)
+    paths = []
+
+    # Start with mock path to ensure any CMock-reworked header files are encountered first
+    paths << File.join( @configurator.cmock_mock_path, subdir ) if @configurator.project_use_mocks
+    paths += @include_pathinator.lookup_test_directive_include_paths( filepath )
+    paths += @include_pathinator.collect_test_include_paths()
+    paths += @configurator.collection_paths_support
+    paths += @configurator.collection_paths_include
+    paths += @configurator.collection_paths_libraries
+    paths += @configurator.collection_paths_vendor
+    paths += @configurator.collection_paths_test_toolchain_include
+    
+    return paths.uniq
+  end
+
+  def framework_defines()
+    defines = []
+
+    # Unity defines
+    defines += @defineinator.defines( topkey:UNITY_SYM, subkey: :defines )
+
+    # CMock defines
+    defines += @defineinator.defines( topkey:CMOCK_SYM, subkey: :defines )
+
+    # CException defines
+    defines += @defineinator.defines( topkey:CEXCEPTION_SYM, subkey: :defines )
+
+    return defines.uniq
+  end
+
+  def tailor_search_paths(filepath:, search_paths:)
+    _search_paths = []
+
+    # Unity search paths
+    if filepath == File.join(PROJECT_BUILD_VENDOR_UNITY_PATH, UNITY_C_FILE)
+      _search_paths += @configurator.collection_paths_support
+      _search_paths << PROJECT_BUILD_VENDOR_UNITY_PATH
+
+    # CMock search paths
+    elsif @configurator.project_use_mocks and 
+      (filepath == File.join(PROJECT_BUILD_VENDOR_CMOCK_PATH, CMOCK_C_FILE))
+      _search_paths += @configurator.collection_paths_support
+      _search_paths << PROJECT_BUILD_VENDOR_UNITY_PATH
+      _search_paths << PROJECT_BUILD_VENDOR_CMOCK_PATH
+      _search_paths << PROJECT_BUILD_VENDOR_CEXCEPTION_PATH if @configurator.project_use_exceptions
+
+    # CException search paths
+    elsif @configurator.project_use_exceptions and 
+      (filepath == File.join(PROJECT_BUILD_VENDOR_CEXCEPTION_PATH, CEXCEPTION_C_FILE))
+      _search_paths += @configurator.collection_paths_support
+      _search_paths << PROJECT_BUILD_VENDOR_CEXCEPTION_PATH
+
+    # Support files search paths
+    elsif (@configurator.collection_all_support.include?(filepath))
+      _search_paths = search_paths
+      _search_paths += @configurator.collection_paths_support
+      _search_paths << PROJECT_BUILD_VENDOR_UNITY_PATH
+      _search_paths << PROJECT_BUILD_VENDOR_CMOCK_PATH if @configurator.project_use_mocks
+      _search_paths << PROJECT_BUILD_VENDOR_CEXCEPTION_PATH if @configurator.project_use_exceptions
+    end
+
+    # Not a vendor file, return original search paths
+    if _search_paths.length == 0
+      return search_paths
+    end
+
+    return _search_paths.uniq
+  end
+
+  def runner_defines()
+    return @test_runner_manager.collect_defines()
+  end
+
+  def compile_defines(context:, filepath:)
+    # If this context exists ([:defines][context]), use it. Otherwise, default to test context.
+    context = TEST_SYM unless @defineinator.defines_defined?( context:context )
+
+    defines = @defineinator.generate_test_definition( filepath:filepath )
+    defines += @defineinator.defines( subkey:context, filepath:filepath )
+
+    return defines.uniq
+  end
+
+  def preprocess_defines(test_defines:, filepath:)
+    # Preprocessing defines for the test file
+    preprocessing_defines = @defineinator.defines( subkey:PREPROCESS_SYM, filepath:filepath, default:nil )
+
+    # If no defines were set, default to using test_defines
+    return test_defines if preprocessing_defines.nil?
+      
+    # Otherwise, return the defines we looked up
+    # This includes an explicitly set empty list to override / clear test_defines
+    return preprocessing_defines
+  end
+
+  def flags(context:, operation:, filepath:, default:[])
+    # If this context + operation exists ([:flags][context][operation]), use it. Otherwise, default to test context.
+    context = TEST_SYM unless @flaginator.flags_defined?( context:context, operation:operation )
+
+    return @flaginator.flag_down( context:context, operation:operation, filepath:filepath, default:default )
+  end
+
+  def preprocess_flags(context:, compile_flags:, filepath:)
+    preprocessing_flags = flags( context:context, operation:OPERATION_PREPROCESS_SYM, filepath:filepath, default:nil )
+
+    # If no flags were set, default to using compile_flags
+    return compile_flags if preprocessing_flags.nil?
+
+    # Otherwise, return the flags we looked up
+    # This includes an explicitly set empty list to override / clear compile_flags
+    return preprocessing_flags
+  end
+
+  def collect_test_framework_sources(mocks)
+    sources = []
+
+    sources << File.join(PROJECT_BUILD_VENDOR_UNITY_PATH, UNITY_C_FILE)
+    sources << File.join(PROJECT_BUILD_VENDOR_CMOCK_PATH, CMOCK_C_FILE) if @configurator.project_use_mocks and mocks
+    sources << File.join(PROJECT_BUILD_VENDOR_CEXCEPTION_PATH, CEXCEPTION_C_FILE) if @configurator.project_use_exceptions
+
+    # If we're (a) using mocks (b) a Unity helper is defined and (c) that unity helper includes a source file component,
+    # then link in the unity_helper object file too.
+    if @configurator.project_use_mocks
+      @configurator.cmock_unity_helper_path.each do |helper|
+        if @file_wrapper.exist?( helper.ext( EXTENSION_SOURCE ) )
+          sources << helper
+        end
+      end
+    end
+
+    return sources
+  end
+
+  def extract_sources(test_filepath)
+    sources = []
+
+    # Get any additional source files specified by TEST_SOURCE_FILE() in test file
+    _sources = @test_context_extractor.lookup_build_directive_sources_list(test_filepath)
+    _sources.each do |source|
+      sources << @file_finder.find_build_input_file(filepath: source, complain: :ignore, context: TEST_SYM)
+    end
+
+    _support_headers = COLLECTION_ALL_SUPPORT.map { |filepath| File.basename(filepath).ext(EXTENSION_HEADER) }
+
+    # Get all #include .h files from test file so we can find any source files by convention
+    includes = @test_context_extractor.lookup_full_header_includes_list(test_filepath)
+    includes.each do |include|
+      _basename = File.basename(include)
+      next if _basename == UNITY_H_FILE                # Ignore Unity in this list
+      next if _basename.start_with?(CMOCK_MOCK_PREFIX) # Ignore mocks in this list
+      next if _support_headers.include?(_basename)     # Ignore any sources in our support files list
+
+      sources << @file_finder.find_build_input_file(filepath: include, complain: :ignore, context: TEST_SYM)
+    end
+
+    # Remove any nil or duplicate entries in list
+    return sources.compact.uniq
+  end
+
+  def fetch_shallow_source_includes(test_filepath)
+    return @test_context_extractor.lookup_source_includes_list(test_filepath)
+  end
+
+  def fetch_include_search_paths_for_test_file(test_filepath)
+    return @test_context_extractor.lookup_include_paths_list(test_filepath)
+  end
+
+  # TODO: Use search_paths to find/match header file from which to generate mock
+  # Today, this is just a pass-through wrapper
+  def find_header_input_for_mock(mock, search_paths)
+    return @file_finder.find_header_input_for_mock( mock )
+  end
+
+  # Transform list of mock names into filenames with source extension
+  def form_mock_filenames(mocklist)
+    return mocklist.map {|mock| mock + @configurator.extension_source}
+  end
+
+  def remove_mock_original_headers( filelist, mocklist )
+    filelist.delete_if do |filepath|
+      # Create a simple mock name from the filepath => mock prefix + filepath base name with no extension
+      mock_name = @configurator.cmock_mock_prefix + File.basename( filepath, '.*' )
+      # Tell `delete_if()` logic to remove inspected filepath if simple mocklist includes the name we just generated
+      mocklist.include?( mock_name )
+    end
+  end
+
+  def clean_test_results(path, tests)
+    tests.each do |test|
+      @file_wrapper.rm_f( Dir.glob( File.join( path, test + '.*' ) ) )
+    end
+  end
+
+  # Convert libraries configuration form YAML configuration
+  # into a string that can be given to the compiler.
+  def convert_libraries_to_arguments()
+    args = ((@configurator.project_config_hash[:libraries_test] || []) + ((defined? LIBRARIES_SYSTEM) ? LIBRARIES_SYSTEM : [])).flatten
+    if (defined? LIBRARIES_FLAG)
+      args.map! {|v| LIBRARIES_FLAG.gsub(/\$\{1\}/, v) }
+    end
+    return args
+  end
+
+  def get_library_paths_to_arguments()
+    paths = (defined? PATHS_LIBRARIES) ? (PATHS_LIBRARIES || []).clone : []
+    if (defined? LIBRARIES_PATH_FLAG)
+      paths.map! {|v| LIBRARIES_PATH_FLAG.gsub(/\$\{1\}/, v) }
+    end
+    return paths
+  end
+
+  def generate_executable_now(context:, build_path:, executable:, objects:, flags:, lib_args:, lib_paths:, options:)
+    begin
+      @generator.generate_executable_file(
+        options[:test_linker],
+        context,
+        objects.map{|v| "\"#{v}\""},
+        flags,
+        executable,
+        @file_path_utils.form_test_build_map_filepath( build_path, executable ),
+        lib_args,
+        lib_paths )
+    rescue ShellException => ex
+      if ex.shell_result[:output] =~ /symbol/i
+        notice =    "If the linker reports missing symbols, the following may be to blame:\n" +
+                    "  1. This test lacks #include statements corresponding to needed source files (see note below).\n" +
+                    "  2. Project file paths omit source files corresponding to #include statements in this test.\n" +
+                    "  3. Complex macros, #ifdefs, etc. have obscured correct #include statements in this test.\n" +
+                    "  4. Your project is attempting to mix C++ and C file extensions (not supported).\n"
+        if (@configurator.project_use_mocks)
+          notice += "  5. This test does not #include needed mocks (that triggers their generation).\n"
+        end
+
+        notice +=   "\n"
+        notice +=   "NOTE: A test file directs the build of a test executable with #include statemetns:\n" +
+                    "  * By convention, Ceedling assumes header filenames correspond to source filenames.\n" +
+                    "  * Which code files to compile and link are determined by #include statements.\n"
+        if (@configurator.project_use_mocks)
+          notice += "  * An #include statement convention directs the generation of mocks from header files.\n"
+        end
+
+        notice +=   "\n"
+        notice +=   "OPTIONS:\n" +
+                    "  1. Doublecheck this test's #include statements.\n" +
+                    "  2. Simplify complex macros or fully specify symbols for this test in :project ↳ :defines.\n" +
+                    "  3. If no header file corresponds to the needed source file, use the TEST_SOURCE_FILE()\n" +
+                    "     build diective macro in this test to inject a source file into the build.\n\n" +
+                    "See the docs on conventions, paths, preprocessing, compilation symbols, and build directive macros.\n\n"
+
+        # Print helpful notice
+        @loginator.log( notice, Verbosity::COMPLAIN, LogLabels::NOTICE )
+      end
+
+      # Re-raise the exception
+      raise ex
+    end
+  end
+
+  def run_fixture_now(context:, test_name:, test_filepath:, executable:, result:, options:)
+    @generator.generate_test_results(
+      tool:          options[:test_fixture], 
+      context:       context,
+      test_name:     test_name,
+      test_filepath: test_filepath,
+      executable:    executable, 
+      result:        result)
+  end
+  
+end

data/lib/ceedling/test_runner_manager.rb

@@ -0,0 +1,47 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/constants'
+
+class TestRunnerManager
+
+  def initialize()
+    @test_case_incl = nil
+    @test_case_excl = nil
+    @test_runner_defines = []
+  end
+
+  def configure_build_options(config)
+    cmdline_args = config[:test_runner][:cmdline_args]
+
+    # Should never happen because of external config handling, but...
+    return if cmdline_args.nil?
+
+    @test_runner_defines << RUNNER_BUILD_CMDLINE_ARGS_DEFINE if cmdline_args
+  end
+
+  def configure_runtime_options(include_test_case, exclude_test_case)
+    if !include_test_case.empty?
+      @test_case_incl = "-f #{include_test_case}"
+    end
+
+    if !exclude_test_case.empty?
+      @test_case_excl = "-x #{exclude_test_case}"
+    end
+  end
+
+  # Return test case arguments (empty if not set)
+  def collect_cmdline_args()
+    return [ @test_case_incl, @test_case_excl ].compact()
+  end
+
+  # Return ['UNITY_USE_COMMAND_LINE_ARGS'] #define required by Unity to enable cmd line arguments
+  def collect_defines()
+    return @test_runner_defines
+  end
+
+end

data/lib/ceedling/tool_executor.rb

@@ -0,0 +1,233 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+require 'benchmark'
+
+class ToolExecutor
+
+  constructor :configurator, :tool_executor_helper, :loginator, :verbosinator, :system_wrapper
+
+  # build up a command line from yaml provided config
+
+  # @param extra_params is an array of parameters to append to executable (prepend to rest of command line)
+  def build_command_line(tool_config, extra_params, *args)
+    command = {}
+
+    command[:name] = tool_config[:name]
+    command[:executable] = tool_config[:executable]
+
+    command[:options] = {} # Blank to hold options set before `exec()` processes
+
+    # Basic premise is to iterate top to bottom through arguments using '$' as
+    # a string replacement indicator to expand globals or inline yaml arrays
+    # into command line arguments via substitution strings.
+    executable = @tool_executor_helper.osify_path_separators(
+      expandify_element(tool_config[:name], tool_config[:executable], *args)
+    )
+
+    command[:line] = [
+      executable,
+      extra_params.join(' ').strip,
+      build_arguments(tool_config[:name], tool_config[:arguments], *args),
+      ].reject{|s| s.nil? || s.empty?}.join(' ').strip
+
+    # Log command as is
+    @loginator.log( "Command: #{command}", Verbosity::DEBUG )
+
+    # Update executable after any expansion
+    command[:executable] = executable
+
+    return command
+  end
+
+
+  # shell out, execute command, and return response
+  def exec(command, args=[])
+    options = command[:options]
+
+    options[:boom] = true if (options[:boom].nil?)
+    options[:stderr_redirect] = StdErrRedirect::NONE if (options[:stderr_redirect].nil?)
+
+    # Build command line
+    command_line = [
+      command[:line].strip,
+      args,
+      @tool_executor_helper.stderr_redirect_cmdline_append( options ),
+      ].flatten.compact.join(' ')
+
+    shell_result = {}
+
+    # Wrap system level tool execution in exception handling
+    begin
+      time = Benchmark.realtime do
+        shell_result = @system_wrapper.shell_capture3( command:command_line, boom:options[:boom] )
+      end
+      shell_result[:time] = time
+
+    # Ultimately, re-raise the exception as ShellException populated with the exception message
+    rescue => error
+      raise ShellException.new( name:pretty_tool_name( command ), message: error.message )
+
+    # Be sure to log what we can
+    ensure
+      # Scrub the string for illegal output
+      unless shell_result[:output].nil?
+        shell_result[:output] = shell_result[:output].scrub if "".respond_to?(:scrub)
+        shell_result[:output].gsub!(/\033\[\d\dm/,'')
+      end
+
+      @tool_executor_helper.log_results( command_line, shell_result )
+    end
+
+    # Go boom if exit code is not 0 and that code means a fatal error
+    # (Sometimes we don't want a non-0 exit code to cause an exception as the exit code may not mean a build-ending failure)
+    if ((shell_result[:exit_code] != 0) and options[:boom])
+      raise ShellException.new( shell_result:shell_result, name:pretty_tool_name( command ) )
+    end
+
+    return shell_result
+  end
+
+  private #############################
+
+
+  def build_arguments(tool_name, config, *args)
+    build_string = ''
+
+    return nil if (config.nil?)
+
+    # Iterate through each argument
+
+    # The yaml blob array needs to be flattened so that yaml alias substitution is handled
+    # correctly as it creates a nested array when an anchor is dereferenced
+    config.flatten.each do |element|
+      argument = ''
+
+      case(element)
+        # If we find a simple string then look for string replacement operators
+        #  and expand with the parameters in this method's argument list
+        when String then argument = expandify_element(tool_name, element, *args)
+        # If we find a hash, then we grab the key as a substitution string and expand the
+        #  hash's value(s) within that substitution string
+        when Hash   then argument = dehashify_argument_elements(tool_name, element)
+      end
+
+      build_string.concat("#{argument} ") if (argument.length > 0)
+    end
+
+    build_string.strip!
+    return build_string if (build_string.length > 0)
+    return nil
+  end
+
+
+  # handle simple text string argument & argument array string replacement operators
+  def expandify_element(tool_name, element, *args)
+    match = //
+    to_process = nil
+    args_index = 0
+
+    # handle ${#} input replacement
+    if (element =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+      args_index = ($2.to_i - 1)
+
+      if (args.nil? or args[args_index].nil?)
+        error = "Tool '#{tool_name}' expected valid argument data to accompany replacement operator #{$1}."
+        raise CeedlingException.new( error )
+      end
+
+      match = /#{Regexp.escape($1)}/
+      to_process = args[args_index]
+    end
+
+    # simple string argument: replace escaped '\$' and strip
+    element.sub!(/\\\$/, '$')
+    element.strip!
+
+    build_string = ''
+
+    # handle array or anything else passed into method to be expanded in place of replacement operators
+    case (to_process)
+      when Array then to_process.each {|value| build_string.concat( "#{element.sub(match, value.to_s)} " ) } if (to_process.size > 0)
+      else build_string.concat( element.sub(match, to_process.to_s) )
+    end
+
+    # handle inline ruby string substitution
+    if (build_string =~ PATTERNS::RUBY_STRING_REPLACEMENT)
+      build_string.replace(@system_wrapper.module_eval(build_string))
+    end
+
+    return build_string.strip
+  end
+
+
+  # handle argument hash: keys are substitution strings, values are data to be expanded within substitution strings
+  def dehashify_argument_elements(tool_name, hash)
+    build_string = ''
+    elements = []
+
+    # grab the substitution string (hash key)
+    substitution = hash.keys[0].to_s
+    # grab the string(s) to squirt into the substitution string (hash value)
+    expand = hash[hash.keys[0]]
+
+    if (expand.nil?)
+      error = "Tool '#{tool_name}' could not expand nil elements for substitution string '#{substitution}'."
+      raise CeedlingException.new( error )
+    end
+
+    # array-ify expansion input if only a single string
+    expansion = ((expand.class == String) ? [expand] : expand)
+
+    expansion.each do |item|
+      # String eval substitution
+      if (item =~ PATTERNS::RUBY_STRING_REPLACEMENT)
+        elements << @system_wrapper.module_eval(item)
+      # Global constants
+      elsif (@system_wrapper.constants_include?(item))
+        const = Object.const_get(item)
+        if (const.nil?)
+          error = "Tool '#{tool_name}' found constant '#{item}' to be nil."
+          raise CeedlingException.new( error )
+        else
+          elements << const
+        end
+      elsif (item.class == Array)
+        elements << item
+      elsif (item.class == String)
+        error = "Tool '#{tool_name}' cannot expand nonexistent value '#{item}' for substitution string '#{substitution}'."
+        raise CeedlingException.new( error )
+      else
+        error = "Tool '#{tool_name}' cannot expand value having type '#{item.class}' for substitution string '#{substitution}'."
+        raise CeedlingException.new( error )
+      end
+    end
+
+    # expand elements (whether string or array) into substitution string & replace escaped '\$'
+    elements.flatten!
+    elements.each do |element|
+      build_string.concat( substitution.sub(/([^\\]*)\$/, "\\1#{element}") ) # don't replace escaped '\$' but allow us to replace just a lonesome '$'
+      build_string.gsub!(/\\\$/, '$')
+      build_string.concat(' ')
+    end
+
+    return build_string.strip
+  end
+
+  def pretty_tool_name(command)
+    # Titleize command's name -- each word capitalized plus underscores replaced with spaces
+    name = "#{command[:name].split(/ |\_/).map(&:capitalize).join(" ")}"
+
+    executable = command[:executable].empty? ? '<no executable>' : command[:executable]
+
+    # 'Name' (executable) 
+    return "'#{name}' " + "(#{executable})"
+  end
+
+end