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
@@ -11,9 +11,9 @@ require 'ceedling/dependencies/dependency_hasher'
11
11
 
12
12
  # Loads, validates, and persists DependencyTracker's on-disk cache file.
13
13
  #
14
- # The persisted shape is a single JSON object:
14
+ # The persisted shape is a single JSON object (each version is recorded in CACHE_SCHEMA.md):
15
15
  # {
16
- # "schema_version": 1,
16
+ # "schema_version": 3,
17
17
  # "hash_algorithm": "sha256",
18
18
  # "entries": {
19
19
  # "<target path>": {
@@ -56,29 +56,33 @@ require 'ceedling/dependencies/dependency_hasher'
56
56
  class DependencyCacheStore
57
57
 
58
58
  # Cache keys are build paths, so a change to where a build puts its output changes the
59
- # schema too. 2: per-test output is placed by the test's path from the project root.
60
- CACHE_SCHEMA_VERSION = 2 unless const_defined?(:CACHE_SCHEMA_VERSION, false)
59
+ # schema too. A release build's layout changes apart from a test build's, so each kind of
60
+ # pipeline has a version of its own: CACHE_SCHEMA_VERSION for every test pipeline, and
61
+ # RELEASE_CACHE_SCHEMA_VERSION for a release build. CACHE_SCHEMA.md records each version
62
+ # and why it was raised.
63
+ CACHE_SCHEMA_VERSION = 4 unless const_defined?(:CACHE_SCHEMA_VERSION, false)
64
+ RELEASE_CACHE_SCHEMA_VERSION = 3 unless const_defined?(:RELEASE_CACHE_SCHEMA_VERSION, false)
61
65
 
62
66
  constructor :file_wrapper, :loginator
63
67
 
64
- # Loads and validates `store_path`, returning
68
+ # Loads and validates `store_path` against its pipeline's `schema_version`, returning
65
69
  # `{ 'schema_version', 'hash_algorithm', 'entries', 'pruned' }`. `entries`
66
70
  # is always a Hash of target path => entry Hash, with any invalid or
67
71
  # deleted-target entries dropped. `pruned` is the list of target paths
68
72
  # dropped this load (malformed or deleted) -- callers use it to also clean
69
73
  # up any DependencyDebugTree data for those same targets, so the debug
70
74
  # tree doesn't outlive the cache entries it exists to explain.
71
- def load(store_path)
72
- return empty_store unless @file_wrapper.exist?( store_path )
75
+ def load(store_path, schema_version: CACHE_SCHEMA_VERSION)
76
+ return empty_store( schema_version ) unless @file_wrapper.exist?( store_path )
73
77
 
74
78
  raw = @file_wrapper.read( store_path )
75
79
  parsed = JSON.parse( raw )
76
80
 
77
- return degrade( store_path, "does not contain a JSON object" ) unless parsed.is_a?( Hash )
78
- return upgrade( store_path ) if earlier_layout?( parsed['schema_version'] )
79
- return degrade( store_path, "has an incompatible or missing schema_version" ) unless parsed['schema_version'] == CACHE_SCHEMA_VERSION
80
- return degrade( store_path, "has an incompatible or missing hash_algorithm" ) unless parsed['hash_algorithm'] == DependencyHasher::HASH_ALGORITHM
81
- return degrade( store_path, "is missing its entries object" ) unless parsed['entries'].is_a?( Hash )
81
+ return degrade( store_path, schema_version, "does not contain a JSON object" ) unless parsed.is_a?( Hash )
82
+ return upgrade( store_path, schema_version ) if earlier_layout?( parsed['schema_version'], schema_version )
83
+ return degrade( store_path, schema_version, "has an incompatible or missing schema_version" ) unless parsed['schema_version'] == schema_version
84
+ return degrade( store_path, schema_version, "has an incompatible or missing hash_algorithm" ) unless parsed['hash_algorithm'] == DependencyHasher::HASH_ALGORITHM
85
+ return degrade( store_path, schema_version, "is missing its entries object" ) unless parsed['entries'].is_a?( Hash )
82
86
 
83
87
  valid_entries = {}
84
88
  pruned = []
@@ -101,25 +105,26 @@ class DependencyCacheStore
101
105
  end
102
106
 
103
107
  {
104
- 'schema_version' => CACHE_SCHEMA_VERSION,
108
+ 'schema_version' => schema_version,
105
109
  'hash_algorithm' => DependencyHasher::HASH_ALGORITHM,
106
110
  'entries' => valid_entries,
107
111
  'pruned' => pruned
108
112
  }
109
113
 
110
114
  rescue JSON::ParserError => e
111
- degrade( store_path, "is not valid JSON (#{e.message})" )
115
+ degrade( store_path, schema_version, "is not valid JSON (#{e.message})" )
112
116
  end
