ceedling 1.2.2 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (390) hide show
  1. checksums.yaml +4 -4
  2. data/GIT_COMMIT_SHA +1 -1
  3. data/README.md +1 -1
  4. data/assets/fixtures/tests_with_partials_coverage/src/private_macro.c +7 -0
  5. data/assets/fixtures/tests_with_partials_coverage/src/private_macro.h +5 -0
  6. data/assets/fixtures/tests_with_partials_coverage/src/tally.c +13 -0
  7. data/assets/fixtures/tests_with_partials_coverage/src/tally.h +4 -0
  8. data/assets/fixtures/tests_with_partials_coverage/test/test_private_macro.c +10 -0
  9. data/assets/fixtures/tests_with_partials_coverage/test/test_tally.c +9 -0
  10. data/docs/BreakingChanges.md +16 -0
  11. data/docs/Changelog.md +71 -0
  12. data/docs/KnownIssues.md +91 -4
  13. data/examples/wondrous_forest/README.md +29 -1
  14. data/examples/wondrous_forest/src/ForestUnits.h +23 -0
  15. data/examples/wondrous_forest/src/RainGauge.c +59 -0
  16. data/examples/wondrous_forest/src/RainGauge.h +39 -0
  17. data/examples/wondrous_forest/src/RainTipIsr.c +17 -0
  18. data/examples/wondrous_forest/src/RainTipIsr.h +14 -0
  19. data/examples/wondrous_forest/test/TestRainGauge.c +126 -0
  20. data/lib/ceedling/c_extractor/README.md +15 -7
  21. data/lib/ceedling/c_extractor/c_extractor.rb +25 -14
  22. data/lib/ceedling/c_extractor/c_extractor_code_text.rb +84 -54
  23. data/lib/ceedling/c_extractor/c_extractor_constants.rb +18 -7
  24. data/lib/ceedling/c_extractor/c_extractor_declarations.rb +319 -283
  25. data/lib/ceedling/c_extractor/c_extractor_declarator.rb +285 -0
  26. data/lib/ceedling/c_extractor/c_extractor_defined_type.rb +111 -0
  27. data/lib/ceedling/c_extractor/c_extractor_definitions.rb +174 -121
  28. data/lib/ceedling/c_extractor/c_extractor_functions.rb +191 -162
  29. data/lib/ceedling/c_extractor/c_extractor_preprocessing.rb +46 -55
  30. data/lib/ceedling/c_extractor/c_extractor_statement.rb +30 -0
  31. data/lib/ceedling/c_extractor/c_extractor_types.rb +63 -41
  32. data/lib/ceedling/c_extractor/c_module_edits.rb +48 -0
  33. data/lib/ceedling/c_identifier.rb +21 -0
  34. data/lib/ceedling/ceedling.h +8 -0
  35. data/lib/ceedling/config/configurator.rb +4 -3
  36. data/lib/ceedling/config/configurator_builder.rb +17 -0
  37. data/lib/ceedling/config/configurator_setup.rb +29 -5
  38. data/lib/ceedling/constants.rb +5 -1
  39. data/lib/ceedling/defaults.rb +31 -1
  40. data/lib/ceedling/dependencies/CACHE_SCHEMA.md +118 -0
  41. data/lib/ceedling/dependencies/README.md +1 -1
  42. data/lib/ceedling/dependencies/dependency_cache_store.rb +30 -25
  43. data/lib/ceedling/dependencies/dependency_tracker.rb +9 -3
  44. data/lib/ceedling/dependencies/dependinator.rb +13 -1
  45. data/lib/ceedling/diagnostics/DOCTOR.md +142 -0
  46. data/lib/ceedling/diagnostics/README.md +5 -0
  47. data/lib/ceedling/diagnostics/build_step_doctor.rb +110 -0
  48. data/lib/ceedling/diagnostics/duplicate_symbol_specialist.rb +108 -0
  49. data/lib/ceedling/diagnostics/guidance_phrases.rb +30 -0
  50. data/lib/ceedling/diagnostics/header_collision_guidance.rb +56 -0
  51. data/lib/ceedling/diagnostics/header_collision_specialist.rb +152 -0
  52. data/lib/ceedling/diagnostics/include_depth_specialist.rb +132 -0
  53. data/lib/ceedling/diagnostics/missing_symbol_specialist.rb +111 -0
  54. data/lib/ceedling/diagnostics/partial_name_specialist.rb +134 -0
  55. data/lib/ceedling/diagnostics/toolchain_output.rb +44 -0
  56. data/lib/ceedling/filesystem/PATH_HANDLING.md +83 -27
  57. data/lib/ceedling/filesystem/README.md +6 -1
  58. data/lib/ceedling/filesystem/build_roots.rb +105 -0
  59. data/lib/ceedling/filesystem/build_subpath.rb +110 -25
  60. data/lib/ceedling/filesystem/file_finder.rb +76 -110
  61. data/lib/ceedling/filesystem/file_finder_helper.rb +33 -11
  62. data/lib/ceedling/filesystem/file_path_utils.rb +113 -91
  63. data/lib/ceedling/filesystem/file_wrapper.rb +105 -28
  64. data/lib/ceedling/filesystem/path_matcher.rb +21 -0
  65. data/lib/ceedling/filesystem/test_build_layout.rb +114 -0
  66. data/lib/ceedling/filesystem/win_long_paths.rb +153 -0
  67. data/lib/ceedling/filesystem/win_path_limit.rb +83 -0
  68. data/lib/ceedling/filesystem/win_path_prober.rb +52 -0
  69. data/lib/ceedling/generators/generator.rb +27 -64
  70. data/lib/ceedling/generators/generator_helper.rb +0 -44
  71. data/lib/ceedling/generators/generator_mocks.rb +5 -0
  72. data/lib/ceedling/generators/generator_partials.rb +305 -243
  73. data/lib/ceedling/generators/generator_test_runner.rb +5 -8
  74. data/lib/ceedling/generators/partial_header_writer.rb +95 -0
  75. data/lib/ceedling/generators/partial_source_writer.rb +137 -0
  76. data/lib/ceedling/includes/header_search.rb +225 -0
  77. data/lib/ceedling/includes/include_factory.rb +9 -12
  78. data/lib/ceedling/includes/include_pathinator.rb +53 -31
  79. data/lib/ceedling/includes/includes.rb +149 -37
  80. data/lib/ceedling/objects.yml +89 -4
  81. data/lib/ceedling/partials/README.md +110 -16
  82. data/lib/ceedling/partials/carry_plan.rb +71 -0
  83. data/lib/ceedling/partials/definition_head.rb +74 -0
  84. data/lib/ceedling/partials/include_groups.rb +37 -0
  85. data/lib/ceedling/partials/interface_extras.rb +25 -0
  86. data/lib/ceedling/partials/partializer.rb +599 -120
  87. data/lib/ceedling/partials/partializer_config.rb +5 -0
  88. data/lib/ceedling/partials/partializer_helper.rb +851 -145
  89. data/lib/ceedling/partials/partializer_reconciler.rb +174 -0
  90. data/lib/ceedling/partials/partializer_utils.rb +89 -109
  91. data/lib/ceedling/partials/partials.rb +153 -10
  92. data/lib/ceedling/partials/type_macros.rb +126 -0
  93. data/lib/ceedling/preprocess/README.md +43 -33
  94. data/lib/ceedling/preprocess/preprocessinator.rb +100 -186
  95. data/lib/ceedling/preprocess/preprocessinator_code_finder.rb +65 -72
  96. data/lib/ceedling/preprocess/preprocessinator_file_assembler.rb +31 -75
  97. data/lib/ceedling/preprocess/preprocessinator_reconstructor.rb +51 -14
  98. data/lib/ceedling/setupinator.rb +16 -3
  99. data/lib/ceedling/test_invoker/HEADER_COLLISIONS.md +21 -7
  100. data/lib/ceedling/test_invoker/PIPELINE.md +57 -16
  101. data/lib/ceedling/test_invoker/README.md +1 -1
  102. data/lib/ceedling/test_invoker/derived_search_path_notices.rb +45 -0
  103. data/lib/ceedling/test_invoker/mock_locator.rb +116 -9
  104. data/lib/ceedling/test_invoker/partial_files_preprocessinator.rb +181 -0
  105. data/lib/ceedling/test_invoker/partials_manager.rb +265 -308
  106. data/lib/ceedling/test_invoker/standin_headerinator.rb +8 -15
  107. data/lib/ceedling/test_invoker/test_bare_includes_extractinator.rb +26 -3
  108. data/lib/ceedling/test_invoker/test_build_executor.rb +338 -198
  109. data/lib/ceedling/test_invoker/test_build_planner.rb +13 -19
  110. data/lib/ceedling/test_invoker/test_build_setup.rb +26 -6
  111. data/lib/ceedling/test_invoker/test_build_validations.rb +23 -20
  112. data/lib/ceedling/test_invoker/test_derived_search_paths.rb +189 -0
  113. data/lib/ceedling/test_invoker/test_file_preprocessinator.rb +1 -2
  114. data/lib/ceedling/test_invoker/test_includes_reconcilinator.rb +1 -1
  115. data/lib/ceedling/test_invoker/test_invoker_types.rb +28 -20
  116. data/lib/ceedling/test_invoker/test_pipeline_helpers.rb +5 -3
  117. data/lib/ceedling/test_invoker/test_pipeline_manager.rb +25 -8
  118. data/lib/ceedling/test_invoker/test_runner_generatinator.rb +31 -3
  119. data/lib/ceedling/test_invoker/test_search_paths.rb +30 -8
  120. data/lib/ceedling/test_invoker/test_substitutions.rb +72 -0
  121. data/lib/ceedling/tools/shell_quoting.rb +45 -0
  122. data/lib/ceedling/tools/tool_quoting.rb +79 -0
  123. data/lib/ceedling/{tool_validator.rb → tools/tool_validator.rb} +18 -7
  124. data/lib/version.rb +1 -1
  125. data/plugins/bullseye/bullseye.rake +1 -3
  126. data/plugins/bullseye/lib/bullseye.rb +15 -2
  127. data/plugins/command_hooks/lib/command_hooks.rb +1 -1
  128. data/plugins/fff/lib/fff.rb +42 -15
  129. data/plugins/fff/lib/fff_mock_generator.rb +12 -9
  130. data/plugins/fff/spec/fff_cmock_wrapper_spec.rb +134 -0
  131. data/plugins/fff/spec/fff_mock_header_generator_spec.rb +9 -0
  132. data/plugins/fff/spec/fff_mock_source_generator_spec.rb +20 -0
  133. data/plugins/gcov/lib/console_reportinator.rb +25 -19
  134. data/plugins/gcov/lib/reportgenerator_reportinator.rb +2 -1
  135. data/site-local/404.html +2 -2
  136. data/site-local/assets/javascripts/{bundle.c21346df.min.js → bundle.a5f9d56c.min.js} +1 -1
  137. data/site-local/assets/javascripts/{bundle.c21346df.min.js.map → bundle.a5f9d56c.min.js.map} +2 -2
  138. data/site-local/configuration/environment-vars.html +2 -2
  139. data/site-local/configuration/global-collections.html +3 -3
  140. data/site-local/configuration/index.html +2 -2
  141. data/site-local/configuration/loading.html +2 -2
  142. data/site-local/configuration/mixins.html +2 -2
  143. data/site-local/configuration/parallel-builds.html +2 -2
  144. data/site-local/configuration/project-file.html +2 -2
  145. data/site-local/configuration/reference/cexception.html +2 -2
  146. data/site-local/configuration/reference/cmock.html +5 -2
  147. data/site-local/configuration/reference/defines.html +2 -2
  148. data/site-local/configuration/reference/environment.html +2 -2
  149. data/site-local/configuration/reference/extension.html +2 -2
  150. data/site-local/configuration/reference/files.html +56 -9
  151. data/site-local/configuration/reference/flags.html +2 -2
  152. data/site-local/configuration/reference/index.html +2 -2
  153. data/site-local/configuration/reference/libraries.html +2 -2
  154. data/site-local/configuration/reference/mixins.html +2 -2
  155. data/site-local/configuration/reference/partials.html +84 -2
  156. data/site-local/configuration/reference/paths.html +7 -2
  157. data/site-local/configuration/reference/plugins.html +2 -2
  158. data/site-local/configuration/reference/project.html +247 -5
  159. data/site-local/configuration/reference/release-build.html +2 -2
  160. data/site-local/configuration/reference/test-build.html +2 -2
  161. data/site-local/configuration/reference/test-runner.html +2 -2
  162. data/site-local/configuration/reference/tools.html +49 -4
  163. data/site-local/configuration/reference/unity.html +2 -2
  164. data/site-local/configuration/which-ceedling.html +2 -2
  165. data/site-local/development/index.html +2 -2
  166. data/site-local/development/plugins/configuration.html +2 -2
  167. data/site-local/development/plugins/index.html +2 -2
  168. data/site-local/development/plugins/plugin-subclass.html +5 -4
  169. data/site-local/development/plugins/rake-tasks.html +2 -2
  170. data/site-local/development/releases.html +2 -2
  171. data/site-local/development/workflow.html +2 -2
  172. data/site-local/getting-started/builds.html +2 -2
  173. data/site-local/getting-started/command-line.html +2 -2
  174. data/site-local/getting-started/example-projects/cipher-quest.html +2 -2
  175. data/site-local/getting-started/example-projects/index.html +2 -2
  176. data/site-local/getting-started/example-projects/temp-sensor.html +2 -2
  177. data/site-local/getting-started/example-projects/wondrous-forest.html +10 -2
  178. data/site-local/getting-started/index.html +2 -2
  179. data/site-local/getting-started/installation.html +2 -2
  180. data/site-local/getting-started/quick-start.html +2 -2
  181. data/site-local/help.html +2 -2
  182. data/site-local/index.html +2 -2
  183. data/site-local/overview/build-system.html +2 -2
  184. data/site-local/overview/index.html +2 -2
  185. data/site-local/overview/test-environments.html +2 -2
  186. data/site-local/overview/tools-and-frameworks.html +2 -2
  187. data/site-local/plugins/beep.html +2 -2
  188. data/site-local/plugins/bullseye/index.html +45 -38
  189. data/site-local/plugins/bullseye/licensing.html +2 -2
  190. data/site-local/plugins/command-hooks.html +4 -4
  191. data/site-local/plugins/compile-commands-json-db.html +2 -2
  192. data/site-local/plugins/cppcheck.html +2 -2
  193. data/site-local/plugins/dependencies.html +2 -2
  194. data/site-local/plugins/fff.html +16 -2
  195. data/site-local/plugins/gcov/examples.html +2 -2
  196. data/site-local/plugins/gcov/gcovr.html +8 -2
  197. data/site-local/plugins/gcov/index.html +2 -2
  198. data/site-local/plugins/gcov/overview.html +2 -2
  199. data/site-local/plugins/gcov/reportgenerator.html +18 -14
  200. data/site-local/plugins/gcov/reporting.html +2 -2
  201. data/site-local/plugins/gcov/setup.html +2 -2
  202. data/site-local/plugins/gcov/tool-versions.html +2 -2
  203. data/site-local/plugins/gcov/troubleshooting.html +2 -2
  204. data/site-local/plugins/index.html +2 -2
  205. data/site-local/plugins/module-generator.html +2 -2
  206. data/site-local/plugins/report-build-warnings-log.html +2 -2
  207. data/site-local/plugins/report-tests-gtestlike-stdout.html +2 -2
  208. data/site-local/plugins/report-tests-ide-stdout.html +2 -2
  209. data/site-local/plugins/report-tests-log-factory.html +2 -2
  210. data/site-local/plugins/report-tests-pretty-stdout.html +2 -2
  211. data/site-local/plugins/report-tests-raw-output-log.html +2 -2
  212. data/site-local/plugins/report-tests-teamcity-stdout.html +2 -2
  213. data/site-local/plugins/sanitize.html +2 -2
  214. data/site-local/plugins/valgrind.html +2 -2
  215. data/site-local/project/index.html +2 -2
  216. data/site-local/project/release-history.html +2 -2
  217. data/site-local/project/sbom.html +2 -2
  218. data/site-local/project/upgrade.html +2 -2
  219. data/site-local/reference/build-directives.html +2 -2
  220. data/site-local/reference/command-line.html +2 -2
  221. data/site-local/reference/environment-vars.html +2 -2
  222. data/site-local/reference/gcov-plugin.html +2 -2
  223. data/site-local/reference/global-collections.html +12 -12
  224. data/site-local/reference/index.html +2 -2
  225. data/site-local/reference/partials-macros.html +47 -2
  226. data/site-local/reference/project-configuration.html +2 -2
  227. data/site-local/sitemap.xml.gz +0 -0
  228. data/site-local/snapshot/examples/cipher_quest/index.html +2 -2
  229. data/site-local/snapshot/examples/temp_sensor/index.html +2 -2
  230. data/site-local/snapshot/examples/wondrous_forest/index.html +72 -15
  231. data/site-local/testing-guide/build-directives.html +2 -2
  232. data/site-local/testing-guide/conventions.html +67 -22
  233. data/site-local/testing-guide/frameworks.html +2 -2
  234. data/site-local/testing-guide/index.html +2 -2
  235. data/site-local/testing-guide/partials/configuration.html +31 -4
  236. data/site-local/testing-guide/partials/conventions.html +509 -8
  237. data/site-local/testing-guide/partials/directives.html +4 -3
  238. data/site-local/testing-guide/partials/example.html +2 -2
  239. data/site-local/testing-guide/partials/index.html +2 -2
  240. data/site-local/testing-guide/partials/overview.html +30 -12
  241. data/site-local/testing-guide/partials/variables.html +169 -4
  242. data/site-local/testing-guide/test-cases.html +2 -2
  243. data/site-local/testing-guide/test-sample.html +2 -2
  244. data/site-local/testing-guide/test-suite-anatomy.html +2 -2
  245. data/spec/integration/build_step_doctor_spec.rb +270 -0
  246. data/spec/integration/c_extractor_composition_spec.rb +254 -4
  247. data/spec/integration/includes_extraction_spec.rb +27 -14
  248. data/spec/integration/nested_test_artifacts_spec.rb +1 -1
  249. data/spec/integration/partial_files_preprocessing_spec.rb +128 -0
  250. data/spec/integration/partials_carry_spec.rb +520 -0
  251. data/spec/integration/partials_declarations_spec.rb +655 -0
  252. data/spec/integration/partials_fallback_preprocessing_spec.rb +65 -0
  253. data/spec/integration/partials_function_pointers_spec.rb +277 -0
  254. data/spec/integration/partials_header_composition_spec.rb +268 -35
  255. data/spec/integration/partials_macro_decorators_spec.rb +267 -0
  256. data/spec/integration/partials_module_resolution_spec.rb +26 -19
  257. data/spec/integration/partials_symbol_linkage_spec.rb +13 -0
  258. data/spec/integration/path_length_reporting_spec.rb +64 -0
  259. data/spec/integration/path_scenarios_spec.rb +80 -3
  260. data/spec/integration/quote_include_isolator_spec.rb +56 -0
  261. data/spec/integration/test_build_parallel_barrier_spec.rb +1 -1
  262. data/spec/integration/test_includes_extractinator_spec.rb +70 -5
  263. data/spec/integration/test_naming_spec.rb +6 -3
  264. data/spec/integration/test_source_file_checks_spec.rb +5 -3
  265. data/spec/integration/tool_executor_spec.rb +1 -1
  266. data/spec/integration/tool_validator_spec.rb +2 -2
  267. data/spec/integration/win_long_paths_probe_spec.rb +46 -0
  268. data/spec/integration/win_path_limit_spec.rb +53 -0
  269. data/spec/integration/windows_registry_query_tool_spec.rb +41 -0
  270. data/spec/support/integration/configurator_integration_helper.rb +8 -3
  271. data/spec/support/integration/partial_files_harness.rb +181 -0
  272. data/spec/support/integration/partials_generation_integration_helper.rb +237 -141
  273. data/spec/support/integration/path_scenario_harness.rb +4 -2
  274. data/spec/support/integration/spec_integration_helper.rb +8 -3
  275. data/spec/support/integration/test_includes_harness.rb +56 -35
  276. data/spec/support/integration/tool_executor_integration_helper.rb +14 -2
  277. data/spec/system/bullseye_deployment_spec.rb +2 -0
  278. data/spec/system/delta_builds_spec.rb +26 -12
  279. data/spec/system/encoding_stress_spec.rb +4 -4
  280. data/spec/system/example_wondrous_forest_spec.rb +2 -2
  281. data/spec/system/gcov_deployment_spec.rb +2 -0
  282. data/spec/system/header_include_path_validation_spec.rb +4 -4
  283. data/spec/system/header_search_paths_spec.rb +1083 -0
  284. data/spec/system/mock_include_folders_spec.rb +121 -0
  285. data/spec/system/mockable_header_reassembly_spec.rb +184 -0
  286. data/spec/system/partials_carry_spec.rb +581 -0
  287. data/spec/system/partials_delta_builds_spec.rb +280 -0
  288. data/spec/system/partials_function_pointers_spec.rb +106 -0
  289. data/spec/system/partials_macro_decorators_spec.rb +127 -0
  290. data/spec/system/partials_module_disambiguation_spec.rb +125 -0
  291. data/spec/system/path_handling_probes_spec.rb +16 -12
  292. data/spec/system/pinned_thread_count_spec.rb +4 -4
  293. data/spec/system/preprocessing_fallback_conditionals_spec.rb +1 -1
  294. data/spec/system/short_build_paths_spec.rb +87 -0
  295. data/spec/system/sibling_header_collision_spec.rb +30 -6
  296. data/spec/system/support/bullseye_common_test_cases.rb +42 -0
  297. data/spec/system/support/common_test_cases.rb +2 -2
  298. data/spec/system/support/gcov_partials_test_cases.rb +48 -0
  299. data/spec/system/test_build_layout_spec.rb +209 -0
  300. data/spec/system/test_source_file_directive_spec.rb +35 -5
  301. data/spec/units/c_extractor/c_extractor_code_text_spec.rb +67 -10
  302. data/spec/units/c_extractor/c_extractor_declarations_spec.rb +501 -4
  303. data/spec/units/c_extractor/c_extractor_declarator_spec.rb +245 -0
  304. data/spec/units/c_extractor/c_extractor_defined_type_spec.rb +45 -0
  305. data/spec/units/c_extractor/c_extractor_definitions_spec.rb +163 -3
  306. data/spec/units/c_extractor/c_extractor_functions_spec.rb +462 -21
  307. data/spec/units/c_extractor/c_extractor_preprocessing_spec.rb +39 -0
  308. data/spec/units/c_extractor/c_extractor_spec.rb +4 -4
  309. data/spec/units/c_extractor/c_extractor_types_spec.rb +163 -0
  310. data/spec/units/c_identifier_spec.rb +35 -0
  311. data/spec/units/config/configurator_builder_spec.rb +24 -0
  312. data/spec/units/config/configurator_setup_spec.rb +72 -4
  313. data/spec/units/config/configurator_spec.rb +27 -1
  314. data/spec/units/dependencies/dependency_cache_store_spec.rb +68 -3
  315. data/spec/units/dependencies/dependency_tracker_spec.rb +25 -0
  316. data/spec/units/dependencies/dependinator_spec.rb +17 -2
  317. data/spec/units/diagnostics/build_step_doctor_spec.rb +170 -0
  318. data/spec/units/diagnostics/duplicate_symbol_specialist_spec.rb +117 -0
  319. data/spec/units/diagnostics/header_collision_specialist_spec.rb +267 -0
  320. data/spec/units/diagnostics/include_depth_specialist_spec.rb +137 -0
  321. data/spec/units/diagnostics/missing_symbol_specialist_spec.rb +154 -0
  322. data/spec/units/diagnostics/partial_name_specialist_spec.rb +129 -0
  323. data/spec/units/diagnostics/toolchain_output_spec.rb +86 -0
  324. data/spec/units/encodinator_spec.rb +3 -4
  325. data/spec/units/filesystem/build_roots_spec.rb +131 -0
  326. data/spec/units/filesystem/build_subpath_spec.rb +113 -0
  327. data/spec/units/filesystem/file_finder_helper_spec.rb +80 -0
  328. data/spec/units/filesystem/file_finder_spec.rb +242 -58
  329. data/spec/units/filesystem/file_path_utils_spec.rb +251 -118
  330. data/spec/units/filesystem/file_wrapper_spec.rb +191 -6
  331. data/spec/units/filesystem/path_matcher_spec.rb +36 -0
  332. data/spec/units/filesystem/test_build_layout_spec.rb +216 -0
  333. data/spec/units/filesystem/win_long_paths_spec.rb +204 -0
  334. data/spec/units/filesystem/win_path_prober_spec.rb +158 -0
  335. data/spec/units/generators/generator_helper_spec.rb +0 -60
  336. data/spec/units/generators/generator_mocks_spec.rb +13 -0
  337. data/spec/units/generators/generator_partials_spec.rb +656 -55
  338. data/spec/units/generators/generator_spec.rb +26 -0
  339. data/spec/units/generators/generator_test_runner_spec.rb +9 -5
  340. data/spec/units/generators/partial_source_writer_spec.rb +129 -0
  341. data/spec/units/includes/header_search_spec.rb +406 -0
  342. data/spec/units/includes/include_factory_spec.rb +22 -5
  343. data/spec/units/includes/include_pathinator_spec.rb +77 -13
  344. data/spec/units/includes/include_spec.rb +14 -0
  345. data/spec/units/includes/includes_spec.rb +176 -19
  346. data/spec/units/loginator_spec.rb +31 -0
  347. data/spec/units/mock_locator_spec.rb +199 -5
  348. data/spec/units/partials/include_groups_spec.rb +42 -0
  349. data/spec/units/partials/partializer_config_spec.rb +25 -0
  350. data/spec/units/partials/partializer_helper_carry_spec.rb +661 -0
  351. data/spec/units/partials/partializer_helper_interface_extras_spec.rb +396 -0
  352. data/spec/units/partials/partializer_helper_spec.rb +529 -277
  353. data/spec/units/partials/partializer_reconciler_spec.rb +661 -0
  354. data/spec/units/partials/partializer_spec.rb +1578 -270
  355. data/spec/units/partials/partializer_utils_spec.rb +269 -232
  356. data/spec/units/partials/partials_rename_spec.rb +160 -0
  357. data/spec/units/partials_manager_spec.rb +554 -261
  358. data/spec/units/plugins/bullseye_spec.rb +34 -0
  359. data/spec/units/plugins/console_reportinator_spec.rb +58 -9
  360. data/spec/units/plugins/report_tests_teamcity_stdout_spec.rb +1 -1
  361. data/spec/units/plugins/reportgenerator_reportinator_spec.rb +51 -3
  362. data/spec/units/preprocess/preprocessinator_code_finder_spec.rb +73 -10
  363. data/spec/units/preprocess/preprocessinator_file_assembler_spec.rb +125 -37
  364. data/spec/units/preprocess/preprocessinator_includes_handler_spec.rb +15 -0
  365. data/spec/units/preprocess/preprocessinator_reconstructor_spec.rb +197 -0
  366. data/spec/units/preprocess/preprocessinator_spec.rb +153 -95
  367. data/spec/units/setupinator_spec.rb +51 -0
  368. data/spec/units/standin_headerinator_spec.rb +27 -11
  369. data/spec/units/test_build_executor_spec.rb +780 -166
  370. data/spec/units/test_build_planner_spec.rb +116 -28
  371. data/spec/units/test_build_setup_spec.rb +83 -18
  372. data/spec/units/test_context_extractor_spec.rb +11 -2
  373. data/spec/units/test_derived_search_paths_spec.rb +259 -0
  374. data/spec/units/test_includes_extractinator_spec.rb +56 -8
  375. data/spec/units/test_invoker/objects_wiring_spec.rb +20 -3
  376. data/spec/units/test_invoker/partial_files_preprocessinator_spec.rb +264 -0
  377. data/spec/units/test_invoker/test_substitutions_spec.rb +122 -0
  378. data/spec/units/test_invoker_types_spec.rb +8 -7
  379. data/spec/units/test_pipeline_manager_spec.rb +54 -13
  380. data/spec/units/test_runner_generatinator_spec.rb +93 -1
  381. data/spec/units/test_search_paths_spec.rb +73 -5
  382. data/spec/units/{default_tools_quoting_spec.rb → tools/default_tools_quoting_spec.rb} +39 -5
  383. data/spec/units/tools/shell_quoting_spec.rb +76 -0
  384. data/spec/units/{tool_executor_helper_spec.rb → tools/tool_executor_helper_spec.rb} +1 -1
  385. data/spec/units/{tool_executor_spec.rb → tools/tool_executor_spec.rb} +1 -1
  386. data/spec/units/{tool_validator_spec.rb → tools/tool_validator_spec.rb} +110 -1
  387. data/spec/units/windows_registry_query_tool_spec.rb +53 -0
  388. metadata +161 -16
  389. /data/lib/ceedling/{tool_executor.rb → tools/tool_executor.rb} +0 -0
  390. /data/lib/ceedling/{tool_executor_helper.rb → tools/tool_executor_helper.rb} +0 -0
