ceedling 1.1.9 → 1.2.0

data/lib/ceedling/objects.yml

@@ -10,12 +10,17 @@ application:
     - system_wrapper
 
 file_wrapper:
+  compose:
+    - loginator
+    - verbosinator
 
 file_system_wrapper:
 
 rake_wrapper:
 
 yaml_wrapper:
+  compose:
+    - file_wrapper
 
 ruby_expandinator:
 
@@ -44,21 +49,8 @@ file_path_collection_utils:
 
 test_runner_manager:
 
-cacheinator:
-  compose:
-    - cacheinator_helper
-    - file_path_utils
-    - file_wrapper
-    - yaml_wrapper
-
-cacheinator_helper:
-  compose:
-    - file_wrapper
-    - yaml_wrapper
-
 tool_executor:
   compose:
-    - configurator
     - tool_executor_helper
     - loginator
     - verbosinator
@@ -77,7 +69,6 @@ tool_validator:
     - file_wrapper
     - loginator
     - system_wrapper
-    - reportinator
     - ruby_expandinator
 
 configurator:
@@ -96,10 +87,11 @@ configurator_setup:
   compose:
     - configurator_builder
     - configurator_validator
-    - configurator_plugins
     - loginator
     - reportinator
     - file_wrapper
+    - system_wrapper
+    - tool_executor
 
 configurator_plugins:
   compose:
@@ -111,7 +103,6 @@ configurator_validator:
     - config_walkinator
     - file_wrapper
     - loginator
-    - system_wrapper
     - reportinator
     - tool_validator
 
@@ -125,7 +116,6 @@ configurator_builder:
 loginator:
   compose:
     - verbosinator
-    - file_wrapper
     - system_wrapper
 
 setupinator:
@@ -146,6 +136,9 @@ plugin_reportinator:
     - plugin_manager
     - reportinator
     - loginator
+    - templateinator
+
+templateinator:
 
 plugin_reportinator_helper:
   compose:
@@ -159,7 +152,6 @@ file_finder:
   compose:
     - configurator
     - file_finder_helper
-    - cacheinator
     - file_path_utils
     - file_wrapper
     - yaml_wrapper
@@ -177,6 +169,7 @@ test_context_extractor:
   compose:
     - configurator
     - file_wrapper
+    - yaml_wrapper
     - include_factory
     - partializer_config
     - file_path_utils
@@ -231,6 +224,8 @@ generator:
     - plugin_manager
     - test_runner_manager
     - generator_test_results_backtrace
+    - system_wrapper
+    - file_wrapper
 
 generator_helper:
   compose:
@@ -243,6 +238,7 @@ generator_test_results:
     - loginator
     - reportinator
     - yaml_wrapper
+    - file_wrapper
 
 generator_test_results_backtrace:
   compose:
@@ -271,21 +267,19 @@ generator_partials:
 
 dependinator:
   compose:
-    - configurator
-    - test_context_extractor
-    - file_path_utils 
-    - rake_wrapper
-    - file_wrapper
+    - dependency_tracker
 
 preprocessinator_line_marker_includes_extractor:
   compose:
     - include_factory
+    - file_wrapper
 
 c_comment_scanner:
 
 preprocessinator_comment_stripper:
   compose:
     - c_comment_scanner
+    - file_wrapper
 
 preprocessinator_reconstructor:
   compose:
@@ -299,8 +293,8 @@ preprocessinator:
     - preprocessinator_file_assembler
     - preprocessinator_reconstructor
     - file_path_utils
-    - tool_executor
     - file_wrapper
+    - tool_executor
     - plugin_manager
     - configurator
     - loginator
@@ -314,6 +308,7 @@ preprocessinator_includes_handler:
     - tool_executor
     - parsing_parcels
     - file_wrapper
+    - quote_include_isolator
     - file_path_utils
     - yaml_wrapper
     - loginator
@@ -331,6 +326,8 @@ preprocessinator_file_assembler:
     - reportinator
 
 preprocessinator_code_finder:
+  compose:
+    - file_wrapper
 
 c_extractor_code_text:
 
@@ -359,6 +356,7 @@ c_extractor:
     - c_extractor_definitions
     - configurator
     - loginator
