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
@@ -12,6 +12,8 @@ A project names one place in many spellings. A `:paths` entry may read `src/**`,
12
12
 
13
13
  Comparing these spellings as text gives wrong answers in two ways. Two spellings of one place compare unequal. A text prefix also suggests containment where there is none. The text `..` begins `../../../Keil_v5/Include`, yet that directory lies far outside `..`.
14
14
 
15
+ An `#include`'s spelling, the text it names a header by, is a separate idea. [Finding a test's headers](../test_invoker/PIPELINE.md#finding-a-tests-headers) defines it.
16
+
15
17
  Placement poses a second challenge. Same-named sources live in many directories. Some lie outside the project or on another drive. Each build file needs a place that belongs to its source alone and still lies inside the build root.
16
18
 
17
19
  ### The rules
@@ -20,8 +22,8 @@ Five rules govern path handling. Each later section expands one of them.
20
22
 
21
23
  1. **One spelling.** Intake spells each path once. The spelling is relative to the working directory, with `~` expanded and the symlinks of its existing part resolved. A path with no relative form stays absolute. `ProjectPaths.canonical` produces it.
22
24
  2. **Containment by directory.** A path lies within a root only when the root is one of its whole ancestor directories. `ProjectPaths.contains?` and `ProjectPaths.subdir_below` answer this. No code asks whether one path's text starts with another's.
23
- 3. **Placement by project path.** A build file sits below its build output root at its source's own directory path from the project root. `BuildSubpath.encode` writes that path so it never climbs or goes absolute. `..` becomes `_up_`, another drive goes under `_abs_` or `_unc_`, and Ceedling's own installed files go under `_ceedling_`.
24
- 4. **Exact inversion.** `BuildSubpath.decode` turns a build subpath back into the source's path. A lookup from a build file therefore finds its source by exact path before it ever falls back to matching by name.
25
+ 3. **Placement by project path.** A build file sits below its build output root at its source's own directory path from the project root. `BuildSubpath.encode` writes that path so it never climbs or goes absolute. `..` becomes `_up_`, another drive goes under `_abs_` or `_unc_`, and Ceedling's own installed files go under `_ceedling_`. A file below a long configured root takes the root's short `_<name>_<hash>` marker in place of the root's location, and keeps its path below the root.
26
+ 4. **Exact inversion.** `BuildSubpath.decode` turns a build subpath back into the source's path, reading a root marker through the same table of shortened roots. A lookup from a build file therefore finds its source by exact path before it ever falls back to matching by name.
25
27
  5. **Collection leaves out the build.** Collection never returns the directories Ceedling creates. A glob based above the build root returns nothing from it. Configuration refuses a build root that holds the project.
26
28
 
27
29
  ### The project root
@@ -39,6 +41,7 @@ The path modules sit in `lib/ceedling/filesystem/`, whose [README](README.md) li
39
41
  | `project_paths.rb` | `ProjectPaths` | Spelling, absolute and relative forms, containment |
40
42
  | `working_dir.rb` | `WorkingDir` | The working directory, read once, and the one way to change it |
41
43
  | `build_subpath.rb` | `BuildSubpath` | Encoding a directory into a build subpath and back |
44
+ | `build_roots.rb` | `BuildRoots` | Which long configured roots build paths shorten, and each one's marker |
42
45
  | `path_spellings.rb` | `PathSpellings` | A place's listed and real spellings, and distances between places |
43
46
  | `path_exclusions.rb` | `PathExclusions` | The three kinds of exclusion collection applies |
44
47
  | `path_mirror.rb` | `PathMirror` | A file's subdirectory below the most specific containing root |
@@ -46,6 +49,7 @@ The path modules sit in `lib/ceedling/filesystem/`, whose [README](README.md) li
46
49
  | `destination_collision.rb` | `DestinationCollision` | Stopping a build when two inputs map to one output |
47
50
  | `file_path_collection_utils.rb` | `FilePathCollectionUtils` | Collecting `:paths` directories and `:files` revisions |
48
51
  | `file_path_utils.rb` | `FilePathUtils` | Test names and every build file's path |
52
+ | `test_build_layout.rb` | `TestBuildLayout` | Each test's own build directories, and which test's a build path lies in |
49
53
  | `file_finder.rb` | `FileFinder` | Finding a build file's input from the build file's path |
50
54
  | `../config/build_root_policy.rb` | `BuildRootPolicy` | What a build root may be, and what Ceedling creates in it |
51
55
  | `../config/configurator_builder.rb` | `ConfiguratorBuilder` | Building collections with the exclusions applied |
@@ -57,9 +61,10 @@ Every change to path code must keep these invariants. Specs pin each one.
57
61
 
58
62
  - A build file lies below the build root. No subpath holds `..` or begins at a filesystem root.
59
63
  - Two distinct inputs never share one output. `DestinationCollision` stops the build when they would.
60
- - `BuildSubpath.decode( BuildSubpath.encode( dir ) )` returns `dir` in intake's spelling.
64
+ - `BuildSubpath.decode( BuildSubpath.encode( dir, roots: t ), roots: t )` returns `dir` in intake's spelling, for any table `t`, including none.
61
65
  - A collection holds each place once, however many entries or spellings reach it.
62
- - `ProjectPaths` and `BuildSubpath` never depend on DIY objects or configuration.
66
+ - No test's own build directory lies inside another's. No test name holds `_t_`, so the first `_t_` below a per-test base ends a name.
67
+ - `ProjectPaths`, `BuildSubpath`, and `BuildRoots` never depend on DIY objects or configuration. A table of roots is passed in.
63
68
  - Comparison folds case on Windows only. Stored spellings never change case.
64
69
 
65
70
  ## Spelling paths: `ProjectPaths`
@@ -103,7 +108,7 @@ Every change to path code must keep these invariants. Specs pin each one.
103
108
 
104
109
  ### Markers
105
110
 
106
- Four marker segments stand for what a relative path cannot hold.
111
+ Marker segments stand for what a relative path cannot hold. One more, `_t_`, closes a test's name in the test's own build directories.
107
112
 
108
113
  | Marker | Stands for | Example directory | Encoded subpath |
109
114
  | --- | --- | --- | --- |
@@ -112,26 +117,51 @@ Four marker segments stand for what a relative path cannot hold.
112
117
  | `_abs_` | A path with no relative form, on another Windows drive | `D:/sdk/inc` | `_abs_/D/sdk/inc` |
113
118
  | `_unc_` | A Windows UNC share | `//server/share/inc` | `_unc_/server/share/inc` |
114
119
  | `_ceedling_` | A file Ceedling ships, from the running installation, outside the project | `<installation>/plugins/fff/src` | `_ceedling_/plugins/fff/src` |
120
+ | `_<name>_<hash>` | A long configured root (see [Shortened roots](#shortened-roots)) | `../../../Keil_v5/ARM/CMSIS/Include/os` | `_Include_3F2A91C0/os` |
121
+ | `_t_` | The end of a test's name below a per-test base (see [Each test's own root](#each-tests-own-root-testbuildlayout)). `TestBuildLayout` writes it, and `encode` never does | Test `test/test_c`'s own root | `test/test_c/_t_` |
115
122
 
116
123
  The project root itself encodes as `''`. Its files sit directly below the output root.
117
124
 
125
+ ### Shortened roots
126
+
127
+ A long configured root adds its whole location to every build path below it. A vendor's include directory far outside the project climbs with a chain of `_up_` and then spells its whole path, and a source root nested deep inside the project spells every directory above it. No build step reads that text: nothing compiles or preprocesses a file in an encoded directory, and every tool reads the original source. Only the file's basename must stay literal.
128
+
129
+ `BuildRoots.table(roots)` decides which roots give way to a marker.
130
+
131
+ - **The roots** are `collection_build_roots`, the canonical bases of `:paths` ↳ `:source`, `:include`, `:test`, and `:support` with globs stripped, which `ConfiguratorBuilder#collect_build_roots` takes through `collect_mirror_roots`. `TEST_INCLUDE_PATH()` directories, `:files` entries, and the search paths a test's `#include`s imply for `:files` headers are not roots.
132
+ - **Outermost only.** A root inside another root is dropped, so a whole tree shares one marker and keeps its structure below it.
133
+ - **Shorter only.** A root is shortened only when its marker is shorter than its encoded spelling. A marker is `_`, the root's own directory name with any leading `_` dropped (or `root`), `_`, and 8 upper-case hexadecimal digits of SHA-256 of the root's encoded release spelling, case-folded on Windows. That is 10 characters more than the name, so `src` never shortens, and a climbing or deeply nested root always does. The decision depends only on the root's spelling, so it holds from run to run and changes only when the root does.
134
+ - **Collisions.** `BuildRoots.collisions` finds two roots that would share a marker, and `collect_build_roots` stops configuration naming both.
135
+ - **Traceability.** `FilePathUtils#publish_build_roots` writes each marker and its root to `<build_root>/build_roots.yml`, or removes the file when no root is shortened, and `Setupinator` logs each at DEBUG.
136
+
137
+ `FilePathUtils#build_roots` builds the table once per configured list and passes it to every placement. ReportGenerator's gcov exclusions match each `.gcno` path through `FilePathUtils#expanded_build_path`, which writes each marker back as its root's encoded spelling, so a pattern written against a full build path still matches.
138
+
118
139
  ### Choosing a marker
119
140
 
120
- `encode(path)` decides in a fixed order. It first asks whether the path lies outside the working directory by containment. If so and the path lies in one of `INSTALLED_DIRS`, the file is Ceedling's own and goes under `_ceedling_`. `INSTALLED_DIRS` are the `assets`, `bin`, `lib`, `plugins`, and `vendor` directories of `INSTALLATION_ROOT`, the directory above `lib/`. If the relative form is still absolute, the path takes `_abs_` or `_unc_`. Otherwise each `..` becomes `_up_`.
141
+ `encode(path, roots:, release:)` decides in a fixed order. It first asks whether the path lies outside the working directory by containment. If so and the path lies in one of `INSTALLED_DIRS`, the file is Ceedling's own and goes under `_ceedling_`. Next, a path below a shortened root of `roots` takes the root's marker, followed by its path below the root. `INSTALLED_DIRS` are the `assets`, `bin`, `lib`, `plugins`, and `vendor` directories of `INSTALLATION_ROOT`, the directory above `lib/`. Otherwise, if the relative form is still absolute, the path takes `_abs_` or `_unc_`, and failing that each `..` becomes `_up_`. Without a table, no root is shortened.
121
142
 
122
143
  `_ceedling_` keeps Ceedling's own files short and stable. A gem installation can sit many directories away from a project. Without the marker its plugin sources would encode as a long chain of `_up_` segments that changes with every install location. A Ceedling copy vendored inside the project lies within the working directory, so it encodes by its ordinary path. A project may also sit inside a Ceedling checkout, as the system specs' projects do. Its sibling directories lie outside `INSTALLED_DIRS`, so they encode by `_up_` like any other.
123
144
 
124
145
  ### Escaping a marker-named directory
125
146
 
126
- A real directory named like a marker gains one leading `_`. `MARKER_NAMED` matches `_up_`, `_abs_`, `_unc_`, and `_ceedling_`, already led by any number of `_`, in any case. So `src/_up_/x` encodes as `src/__up_/x`, and `src/__abs_` as `src/___abs_`. `decode` strips one leading `_` from a marker-named segment that begins with `__`. The match ignores case because macOS and Windows file systems fold case, so `_UP_` and `_up_` can name one directory there.
147
+ A real directory named like a marker gains one leading `_`. `MARKER_NAMED` matches `_up_`, `_abs_`, `_unc_`, and `_ceedling_`, already led by any number of `_`, in any case. `ROOT_MARKER_NAMED` matches anything shaped like a root marker, `_` led and ending in `_` and 8 hexadecimal digits, such as a date-stamped `_v_20240101`. An escaped name always begins with `__`, and a root marker never does. So `src/_up_/x` encodes as `src/__up_/x`, and `src/__abs_` as `src/___abs_`. `decode` strips one leading `_` from a marker-named segment that begins with `__`. The match ignores case because macOS and Windows file systems fold case, so `_UP_` and `_up_` can name one directory there.
148
+
149
+ ### Test and release spellings
150
+
151
+ A test build escapes one more name, since `_t_` (`OWN_SEGMENT`) closes a test's name below each per-test base. `encode` and `decode` take `release:`, false by default.
152
+
153
+ - **A test build** escapes each segment of the release spelling that `OWN_NAMED` matches, `_t_` led by any number of `_`, in any case. A test at `test/_t_/test_c.c` is therefore named `test/__t_/test_c`, and its source `src/_t_/foo.c` builds to `…/_t_/src/__t_/foo.o`. No marker `encode` writes matches `OWN_NAMED`, so the escape is a layer over the release spelling, and `decode` takes it off first. The escape applies wherever `BuildSubpath` places a file. A mock or Partial mirrors its header's directory below the test's root as it is, so its root's `_t_` still comes first.
154
+ - **A release build** has no per-test directories and keeps such a directory as it is. `src/_t_/foo.c` builds to `build/release/out/src/_t_/foo.o`. `FilePathUtils` places release objects and dependencies files, and `FileFinder` decodes a release object, with `release: true`.
155
+
156
+ `BuildRoots` hashes a root's release spelling, so test and release builds, which share one table, give a root one marker.
127
157
 
128
158
  ### Decoding
129
159
 
130
- `decode(subpath)` inverts `encode` exactly. A leading `_ceedling_` joins the rest to `INSTALLATION_ROOT` and returns it relative to the working directory. A leading `_unc_` rebuilds `//server/share/…`. A leading `_abs_` rebuilds `D:/…` from its drive segment. Any other subpath maps each `_up_` back to `..` and unescapes the rest.
160
+ `decode(subpath, roots:, release:)` inverts `encode` exactly. A leading segment shaped like a root marker (`ROOT_MARKER`) becomes the root the table holds for it, joined with the rest. A marker the table doesn't hold, left by a build with other roots, decodes to nil. A leading `_ceedling_` joins the rest to `INSTALLATION_ROOT` and returns it relative to the working directory. A leading `_unc_` rebuilds `//server/share/…`. A leading `_abs_` rebuilds `D:/…` from its drive segment. Any other subpath maps each `_up_` back to `..` and unescapes the rest.
131
161
 
132
162
  ### Memo
133
163
 
134
- `of_directory(dir)` memoizes `encode` per working directory and directory behind a Mutex. A build places many files from each directory, and build threads share the memo.
164
+ `of_directory(dir, roots:)` memoizes `encode` per working directory, table digest, and directory behind a Mutex. A build places many files from each directory, and build threads share the memo.
135
165
 
136
166
  ## Placement rules: `FilePathUtils`
137
167
 
@@ -141,21 +171,21 @@ A real directory named like a marker gains one leading `_`. `MARKER_NAMED` match
141
171
 
142
172
  The rule has three cases, tried in order.
143
173
 
144
- 1. A file below one of the caller's `generated_roots` mirrors below that root. These roots are the test's own mock and Partials directories, from `generated_roots(test)`. A mock's object therefore keeps the mock's own subdirectory.
174
+ 1. A file below one of the caller's `generated_roots` mirrors below that root. These roots are the test's own mock and Partials roots, from `TestBuildLayout#generated_roots`. A mock's object therefore keeps the mock's own subdirectory below the test's own output root.
145
175
  2. A file elsewhere below the build root lands flat. These are vendored framework sources and runners, which never share a basename within one test.
146
- 3. Any other file lands at `BuildSubpath.of_directory( File.dirname( file ) )`.
176
+ 3. Any other file lands at `BuildSubpath.of_directory( File.dirname( file ), roots: build_roots )`.
147
177
 
148
- In test `test/drivers/test_uart`, the source `src/drivers/uart.c` builds to `build/test/out/test/drivers/test_uart/src/drivers/uart.o`. A release builds it to `build/release/out/src/drivers/uart.o`. The source `../shared/crc.c` builds to `…/_up_/shared/crc.o`.
178
+ In test `test/drivers/test_uart`, the source `src/drivers/uart.c` builds to `build/test/out/test/drivers/test_uart/_t_/src/drivers/uart.o`. A release builds it to `build/release/out/src/drivers/uart.o`. The source `../shared/crc.c` builds to `…/_up_/shared/crc.o`.
149
179
 
150
180
  ### Forming paths
151
181
 
152
- `build_filepath(file, root:, ext:, generated_roots:)` joins the output root, the subpath, and the basename with the new extension. It checks each formed path's length once through `FileWrapper#check_path_length`. `@formed_paths`, a Set behind `@formed_lock`, remembers which paths were checked.
182
+ `build_filepath(file, root:, ext:, generated_roots:)` joins the output root, the subpath, and the basename with the new extension. It checks each formed path's length through `FileWrapper#check_path_length`, which reports a path once however often it is formed.
153
183
 
154
184
  `mirror_build_objects(files, root:, ext:, generated_roots:)` maps a list of sources at once. It first drops duplicate sources by absolute path, since one file can reach a list under two spellings. It then calls `validate_distinct_build_files!`. That method uses `DestinationCollision.find` and `DestinationCollision.raise_for` to stop the build when two sources would build to one file. The message reads "`a` and `b` would build to the same file `x`. Rename one, or move it to its own directory."
155
185
 
156
186
  These callers use the rule.
157
187
 
158
- - `form_test_object_filepath` and `form_test_build_objects_filelist` place test objects below `build/test/out/<test name>/`.
188
+ - `form_test_object_filepath` and `form_test_build_objects_filelist` place test objects below `build/test/out/<test name>/_t_/`, the test's own output root.
159
189
  - `form_release_build_objects_filelist` and `form_release_dependencies_filelist` place release objects and their `.d` files.
160
190
  - `form_release_dependencies_filepath` mirrors a release object's own subpath below the release dependencies directory.
161
191
  - `preprocessed_file_subpath` places preprocessed headers and sources below each test's preprocessing directories.
@@ -163,7 +193,26 @@ These callers use the rule.
163
193
 
164
194
  ### Test names
165
195
 
166
- A test's name is its path from the project root without its extension. `form_test_name(filepath)` is `BuildSubpath.encode( filepath.ext( '' ) )`. The name places the test's build output, results, runner, mocks, preprocessing, and logs. `test/unit/test_foo.c` is named `test/unit/test_foo`. A test at `../tests/test_x.c` is named `_up_/tests/test_x`. `TestBuildValidations` stops the build through `DestinationCollision` when two tests share a name.
196
+ A test's name is its path from the project root without its extension. `form_test_name(filepath)` is `BuildSubpath.encode( filepath.ext( '' ) )`, with no roots table, so a test name never shortens. The name places the test's build output, results, runner, mocks, preprocessing, and logs. Below each per-test base, `_t_` closes the name (see [Each test's own root](#each-tests-own-root-testbuildlayout)). `test/unit/test_foo.c` is named `test/unit/test_foo`. A test at `../tests/test_x.c` is named `_up_/tests/test_x`. `TestBuildValidations` stops the build through `DestinationCollision` when two tests share a name.
197
+
198
+ ### Each test's own root: `TestBuildLayout`
199
+
200
+ `TestBuildLayout` composes every per-test directory, and is the one place that does. A test's name is a path, so `<base>/<name>` alone can't keep tests apart. `build/test/mocks/test/test_c/test_x/` would be both test `test/test_c/test_x`'s mock directory and the folder `test_x` below test `test/test_c`'s. Each kind of per-test file therefore has a base every test shares, and a test's root of that kind is `<base>/<name>/_t_`. No name holds `_t_`, since a test build's `BuildSubpath` spelling escapes a directory named like it (see [Test and release spellings](#test-and-release-spellings)).
201
+
202
+ | Kind | Base |
203
+ | --- | --- |
204
+ | `:mocks` | `:cmock` ↳ `:mock_path`, with mocks enabled |
205
+ | `:partials` | `build/test/partials`, with Partials enabled |
206
+ | `:preprocess_includes`, `:preprocess_files`, `:build_directives` | `build/test/preprocess/includes`, `…/files`, `…/build_directives` |
207
+ | `:out`, `:dependencies` | `<build_root>/<context>/out` and `…/dependencies`, such as `build/gcov/out` |
208
+
209
+ - `root(kind, name, context:)` gives `<base>/<name>/_t_`, or nil for an empty name or a disabled feature. It checks the root's length once, as a directory's, through `FileWrapper#check_path_length`. Every per-test path gains these 4 characters.
210
+ - `file(kind, name, subpath, context:)` gives a file below a root.
211
+ - `generated_roots(name)` gives the enabled Partials and mock roots.
212
+ - `locate(path, context:)` gives the name of the test whose root holds the path, or nil. Below a base, the first `_t_` ends the name exactly, so no table of test names is needed.
213
+ - `subpath(path, kind:, name:)` gives the path below one test's root of a kind with no build context, or nil.
214
+
215
+ `FilePathUtils` forms each test's directories, its object and dependencies files, its preprocessed files, and its stand-in headers through it. A test's executable and linker map sit in its own output root with its objects. `form_test_build_path( nil, context: )` and `form_test_dependencies_path( nil, context: )` give the context's base, where a plugin's own sources outside any test build. `FileFinder` scopes its mock and Partial searches to a test's roots, and `IncludeFactory` strips a mock `#include`'s leading root through `subpath`. Every other stage reads a test's directories from `Testable#paths`. Runners, results, logs, and artifacts are files named by a test's basename below the directories of its name, which can't collide, so they stay outside the layout.
167
216
 
168
217
  ### The Dependencies plugin
169
218
 
@@ -171,9 +220,9 @@ The Dependencies plugin places objects by a different root. `Dependencies#prepar
171
220
 
172
221
  ## Mocks: `MockLocator`
173
222
 
174
- Mocks keep placement relative to their include root, not the project root. CMock's folder semantics need it. The test's search path `-I build/test/mocks/<test>` must resolve `#include "drv/mock_gpio.h"` as written. A mock's identity, its CMock symbols and runner entries, also comes from that path.
223
+ Mocks keep placement relative to their include root, not the project root. CMock's folder semantics need it. The test's search path `-I build/test/mocks/<test>/_t_`, its mock root, must resolve `#include "drv/mock_gpio.h"` as written. A mock's identity, its CMock symbols and runner entries, also comes from that path.
175
224
 
176
- `FileFinder#resolve_mock` finds the mocked header. It then takes the header's subdirectory below the most specific root of `collection_mirror_roots_headers` through `PathMirror.relative_subdir_from_clean_roots`. Containment is by whole directories, so a header outside every root yields `''`. Its mock then lands flat in the test's mock directory.
225
+ `FileFinder#resolve_mock` finds the mocked header through the test's `HeaderSearch`, joining each search path with the `#include`'s path as the compiler does. It then takes the header's subdirectory below the most specific root of `collection_mirror_roots_headers` through `PathMirror.relative_subdir_from_clean_roots`. Containment is by whole directories, so a header outside every root yields `''`. Its mock then lands flat in the test's mock directory, or at the path its `#include` folder writes, as for a `:files` ↳ `:include` header outside every `:paths` root.
177
226
 
178
227
  `MockLocator#placement(mocks_root:, subdir:, include_path:)` returns a `MockPlacement` struct with four fields.
179
228
 
@@ -192,11 +241,13 @@ A lookup from a build file inverts placement exactly. It finds the input by path
192
241
 
193
242
  1. A path outside the build root is a source-tree query from an `#include` or `TEST_SOURCE_FILE()`. `header_root_relative_query` handles it.
194
243
  2. Inside the build root, `placement_root` names the release output root or the test's build path.
195
- 3. The subdirectory below that root is decoded by `BuildSubpath.decode` and joined with the basename. The query is marked exact.
244
+ 3. The subdirectory below that root is decoded by `BuildSubpath.decode` with `FilePathUtils#build_roots`, in the release spelling for a release object, and joined with the basename. The query is marked exact. A marker no root holds falls back to the bare basename.
196
245
 
197
246
  `find_compiled_input` tries an exact query first through `exact_file`. `exact_file` builds an index per collection, keyed by `compare_by_identity` and then by absolute path. A tail match by trailing segments follows only when the exact query misses. It also serves a query that is not exact, such as an object below a third-party plugin's build root that placement does not know.
198
247
 
199
- `test_context_of(filepath)` recovers a test name from a path below `build/test/out/`. Objects nest below the name at their own paths, so it returns the longest known test name that the directory begins with.
248
+ `test_context_of(filepath, context)` recovers a test name from a build file's path through `TestBuildLayout#locate`. A source-tree query, from an `#include` or `TEST_SOURCE_FILE()`, recovers none. The mock and Partial searches look only below a known test's own roots, so such a query never finds another test's generated files.
249
+
250
+ A name with the mock or Partial prefix may also be a hand-written source's, linked through `TEST_SOURCE_FILE()`. A miss among the test's own generated files therefore falls through to `find_compiled_input`. A miss of both complains of the generated file, by the name the generated search sought.
200
251
 
201
252
  `header_root_relative_query(filepath)` correlates a header with the source beside it. Headers and sources often sit below different roots, such as `include/` and `src/`. The query is the header's subdirectory below its root in `collection_mirror_roots_include`, so `include/drv/gpio.h` looks for a source whose path ends in `drv/gpio`. `Partializer` uses the same roots for module sources.
202
253
 
@@ -234,7 +285,7 @@ The `minus` rule lets `+:src/legacy/keep` survive beside `-:src/legacy`, because
234
285
 
235
286
  ### Mirror roots
236
287
 
237
- `collect_mirror_roots(entries)` computes the roots that mocks and header lookups measure against, once, at configuration time. It strips a `/**` or `/*` tail, expands a glob in the middle of an entry into one root per directory, and canonicalizes each. `ConfiguratorBuilder#collect_mirror_roots` stores two lists. `collection_mirror_roots_include` comes from `:paths` ↳ `:include`. `collection_mirror_roots_headers` adds `:test` and `:support`.
288
+ `collect_mirror_roots(entries)` computes the roots that mocks and header lookups measure against, once, at configuration time. It strips a `/**` or `/*` tail, expands a glob in the middle of an entry into one root per directory, and canonicalizes each. `ConfiguratorBuilder#collect_mirror_roots` stores two lists. `collection_mirror_roots_include` comes from `:paths` ↳ `:include`. `collection_mirror_roots_headers` adds `:test` and `:support`. `collect_build_roots` stores a third, `collection_build_roots`, from `:source`, `:include`, `:test`, and `:support`, for [shortened roots](#shortened-roots).
238
289
 
239
290
  ## The build root: `BuildRootPolicy`
240
291
 
@@ -252,7 +303,7 @@ A `-:` entry that matches nothing is never an error. `ConfiguratorPathsValidator
252
303
 
253
304
  Several settings reach paths outside `:paths` and `:files`. Each spells its paths through `ProjectPaths` at intake.
254
305
 
255
- - `TestContextExtractor` canonicalizes every `TEST_INCLUDE_PATH()` entry. `IncludePathinator#prioritized_header_files` then ranks headers by walking up each header's directories to the nearest search root, with `rank_key` folding case on Windows.
306
+ - `TestContextExtractor` canonicalizes every `TEST_INCLUDE_PATH()` entry. `IncludePathinator#prioritize` then ranks headers by walking up each header's directories to the nearest search root, with `rank_key` folding case on Windows. `prioritized_header_files` ranks the whole collection for Partials, and `collection_candidates` ranks a query's matches when stage 2 derives a search path for a `:files` header.
256
307
  - `LibraryResolver#search_directories` collects `:paths` ↳ `:libraries` through `collect_paths` and memoizes the result. `search_path_arguments` forms the `-L` arguments from it.
257
308
  - `ConfiguratorBuilder#set_release_target` standardizes `:release_build` ↳ `:output`. An absolute output names the artifact itself.
258
309
  - `CliHelper#process_logging_path` applies inline Ruby expansion and `standardize` to the build root before configuration loads. It refuses one that expands to nothing.
@@ -271,7 +322,10 @@ Paths behave differently on Windows, macOS, and other POSIX systems. The code ha
271
322
  - **`_abs_`.** Only Windows produces `_abs_`. A path on another drive has no relative form, and `Pathname#relative_path_from` raises `ArgumentError`. `relative` then returns the absolute path, and `encode` places it under `_abs_/<drive>/…`.
272
323
  - **UNC shares.** `unc?` is true only on Windows. `unc_absolute` resolves `..` but never climbs above `//server/share`. A share encodes under `_unc_`.
273
324
  - **Unclean segments.** `File.expand_path` lengthens a short `~1` name and drops a trailing dot or space. `UNCLEAN` therefore treats `~`, a trailing dot, and a trailing space as unclean, so those paths always pass through `File.expand_path`.
274
- - **Path length.** Placement by project path lengthens build paths. A source far from the project gains one `_up_` per climbing level. `build_filepath` checks each path once against the 260-character limit through `FileWrapper#check_path_length`, which warns. `_ceedling_` keeps installed files short.
325
+ - **Path length.** Placement by project path lengthens build paths. A source far from the project gains one `_up_` per climbing level, unless a shortened root holds it, and `_ceedling_` keeps installed files short. `FileWrapper#check_path_length` measures each path it is given against the remembered working directory, with no system call, and reports it once per process: a warning within 25 characters of the limit, an error at or past it. Only a reported path is recorded, keyed by its `absolute` spelling, so a build's many short paths cost one comparison each and are never remembered.
326
+ - **The limit.** `:project` ↳ `:win_path_limit` picks it. `:classic`, the default, is Windows' classic limit: 260 characters for a file and 248 for a directory that `mkdir` or `mkdir_tmp` creates. `:long_paths` and `:auto` can lift it to 32,767.
327
+ - **The probe.** Long paths need the host's `LongPathsEnabled` and a long-path-aware program, and Ruby before 4.0 can write long paths but not list them. So `WinLongPaths.probe` writes, reads, and lists a file nested past 260 characters below the build root, then removes exactly what it made. `WinPathProber` runs it once per process, under a lock, when `FileWrapper` first sees a path near 260, and only for `:long_paths` or `:auto`. The registry is read only when files fail, to name the cause, through `:tools` ↳ `:windows_registry_query` and `ToolExecutor`. Configuration adds that optional tool only on Windows with one of those two modes.
328
+ - **The answer.** `WinPathLimit.decision` turns the probe's result and the mode into the limit and one message, which `WinPathProber` logs. `:auto` lifts the limit only when listing works too. `:long_paths` lifts it whenever files work, warning once when listing doesn't. Without long path support, either keeps 260 and says why. `FileWrapper` keeps the answer, and the launcher's `FileWrapper`, which has no prober, keeps the classic limits.
275
329
  - **Real-path casing.** Intake takes a path's on-disk casing from `File.realpath`, along the existing part of the path.
276
330
 
277
331
  ### macOS
@@ -281,7 +335,7 @@ Paths behave differently on Windows, macOS, and other POSIX systems. The code ha
281
335
 
282
336
  ### Linux and other POSIX systems
283
337
 
284
- - **Absolute paths.** Every absolute path has a relative form. A header at `/opt/sdk/inc` encodes as a chain of `_up_` segments followed by `opt/sdk/inc`, never as `_abs_`. The chain grows with the project's depth below `/`.
338
+ - **Absolute paths.** Every absolute path has a relative form. A header at `/opt/sdk/inc` encodes as a chain of `_up_` segments followed by `opt/sdk/inc`, never as `_abs_`. The chain grows with the project's depth below `/`, unless `/opt/sdk/inc` is a configured root, which then takes its marker.
285
339
  - **Doubled separators.** A leading `//` is the filesystem root, not a share. `absolute` squeezes it to `/`.
286
340
 
287
341
  ## Changing path code
@@ -291,14 +345,16 @@ A change to path code keeps the invariants by following the patterns above. Thes
291
345
  - Compare places with `ProjectPaths.contains?` or `subdir_below`. Never compare path text with `start_with?` or `include?`.
292
346
  - Spell configured paths with `standardize` at intake and `canonical` where a symlinked spelling matters.
293
347
  - Place build files through `form_build_subpath` or `build_filepath`. Never join a source's directory under a build root directly.
348
+ - Compose a per-test directory only through `TestBuildLayout`, and read a test's directories from `Testable#paths`.
294
349
  - Run a new list of outputs through `DestinationCollision`.
295
- - Add a marker by updating `MARKER_NAMED`, `encode`, and `decode` together, with a round-trip spec.
296
- - Keep `ProjectPaths`, `BuildSubpath`, `PathSpellings`, and `PathExclusions` free of DIY objects and configuration.
350
+ - Add a marker by updating `MARKER_NAMED` (or `ROOT_MARKER_NAMED`), `encode`, and `decode` together, with a round-trip spec.
351
+ - Keep `ProjectPaths`, `BuildSubpath`, `BuildRoots`, `PathSpellings`, and `PathExclusions` free of DIY objects and configuration.
352
+ - Match a pattern written against build paths through `FilePathUtils#expanded_build_path`, so a shortened root never hides text the pattern names.
297
353
 
298
354
  ## Specs
299
355
 
300
356
  Each tier pins a different layer of this design.
301
357
 
302
- - **Unit.** `spec/units/filesystem/project_paths_spec.rb`, `build_subpath_spec.rb`, `path_mirror_spec.rb`, `path_matcher_spec.rb`, `destination_collision_spec.rb`, `file_path_utils_spec.rb`, `file_path_collection_utils_spec.rb`, and `file_finder_spec.rb`, with `spec/units/mock_locator_spec.rb`, `spec/units/library_resolver_spec.rb`, and `spec/units/config/build_root_policy_spec.rb`. Windows drive and UNC examples run only on Windows.
358
+ - **Unit.** `spec/units/filesystem/project_paths_spec.rb`, `build_subpath_spec.rb`, `build_roots_spec.rb`, `path_mirror_spec.rb`, `path_matcher_spec.rb`, `destination_collision_spec.rb`, `test_build_layout_spec.rb`, `file_path_utils_spec.rb`, `file_path_collection_utils_spec.rb`, and `file_finder_spec.rb`, with `spec/units/mock_locator_spec.rb`, `spec/units/library_resolver_spec.rb`, and `spec/units/config/build_root_policy_spec.rb`. Windows drive and UNC examples run only on Windows.
303
359
  - **Integration.** `spec/integration/path_scenarios_spec.rb` and `path_intake_scenarios_spec.rb` configure real projects in temporary workspaces through `spec/support/integration/path_scenario_harness.rb`. `expect_collections_outside_build` and `expect_one_spelling_each` assert the invariants.
304
- - **System.** `spec/system/path_handling_probes_spec.rb`, `build_output_mirroring_spec.rb`, `rake_release_task_path_disambiguation_spec.rb`, `bracket_path_handling_spec.rb`, and `special_path_characters_spec.rb` run full builds.
360
+ - **System.** `spec/system/path_handling_probes_spec.rb`, `test_build_layout_spec.rb`, `short_build_paths_spec.rb`, `build_output_mirroring_spec.rb`, `rake_release_task_path_disambiguation_spec.rb`, `bracket_path_handling_spec.rb`, and `special_path_characters_spec.rb` run full builds.
@@ -14,12 +14,15 @@ Pure modules with no state beyond memos.
14
14
  | --- | --- | --- |
15
15
  | [`project_paths.rb`](project_paths.rb) | `ProjectPaths` | One spelling for every path. Absolute, relative, and canonical forms, and containment by whole directories |
16
16
  | [`working_dir.rb`](working_dir.rb) | `WorkingDir` | The working directory, read once, and `chdir`, the one way Ceedling code changes it |
17
- | [`build_subpath.rb`](build_subpath.rb) | `BuildSubpath` | A build file's place from its source's path from the project root, with the `_up_`, `_abs_`, `_unc_`, and `_ceedling_` markers, and back |
17
+ | [`build_subpath.rb`](build_subpath.rb) | `BuildSubpath` | A build file's place from its source's path from the project root, with the `_up_`, `_abs_`, `_unc_`, and `_ceedling_` markers, and back. A test build also escapes a directory named like `_t_`, the segment closing a test's name, and a release build doesn't |
18
+ | [`build_roots.rb`](build_roots.rb) | `BuildRoots` | Which long configured roots build paths spell by a short `_<name>_<hash>` marker, and each marker |
18
19
  | [`path_spellings.rb`](path_spellings.rb) | `PathSpellings` | A place's listed and real spellings, and how far one place lies below another |
19
20
  | [`path_exclusions.rb`](path_exclusions.rb) | `PathExclusions` | What collection leaves out: `-:` entries, excluded places, and reserved places |
20
21
  | [`path_mirror.rb`](path_mirror.rb) | `PathMirror` | A file's subdirectory below the most specific configured root that contains it |
21
22
  | [`path_matcher.rb`](path_matcher.rb) | `PathMatcher` | Resolving `..` in a query, and matching a query's trailing segments against a collection |
22
23
  | [`destination_collision.rb`](destination_collision.rb) | `DestinationCollision` | Stopping a build when two inputs map to one output |
24
+ | [`win_long_paths.rb`](win_long_paths.rb) | `WinLongPaths` | Windows' path length limits, and a probe of whether this Ruby can create and list paths past 260 characters, given a registry query to name the cause of a failure |
25
+ | [`win_path_limit.rb`](win_path_limit.rb) | `WinPathLimit` | What `:project` ↳ `:win_path_limit` means once the probe answers: the limit that applies, and the one message saying why |
23
26
 
24
27
  ## Path services
25
28
 
@@ -28,9 +31,11 @@ DIY objects that apply the modules above to a project's configuration.
28
31
  | File | Class | Role |
29
32
  | --- | --- | --- |
30
33
  | [`file_path_utils.rb`](file_path_utils.rb) | `FilePathUtils` | Test names and the path of every build file |
34
+ | [`test_build_layout.rb`](test_build_layout.rb) | `TestBuildLayout` | Each test's own build directories, `<base>/<name>/_t_`, and which test's a build path lies in |
31
35
  | [`file_path_collection_utils.rb`](file_path_collection_utils.rb) | `FilePathCollectionUtils` | Collecting `:paths` directories and `:files` revisions, with exclusions applied |
32
36
  | [`file_finder.rb`](file_finder.rb) | `FileFinder` | Finding a build file's input from the build file's own path |
33
37
  | [`file_finder_helper.rb`](file_finder_helper.rb) | `FileFinderHelper` | Resolving a query against a collection: its one match, the first of several with a notice, or a report of none |
38
+ | [`win_path_prober.rb`](win_path_prober.rb) | `WinPathProber` | Whether Windows long paths are in effect for `:project` ↳ `:win_path_limit`: the probe, run once below the build root, with the registry read through the `:windows_registry_query` tool |
34
39
 
35
40
  ## File I/O
36
41
 
@@ -0,0 +1,105 @@
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
+ # Loaded eagerly: Digest's lazy autoload is not thread-safe, and build threads form paths
9
+ require 'digest/sha2'
10
+ require 'ceedling/filesystem/project_paths'
11
+ require 'ceedling/filesystem/build_subpath'
12
+
13
+ # Which configured roots a build path spells by a short marker instead of their whole
14
+ # location, and what each marker is.
15
+ #
16
+ # A build file sits below the build directory at its source's path from the project root
17
+ # (see BuildSubpath). For a source below a long root, such as a vendor's include directory
18
+ # far outside the project, most of that path is the root's own location, which no build
19
+ # step reads. Such a root is replaced by `_<name>_<hash>`: its own directory name, then 8
20
+ # hex digits of SHA-256 of its encoded spelling. Everything below the root keeps its path.
21
+ # Test and release builds share one table, so the spelling hashed is a release build's.
22
+ #
23
+ # Only the outermost of nested roots counts, so a whole tree shares one marker, and a root
24
+ # is shortened only when its marker is shorter than its encoded spelling. The decision
25
+ # depends on nothing but the root's spelling, so it holds from run to run.
26
+ module BuildRoots
27
+
28
+ HASH_LENGTH = 8
29
+
30
+ # A build subpath's first segment shaped like a marker. Only a table says whether it is one.
31
+ MARKER = BuildSubpath::ROOT_MARKER
32
+
33
+ # The roots shortened, and their markers
34
+ class Table
35
+
36
+ attr_reader :digest
37
+
38
+ def initialize(markers)
39
+ @markers = markers.freeze
40
+ @roots = markers.invert.freeze
41
+ @absolutes = markers.keys.to_h { |root| [root, ProjectPaths.absolute( root )] }.freeze
42
+ @digest = markers.map { |root, marker| "#{marker}=#{root}" }.join( "\n" ).freeze
43
+ freeze
44
+ end
45
+
46
+ def marker_for(root) = @markers[root]
47
+
48
+ def root_for(marker) = @roots[marker]
49
+
50
+ # The shortened root holding an absolute path, if any. Roots are outermost, so at most one does.
51
+ def containing(full)
52
+ return @absolutes.find { |_root, absolute| ProjectPaths.contains?( absolute, full ) }&.first
53
+ end
54
+
55
+ # Each shortened root and its marker, in configuration order
56
+ def entries = @markers.to_a
57
+
58
+ def empty? = @markers.empty?
59
+
60
+ end
61
+
62
+ # The table for canonical root spellings, as configuration collects them
63
+ def self.table(roots, windows: ProjectPaths::WINDOWS)
64
+ return Table.new( candidates( roots, windows ).uniq { |_root, marker| marker }.to_h )
65
+ end
66
+
67
+ # Pairs of distinct roots whose markers would be the same
68
+ def self.collisions(roots, windows: ProjectPaths::WINDOWS)
69
+ return candidates( roots, windows ).group_by { |_root, marker| marker }.values
70
+ .select { |group| group.length > 1 }
71
+ .flat_map { |group| group.map( &:first ).combination( 2 ).to_a }
72
+ end
73
+
74
+ # The outermost roots worth shortening, each with its marker
75
+ def self.candidates(roots, windows)
76
+ # Two spellings of one place are one root
77
+ return outermost( roots.map( &:to_s ).uniq { |root| ProjectPaths.absolute( root ) } ).filter_map do |root|
78
+ encoded = BuildSubpath.encode( root, release: true )
79
+ # A file Ceedling ships is already placed briefly below `_ceedling_`
80
+ next if encoded.start_with?( BuildSubpath::INSTALLED_SEGMENT )
81
+
82
+ marker = marker( root, encoded, windows )
83
+ [root, marker] if marker.length < encoded.length
84
+ end
85
+ end
86
+
87
+ def self.outermost(roots)
88
+ absolutes = roots.to_h { |root| [root, ProjectPaths.absolute( root )] }
89
+
90
+ return roots.reject do |root|
91
+ absolutes.any? { |other, absolute| other != root && ProjectPaths.contains?( absolute, absolutes[root] ) }
92
+ end
93
+ end
94
+
95
+ def self.marker(root, encoded, windows)
96
+ key = windows ? encoded.downcase : encoded
97
+ name = ProjectPaths.segments( ProjectPaths.absolute( root ) ).last.to_s.delete( ':' ).sub( /\A_+/, '' )
98
+ name = 'root' if name.empty?
99
+
100
+ return "_#{name}_#{Digest::SHA256.hexdigest( key )[0, HASH_LENGTH].upcase}"
101
+ end
102
+
103
+ private_class_method :candidates, :outermost, :marker
104
+
105
+ end
@@ -10,9 +10,15 @@ require 'ceedling/filesystem/project_paths'
10
10
  # Where a build places a file of a path: by its path from the project root, so two files
11
11
  # never share a build file and none lands outside the build directory. `..` becomes `_up_`,
12
12
  # a path on another drive goes under `_abs_` or `_unc_`, and a file the running Ceedling
13
- # installation ships, outside the project, goes under `_ceedling_`. A directory of a path
14
- # that is itself named like one of these gains a leading `_`, so `decode` inverts `encode`
13
+ # installation ships, outside the project, goes under `_ceedling_`. Given a table of
14
+ # shortened roots (see BuildRoots), a path below one of them goes under the root's
15
+ # `_<name>_<hash>` marker instead, keeping its path below the root. A directory of a path
16
+ # that is itself named like any of these gains a leading `_`, so `decode` inverts `encode`
15
17
  # exactly.
18
+ #
19
+ # A test build also escapes a directory named like `_t_` in the same way, since that
20
+ # segment closes a test's name. A release build, `release: true`, has no per-test
21
+ # directories and keeps such a directory as it is.
16
22
  module BuildSubpath
17
23
 
18
24
  PARENT_SEGMENT = '_up_'
@@ -20,10 +26,26 @@ module BuildSubpath
20
26
  UNC_SEGMENT = '_unc_'
21
27
  INSTALLED_SEGMENT = '_ceedling_'
22
28
 
29
+ # The segment that closes a test's name in its own build directories (see TestBuildLayout).
30
+ # A test build's `encode` writes it nowhere, and escapes a directory named like it, so no
31
+ # name holds it.
32
+ OWN_SEGMENT = '_t_'
33
+
23
34
  # A segment of a path named like a marker, perhaps already led by more `_`, in any case,
24
35
  # since macOS and Windows file systems fold it
25
36
  MARKER_NAMED = /\A_+(?:up|abs|unc|ceedling)_\z/i
26
37
 
38
+ # A segment named like OWN_SEGMENT in the same way
39
+ OWN_NAMED = /\A_+t_\z/i
40
+
41
+ # A segment of a path shaped like a shortened root's marker (see BuildRoots::MARKER),
42
+ # perhaps already led by more `_`, in any case
43
+ ROOT_MARKER_NAMED = /\A_+[^\/]*_[0-9a-f]{8}\z/i
44
+
45
+ # A segment shaped like a marker itself, which only `encode` writes: escaping leads every
46
+ # look-alike with at least two `_`. Kept in step with BuildRoots::MARKER.
47
+ ROOT_MARKER = /\A_[^_\/][^\/]*_[0-9A-F]{8}\z/
48
+
27
49
  # The running Ceedling installation, above lib/ceedling/filesystem/
28
50
  INSTALLATION_ROOT = File.expand_path( '../../..', __dir__ )
29
51
 
@@ -34,38 +56,72 @@ module BuildSubpath
34
56
  @lock = Mutex.new
35
57
  @subpaths = {}
36
58
 
37
- # The build subpath that places a file of `path` by its path from the project root
38
- def self.encode(path)
39
- full = ProjectPaths.absolute( path )
40
- rel = ProjectPaths.relative( full )
41
-
42
- # Another drive, with no relative path to the project, lies outside it as a climb does
43
- beyond = !ProjectPaths.contains?( ProjectPaths.working_dir, full )
44
- return installed_segments( full ).join( '/' ) if beyond && installed?( full )
45
- return absolute_segments( rel ).join( '/' ) if ProjectPaths.absolute?( rel )
59
+ # The build subpath that places a file of `path` by its path from the project root, or
60
+ # below the marker of the shortened root in `roots` that holds it
61
+ def self.encode(path, roots: nil, release: false)
62
+ segments = placed_segments( ProjectPaths.absolute( path ), roots )
63
+ segments = segments.map { |segment| escape_own( segment ) } unless release
46
64
 
47
- return ProjectPaths.segments( rel ).map { |segment| segment == '..' ? PARENT_SEGMENT : escape( segment ) }.join( '/' )
65
+ return segments.join( '/' )
48
66
  end
49
67
 
50
- # The path, in intake's spelling, that `encode` made `subpath` from
51
- def self.decode(subpath)
68
+ # The path, in intake's spelling, that `encode` made `subpath` from, or nil for a root
69
+ # marker that `roots` does not hold
70
+ def self.decode(subpath, roots: nil, release: false)
52
71
  segments = ProjectPaths.segments( subpath )
72
+ segments = segments.map { |segment| unescape_own( segment ) } unless release
53
73
  rest = unescaped( segments.drop( 1 ) )
54
74
 
75
+ return decoded_root( roots, segments.first, rest ) if segments.first.to_s.match?( ROOT_MARKER )
76
+
77
+ return decoded_marker( segments, rest ) || segments.map { |segment| segment == PARENT_SEGMENT ? '..' : unescape( segment ) }.join( '/' )
78
+ end
79
+
80
+ # `encode` for a directory, memoized per table of roots and kind of build, since a build
81
+ # places many files from each directory. The working directory itself encodes as ''.
82
+ def self.of_directory(dir, roots: nil, release: false)
83
+ key = [ProjectPaths.working_dir, roots&.digest, release, dir.to_s]
84
+ return @lock.synchronize { @subpaths[key] ||= encode( dir, roots: roots, release: release ) }
85
+ end
86
+
87
+ # The segments of a release build's spelling of an absolute path
88
+ def self.placed_segments(full, roots)
89
+ return outside_segments( full, roots ) unless ProjectPaths.contains?( ProjectPaths.working_dir, full )
90
+
91
+ root = roots&.containing( full )
92
+ return root_segments( roots, root, full ) unless root.nil?
93
+
94
+ return relative_segments( ProjectPaths.relative( full ) )
95
+ end
96
+
97
+ # A path outside the project, a climb or another drive: a file Ceedling ships goes below
98
+ # `_ceedling_`, before any root, since it is already placed briefly
99
+ def self.outside_segments(full, roots)
100
+ return installed_segments( full ) if installed?( full )
101
+
102
+ root = roots&.containing( full )
103
+ return root_segments( roots, root, full ) unless root.nil?
104
+
105
+ return relative_segments( ProjectPaths.relative( full ) )
106
+ end
107
+
108
+ # A relative path's segments with each `..` as `_up_`, or an absolute one's below `_abs_`
109
+ # or `_unc_`
110
+ def self.relative_segments(rel)
111
+ return absolute_segments( rel ) if ProjectPaths.absolute?( rel )
112
+
113
+ return ProjectPaths.segments( rel ).map { |segment| segment == '..' ? PARENT_SEGMENT : escape( segment ) }
114
+ end
115
+
116
+ # The path a leading `_ceedling_`, `_unc_`, or `_abs_` marker stands for, or nil
117
+ def self.decoded_marker(segments, rest)
55
118
  case segments.first
56
119
  when INSTALLED_SEGMENT then return ProjectPaths.relative( File.join( INSTALLATION_ROOT, *rest ) )
57
120
  when UNC_SEGMENT then return "//#{rest.join( '/' )}"
58
121
  when ABSOLUTE_SEGMENT then return "#{segments[1]}:/#{rest.drop( 1 ).join( '/' )}"
59
122
  end
60
123
 
61
- return segments.map { |segment| segment == PARENT_SEGMENT ? '..' : unescape( segment ) }.join( '/' )
62
- end
63
-
64
- # `encode` for a directory, memoized, since a build places many files from each directory.
65
- # The working directory itself encodes as ''.
66
- def self.of_directory(dir)
67
- key = [ProjectPaths.working_dir, dir.to_s]
68
- return @lock.synchronize { @subpaths[key] ||= encode( dir ) }
124
+ return nil
69
125
  end
70
126
 
71
127
  def self.installed?(full)
@@ -77,11 +133,38 @@ module BuildSubpath
77
133
  end
78
134
 
79
135
  def self.escape(segment)
80
- return segment.match?( MARKER_NAMED ) ? "_#{segment}" : segment
136
+ return marker_named?( segment ) ? "_#{segment}" : segment
81
137
  end
82
138
 
83
139
  def self.unescape(segment)
84
- return segment.match?( MARKER_NAMED ) && segment.start_with?( '__' ) ? segment[1..] : segment
140
+ return marker_named?( segment ) && segment.start_with?( '__' ) ? segment[1..] : segment
141
+ end
142
+
143
+ def self.marker_named?(segment)
144
+ return segment.match?( MARKER_NAMED ) || segment.match?( ROOT_MARKER_NAMED )
145
+ end
146
+
147
+ # No marker `encode` writes is named like OWN_SEGMENT, so a test build escapes the
148
+ # segments of a release build's spelling, and unescapes them before reading it
149
+ def self.escape_own(segment)
150
+ return segment.match?( OWN_NAMED ) ? "_#{segment}" : segment
151
+ end
152
+
153
+ def self.unescape_own(segment)
154
+ return segment.match?( OWN_NAMED ) && segment.start_with?( '__' ) ? segment[1..] : segment
155
+ end
156
+
157
+ # A path below a shortened root: the root's marker, then the path below the root
158
+ def self.root_segments(roots, root, full)
159
+ below = ProjectPaths.subdir_below( ProjectPaths.absolute( root ), full )
160
+ return [roots.marker_for( root )] + ProjectPaths.segments( below ).map { |segment| escape( segment ) }
161
+ end
162
+
163
+ def self.decoded_root(roots, marker, rest)
164
+ root = roots&.root_for( marker )
165
+ return nil if root.nil?
166
+
167
+ return rest.empty? ? root : File.join( root, *rest )
85
168
  end
86
169
 
87
170
  def self.unescaped(segments)
@@ -97,6 +180,8 @@ module BuildSubpath
97
180
  return [ABSOLUTE_SEGMENT] + parts.each_with_index.map { |part, index| index.zero? ? part.delete_suffix( ':' ) : escape( part ) }
98
181
  end
99
182
 
100
- private_class_method :installed?, :installed_segments, :absolute_segments, :escape, :unescape, :unescaped
183
+ private_class_method :installed?, :installed_segments, :absolute_segments, :escape, :unescape, :unescaped,
184
+ :marker_named?, :root_segments, :decoded_root, :outside_segments, :relative_segments, :decoded_marker,
185
+ :placed_segments, :escape_own, :unescape_own
101
186
 
102
187
  end