@@ -6,24 +6,25 @@ Each test file in a run gets its own `Testable` record, and every `Testable` tra
6
6
 
7
7
  ## The pipeline's shape
8
8
 
9
- Nine classes divide the stages, each owning one concern:
9
+ Ten classes divide the stages, each owning one concern:
10
10
 
11
11
  - **`TestInvoker`** owns one test build run from start to finish. It opens the dependency cache before the run and flushes it afterward, and fires the `pre_test_build` and `post_test_build` plugin hooks around it. When anything in the pipeline raises, it catches the exception, logs it, and records the run as a failed build. Once a run finishes, it also answers narrow questions such as which sources a test pulled in, for callers that want dependency information rather than a real build.
12
12
  - **`TestPipelineManager`** owns the stage sequence: the fixed list of stages below, and the feature toggles and stop points that let a stage decline to run. It knows nothing of how a stage does its work, only whether it runs.
13
13
  - **`TestBuildSetup`** does each test's groundwork in stages 1–3: build directories, the text scan of the test file's `#include`s and build directives, and the flags, defines, and search paths every later stage uses.
14
14
  - **`TestIncludesExtractinator`** runs stage 4, which replaces the text scan's `#include`s with what the real preprocessor found. It sequences one class per pass: `TestBareIncludesExtractinator`, `TestIncludesPreprocessinator`, and `TestIncludesReconcilinator`.