+    - file_wrapper
 
 partializer_config:
   compose:
@@ -375,14 +373,18 @@ partializer_helper:
     - c_extractor
     - c_extractor_declarations
     - file_path_utils
+    - parsing_parcels
     - loginator
 
 partializer:
   compose:
+    - configurator
     - partializer_helper
     - file_finder
     - c_extractor
     - file_path_utils
+    - preprocessinator_reconstructor
+    - file_wrapper
     - reportinator
     - loginator
 
@@ -395,14 +397,25 @@ batchinator:
 test_invoker:
   compose:
     - application
-    - configurator
+    - plugin_manager
+    - dependinator
+    - loginator
+    - verbosinator
+    - test_pipeline_manager
+
+test_pipeline_manager:
+  compose:
     - test_build_setup
+    - test_includes_extractinator
     - test_build_planner
+    - partials_manager
     - test_build_executor
-    - plugin_manager
+    - test_file_preprocessinator
+    - test_runner_generatinator
+    - configurator
     - batchinator
     - loginator
-    - verbosinator
+    - reportinator
 
 test_build_setup:
   compose:
@@ -412,12 +425,77 @@ test_build_setup:
     - batchinator
     - test_context_extractor
     - include_pathinator
-    - preprocessinator
     - defineinator
     - flaginator
     - file_wrapper
     - file_path_utils
+    - file_finder
     - test_runner_manager
+    - dependinator
+    - test_search_paths
+    - mock_locator
+
+test_includes_extractinator:
+  compose:
+    - test_bare_includes_extractinator
+    - test_includes_preprocessinator
+    - test_includes_reconcilinator
+
+test_bare_includes_extractinator:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - batchinator
+    - preprocessinator
+    - file_path_utils
+    - dependinator
+    - test_search_paths
+    - standin_headerinator
+
+test_includes_preprocessinator:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - batchinator
+    - preprocessinator
+    - file_path_utils
+    - file_wrapper
+    - dependinator
+
+test_includes_reconcilinator:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - batchinator
+    - test_context_extractor
+    - preprocessinator
+    - test_search_paths
+    - mock_locator
+
+standin_headerinator:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - file_wrapper
+    - file_path_utils
+    - mock_locator
+
+test_search_paths:
+  compose:
+    - configurator
+    - include_pathinator
+    - test_context_extractor
+
+test_source_file_directive_resolver:
+  compose:
+    - test_context_extractor
+    - file_finder
+    - configurator
+    - loginator
 
 test_build_planner:
   compose:
@@ -426,35 +504,142 @@ test_build_planner:
     - reportinator
     - batchinator
     - test_context_extractor
+    - include_pathinator
     - partializer
     - file_finder
     - file_path_utils
     - file_wrapper
     - plugin_manager
+    - test_source_file_directive_resolver
+    - mock_locator
 
-test_build_executor:
+mock_locator:
+  compose:
+    - configurator
+    - include_pathinator
+    - file_finder
+    - file_path_utils
+
+test_file_preprocessinator:
   compose:
     - configurator
     - loginator
     - reportinator
     - batchinator
     - preprocessinator
-    - partializer
+    - test_context_extractor
+    - file_path_utils
+    - file_wrapper
+    - dependinator
+    - test_source_file_directive_resolver
+
+test_runner_generatinator:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - batchinator
     - generator
     - test_context_extractor
+    - dependinator
+
+test_build_executor:
+  compose:
+    - configurator
+    - loginator
+    - reportinator
+    - batchinator
+    - preprocessinator
+    - generator
     - plugin_manager
     - file_path_utils
     - file_finder
     - file_wrapper
+    - dependinator
+    - gcc_dependency_parser
+    - quote_include_isolator
+    - generator_helper
 
-release_invoker:
+partials_manager:
   compose:
     - configurator
+    - loginator
+    - reportinator
+    - batchinator
+    - preprocessinator
+    - partializer
+    - generator
+    - dependinator
+    - file_path_utils
+
+release_invoker:
+  compose:
+    - application
+    - plugin_manager
+    - dependinator
+    - loginator
     - batchinator
+    - release_build_planner
+    - release_build_executor
+
+release_build_planner:
+  compose:
+    - configurator
+    - loginator
     - reportinator