113
117
 
114
- # Persists `entries` (a Hash of target path => entry Hash) to `store_path`.
118
+ # Persists `entries` (a Hash of target path => entry Hash) to `store_path`, as of its
119
+ # pipeline's `schema_version`.
115
120
  # Writes to a temp file in the same directory and renames into place so a
116
121
  # reader never observes a partially-written cache file, even if two
117
122
  # Ceedling invocations somehow raced on the same project.
118
- def persist(store_path, entries)
123
+ def persist(store_path, entries, schema_version: CACHE_SCHEMA_VERSION)
119
124
  @file_wrapper.mkdir( @file_wrapper.dirname( store_path ) )
120
125
 
121
126
  payload = {
122
- 'schema_version' => CACHE_SCHEMA_VERSION,
127
+ 'schema_version' => schema_version,
123
128
  'hash_algorithm' => DependencyHasher::HASH_ALGORITHM,
124
129
  'entries' => entries
125
130
  }
@@ -132,30 +137,30 @@ class DependencyCacheStore
132
137
  ### Private ###
133
138
  private
134
139
 
135
- def empty_store
136
- { 'schema_version' => CACHE_SCHEMA_VERSION, 'hash_algorithm' => DependencyHasher::HASH_ALGORITHM, 'entries' => {}, 'pruned' => [] }
140
+ def empty_store(schema_version)
141
+ { 'schema_version' => schema_version, 'hash_algorithm' => DependencyHasher::HASH_ALGORITHM, 'entries' => {}, 'pruned' => [] }
137
142
  end
138
143
 
139
- def degrade(store_path, reason)
144
+ def degrade(store_path, schema_version, reason)
140
145
  @loginator.log(
141
146
  "Dependency cache #{store_path} #{reason} -- treating it as absent (full rebuild for tracked targets).",
142
147
  Verbosity::COMPLAIN
143
148
  )
144
- empty_store
149
+ empty_store( schema_version )
145
150
  end
146
151
 
147
- def earlier_layout?(version)
148
- return version.is_a?( Integer ) && version.between?( 1, CACHE_SCHEMA_VERSION - 1 )
152
+ def earlier_layout?(version, schema_version)
153
+ return version.is_a?( Integer ) && version.between?( 1, schema_version - 1 )
149
154
  end
150
155
 
151
156
  # An earlier build layout leaves its output where this build no longer looks
152
- def upgrade(store_path)
157
+ def upgrade(store_path, schema_version)
153
158
  @loginator.log(
154
159
  "Dependency cache #{store_path} comes from an earlier Ceedling build layout -- rebuilding everything once. " \
155
160
  "Run `ceedling clobber` to remove any orphaned build output left in the old layout.",
156
161
  Verbosity::COMPLAIN
157
162
  )
158
- empty_store
163
+ empty_store( schema_version )
159
164
  end
160
165
 
161
166
  def valid_entry?(entry)
@@ -8,6 +8,7 @@
8
8
  require 'time'
9
9
  require 'ceedling/constants'
10
10
  require 'ceedling/exceptions'
11
+ require 'ceedling/dependencies/dependency_cache_store'
11
12
 
12
13
  # A pure query module for content-hash-based rebuild staleness -- not a build
13
14
  # scheduler. Ceedling's existing Rake-based, multithreaded, conditionally-
@@ -67,6 +68,7 @@ class DependencyTracker
67
68
  def setup()
68
69
  @mutex = Mutex.new
69
70
  @store_path = nil
71
+ @schema_version = DependencyCacheStore::CACHE_SCHEMA_VERSION
70
72
  @debug_root = nil
71
73
  @debug_tier = DEBUG_TIERS[:none]
72
74
  @relationships = {}
@@ -86,14 +88,18 @@ class DependencyTracker
86
88
  # deleted from disk -- see DependencyCacheStore#load) have their
87
89
  # DependencyDebugTree data pruned too, so the debug tree never outlives
88
90
  # the cache entries it exists to explain.
89
- def open(store_path:, debug_tier: nil)
91
+ #
92
+ # `schema_version` is the version the cache's pipeline reads and writes (see
93
+ # CACHE_SCHEMA.md).
94
+ def open(store_path:, schema_version: DependencyCacheStore::CACHE_SCHEMA_VERSION, debug_tier: nil)
90
95
  @store_path = store_path
96
+ @schema_version = schema_version
91
97
  @debug_root = debug_root_for( store_path )
92
98
  @debug_tier = resolve_debug_tier( debug_tier )
93
99
 
94
100
  @mutex.synchronize do
95
101
  @relationships = {}
96
- @cache = @dependency_cache_store.load( @store_path )
102
+ @cache = @dependency_cache_store.load( @store_path, schema_version: @schema_version )
97
103
  ( @cache['pruned'] || [] ).each { |target| @dependency_debug_tree.prune( @debug_root, target ) }