15
15
  - **`TestBuildPlanner`** decides what to generate and build: which mocks a test needs, what its runner and Partials will be, and, once everything upstream has run, the final sources, objects, and artifacts to compile and link.
16
- - **`PartialsManager`** preprocesses each Partial's header and source files and generates its implementation, interface, and, when needed, types header, calling on `Partializer` (`lib/ceedling/partials/`) for the C parsing and extraction.
16
+ - **`PartialFilesPreprocessinator`** runs stages 6 and 7, which preprocess each Partial's header and source files, one tracked job per file.
17
+ - **`PartialsManager`** runs stage 8, which generates each Partial's implementation, interface, and, when needed, types and extras headers. It calls on `Partializer` (`lib/ceedling/partials/`) for the C parsing and extraction.
17
18
  - **`TestFilePreprocessinator`** runs stage 11, which preprocesses each test file and extracts its `TEST_SOURCE_FILE()` directives.
18
19
  - **`TestRunnerGeneratinator`** runs stages 12 and 13, which parse test case names and generate each test's Unity runner.
19
20
  - **`TestBuildExecutor`** does the remaining work the planner decided on: generating mocks, compiling objects, linking executables, and running the test fixtures.
20
21
 
21
- The seven stage classes never call each other. `TestPipelineManager` alone sequences them, calling each stage's method on the shared `PipelineState` in turn.
22
+ The eight stage classes never call each other. `TestPipelineManager` alone sequences them, calling each stage's method on the shared `PipelineState` in turn.
22
23
 