+    - flaginator
+    - defineinator
+    - file_path_utils
+    - file_wrapper
+
+release_build_executor:
+  compose:
+    - configurator
     - loginator
-    - rake_wrapper
+    - reportinator
+    - batchinator
+    - generator
+    - file_finder
+    - file_wrapper
     - file_path_utils
+    - dependinator
+
+gcc_dependency_parser:
+
+quote_include_isolator:
+  compose:
+    - file_wrapper
+    - loginator
+
+dependency_hasher:
+  compose:
+    - file_wrapper
+
+dependency_path_normalizer:
+  compose:
+    - file_wrapper
+
+dependency_cache_store:
+  compose:
     - file_wrapper
+    - loginator
+
+dependency_debug_tree:
+  compose:
+    - file_wrapper
+    - yaml_wrapper
+
+dependency_differ:
+
+dependency_tracker:
+  compose:
+    - file_wrapper
+    - system_wrapper
+    - loginator
+    - dependency_hasher
+    - dependency_path_normalizer
+    - dependency_cache_store
+    - gcc_dependency_parser
+    - dependency_debug_tree
+    - dependency_differ
 
-erb_wrapper:

data/lib/ceedling/parsing_parcels.rb

@@ -11,9 +11,9 @@ require 'ceedling/encodinator'
 class ParsingParcels
 
   # This parser accepts a collection of lines which it will sweep through and tidy, giving the purified
-  # lines to the block (one line at a time) for further analysis. It analyzes a single line at a time, 
-  # which is far more memory efficient and faster for large files. However, this requires it to also 
-  # handle backslash line continuations as a single line at this point.
+  # lines to the block (one line at a time) for further analysis. Encoding cleanup happens once against
+  # the whole buffer up front; comment-stripping and backslash line continuations are still handled one
+  # logical line at a time after that.
   # @param input [IO, File, String] The input source to parse line by line
   # @yield [line] Gives each cleaned line to the block
   # @yieldparam line [String] The cleaned code line
@@ -22,34 +22,53 @@ class ParsingParcels
   end
 
   # This parser accepts a collection of lines which it will sweep through and tidy, giving the purified
-  # lines to the block (one line at a time) for further analysis along with the line number. It analyzes 
-  # a single line at a time, which is far more memory efficient and faster for large files. However, this 
-  # requires it to also handle backslash line continuations as a single line at this point.
+  # lines to the block (one line at a time) for further analysis along with the line number. Encoding
+  # cleanup happens once against the whole buffer up front; comment-stripping and backslash line
+  # continuations are still handled one logical line at a time after that.
   #
   # @param input [IO, File, String] The input source to parse line by line
-  # @yield [line, line_num] Gives each cleaned line and its line number to the block
+  # @yield [line, line_num, end_line_num] Gives each cleaned line, its starting line number,
+  #   and its ending line number to the block
   # @yieldparam line [String] The cleaned code line
   # @yieldparam line_num [Integer] The line number (1-indexed) where this line appears in the input.
   #   For continuation lines (lines ending with backslash), the line number of the first line in the
   #   continuation sequence is provided.
+  # @yieldparam end_line_num [Integer] The line number (1-indexed) of the LAST physical line this
+  #   logical line spans. Identical to `line_num` for an ordinary, uncontinued line; for a folded
+  #   backslash continuation it's the run's final physical line, not its first. A block that only
+  #   declares 2 params never sees this value -- Ruby silently drops extra yielded values rather
+  #   than raising, so every existing 2-param caller is unaffected by its addition.
   def code_lines_with_num(input)
     comment_block = false
     full_line = ''
     line_num = 0
     continuation_start_line = 0
-    
-    input.each_line do |line|
+
+    # Clean the whole buffer once instead of per line -- clean_encoding's cost
+    # (a double ASCII/UTF-8 transcode) scales with call count as much as with
+    # content size, and this method is the single most fanned-out consumer of
+    # clean_encoding in the codebase. `input` may be an IO (slurp via #read)
+    # or already a String (some callers, e.g. PreprocessinatorReconstructor's
+    # extract_tokens_by_regex_list, pass file contents already in memory) --
+    # either way, the rest of this method works identically off the resulting
+    # String's own #each_line, exactly as it did off the IO's #each_line
+    # before.
+    content = ( input.respond_to?( :read ) ? input.read : input ).clean_encoding
+
+    content.each_line do |line|
       line_num += 1