98
104
  end
99
105
  end
@@ -249,7 +255,7 @@ class DependencyTracker
249
255
  @cache['entries'].dup
250
256
  end
251
257
 
252
- @dependency_cache_store.persist( @store_path, entries )
258
+ @dependency_cache_store.persist( @store_path, entries, schema_version: @schema_version )
253
259
  end
254
260
 
255
261
  # Explains why `target` is (or was last found to be) stale: which of
@@ -5,6 +5,9 @@
5
5
  # SPDX-License-Identifier: MIT
6
6
  # =========================================================================
7
7
 
8
+ require 'ceedling/constants'
9
+ require 'ceedling/dependencies/dependency_cache_store'
10
+
8
11
  # Ceedling-specific adapter between the build pipeline and the generic,
9
12
  # application-agnostic DependencyTracker -- owns the tracker's lifecycle
10
13
  # (where its cache file lives, when it's opened and flushed) so pipeline
@@ -26,12 +29,21 @@ class Dependinator
26
29
  File.join( PROJECT_BUILD_DEPENDENCIES_CACHE_PATH, ".#{identifier}.#{CACHE_FILENAME}" )
27
30
  end
28
31
 
32
+ # The schema version of a pipeline's cache (see CACHE_SCHEMA.md). A release build places
33
+ # its files apart from any test's own root, so its layout and version change on their own.
34
+ # Every other pipeline is a test build's.
35
+ def self.cache_schema_version(identifier)
36
+ return DependencyCacheStore::RELEASE_CACHE_SCHEMA_VERSION if identifier == RELEASE_SYM
37
+
38
+ return DependencyCacheStore::CACHE_SCHEMA_VERSION
39
+ end
40
+
29
41
  # `identifier` isolates one pipeline's cache from another's -- sharing a single
30
42
  # cache file between, say, test and release builds would make a full test:all
31
43
  # run's pruning flush (see `flush`) silently evict every cached release entry,
32
44
  # and vice versa, since pruning drops anything not registered in the current run.
33
45
  def open(identifier: :test)
34
- @dependency_tracker.open( store_path: self.class.cache_store_path( identifier ) )
46
+ @dependency_tracker.open( store_path: self.class.cache_store_path( identifier ), schema_version: self.class.cache_schema_version( identifier ) )
35
47
  end
36
48
 
37
49
  def register(target, files: [], meta: {}, outputs: [])