23
24
  Three collaborators hold logic more than one stage needs, so the stages cannot drift apart:
24
25
 
25
- - **`TestSearchPaths`** composes a test's search paths in the order the compiler searches them, and sets a test's mock search paths (stages 2, 3, and 4).
26
- - **`MockLocator`** resolves a mock's real header and places the mock: its directory below the test's mock root, the folder and root CMock writes it by, and the directory its `#include` as written reaches it from (stages 2, 4, 5, and 10).
26
+ - **`TestSearchPaths`** composes a test's search paths in the order the compiler searches them, gives the paths its real headers are found through and the paths mock preprocessing reads a mocked header through, and sets a test's mock search paths (stages 2, 3, 4, and 9).
27
+ - **`MockLocator`** finds a test's real headers and places its mocks: a mock's directory below the test's mock root, the folder and root CMock writes it by, and the directory its `#include` as written reaches it from (stages 2, 4, 5, 10, 12, and 13).
27
28
  - **`StandinHeaderinator`** places stand-in headers for mocks and Partials (stage 4).
28
29
 
29
30
  ## `PipelineState` and `Testable`
@@ -32,10 +33,10 @@ Three collaborators hold logic more than one stage needs, so the stages cannot d
32
33
 
33
34
  - **Identity**: a `Testable`'s `filepath` and `name`, set in the first stage and never changed. The name is the test's path from the project root without its extension (`FilePathUtils#form_test_name`), unique in every build, and it keys `PipelineState#testables` and places every per-test directory. A path outside the project writes each `..` as `_up_`, so no name reaches outside the build directory. `FileFinder` maps a name back to its test file exactly, never by search.
34
35
  - **Paths and preprocessing scratch state**: where this test's build output, mocks, Partials, and preprocessed files live, and the bookkeeping preprocessing needs along the way. These stay plain Hashes because their keys are sparse and conditional. A project with mocking disabled has no `:mocks` path at all, which a Hash tolerates better than a struct field with no meaningful default.