-      m = line.clean_encoding.match /(.*)\\\s*$/
+      m = line.match( /(.*)\\\s*$/ )
       if (!m.nil?)
         full_line += m[1]
         continuation_start_line = line_num if full_line == m[1]
       elsif full_line.empty?
         _line, comment_block = clean_code_line( line, comment_block )
-        yield( _line, line_num )
+        yield( _line, line_num, line_num )
       else
         _line, comment_block = clean_code_line( full_line + line, comment_block )
-        yield( _line, continuation_start_line )
+        # line_num is still this iteration's own physical line -- the last one the
+        # continuation run folded in -- so it doubles as the run's ending line number.
+        yield( _line, continuation_start_line, line_num )
         full_line = ''
         continuation_start_line = 0
       end
@@ -59,7 +78,14 @@ class ParsingParcels
   private ######################################################################
 
   def clean_code_line(line, comment_block)
-    _line = line.clean_encoding
+    # `line` is already clean_encoding'd content by the time it gets here (see
+    # code_lines_with_num) -- dup rather than re-clean, since this method
+    # mutates _line in place via gsub! below and must not mutate the caller's
+    # string (both call sites -- a bare line from content.each_line, and
+    # full_line + line -- happen to already hand over a fresh, safely-mutable
+    # String today, but dup keeps that an explicit guarantee, not an
+    # incidental one).
+    _line = line.dup
 
     # Remove line comments
     _line.gsub!(/\/\/.*$/, '')

data/lib/ceedling/partials/README.md