@@ -0,0 +1,142 @@
1
+ # The Build Step Doctor
2
+
3
+ The build step doctor explains a failed build step to the test developer. When a test's compilation or linking fails, the doctor reads the tool's output and the inputs it ran with, recognizes failures with a known cause, and logs guidance beside the tool's own error. The error is still raised, so the guidance only adds to it.
4
+
5
+ ## Why it exists
6
+
7
+ Some toolchain errors have causes that only Ceedling's conventions explain. A redeclaration error can mean a mocked header's real content reached the compilation a second way. A missing symbol most often means a test's `#include` directives left out a source it needs. A duplicate symbol can mean a mock was linked beside the source it stands in for. An `#include` nested too deeply most often means a header that includes its own filename found itself first. The raw error names none of this. A developer reading only the compiler's words may spend a long time finding a cause Ceedling could have pointed to.
8
+
9
+ Each kind of guidance follows the same pattern:
10
+
11
+ 1. **Match the output.** The failed step's output shows a known error, in any of the wordings different toolchains use.
12
+ 2. **Examine the case.** The step's inputs, such as the test's mocks, its search paths, the headers its `.d` file lists, or the objects it linked, confirm the cause applies. Each case that applies writes its own guidance, so one failure can draw several.
13
+
14
+ The doctor holds that pattern once. Each kind of guidance is a small diagnosis written against it.
15
+
16
+ ## The mechanism
17
+
18
+ `BuildStepDoctor` (`build_step_doctor.rb`) is the engine. It knows nothing about Ceedling. Specialists hold the knowledge, and the doctor gathers their diagnoses once, in `setup`.
19
+
20
+ - **`Diagnosis`** is a struct a specialist builds. It has a `name`, the `steps` it covers (`:preprocess`, `:compile`, `:link`), the `outcomes` it covers (`:failure` by default, or `:warning`), its `symptoms`, and its `examination`.
21
+ - **Symptoms** are a Regexp, or an Array of them with one per toolchain family. Any match makes the case a candidate.
22
+ - **The examination** is a callable that takes a `Case` and returns a prescription (a String), several (an Array), or nil when the case turns out not to be its own.
23
+ - **`Case`** holds the `step`, the `outcome`, the tool's `output`, the `symptoms` MatchData, and the step's `inputs` Hash.
24
+ - **`BuildStepDoctor#diagnose(step:, output:, inputs:, outcome: :failure)`** runs every diagnosis whose steps, outcomes, and symptoms fit, in the order the specialists were composed. It logs each prescription at `Verbosity::ERRORS` with `LogLabels::NOTICE`, and returns them.
25
+ - **`BuildStepDoctor#attend(step:, inputs:) { … }`** runs a step's block. A `ShellException` the block raises goes to `diagnose` with the tool's output, and is then raised again.
26
+
27
+ An examination that raises is a bug in guidance, never a reason to hide a build's real failure. The doctor logs the error at DEBUG and runs the remaining diagnoses. A step or outcome the doctor doesn't know raises `ArgumentError`, at `setup` or at `diagnose`, so a typo can't silently disable a diagnosis.
28
+
29
+ `ToolchainOutput` (`toolchain_output.rb`) reads the header and object paths an output mentions. A path is any token ending in a wanted extension, quoted or not, so one reader serves every location format below. A stray match is harmless, because each specialist compares paths against files it already knows.
30
+
31
+ ### Specialists
32
+
33
+ | Specialist | Step | Diagnoses |
34
+ |---|---|---|
35
+ | `HeaderCollisionSpecialist` | compilation | `:substituted_header_collision`: a header the test mocks or Partializes collides with its own real content. `:shared_directory_collision`: a header collides in a directory it shares with other headers, none of them substituted (see `test_invoker/HEADER_COLLISIONS.md`). |
36
+ | `MissingSymbolSpecialist` | linking | `:missing_symbols`: a symbol no linked object defines. |
37
+ | `DuplicateSymbolSpecialist` | linking | `:duplicate_symbols`: a symbol more than one linked object defines. The guidance names a mock linked beside the source it stands in for. |
38
+ | `IncludeDepthSpecialist` | preprocessing, compilation | `:include_nested_too_deeply`: `#include` directives nested past the compiler's limit. The guidance names a header that includes its own filename and reaches itself first. It tells an angled `#include`, which the search path order decides, from a quoted one, which reaches its own directory first whatever that order. |
39
+ | `PartialNameSpecialist` | compilation | `:partial_local_var` and `:partial_type`: a name that `PARTIAL_LOCAL_VAR()`, or `PARTIAL_TYPE()` or `PARTIAL_LOCAL_TYPE()`, builds and nothing declares, in the test file of a build with Partials. The guidance lists the names the test's generated Partial headers provide. |
40
+
41
+ `TestSubstitutions` (`test_invoker/test_substitutions.rb`) answers two questions both sibling-header isolation and the collision diagnoses ask: which real headers a test substitutes, and which directories hold Ceedling's own generated content.
42
+
43
+ ### Where the doctor is connected
44
+
45
+ The doctor sees a failure just before it is raised, at four places:
46
+
47
+ - **`TestBuildExecutor#compile_test_component`**, for a C compilation, with `tool`, `source`, `object`, `search_paths`, `flags`, `defines`, `testable`, and `dependencies`. `dependencies` is the first attempt's `.d` file, whose paths are the real headers, even when an isolated retry produced the failure. This site calls `diagnose` itself, after any isolated retry has failed too.
48
+ - **`TestBuildExecutor#generate_executable`**, for a link, with `tool`, `objects`, `executable`, `flags`, `lib_args`, `lib_paths`, and `testable`. The link runs under `attend`.
49
+ - **`PreprocessinatorFileAssembler`'s full expansions of a test file and of a header to be mocked**, with `tool`, `source`, `search_paths`, `flags`, and `defines`. Both run under `attend`. Neither has a fallback, so a failure there ends the build.
50
+
51
+ Compilation and linking failures are where guidance helps a test developer most. Ceedling runs the preprocessor many times per test. Most of those runs are expected to fail at times and fall back by design, so they aren't connected. A misplaced prescription there would only add noise. The full expansions of a test file and of a header to be mocked are the exception, since their failure stops the build. Assembly and release builds aren't connected either. The engine accepts a `:warning` outcome, so connecting more needs only a call site.
52
+
53
+ ### Sharing the doctor without a lock
54
+
55
+ Every compilation thread in a test build shares one doctor. That needs no lock, because the doctor fixes its diagnoses in `setup` and `diagnose` only reads them. Specialists keep no state between examinations either. Adding a diagnosis after `setup`, or giving a specialist mutable state, would break this guarantee.
56
+
57
+ The doctor composes its specialists, rather than each specialist registering itself, because DIY builds an object only when something references it.
58
+
59
+ ## Adding a diagnosis
60
+
61
+ 1. Add a `Diagnosis` to an existing specialist's `diagnoses`, or write a new specialist and compose it into `build_step_doctor` in `objects.yml`.
62
+ 2. Give it symptoms for each toolchain family you can, ending in a generic net. Err toward matching, since the examination decides whether the case applies.
63
+ 3. Write its examination against the `Case` inputs. Return nil when the inputs show the cause doesn't apply.
64
+ 4. Write its prescription in the shared shape:
65
+ - a tentative opening, such as "The linker output appears to report…", since no matcher reads every toolchain perfectly;
66
+ - a blank line, then a heading such as `HOW THIS HAPPENS:` over `•` bullets on the C mechanics, mentioning Ceedling only briefly;
67
+ - a blank line, then `OPTIONS:` over a numbered list of ways to resolve the problem;
68
+ - every line left-justified, so a narrow terminal wraps it cleanly. The loginator turns `•` into `*` when decorators are off.
69
+ - adapted to the project, read from the configurator at examination time. A cause tied to a feature, such as mocks, Partials, or test preprocessing, appears only when the project's settings make it possible. A remedy that mocks or Partializes a header appears either way, and names the setting that turns on a disabled feature (`GuidancePhrases`).
70
+ 5. Cover it in a unit spec under `spec/units/diagnostics/`, with one case per wording, and in `spec/integration/build_step_doctor_spec.rb` when a real compiler can produce the failure.
71
+
72
+ ## Known toolchain wordings
73
+
74
+ Each table lists what the symptoms match, family by family. The evidence column states how each wording is known:
75
+
76
+ - **real toolchain:** produced by a real compiler or linker in `spec/integration/build_step_doctor_spec.rb`, which runs on GCC 14, Apple Clang 15, and CI's compilers;
77
+ - **vendor forums:** quoted from build logs posted in vendor support forums;
78
+ - **expected:** the toolchain's documented message format, not yet observed in this project.
79
+
80
+ ### Collisions at compilation
81
+
82
+ | Family | Wordings | Evidence |
83
+ |---|---|---|
84
+ | GCC | `redefinition of`, `redeclaration of`, `conflicting types for`, `previous definition of`, `previous declaration of`, `redeclared as different kind of symbol` | real toolchain |
85
+ | Clang, armclang, Microchip XC8 v2 and later | `redefinition of`, `typedef redefinition with different types`, `previous definition is here`, `conflicting types for` | real toolchain (Clang) |
86
+ | IAR | `Error[Pe101]: … has already been declared in the current scope`, `Pe147` `declaration is incompatible with`, `Pe256` `invalid redeclaration of type name` | vendor forums (Pe101), expected (Pe147, Pe256) |
87
+ | Arm armcc | `Error: #101: … has already been declared in the current scope` | vendor forums |
88
+ | TI, Green Hills | `error #101`, `error #147`, `error #256`, with the EDG texts above | expected |
89
+ | MSVC | `C2011` type redefinition, `C2084` function already has a body, `C2370` and `C2371` `redefinition; different` | expected |
90
+ | TASKING, SDCC, others | generic: `redefin`, `redeclar`, `already declared`, `already defined`, `duplicate definition`, `duplicate declaration` | expected |
91
+
92
+ Header paths are read in each location format: `a.h:12:3` (GCC, Clang), `"a.h",12` (IAR), `"a.h", line 12` (Arm armcc, TI, Green Hills), `a.h(12)` (MSVC), and prose such as `declared at line 5 of "a.h"`.
93
+
94
+ ### Missing symbols at link time
95
+
96
+ | Family | Wordings | Evidence |
97
+ |---|---|---|
98
+ | GNU ld, Microchip XC16 and XC32 | `undefined reference to` | real toolchain (CI's Linux jobs) |
99
+ | Apple ld | `Undefined symbols for architecture`, `symbol(s) not found` | real toolchain |
100
+ | LLD | `undefined symbol:` | expected |
101
+ | MSVC | `LNK2019`, `LNK2001`, `unresolved external symbol` | expected |
102
+ | IAR ILINK | `Error[Li005]: no definition for` | vendor forums |
103
+ | Arm armlink | `Error: L6218E: Undefined symbol` | vendor forums |
104
+ | TI | `undefined first referenced` table header, `unresolved symbols remain` | vendor forums |
105
+ | Green Hills, TASKING, SDCC, others | generic: `undefined global`, `undefined external`, `unresolved external`, `unresolved symbol` | expected |
106
+
107
+ ### Duplicate symbols at link time
108
+
109
+ | Family | Wordings | Evidence |
110
+ |---|---|---|
111
+ | GNU ld | `multiple definition of`, `first defined here` | real toolchain (CI's Linux jobs) |
112
+ | Apple ld | `duplicate symbol` | real toolchain |
113
+ | LLD | `duplicate symbol:` | expected |
114
+ | MSVC | `LNK2005` `already defined in`, `LNK1169` | expected |
115
+ | IAR ILINK | `Error[Li006]: duplicate definitions for` | vendor forums |
116
+ | Arm armlink | `Error: L6200E: Symbol … multiply defined` | vendor forums |
117
+ | TI | `error #10056: symbol … redefined: first defined in` | vendor forums |
118
+ | Green Hills, TASKING, SDCC, others | generic: `multiple definition`, `multiply defined`, `duplicate symbol`, `duplicate definition`, `already defined` | expected |
119
+
120
+ ### Undeclared names at compilation
121
+
122
+ A wording alone matches any undeclared name, so `PartialNameSpecialist` also asks for a name its macros build, `partial_…` or `ceedling_partial_…_t`, or for a note naming one of the macros.
123
+
124
+ | Family | Wordings | Evidence |
125
+ |---|---|---|
126
+ | GCC, Microchip XC16 and XC32 | `'x' undeclared (first use in this function)`, `unknown type name` | real toolchain |
127
+ | Clang, armclang, Microchip XC8 v2 and later | `use of undeclared identifier`, `unknown type name` | real toolchain (Clang) |
128
+ | IAR | `Error[Pe020]: identifier "x" is undefined` | expected |
129
+ | Arm armcc, TI, Green Hills | `error #20: identifier "x" is undefined` | expected |
130
+ | MSVC | `C2065` `undeclared identifier`, `C2061`, `C4430`, `C2146` | expected |
131
+ | SDCC | `Undefined identifier` | expected |
132
+ | TASKING, others | generic: `undefined identifier`, `not declared`, `unknown type`, `is not a type` | expected |
133
+
134
+ ### Nested includes at preprocessing or compilation
135
+
136
+ | Family | Wordings | Evidence |
137
+ |---|---|---|
138
+ | GCC 10 and later | `#include nested depth 200 exceeds maximum of 200`, with the directive quoted as `'#include'` or `‘#include’` in newer releases | real toolchain (GCC 14 unquoted, MSYS2 UCRT GCC quoted) |
139
+ | Clang, armclang, GCC before 10 | `#include nested too deeply` | real toolchain (Clang) |
140
+ | MSVC | `C1014` `too many include files` | expected |
141
+ | IAR, Arm armcc, TI, Green Hills | `#include file … includes itself`, `include file nesting` | expected |
142
+ | TASKING, SDCC, others | generic: `include depth`, `include nesting`, `nested include`, `nested too deep`, `too many include` | expected |
@@ -0,0 +1,5 @@
1
+ # Diagnostics
2
+
3
+ This directory explains failed build steps to the test developer, from the failed tool's output and the inputs it ran with.
4
+
5
+ - **`DOCTOR.md`** -- why the build step doctor exists, how `BuildStepDoctor`, its specialists, and their diagnoses fit together, how to add a diagnosis, and the toolchain wordings each diagnosis matches.
@@ -0,0 +1,110 @@
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/exceptions'
10
+
11
+ # Explains a failed build step from its output and inputs (see DOCTOR.md).
12
+ #
13
+ # Specialists teach the doctor diagnoses. A diagnosis names the steps and outcomes it
14
+ # covers, the symptoms its output must show, and an examination that decides whether
15
+ # the case is really its own. Every diagnosis that applies writes a prescription, so
16
+ # one failure can draw several. The doctor logs each at ERRORS as a notice. The failure
17
+ # is still raised, so guidance never takes the place of the tool's own error.
18
+ #
19
+ # The doctor gathers its diagnoses once, in setup, and only reads them afterward. That
20
+ # is what lets every compilation thread share one doctor without a lock. Adding a
21
+ # diagnosis after setup would break it.
22
+ class BuildStepDoctor
23
+ # Build steps a diagnosis may cover. Compilation, linking, and the full expansions of a test
24
+ # file and of a header to be mocked are connected, since none of them has a fallback. The
25
+ # other preprocessor runs fail by design and fall back, so none of them is.
26
+ STEPS = [:preprocess, :compile, :link].freeze
27
+ OUTCOMES = [:failure, :warning].freeze
28
+
29
+ # What a specialist teaches the doctor. `symptoms` is a Regexp, or several, any of
30
+ # which marks the case as a candidate. `examination` takes a Case and returns a
31
+ # prescription, several, or nil when the case is not this diagnosis's after all.
32
+ Diagnosis = Struct.new( :name, :steps, :outcomes, :symptoms, :examination, keyword_init: true ) do
33
+ def initialize(outcomes: [:failure], **fields)
34
+ super
35
+ end
36
+
37
+ # The first symptom match, or nil
38
+ def symptom_in(output)
39
+ Array( symptoms ).each do |symptom|
40
+ match = symptom.match( output )
41
+ return match if match
42
+ end
43
+ nil
44
+ end
45
+ end
46
+
47
+ # One failure as the doctor sees it. `symptoms` is the diagnosis's MatchData, and
48
+ # `inputs` holds whatever the step ran with, such as its tool, source, and search paths.
49
+ Case = Struct.new( :step, :outcome, :output, :symptoms, :inputs, keyword_init: true )
50
+
51
+ constructor :loginator, :header_collision_specialist, :missing_symbol_specialist, :duplicate_symbol_specialist, :partial_name_specialist,
52
+ :include_depth_specialist
53
+
54
+ def setup()
55
+ specialists = [
56
+ @header_collision_specialist, @missing_symbol_specialist, @duplicate_symbol_specialist, @partial_name_specialist,
57
+ @include_depth_specialist
58
+ ]
59
+
60
+ @diagnoses = specialists.flat_map( &:diagnoses ).freeze
61
+ @diagnoses.each { |diagnosis| check_scope( diagnosis.steps, diagnosis.outcomes, diagnosis.name ) }
62
+ end
63
+
64
+ # Logs every prescription the case draws, and returns them
65
+ def diagnose(step:, output:, inputs:, outcome: :failure)
66
+ check_scope( [step], [outcome], 'diagnosis request' )
67
+ return [] if output.nil?
68
+
69
+ return @diagnoses.flat_map do |diagnosis|
70
+ next [] unless diagnosis.steps.include?( step ) && diagnosis.outcomes.include?( outcome )
71
+
72
+ prescriptions = examine( diagnosis, output: output, step: step, outcome: outcome, inputs: inputs )
73
+ prescriptions.each { |prescription| @loginator.log( prescription, Verbosity::ERRORS, LogLabels::NOTICE ) }
74
+ end
75
+ end
76
+
77
+ # Runs a step's block, and diagnoses a tool failure it raises before raising it again. The
78
+ # step is checked first, so a typo can't replace a real failure with its own error.
79
+ def attend(step:, inputs:)
80
+ check_scope( [step], [:failure], 'attend request' )
81
+
82
+ return yield
83
+ rescue ShellException => e
84
+ diagnose( step: step, output: e.shell_result[:output], inputs: inputs )
85
+ raise
86
+ end
87
+
88
+ ### Private ###
89
+
90
+ private
91
+
92
+ # An examination that raises is a bug in guidance, never a reason to hide the build's
93
+ # real failure. It is noted for debugging, and the other diagnoses still run.
94
+ def examine(diagnosis, output:, **case_fields)
95
+ match = diagnosis.symptom_in( output )
96
+ return [] if match.nil?
97
+
98
+ return Array( diagnosis.examination.call( Case.new( output: output, symptoms: match, **case_fields ) ) ).compact
99
+ rescue StandardError => e
100
+ @loginator.log( "Diagnosis #{diagnosis.name} failed to examine its case: #{e.class}: #{e.message}", Verbosity::DEBUG )
101
+ return []
102
+ end
103
+
104
+ def check_scope(steps, outcomes, name)
105
+ unknown = (steps - STEPS) + (outcomes - OUTCOMES)
106
+ return if unknown.empty?
107
+
108
+ raise ::ArgumentError, "#{name} names unknown build steps or outcomes: #{unknown.join( ', ' )}"
109
+ end
110
+ end
@@ -0,0 +1,108 @@
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/diagnostics/build_step_doctor'
9
+ require 'ceedling/diagnostics/toolchain_output'
10
+ require 'ceedling/diagnostics/guidance_phrases'
11
+
12
+ # Explains linker errors for symbols more than one linked object defines.
13
+ #
14
+ # Most duplicates come from C itself: a definition in a header, or a test redefining a
15
+ # function its source under test defines. One comes from Ceedling's conventions: a mock
16
+ # defines every function its header declares, so a test that links a mock beside the
17
+ # source it stands in for defines each of them twice. The pair is named when the linked
18
+ # objects hold one, among the objects the output names if it names any.
19
+ class DuplicateSymbolSpecialist
20
+
21
+ # Each family's wording for a symbol defined twice, ending in a generic net
22
+ DUPLICATE_SYMBOL_SYMPTOMS = [
23
+ # GNU ld
24
+ /multiple definition of|first defined here/i,
25
+ # LLD and Apple ld
26
+ /duplicate symbol/i,
27
+ # MSVC
28
+ /\bLNK(?:2005|1169)\b|already defined in/i,
29
+ # IAR ILINK
30
+ /\bLi006\b|duplicate definitions for/i,
31
+ # Arm armlink
32
+ /\bL6200E\b|multiply defined/i,
33
+ # TI
34
+ /symbol .* redefined|first defined in/i,
35
+ # Green Hills, TASKING, SDCC, and other linkers
36
+ /multipl(?:e|y) defin|duplicate (?:symbol|definition)|already defined/i
37
+ ].freeze
38
+
39
+
40
+ # Each joins the end of the line before it, when the project uses mocks
41
+ MOCK_CAUSE = "\n• A mock defines every function its header declares; linking a mock and the source it stands in for duplicates them."
42
+ MOCK_OPTION = "\n4. Don't #include both a mock and its real header in one test and don't name a mocked module's source in TEST_SOURCE_FILE()."
43
+
44
+ GUIDANCE = <<~GUIDANCE.freeze
45
+ HOW THIS HAPPENS:
46
+ • A program may define each function and each global variable only once across all its object files.
47
+ • A definition in a header, a function body or a variable without extern, is repeated in every source that #includes the header.
48
+ • A test file that defines a function the source under test also defines places two definitions in one executable.%{mock_cause}
49
+
50
+ OPTIONS:
51
+ 1. Declare header variables extern, and define each one in a single source file.
52
+ 2. Make functions defined in headers static inline, or move their bodies into one source file.
53
+ 3. Remove a test's own definition of a function the linked source already provides, or mock the source's header instead.%{mock_requirement}%{mock_option}
54
+ GUIDANCE
55
+
56
+ constructor :configurator
57
+
58
+ def diagnoses()
59
+ return [
60
+ BuildStepDoctor::Diagnosis.new(
61
+ name: :duplicate_symbols,
62
+ steps: [:link],
63
+ symptoms: DUPLICATE_SYMBOL_SYMPTOMS,
64
+ examination: method( :examine )
65
+ )
66
+ ]
67
+ end
68
+
69
+ ### Private ###
70
+
71
+ private
72
+
73
+ def examine(kase)
74
+ lead = 'The linker output appears to report a symbol defined more than once.'
75
+ pair = mock_and_source( kase.output, kase.inputs[:objects] || [] )
76
+ lead += " This test links both '#{pair[0]}' and '#{pair[1]}', which may define the same functions." if pair
77
+
78
+ return "#{lead}\n\n#{guidance()}"
79
+ end
80
+
81
+ # Mock causes and remedies appear only as the project's mocking allows
82
+ def guidance()
83
+ mocks = @configurator.project_use_mocks
84
+
85
+ return format( GUIDANCE,
86
+ mock_cause: mocks ? MOCK_CAUSE : '',
87
+ mock_requirement: GuidancePhrases.requirements( mocks: mocks ),
88
+ mock_option: mocks ? MOCK_OPTION : ''
89
+ )
90
+ end
91
+
92
+ # A mock object and its source's object, by basename, or nil
93
+ def mock_and_source(output, objects)
94
+ return nil unless @configurator.project_use_mocks
95
+
96
+ candidates = candidate_objects( output, objects.map { |object| File.basename( object ) } )
97
+ prefix = @configurator.cmock_mock_prefix
98
+
99
+ mock = candidates.find { |object| object.start_with?( prefix ) && candidates.include?( object.delete_prefix( prefix ) ) }
100
+ return mock && [mock, mock.delete_prefix( prefix )]
101
+ end
102
+
103
+ # The linked objects the output names, or every linked object when it names none
104
+ def candidate_objects(output, linked)
105
+ named = ToolchainOutput.objects( output, extension: @configurator.extension_object.primary ).map { |object| File.basename( object ) }
106
+ return (named & linked).then { |both| both.empty? ? linked : both }
107
+ end
108
+ end
@@ -0,0 +1,30 @@
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
+ # Wording the specialists share when a remedy relies on a Ceedling feature.
9
+ #
10
+ # A remedy that mocks or Partializes a header is worth offering even when the project
11
+ # has that feature off, as long as the prescription says which setting turns it on.
12
+ module GuidancePhrases
13
+ MOCKS_SETTING = ':project ↳ :use_mocks'
14
+ PARTIALS_SETTING = ':project ↳ :use_partials'
15
+
16
+ # "Mock or Partialize", followed by `rest`, then a sentence naming any setting the
17
+ # remedy needs that the project has off
18
+ def self.substitute(rest, mocks:, partials:)
19
+ return "Mock or Partialize #{rest}#{requirements( mocks: mocks, partials: partials )}"
20
+ end
21
+
22
+ # Sentences naming the settings that turn on whichever feature is off, or ''
23
+ def self.requirements(mocks:, partials: true)
24
+ needs = []
25
+ needs << "Mocking requires #{MOCKS_SETTING}." unless mocks
26
+ needs << "Partializing requires #{PARTIALS_SETTING}." unless partials
27
+
28
+ return needs.empty? ? '' : " #{needs.join( ' ' )}"
29
+ end
30
+ end