35
- - **Flags, defines, and search paths**: the compiler, linker, and preprocessor arguments resolved once per test and reused by every stage that runs a tool. `mock_search_paths` holds the part of `search_paths` that points at this test's mirrored mock directories (see [Mock search paths](#mock-search-paths)), so a stage can take them back out when it needs the ordering without them.
36
+ - **Flags, defines, and search paths**: the compiler, linker, and preprocessor arguments resolved once per test and reused by every stage that runs a tool. `mock_search_paths` holds the part of `search_paths` that points at this test's mirrored mock directories (see [Mock search paths](#mock-search-paths)), so a stage can take them back out when it needs the ordering without them. `derived_search_paths` holds the directories the test's `#include`s imply for headers no search path lists, which end `search_paths`, and `search_path_refusals` explains each header refused one (see [Finding a test's headers](#finding-a-tests-headers)).
36
37
  - **Generated-content records**: `runner` (a `RunnerInfo`), each resolved mock in `mocks` (a `MockDetails`), and `partials` (a `TestablePartials`, holding a config map and the two lists of module names Partials generation has produced so far). These have a fixed shape every instance shares, which is what a struct is for: a mistyped field name fails loudly instead of silently doing nothing.
37
38
  - **Build artifacts and results**: the final sources, objects, and executable path a test resolves to, and where its results are written.
38
- - **`isolated_headers_path`**: set the first time stage 15's sibling-header isolation stages something for this test (see `HEADER_COLLISIONS.md`), and nil otherwise. Stage 15 reads it once more at its end to know what to clean up.
39
+ - **`header_isolation`**: set when stage 15's sibling-header isolation stages something for this test (see `HEADER_COLLISIONS.md`), and nil otherwise. It holds the isolation directory and its copies. Later objects use it to keep the copies out of their dependencies, and stage 15 reads it once more at its end to know what to clean up.
39
40
  - **`executable_rebuilt`**: set by stage 16 and read by stage 17. It is carried rather than re-derived because by the time stage 17 asks, the dependency tracker has already been told the executable is fresh, and asking it again would always answer "no."
40
41
 
41
42
  `PipelineState` carries the run's list of tests, the Hash of every `Testable`, the run's context and options, a `Mutex` guarding concurrent writes, and four accumulator lists: `partials_headers`, `partials_sources`, `mocks_list`, and `objects_list`. These exist so later stages can hand every Partial file, mock, or object across every test to the parallelism machinery as one flat batch instead of one nested loop per test. Each item in them (`PartialWork`, `MockWork`, `ObjectWork`) is a small struct, for the same reason `RunnerInfo` and `MockDetails` are.
@@ -56,19 +57,27 @@ Stages 2 and 3 run before stage 4, so anything they derive from the `#include`s
56
57
  **Context collection (stages 1-4)** finds out what a test needs, without generating or compiling anything.
57
58
 
58
59
  - **Stage 1** names each test, creates its build directories, and creates its `Testable`. It first stops a build that includes a test whose name another test maps onto, which only two paths differing in extension alone, or a path outside the project mapping onto a real `_up_` or `_abs_` directory, can cause.
59
- - **Stage 2** scans the test file as text: its `#include`s, its include path build directives (cached between runs), and its Partials configuration. With test preprocessing off, it also scans `TEST_SOURCE_FILE()` directives and test case names, since nothing later will, and checks this test's `TEST_SOURCE_FILE()` entries. It checks that the test uses mocks or Partials only where the project enables them, and it collects the test's first mock search paths from the text-scan list.
60
+ - **Stage 2** scans the test file as text: its `#include`s, its include path build directives (cached between runs), and its Partials configuration. With test preprocessing off, it also scans `TEST_SOURCE_FILE()` directives and test case names, since nothing later will, and checks this test's `TEST_SOURCE_FILE()` entries. It checks that the test uses mocks or Partials only where the project enables them. From the text-scan list it then derives search paths for headers no search path lists. A test that names one header's mock two ways, as `mock_task.h` and `drivers/mock_task.h` both do for `src/drivers/task.h` under `src/**`, keeps one of them, the `#include` with the most path (`MockLocator#one_per_header`). Two mocks of one header can't both link, and a pathless `#include` reaches the mock the other names. Stage 2 then collects the test's first mock search paths.
60
61
  - **Stage 3** resolves the flags, defines, and search paths every later tool call for this test uses.
61
62
  - **Stage 4** runs only with test preprocessing on. It extracts the test file's `#include`s through the real preprocessor in three passes, described below, ends by replacing the text-scan list with the reconciled one, and narrows the mock search paths to the mocks that remain.
62
63
 
63
64
  **Planning (stage 5)** is where `TestBuildPlanner` decides what this test needs generated: which of its includes are mocks and where each one's real header resolves, what its Partials configuration looks like, and where its runner will live. It checks that every header the test includes exists, and it fires the `pre_test` plugin hook. Nothing is generated yet.
64
65
 
65
- **Partials (stages 6-8)** run only when the project uses Partials and this run has any. A transform first flattens every test's Partials configuration into two lists, one of Partial header files and one of Partial source files, so stages 6 and 7 can preprocess every Partial file across every test as one parallel batch. Stage 8 then generates each Partial's implementation and interface from that output.
66
+ **Partials (stages 6-8)** run only when the project uses Partials and this run has any. A transform first flattens every test's Partials configuration into two lists, one of Partial header files and one of Partial source files. Stages 6 and 7 hand each list to `PartialFilesPreprocessinator`, which preprocesses every Partial file across every test as one parallel batch. Stage 8 then generates each Partial's implementation and interface from that output. It writes each `#include` a Partial carries as the test's search paths reach the header, as the runner does. A Partial whose implementation and interface are already fresh is passed over without extraction.
66
67
 
67
- **Mocks (stages 9-10)** run only when the project uses mocks and this run has any. A transform flattens every test's planned mocks into one list, as the Partials transform does. Stage 9, with mock preprocessing on (`:mocks` or `:all`), preprocesses each header to be mocked. Stage 10 generates each mock's source and header with CMock, into a directory that mirrors its real header's location below the test's mock root. The `:mocking` stop point ends the run here.
68
+ Each Partial file is one job of three preprocessor runs, each feeding a later step:
69
+
70
+ 1. A directives-only run keeps the file's macros and records every file it entered. Fallback has no such run.
71
+ 2. A bare-includes run yields the file's reconciled `#include`s. Assembly then writes the copy stage 8 extracts from.
72
+ 3. A full `-E` expansion shows what a macro hides, such as the `static` that `#define PRIVATE static` supplies. Its own lines are what stage 8 reconciles the extracted code with (see `partials/README.md`).
73
+
74
+ A job is skipped when nothing it read has changed. The project headers named in the raw expansion's line markers are among its dependencies, so editing the header that defines `PRIVATE` reruns it. A job whose full expansion fails leaves no expansion behind and stays stale, so the next run tries again. A file whose directives-only run fails is preprocessed its fallback way, and its record says so for stage 8.
75
+
76
+ **Mocks (stages 9-10)** run only when the project uses mocks and this run has any. A transform flattens every test's planned mocks into one list, as the Partials transform does. Stage 9, with mock preprocessing on (`:mocks` or `:all`), preprocesses each header to be mocked. It searches the test's Partial directories, then its header paths, so a mocked header reaches a header stage 8 generated. The mock root and the mock directories are left out, since they hold CMock's copies of headers, which stage 10 brings up to date only after this stage. The project headers named in its full expansion's line markers are among its dependencies, so editing a header the mocked header includes reruns it. Under `:cmock` ↳ `:treat_inlines: :include`, CMock copies that preprocessed header beside the mock, so its `#include`s are written as the test's search paths reach each header too. A Partial mock is left out, since CMock reads its generated interface header itself. Stage 10 generates each mock's source and header with CMock, into a directory that mirrors its real header's location below the test's mock root. Each mock's record holds CMock's configuration, less its verbosity, which changes only what CMock prints, and the class that writes the mock, which a plugin such as FFF replaces. A mock generated again first loses any copy of its header an earlier `:include` generation left beside it. An FFF fake writes the same copy under `:include`. A test's mock root stays on its search paths even with no mocks left in it, so a copy that outlives its mock would shadow its header in the test's own compile. A copy is a header with its mock beside it, since no build removes a mock. Before stage 9, a transform removes each copy no current mock writes, so the test's compile reads each real header. With test preprocessing, another transform before stage 4 first sets every copy aside under a name no search finds, since stage 4 preprocesses the test through its mock root before any mock is planned and must read each real header. It sets each copy's mock aside too, since the mock may include its header by a text only the copy reaches, and stage 4 places a stand-in in its place, as on a first build. The transform before stage 9 then puts back every mock and the copies current mocks write. A mock under `:include` whose copy is gone is generated again. The `:mocking` stop point ends the run here.
68
77
 
69
78
  Two same-named headers mocked by directory stay distinct through `:cmock` ↳ `:mock_name_include_folder`, on by default. CMock names a mock's include guard and lifecycle functions by the folder its `#include` names, and the runner names its calls by the same `#include`, so the two always agree. `MockLocator#placement` decides where each mock goes, and generation, the planner's mock sources, the stand-ins, and the mock search paths all use it. When the folder ends the header's mirrored subdirectory, the mock stays in the mirrored directory. An `#include` spelling more path than the mirror holds puts its mock at the written path below the test's mock root instead, and one climbing with `..` stays below the mock root with an `_up_` directory for each `..`. The directory the `#include` as written reaches the mock from joins the mock search paths.
70
79
 
71
- **Test file preprocessing and runners (stages 11-13)** work on the test file itself. Stages 11 and 12 run only with test preprocessing on. Stage 11 preprocesses the test file, extracts its `TEST_SOURCE_FILE()` directives from the result, and checks them. Each test checks only its own entries, once, under its own name. Stage 12 parses test case names from that output. Stage 13 always runs and generates the Unity test runner, from the preprocessed test file when there is one and the original otherwise. The `:test_runner` stop point ends the run here.
80
+ **Test file preprocessing and runners (stages 11-13)** work on the test file itself. Stages 11 and 12 run only with test preprocessing on. Stage 11 preprocesses the test file, extracts its `TEST_SOURCE_FILE()` directives from the result, and checks them. Each test checks only its own entries, once, under its own name. Stage 12 parses test case names from that output. Stage 13 always runs and generates the Unity test runner, from the preprocessed test file when there is one and the original otherwise. The runner includes each of the test's headers by the text the test's search paths find it through, its filename whenever that does. The `:test_runner` stop point ends the run here.
72
81
 
73
82
  Each of these stages is skipped when nothing its output is built from has changed, which takes in more than the test file. Stage 11's full expansion reads every header the test reaches, so the project headers named in its line markers are among stage 11's dependencies, as they are for stage 4's second pass. Editing the macro in a header that enables a test case therefore reruns stage 11. When stage 11 is skipped, its `TEST_SOURCE_FILE()` directives are recalled from a cache. Stages 12 and 13 check one runner target. It depends on the test file, the file test case names are parsed from, the runner and Unity configuration, and the test's mock and include lists. With test preprocessing, those lists come from stage 4's reconciliation, so a header that changes which mocks a test has regenerates its runner although the test file is unchanged.
74
83
 
@@ -86,10 +95,12 @@ Stage 4 gets a test file's `#include`s from the real preprocessor, and its three
86
95
 
87
96
  The isolated copy can't open any other header, so an `#include` guarded by a macro another header defines evaluates false there and drops out. The test file's literal `#include` lines are therefore added to GCC's list as candidates, as they are for a mockable header (`Preprocessinator#supplement_with_text_includes`). A candidate survives only if the second pass confirms it.
88
97
 
89
- Stand-ins are placed for every candidate mock and Partial (see [Stand-in headers](#stand-in-headers)). A mock on GCC's list must have a real header. A mock only the text scan found may sit in a branch that is off and name a header that doesn't exist, so it gets no stand-in then. The test's mock search paths are then set from the candidates' mocks.
98
+ Stand-ins are placed for every candidate mock and Partial (see [Stand-in headers](#stand-in-headers)), each by its `#include` anchored to the test file's directory, as the text scan anchors it. A climbing `../x/mock_foo.h` is placed as `x/mock_foo.h`, where stages 5 and 10 place its mock. A mock on GCC's list must have a real header. A mock only the text scan found may sit in a branch that is off and name a header that doesn't exist, so it gets no stand-in then. The test's mock search paths are then set from the candidates' mocks. Both lists then keep one mock per real header, as stage 2's does, so reconciliation keeps one mock. Every spelling keeps its stand-in, since the test file still includes each. The cache keeps GCC's list as it came.
90
99
  2. **Preprocessed includes** (`TestIncludesPreprocessinator`). The preprocessor runs over the test file with `-fdirectives-only`, using the test's full search paths. This pass follows `#include`s, through the stand-ins into the headers they name, so it sees what the compile will see. Its output records which `#include`s came from the test file itself. Because the output depends on every file the pass read, the project files its line markers show it entered are registered as its dependencies, as a compile registers its `.d` file, so editing a header the test reaches reruns it. Generated files below the build root, such as stand-ins and mocks, are left out.
91
100
  3. **Reconciliation** (`TestIncludesReconcilinator`). The user and system `#include`s from pass 2 are checked against the candidates plus any `#include` a macro names, as resolved by pass 2's output (`Preprocessinator#supplement_with_computed_includes`). The result replaces the stored text-scan list, and the mock search paths narrow to the mocks that remain.
92
101
 
102
+ Each bare entry pairs with one candidate, the most constrained entry first, so a pathless `config.h` never takes the header `app/config.h` names (see `preprocess/README.md`). A mock keeps the text of its `#include`, since CMock and the runner name the mock by it. The text comes from the first bare entry that names the mock, anchored to the test file's directory as the text scan anchors it. Pass 1's entry comes first. It holds the `#include` as the test wrote it, less a leading `./`, or the text a macro the isolated copy sees expands to. Pass 2 found the mock at its place below its mirror root, which can carry folders the `#include` never wrote. A mock that only a computed `#include`'s line-marker path names keeps that place, since no text names it.
103
+
93
104
  If pass 2 failed for one file, that file's text-scan includes take its place, checked against GCC's list alone. The candidates hold those same text-scan includes, so checking against them would keep every one, including mocks in branches that are off. GCC's list still evaluated those branches. If GCC's list is empty too, nothing is left to check the text scan against. Stage 2's list then stands as it is, the Partial headers its configuration added included. That is a best effort, and mocks in branches that are off stay with it.
94
105
 
95
106
  Reconciliation never replaces a non-empty text-scan list with an empty one. An empty result while the test file's text names `#include`s means preprocessing found none it should have. Ingesting it would replace the test's header and source `#include`s at once. Stage 2's list stands instead, and a warning at default verbosity names the file. Configuration validation rejects the usual cause in advance: `-P` and `--no-line-commands`, which drop the line markers pass 2 is read through (see `preprocess/README.md`).
@@ -104,7 +115,7 @@ One shape still escapes: an `#include` of a mock that a macro from another heade
104
115
 
105
116
  A stand-in is a file placed where a test's mock or Partial header will later be generated. The preprocessor needs something to find at each mocked or Partialized `#include` before stage 8 or stage 10 has produced the real file. A stand-in sits exactly where the real file will: a mock's mirrors its real header's directory below the test's mock root, a Partial mock's follows its own `#include`'s path below that root, and a Partial's follows the directory its generated `#include` names.
106
117
 
107
- A mock's stand-in includes the mock's real header, the line CMock opens the generated mock with (`:orig_header_include_fmt` around the header's name). A macro the header defines is then visible to pass 2 through the stand-in, as it will be through the real mock. A Partial's stand-in is blank. Every stand-in starts with a marker line that tells it apart from a real mock.
118
+ A mock's stand-in includes the mock's real header, the line CMock opens the generated mock with (`:orig_header_include_fmt` around the text the mock includes the header by). A macro the header defines is then visible to pass 2 through the stand-in, as it will be through the real mock. A Partial's stand-in is blank. Every stand-in starts with a marker line that tells it apart from a real mock.
108
119
 
109
120
  Pass 1 places stand-ins whether its list was just extracted or recalled from cache, since a cached list says nothing about whether its stand-ins survived. A real mock or Partial already at a stand-in's path is left alone, as is a stand-in that is already current. Mock generation tracks the file at a mock's path as an input, so rewriting one would invalidate the mock for no reason. A stand-in that is out of date, such as a blank one an earlier version wrote, is rewritten.
110
121
 
@@ -118,9 +129,31 @@ Where the paths come from follows which `#include` list drives the build:
118
129
  - **Stage 4's first pass** replaces them with the directories of the candidates' mocks. Reconciliation draws only on the candidates, so these cover every mock the build will use, including one only the preprocessor sees, such as one a macro names. The paths must be settled here, not later, because pass 2 already needs them to find the stand-ins.
119
130
  - **Stage 4's third pass** narrows them to the reconciled list's mocks, dropping directories for candidates the preprocessor discarded.
120
131
 
121
- Every stage that resolves a mock's header does so through `MockLocator`, against the test's search paths minus its `mock_search_paths`, so stages 2, 4, and 5 resolve each mock identically.
132
+ Every stage that resolves a mock's header does so through `MockLocator`, so stages 2, 4, and 5 resolve each mock identically (see [Finding a test's headers](#finding-a-tests-headers)).
133
+
134
+ ## Finding a test's headers
135
+
136
+ A test's real headers are found as its compiler finds them. `MockLocator#header_search` builds a `HeaderSearch` (`lib/ceedling/includes/header_search.rb`) over the test's header paths, `TestSearchPaths#header_paths`. Those are the test's search paths without the directories its mocks and Partials are generated in, which hold no real headers. CMock's copy of a header under `:treat_inlines: :include` sits in a mock directory, so it is never taken for the real one.
137
+
138
+ `HeaderSearch#header_candidates` gives the headers a query names, the compiler's choice first. It tries three ways in turn and stops at the first that finds anything:
139
+
140
+ 1. **Join.** Each search path in order, joined with the query's path. A bare name joins to a search path's own listing, so it finds exactly what a flat listing of every search path holds. A query that climbs with `..`, is absolute, or holds a glob character is never joined.
141
+ 2. **Trailing match.** A header directly in a search path whose trailing path is the query. A mock that only a computed `#include`'s line-marker path names takes its place below its mirror root as its `#include` at stage 4, and that place need not join to a search path.
142
+ 3. **The query itself.** A header the query names that lies below a search path. A plain `#include` after stage 4 carries the path GCC found it by, such as `src/drivers/foo.h` for `"drivers/foo.h"` with `-Isrc`.
143
+
144
+ A mock reconciled from a preprocessed test file keeps the text of its `#include`, so stage 4's third pass and stage 5 find its header as without test preprocessing, the join first. `HeaderSearch#joins?` checks a join alone, as the compiler's `-I` does.
122
145
 
123
- Resolving needs every header on those search paths, in search order. `IncludePathinator#ordered_header_files` builds that list from each search path's own listing. A directory outside the build root keeps its listing for the whole test build: the build never writes there, and every stage asks for the same directories for every test. A directory under the build root, such as a mock or Partials directory, is listed on every call, since the build fills it as it runs. Stage 5 builds the list once per test and shares it across the test's mocks. `TestInvoker` forgets the listings at the start of each test build, after the `pre_test_build` hook.
146
+ An `#include`'s **spelling** is the text it names its header by, between its quotes or angle brackets. One header can have several spellings. With `src` and `src/drivers` both search paths, `foo.h` and `drivers/foo.h` both name `src/drivers/foo.h`. A spelling **reaches** a header when the compiler, joining it with each search path in order, finds that header first. A file Ceedling generates lives in the build directory, away from the file it comes from, so it reaches a header only through the search paths. It includes each header by a spelling that reaches it or, where no spelling reaches it, by its absolute path. A **respelling** replaces a text that reaches another header, or none. A path's spelling, in `lib/ceedling/filesystem/PATH_HANDLING.md`, is a separate idea: the form one path to a place is written in.
147
+
148
+ `HeaderSearch#spelling` gives a spelling that reaches a header. Stage 13 writes it into the runner, and stages 8 and 9 into the files they generate (`Include#spelled_by`). Each spells the header the compiler found. A preprocessed file's `#include` holds that header's path, which names the header itself (`HeaderSearch#at`), since a later search path joined with it could name another. A text scan's holds the `#include` as written, which names a header beside its file first. An `#include` keeps its text wherever that already reaches the header. An `#include` of a header no search path reaches by any spelling is written by that header's absolute path, which reaches it from the build directory too. That holds for a preprocessed file's `#include` and for a text scan's of the header beside its file. A header in the build root, such as a generated Partial's, keeps its text instead, since the compiler's own search paths reach it. Build files are temporary, so the absolute path costs nothing. A text scan's `#include` with no header beside its file is spelled by the header the search paths find, which the compiler finds from the build directory. One whose header isn't found keeps its text. `HeaderSearch#hint_files` lists every header a search looked at, so a header missing only by letter case is named.
149
+
150
+ Each search lists a directory once and indexes its headers by filename. Behind it, `IncludePathinator#header_listing` keeps a directory outside the build root listed for the whole test build: the build never writes there, and every stage asks for the same directories for every test. A directory under the build root, such as a vendor path, is listed afresh for each search, since a plugin or the build itself can write headers there as it runs. Stage 5 builds one search per test and shares it across the test's mocks and its `#include` validation. `TestInvoker` forgets the listings at the start of each test build, after the `pre_test_build` hook.
151
+
152
+ A header whose own directory no search path lists, as is usual for one that only `:files` ↳ `:include` supplies, is out of the compiler's reach. Stage 2's `TestDerivedSearchPaths` walks the text-scan list for an `#include` whose text joins to nothing, and finds its header among the search paths' or the collection's headers. When no search path lists that header's own directory, the test gets the directory its `#include` implies: the header's path with the compiled `#include` text taken off its end (`PathMatcher.strip_tail`). For a mock that text is the one the mock writes, its folder and header name, or the name alone without `:mock_name_include_folder`. Each directory is logged as a NOTICE once a build, naming the first test that needed it, and stored in `derived_search_paths`. `TestSearchPaths#compose` puts them after every configured path, so they never shadow a configured header, and stage 4's stand-ins, stage 9's mock preprocessing, and every compile reach the header through them.
153
+
154
+ CMock includes a mock's real header by the folder the test named the mock by and the header's filename, as `drivers/foo.h` for `drivers/mock_foo.h`. A search path listing only the header's own directory, as `src/drivers/**` does, joins no such folder. Stage 5 then records a respelling, the spelling the search paths reach the header by (`MockLocator#header_respelling`), here `foo.h`, in the mock's `MockDetails#header_include`. Stage 10 records it so a change regenerates the mock. An FFF fake includes the header by it. CMock writes it into `:orig_header_include_fmt` only where the format's text is the whole operand, between quotes or angle brackets (`MockLocator#respellable_format?`). Under `:cmock` ↳ `:treat_inlines: :include` CMock keeps its own text, which reaches the copy of the header it writes beside the mock. CMock's text, and a fake's, stays wherever it reaches a header, even a same-named one the mock wasn't located by, since the compiler includes that one. It stays for a folder that climbs with `..` too. A stand-in includes the header by the respelling wherever the format takes one (`MockLocator#header_include`), even under `:include`, since CMock's copy doesn't exist when stage 4 writes the stand-in. Stage 2 derives no search path for that folder. One could hold a project header named like a system one, such as `string.h`, which `-I` puts ahead of the system's.
155
+
156
+ Some `#include`s get no derived directory. One that climbs with `..`, including one the scan rewrote against the test file's directory (`Include#directory_relative?`), resolves without a search path, and so does an absolute one. A header below the build root is Ceedling's own. A bare name for a header outside the working directory would give the header's own directory, which can hold forwarding headers such as glibc's `sys/`. Stage 2 records a refusal for it in `search_path_refusals` instead, under each name the header's failed lookup can report: a mock's query, or a plain `#include`'s query with each configured header extension, since `FileFinder#find_header_file` reports the last it tries. Every stage looks a test's mocks up first, so a mock's refusal explains a name it shares with a plain `#include`. The test's `HeaderSearch` carries the refusals, so the header's failed lookup raises an error that explains the refusal and suggests an `#include` that references the parent folder (`HeaderSearch#refusal`). An `#include` that test preprocessing removes is never looked up, so its refusal never shows.
124
157
 
125
158
  ## Stop points
126
159
 
@@ -137,7 +170,15 @@ A fifth option, `:refresh_dependencies`, is not a stop point, and no stage reads
137
170
 
138
171
  There is no "stop the pipeline" signal. Every stage is still visited, and each carries a condition that checks `PipelineState#options` and skips the stage when there is nothing to do. A `:mocking` run doesn't end the loop after stage 10; stages 11 through 17 are visited and each declines to run. Feature toggles work the same way: with Partials disabled, stages 6-8 skip by the same mechanism.
139
172
 
140
- The three Partials stages and the two mock stages carry a second check. A project can enable Partials or mocking while a particular run has none of that work, such as a `test:pattern` run over files that use neither. The stage then declines to run as if the feature were off, but logs one line at OBNOXIOUS verbosity saying there was nothing to do, so a narrow run isn't left with headings that have nothing under them.
173
+ The three Partials stages and the two mock stages carry a second check. A project can enable Partials or mocking while a particular run has none of that work, such as a `test:pattern` run over files that use neither. The stage then declines to run as if the feature were off, but logs one line at OBNOXIOUS verbosity saying there was nothing to do, so a narrow run isn't left with headings that have nothing under them. Stage 9 also declines when every mock in the run is a Partial's.
174
+
175
+ ## Guidance from failed build steps
176
+
177
+ A failed compilation or link in stages 15 and 16 gets an explanation, where Ceedling can offer one, before its error is raised. `TestBuildExecutor` hands the tool's output and the inputs it ran with to `BuildStepDoctor` (see `diagnostics/DOCTOR.md`). Specialists recognize failures whose cause lies in Ceedling's conventions: a header colliding with its own substitute, headers colliding in a shared directory, a missing symbol, or a symbol defined twice. Each one that applies logs a notice, so one failure can draw several. The tool's error is still raised.
178
+
179
+ A compilation is diagnosed with its first attempt's `.d` file, whose paths are the real headers, even when sibling-header isolation's retry produced the failure. Preprocessing is connected only where a failure stops the build: the full expansions of a test file and of a header to be mocked. Ceedling's other preprocessor runs are expected to fail at times and fall back, so their failures yield little useful guidance.
180
+
181
+ Stage 15's compilation threads share one doctor without a lock. The doctor fixes its diagnoses when it is built and only reads them afterward.
141
182
 
142
183
  ## Parallelism
143
184
 
@@ -3,4 +3,4 @@
3
3
  This directory implements Ceedling's test-build pipeline -- from a list of test-file paths to compiled, linked, executed test results.
4
4
 
5
5
  - **`PIPELINE.md`** -- the pipeline's overall architecture: its stages, the classes that own them, and the state (`PipelineState`, `Testable`) they share.
6
- - **`HEADER_COLLISIONS.md`** -- how a mock or Partial's substitution can be silently bypassed by the real header it's meant to replace, why that happens, and the two mechanisms (`TestBuildExecutor`) that address it.
6
+ - **`HEADER_COLLISIONS.md`** -- how a mock or Partial's substitution can be silently bypassed by the real header it's meant to replace, why that happens, how `TestBuildExecutor` prevents it, and how the build step doctor explains a collision prevention can't resolve.
@@ -0,0 +1,45 @@
1
+ # =========================================================================
2
+ # Ceedling - Test-Centered Build System for C
3
+ # ThrowTheSwitch.org
4
+ # Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
5
+ # SPDX-License-Identifier: MIT
6
+ # =========================================================================
7
+
8
+ require 'set'
9
+ require 'ceedling/constants'
10
+ require 'ceedling/filesystem/project_paths'
11
+
12
+ # The NOTICE for each search path a test's #includes imply. Each directory is logged once
13
+ # a build, however many tests need it, naming the first.
14
+ class DerivedSearchPathNotices
15
+
16
+ def initialize(loginator:)
17
+ @loginator = loginator
18
+ @noticed = Set.new
19
+ @lock = Mutex.new
20
+ end
21
+
22
+ def forget
23
+ @lock.synchronize { @noticed.clear }
24
+ end
25
+
26
+ def added(testable, root, text, header)
27
+ return unless first?( location( root ) )
28
+
29
+ msg = "Added search path '#{root}' for #{testable.filepath} after every configured search path, so \"#{text}\" reaches #{header}."
30
+ @loginator.log( msg, Verbosity::COMPLAIN, LogLabels::NOTICE )
31
+ end
32
+
33
+ private
34
+
35
+ def first?(key)
36
+ return !@lock.synchronize { @noticed.add?( key ) }.nil?
37
+ end
38
+
39
+ # Windows compares paths without regard to case
40
+ def location(path)
41
+ absolute = ProjectPaths.absolute( path )
42
+ return ProjectPaths::WINDOWS ? absolute.downcase : absolute
43
+ end
44
+
45
+ end
@@ -8,12 +8,15 @@
8
8
  require 'ceedling/constants'
9
9
  require 'ceedling/filesystem/build_subpath'
10
10
  require 'ceedling/filesystem/path_matcher'
11
+ require 'ceedling/filesystem/project_paths'
11
12
  require 'ceedling/test_invoker/test_pipeline_helpers'
12
13
 
13
14
  # Where a test's mocks come from and where they go. A mock's real header resolves
14
- # against the test's search paths, and the mock is written to a directory below the
15
- # test's mock root mirroring that header's location. Stand-ins, mock search paths, and
16
- # the real mock must all agree on that directory, so every stage locates mocks here.
15
+ # through the test's search paths as the compiler resolves it, and the mock is written to
16
+ # a directory below the test's mock root mirroring that header's location. Stand-ins,
17
+ # mock search paths, and the real mock must all agree on that directory, so every stage
18
+ # locates mocks here. A stand-in includes the real header as its mock does, except where the
19
+ # mock includes CMock's copy of it.
17
20
  class MockLocator
18
21
 
19
22
  include TestPipelineHelpers
@@ -23,12 +26,16 @@ class MockLocator
23
26
  # the mock from (`reach`), which a search path must name
24
27
  MockPlacement = Struct.new( :folder, :directory, :root, :reach, keyword_init: true )
25
28
 
26
- constructor :configurator, :include_pathinator, :file_finder, :file_path_utils
29
+ # An :orig_header_include_fmt whose text is the whole operand, between quotes or brackets
30
+ OPERAND_FORMAT = /\A\s*#\s*include\s*(?:"%s"|<%s>)\s*\z/
27
31
 
28
- # The headers a test's mocks resolve against: those on its search paths, in search
29
- # order, without its own mock directories, which hold mocks rather than real headers
30
- def header_collection(search_paths, mock_search_paths = [])
31
- return @include_pathinator.ordered_header_files( search_paths - mock_search_paths )
32
+ constructor :configurator, :include_pathinator, :test_search_paths, :file_finder, :file_path_utils
33
+
34
+ # How a test's real headers are found: through its search paths in order, without the
35
+ # directories its mocks and Partials are generated in, which hold no real headers. A
36
+ # header that stage 2 refused a search path explains its failed lookup.
37
+ def header_search(testable)
38
+ return @include_pathinator.header_search( @test_search_paths.header_paths( testable ), refusals: testable.search_path_refusals )
32
39
  end
33
40
 
34
41
  # A mock's real header and the subdirectory mirroring its location. `complain` sets
@@ -37,6 +44,22 @@ class MockLocator
37
44
  return @file_finder.resolve_mock( include.filepath, collection: collection, complain: complain )
38
45
  end
39
46
 
47
+ # The #includes with one mock per real header. A test can name one header's mock two ways,
48
+ # as `mock_task.h` and `drivers/mock_task.h` do for src/drivers/task.h under src/**. CMock
49
+ # and the runner would make two mocks of it, which can't both link. The #include with the
50
+ # most path stays, the first among equals, since a pathless one reaches that mock too.
51
+ # Test preprocessing rebuilds the test file with the kept spelling alone.
52
+ # A climbing #include is looked up anchored to `from` and kept as written. Every other
53
+ # #include, a Partial mock, and a mock whose header isn't found pass through. Two mocks of
54
+ # one header share a filename, so only a repeated filename is looked up.
55
+ def one_per_header(includes, collection:, from: nil)
56
+ lookups = includes.map { |include| from ? include.anchored( from ) : include }
57
+ headers = repeated_mock_headers( lookups, collection )
58
+ kept = header_keepers( lookups, headers )
59
+
60
+ return includes.select.with_index { |_, index| headers[index].nil? or kept[headers[index]] == index }
61
+ end
62
+
40
63
  # Each mock's mirrored directory below `mocks_root`, once each. A Partial mock has no
41
64
  # real header and lives in the root itself, and a mock whose missing header the caller
42
65
  # tolerates has no directory.
@@ -72,13 +95,97 @@ class MockLocator
72
95
  def placement(mocks_root:, subdir:, include_path:)
73
96
  written = written_folder( include_path )
74
97
  spot = written.nil? ? mirrored_spot( mocks_root, subdir ) : written_spot( mocks_root, subdir.to_s, written )
75
- folder = @configurator.cmock_mock_name_include_folder ? written : nil
98
+ folder = cmock_folder( include_path )
76
99
 
77
100
  return MockPlacement.new( folder: folder, directory: spot[:directory], root: (folder ? spot[:reach] : spot[:directory]), reach: spot[:reach] )
78
101
  end
79
102
 
103
+ # The text the stand-in for the mock `include` names includes its real `header` by, inside
104
+ # :orig_header_include_fmt. It's CMock's, the folder CMock is given and the header's
105
+ # filename, unless the format takes a respelling (`header_respelling`). The mock includes the
106
+ # same text, except under :treat_inlines :include, where CMock's reaches its copy of the
107
+ # header. The copy doesn't exist yet when the stand-in is written.
108
+ def header_include(include, header, search)
109
+ respelled = header_respelling( include, header, search )
110
+ return (respelled and respellable_format?) ? respelled : cmock_header_include( include.filepath, header )
111
+ end
112
+
113
+ # A respelling of the #include a mock opens with: the spelling `search` reaches its real
114
+ # `header` by (see HeaderSearch on spellings), in place of CMock's, when CMock's reaches no
115
+ # header, as through a search path listing the header's own directory. Nil when CMock's
116
+ # reaches a header, or nothing reaches this one. It's the whole operand of the #include. An
117
+ # FFF fake writes it as it is, and CMock and a stand-in only into a format that takes it.
118
+ #
119
+ # CMock's stays wherever the respelling can't be judged:
120
+ # - CMock's reaches a same-named header. The compiler includes that one, whichever header
121
+ # the mock was located by.
122
+ # - Its folder climbs. The compiler joins `..` as written, which a search can't follow.
123
+ # - It's a Partial mock, whose header is Ceedling's own, in the mock root.
124
+ def header_respelling(include, header, search)
125
+ return nil if mock_partial?( include )
126
+
127
+ written = cmock_header_include( include.filepath, header )
128
+ return nil if ProjectPaths.segments( written ).include?( '..' ) or search.joins?( written )
129
+
130
+ return search.spelling( header )
131
+ end
132
+
133
+ # Whether :orig_header_include_fmt takes a respelling: its text is the whole operand, between
134
+ # quotes or angle brackets. A respelling is never weighed with more around it.
135
+ def respellable_format?
136
+ return header_include_format.match?( OPERAND_FORMAT )
137
+ end
138
+
139
+ # The line CMock opens a mock with: its :orig_header_include_fmt around `text`
140
+ def header_include_line(text)
141
+ return header_include_format.gsub( '%s' ) { text }
142
+ end
143
+
80
144
  private
81
145
 
146
+ # Each lookup's real header where its filename repeats, or nil
147
+ def repeated_mock_headers(lookups, collection)
148
+ repeated = lookups.map( &:filename ).tally
149
+ return lookups.map { |lookup| repeated[lookup.filename] > 1 ? real_header( lookup, collection ) : nil }
150
+ end
151
+
152
+ # The index kept for each header: the most path, the first among equals
153
+ def header_keepers(lookups, headers)
154
+ length = ->(index) { ProjectPaths.segments( lookups[index].filepath ).length }
155
+ kept = {}
156
+ headers.each_with_index do |header, index|
157
+ next if header.nil? or (kept[header] and length.( index ) <= length.( kept[header] ))
158
+
159
+ kept[header] = index
160
+ end
161
+
162
+ return kept
163
+ end
164
+
165
+ # A mock's real header, by its absolute path, or nil for anything but a found mock's
166
+ def real_header(include, collection)
167
+ return nil if include.is_a?( SystemInclude ) or !include.filename.start_with?( @configurator.cmock_mock_prefix )
168
+ return nil if mock_partial?( include )
169
+
170
+ source, _ = locate( include, collection: collection, complain: :silent )
171
+ return source && ProjectPaths.absolute( source )
172
+ end
173
+
174
+ def header_include_format
175
+ return @configurator.get_cmock_config[:orig_header_include_fmt] || '#include "%s"'
176
+ end
177
+
178
+ # The folder CMock is given for a mock's #include, or nil without :mock_name_include_folder
179
+ def cmock_folder(include_path)
180
+ return @configurator.cmock_mock_name_include_folder ? written_folder( include_path ) : nil
181
+ end
182
+
183
+ # The text CMock includes a mock's real header by
184
+ def cmock_header_include(include_path, header)
185
+ folder = cmock_folder( include_path )
186
+ return folder.nil? ? File.basename( header ) : File.join( folder, File.basename( header ) )
187
+ end
188
+
82
189
  # The folder of a mock's #include as written, without a leading ./, or nil for none
83
190
  def written_folder(include_path)
84
191
  folder = File.dirname( include_path.to_s ).sub( %r{\A(?:\./)+}, '' )
@@ -0,0 +1,181 @@
1
+ # =========================================================================
2
+ # Ceedling - Test-Centered Build System for C
3
+ # ThrowTheSwitch.org
4
+ # Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
5
+ # SPDX-License-Identifier: MIT
6
+ # =========================================================================
7
+
8
+ require 'ceedling/constants'
9
+ require 'ceedling/test_invoker/test_pipeline_helpers'
10
+
11
+ # Stages 6 and 7. Each Partial header (stage 6) and source (stage 7) is preprocessed in one
12
+ # job, and each job's three runs feed a later step:
13
+ # 1. A -fdirectives-only run keeps macros and records every file it entered. It is
14
+ # skipped in fallback, without -fdirectives-only.
15
+ # 2. A bare-includes run, checked against that output or in fallback the file's own
16
+ # text, yields the reconciled #includes. Assembly then writes the copy extraction parses.
17
+ # 3. A full expansion shows what a macro hides. Its own lines are what reconciliation
18
+ # parses.
19
+ #
20
+ # The job's target is the assembled copy. Its dependencies are the file itself and every
21
+ # project header the full expansion entered, so editing a macro in any of them reruns
22
+ # the job. A job whose expansion fails is left stale, and its expansion is gone, so the
23
+ # next run tries again rather than reading an earlier run's expansion.
24
+ #
25
+ # A fresh job's record is rebuilt from the files its last run left. Each run either
26
+ # leaves a file or removes it, so a file's presence says what that run produced.
27
+ class PartialFilesPreprocessinator
28
+
29
+ include TestPipelineHelpers
30
+
31
+ # How each stage names the files it preprocesses
32
+ NOUNS = { header: 'headers', source: 'sources' }.freeze
33
+
34
+ # The tools a job runs, each of which shapes its outputs
35
+ TOOLS = %i[tools_test_file_directives_only_preprocessor tools_test_bare_includes_preprocessor tools_test_file_full_preprocessor].freeze
36
+
37
+ # Where each file a job reads or writes lives
38
+ PATHS = {
39
+ target: :form_preprocessed_file_filepath,
40
+ raw_directives_only: :form_preprocessed_file_raw_directives_only_filepath,
41
+ raw_expansion: :form_preprocessed_file_full_expansion_filepath,
42
+ expanded_code: :form_preprocessed_file_expanded_code_filepath,
43
+ includes_list: :form_preprocessed_includes_list_filepath
44
+ }.freeze
45
+
46
+ constructor :configurator, :loginator, :reportinator, :batchinator, :preprocessinator, :file_path_utils, :file_wrapper,
47
+ :dependinator
48
+
49
+ # Stage 6
50
+ def preprocess_headers(state)
51
+ preprocess( state, state.partials_headers, :header )
52
+ end
53
+
54
+ # Stage 7
55
+ def preprocess_sources(state)
56
+ preprocess( state, state.partials_sources, :source )
57
+ end
58
+
59
+ private
60
+
61
+ def preprocess(state, items, kind)
62
+ skipped = 0
63
+
64
+ @batchinator.exec( workload: :compile, things: items ) do |work|
65
+ target = register( work )
66
+ next generate( work, target, kind ) if stale?( work, target )
67
+
68
+ recall( work, target, kind )
69
+ state.lock.synchronize { skipped += 1 }
70
+ end
71
+
72
+ log_skip_summary( task: "partial #{kind} preprocessing", count: skipped, noun: NOUNS[kind] )
73
+ end
74
+
75
+ # The target path is deterministic, so it is registered and checked before any run.
76
+ # The previous run's expansion names the headers it entered, which this run's staleness
77
+ # depends on too.
78
+ def register(work)
79
+ testable = work.testable
80
+ target = path( work, :target )
81
+ meta = dependency_meta(
82
+ flags: testable.preprocess_flags, defines: testable.preprocess_defines, search_paths: testable.search_paths,
83
+ tools: TOOLS.map { |tool| @configurator.public_send( tool ) }, partials: @configurator.get_partials_config
84
+ )
85
+
86
+ @dependinator.register( target, files: [work.config.filepath], meta: meta )
87
+
88
+ raw_expansion = path( work, :raw_expansion )
89
+ register_preprocessed_dependencies( target, raw_expansion ) if @file_wrapper.exist?( raw_expansion )
90
+
91
+ return target
92
+ end
93
+
94
+ # A fresh record without its expanded code reruns, since reconciliation needs that file
95
+ def stale?(work, target)
96
+ return (@dependinator.stale?( target ) or !@file_wrapper.exist?( path( work, :expanded_code ) ))
97
+ end
98
+
99
+ def generate(work, target, kind)
100
+ config = work.config
101
+ log_progress( "Preprocessing partial #{kind} for", work )
102
+
103
+ run = { filepath: config.filepath, test: work.testable.name, **tool_args( work.testable ) }
104
+
105
+ assemble( work, kind, run )
106
+ config.expansion_filepath = @preprocessinator.generate_partial_expansion( **run )
107
+ config.raw_expansion_filepath = config.expansion_filepath && path( work, :raw_expansion )
108
+
109
+ mark_fresh( work, target ) unless config.expansion_filepath.nil?
110
+ end
111
+
112
+ # The directives-only run, then the assembled copy built from its output. A run with no
113
+ # directives-only output removes an earlier one, so a raw copy on disk means this file
114
+ # was preprocessed accurately.
115
+ def assemble(work, kind, run)
116
+ config = work.config
117
+
118
+ raw = directives_only? ? @preprocessinator.generate_directives_only_output( **run ) : nil
119
+ @file_wrapper.rm_f( path( work, :raw_directives_only ) ) if raw.nil?
120
+
121
+ config.raw_directives_only_filepath = raw
122
+ config.fallback = directives_only_fallback?( directives_only?, raw )
123
+
124
+ config.assembled_filepath, config.includes = @preprocessinator.preprocess_partial_file(
125
+ kind: kind, directives_only_filepath: raw, fallback: config.fallback, **run
126
+ )
127
+ end
128
+
129
+ # Every file a later build trusts is an output, so a missing or edited one makes the job stale
130
+ def mark_fresh(work, target)
131
+ config = work.config
132
+ outputs = [path( work, :includes_list ), config.raw_directives_only_filepath, config.raw_expansion_filepath, config.expansion_filepath]
133
+
134
+ @dependinator.register( target, outputs: outputs.compact )
135
+ register_preprocessed_dependencies( target, config.raw_expansion_filepath )
136
+ @dependinator.mark_fresh( target )
137
+ end
138
+
139
+ # A fresh job's record, from the files its last run left. The raw copy alone says whether
140
+ # that run was accurate, whatever this run's toolchain supports.
141
+ def recall(work, target, kind)
142
+ log_progress( "Skipping partial #{kind} preprocessing for", work, Verbosity::OBNOXIOUS )
143
+
144
+ raw = present( work, :raw_directives_only )
145
+ fill(
146
+ work.config, raw_directives_only_filepath: raw, fallback: raw.nil?, assembled_filepath: target,
147
+ includes: @preprocessinator.load_includes_list( test: work.testable.name, filepath: work.config.filepath ),
148
+ raw_expansion_filepath: present( work, :raw_expansion ), expansion_filepath: path( work, :expanded_code )
149
+ )
150
+ end
151
+
152
+ def fill(config, **fields)
153
+ fields.each { |field, value| config[field] = value }
154
+ end
155
+
156
+ def tool_args(testable)
157
+ return { flags: testable.preprocess_flags, include_paths: testable.search_paths, vendor_paths: vendor_search_paths(), defines: testable.preprocess_defines }
158
+ end
159
+
160
+ # Settled per run, since the configurator learns of directives-only support after this
161
+ # object is built
162
+ def directives_only?
163
+ return @configurator.test_build_preprocess_directives_only_available
164
+ end
165
+
166
+ def path(work, kind)
167
+ return @file_path_utils.public_send( PATHS[kind], work.config.filepath, work.testable.name )
168
+ end
169
+
170
+ def present(work, kind)
171
+ file = path( work, kind )
172
+ return @file_wrapper.exist?( file ) ? file : nil
173
+ end
174
+
175
+ # A Partial's progress names its own file rather than the test's
176
+ def log_progress(operation, work, verbosity = Verbosity::NORMAL)
177
+ msg = @reportinator.generate_module_progress( operation: operation, module_name: work.testable.name, filename: File.basename( work.config.filepath ) )
178
+ @loginator.log( msg, verbosity )
179
+ end
180
+
181
+ end