@@ -0,0 +1,53 @@
+# Partials
+
+Partials allow a test to exercise a C module's features in ways otherwise impossible. Partials copies selected functions and variables, whole and unmodified, out of their home source file and into a file generated just for one test. These functions and variables are stripped of decorators `static` and `inline` allowing a test to access the variables, call the functions, and CMock to mock the functions like any other. This not only allows access to functions that previously required source rewrites, but it also allows mocking of individual functions inside a module instead of mocking all functions in a header file.
+
+See the detailed documentation for using Partials in `docs/mkdocs/testing-guide/partials/`. This documentation discusses Partials' implementation.
+
+## Where This Fits in a Test Build
+
+Ceedling's test pipeline drives this subsystem through a handful of stages dedicated to Partials. Those stages read a test's Partial configuration, preprocess the real header and source files that a test's Partials depend on, and then generate the Partial files themselves. The stage-by-stage view of that pipeline lives in this codebase's `test_invoker/` documentation. 
+
+## Choosing Functions With Macros
+
+A test file selects its Partials through macros typically located near the top of the file, such as `TEST_PARTIAL_PRIVATE_MODULE(calculator)`. Each macro names a module and a selection mode.
+
+Four selection modes exist, and each answers a different question about where to start. A public mode begins with every one of the module's ordinary, non-`static` functions. A private mode begins with every one of the module's `static` functions instead. An accumulate mode begins with nothing at all. A deduct mode begins with everything, public and private alike.
+
+A second macro, `TEST_PARTIAL_CONFIG` or `MOCK_PARTIAL_CONFIG`, can add or remove specific functions by name to the list the macros described above create. A name written plainly, or with a leading `+`, is an addition. A name written with a leading `-` is a subtraction. An accumulate mode has no baseline to subtract from, so subtractions are not allowed there. A deduct mode already starts with everything, so additions are not allowed there either. Both rules exist because either combination would be a contradiction rather than a meaningful instruction.
+
+A single test file can select both a test side and a mock side for the same module, or for two different modules entirely. It is common, for example, to test a module's public functions directly while mocking one of its private helpers, all from within one test file.
+
+## Reading a Test's Configuration
+
+Before any real C file is touched, a class called `PartializerConfig` scans a test file's own source text for the macro calls discussed in the previous section. It works in three passes. The first pass reads every `MODULE` macro and starts a `Config` record for each module it names. The second pass reads every `CONFIG` macro and fills in that module's additions and subtractions. The third pass checks everything the first two passes built. Each `Config` record describes, for one module, what its Partialized test side and mock side should contain. `Config` and its companion records live together in a shared module called `Partials`, alongside the rest of this subsystem's common vocabulary.
+
+This scan enforces a few rules of its own. A `CONFIG` macro must refer to a module already named by an earlier `MODULE` macro, since a configuration with nothing to configure is meaningless. A module's test side or mock side may only be declared once, since declaring it twice would leave two contradictory instructions in place at once. An accumulate mode with no additions at all is also rejected, since it would describe a Partial with nothing in it.
+
+A further round of checks happens later, once the module's real functions are known. Every function named in an addition or a subtraction must genuinely exist in the module. No function may be named as both an addition and a subtraction on the same side. And subtractions on a public or private side must actually match that side's own visibility, since subtracting a private function from a public selection would be removing something that was never there to begin with.
+
+## Extracting the Real Content
+
+Once a module's configuration is known, a class called `Partializer` locates its real header and source files and hands them off for preprocessing. The preprocessed result is then handed to the c_extractor subsystem, which returns a structured picture of every function, variable, and type the module contains. The header's picture and the source's picture are merged into one combined view of the whole module.
+
+A second class, `PartializerHelper`, finishes preparing that combined view. It traces every function back to its original line number, following it through preprocessing to the real file it came from. This traceability matters later, when a generated file needs to point a coverage tool or a debugger back at the function's true home, rather than at the generated Partial standing in for it. `PartializerHelper` leans on a lower layer of its own, `PartializerUtils`, for the actual text work this requires.
+
+`PartializerHelper` also reconciles each function's visibility against a fully macro-expanded version of the same file. This second pass exists because a project can hide `static` behind a macro of its own, such as `#define PRIVATE static`. A file preprocessed only far enough to preserve macros cannot see through that indirection. A fully expanded file can.
+
+## Promoting Function-Scoped Statics
+
+C allows a `static` variable to live inside a single function, retaining its value between calls while staying invisible to the rest of the file. Once that function is copied into a generated Partial file, this kind of variable becomes a problem. It needs a home at module scope in the new file, with a name that cannot collide with anything else.
+
+`PartializerHelper` solves this by renaming the variable to something unique, built from the function's name and the variable's own name, and moving its declaration out to module scope in the generated file. Inside the function body, the original declaration is replaced with a harmless no-op, and every reference to the old name is rewritten to the new one. `PartializerUtils` supplies the actual no-op and renaming primitives this work is built from. The no-op is written so the total line count of the function does not change, keeping line numbers and coverage data lined up correctly. A test author reaches a promoted variable through a small macro of its own, letting a test read or reset the variable between calls without needing to know the generated name directly.
+
+## Deciding What's Tested and What's Mocked
+
+With the module's content extracted, and its configuration validated, `Partializer` splits the functions into two lists. One list holds `FunctionDefinition` records for the functions destined to be tested directly, each complete with its body. The other holds `FunctionDeclaration` records for the functions destined to be mocked, each needing only its signature. Both record shapes, like `Config`, live in the shared `Partials` module.
+
+A module often has `typedef`s and struct definitions that both lists would otherwise need to repeat. Rather than duplicate that content, and risk defining the same type twice in one test file, it is written once to a shared types file. Both the testable file and the mockable file then include that shared file relying on its internal `#include` guards instead of restating its contents.
+
+A function can never appear in both lists at once. Being directly tested means its real body is compiled into the test. Being mocked means the linker is provided a mock in its place instead. These two things cannot both be true of the same function in the same test, so this case is rejected outright.
+
+## Writing the Generated Files
+
+Once both lists are settled, a separate class named `GeneratorPartials` writes the actual files to disk. It lives outside this directory, alongside Ceedling's other file-writing classes, deliberately kept apart from the classes that decide what belongs in a Partial. A tested module gets an implementation header and source. A mocked module gets an interface header, in the same shape CMock expects for any other header it mocks. Each promoted function is written with a line marker (`#line`) immediately ahead of it, pointing a coverage tool or a debugger back at the function's real, original location rather than at the generated file holding it.