ceedling 1.2.1 → 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 (545) hide show
  1. checksums.yaml +4 -4
  2. data/GIT_COMMIT_SHA +1 -1
  3. data/README.md +11 -9
  4. data/Rakefile +2 -1
  5. data/assets/features/ceedling +1 -1
  6. data/assets/fixtures/test_source_file_duplicate_basenames/test_calc_typo.c +14 -0
  7. data/assets/fixtures/tests_with_duplicate_test_names/test_foo.c +21 -0
  8. data/assets/fixtures/tests_with_partials_coverage/src/private_macro.c +7 -0
  9. data/assets/fixtures/tests_with_partials_coverage/src/private_macro.h +5 -0
  10. data/assets/fixtures/tests_with_partials_coverage/src/tally.c +13 -0
  11. data/assets/fixtures/tests_with_partials_coverage/src/tally.h +4 -0
  12. data/assets/fixtures/tests_with_partials_coverage/test/test_private_macro.c +10 -0
  13. data/assets/fixtures/tests_with_partials_coverage/test/test_tally.c +9 -0
  14. data/bin/actionator.rb +6 -12
  15. data/bin/app_cfg.rb +14 -1
  16. data/bin/ceedling +13 -3
  17. data/bin/cli.rb +25 -6
  18. data/bin/cli_handler.rb +113 -73
  19. data/bin/cli_helper.rb +51 -78
  20. data/bin/installation_selector.rb +81 -0
  21. data/bin/launchinator.rb +69 -0
  22. data/bin/mixin_resolvinator.rb +26 -36
  23. data/bin/objects.yml +13 -0
  24. data/bin/path_validator.rb +25 -29
  25. data/bin/versionator.rb +47 -48
  26. data/ceedling.gemspec +19 -15
  27. data/docs/BreakingChanges.md +86 -1
  28. data/docs/Changelog.md +145 -3
  29. data/docs/KnownIssues.md +179 -6
  30. data/docs/ReleaseNotes.md +13 -0
  31. data/examples/wondrous_forest/README.md +29 -1
  32. data/examples/wondrous_forest/src/ForestUnits.h +23 -0
  33. data/examples/wondrous_forest/src/RainGauge.c +59 -0
  34. data/examples/wondrous_forest/src/RainGauge.h +39 -0
  35. data/examples/wondrous_forest/src/RainTipIsr.c +17 -0
  36. data/examples/wondrous_forest/src/RainTipIsr.h +14 -0
  37. data/examples/wondrous_forest/test/TestRainGauge.c +126 -0
  38. data/lib/ceedling/build_log_writer.rb +33 -0
  39. data/lib/ceedling/c_extractor/README.md +15 -7
  40. data/lib/ceedling/c_extractor/c_extractor.rb +25 -14
  41. data/lib/ceedling/c_extractor/c_extractor_code_text.rb +84 -54
  42. data/lib/ceedling/c_extractor/c_extractor_constants.rb +18 -7
  43. data/lib/ceedling/c_extractor/c_extractor_declarations.rb +319 -283
  44. data/lib/ceedling/c_extractor/c_extractor_declarator.rb +285 -0
  45. data/lib/ceedling/c_extractor/c_extractor_defined_type.rb +111 -0
  46. data/lib/ceedling/c_extractor/c_extractor_definitions.rb +174 -121
  47. data/lib/ceedling/c_extractor/c_extractor_functions.rb +191 -162
  48. data/lib/ceedling/c_extractor/c_extractor_preprocessing.rb +46 -55
  49. data/lib/ceedling/c_extractor/c_extractor_statement.rb +30 -0
  50. data/lib/ceedling/c_extractor/c_extractor_types.rb +63 -41
  51. data/lib/ceedling/c_extractor/c_module_edits.rb +48 -0
  52. data/lib/ceedling/c_identifier.rb +21 -0
  53. data/lib/ceedling/ceedling.h +8 -0
  54. data/lib/ceedling/config/build_root_policy.rb +70 -0
  55. data/lib/ceedling/config/configurator.rb +18 -19
  56. data/lib/ceedling/config/configurator_builder.rb +75 -28
  57. data/lib/ceedling/config/configurator_paths_validator.rb +179 -0
  58. data/lib/ceedling/config/configurator_plugins.rb +1 -1
  59. data/lib/ceedling/config/configurator_setup.rb +44 -33
  60. data/lib/ceedling/config/configurator_validator.rb +1 -110
  61. data/lib/ceedling/constants.rb +5 -1
  62. data/lib/ceedling/defaults.rb +35 -5
  63. data/lib/ceedling/dependencies/CACHE_SCHEMA.md +118 -0
  64. data/lib/ceedling/dependencies/README.md +18 -16
  65. data/lib/ceedling/dependencies/dependency_cache_store.rb +43 -21
  66. data/lib/ceedling/dependencies/dependency_hasher.rb +35 -1
  67. data/lib/ceedling/dependencies/dependency_tracker.rb +9 -3
  68. data/lib/ceedling/dependencies/dependinator.rb +13 -1
  69. data/lib/ceedling/diagnostics/DOCTOR.md +142 -0
  70. data/lib/ceedling/diagnostics/README.md +5 -0
  71. data/lib/ceedling/diagnostics/build_step_doctor.rb +110 -0
  72. data/lib/ceedling/diagnostics/duplicate_symbol_specialist.rb +108 -0
  73. data/lib/ceedling/diagnostics/guidance_phrases.rb +30 -0
  74. data/lib/ceedling/diagnostics/header_collision_guidance.rb +56 -0
  75. data/lib/ceedling/diagnostics/header_collision_specialist.rb +152 -0
  76. data/lib/ceedling/diagnostics/include_depth_specialist.rb +132 -0
  77. data/lib/ceedling/diagnostics/missing_symbol_specialist.rb +111 -0
  78. data/lib/ceedling/diagnostics/partial_name_specialist.rb +134 -0
  79. data/lib/ceedling/diagnostics/toolchain_output.rb +44 -0
  80. data/lib/ceedling/filename_extension.rb +7 -1
  81. data/lib/ceedling/filesystem/FILE_TREE.md +253 -0
  82. data/lib/ceedling/filesystem/PATH_HANDLING.md +360 -0
  83. data/lib/ceedling/filesystem/README.md +46 -0
  84. data/lib/ceedling/filesystem/build_roots.rb +105 -0
  85. data/lib/ceedling/filesystem/build_subpath.rb +187 -0
  86. data/lib/ceedling/filesystem/destination_collision.rb +25 -0
  87. data/lib/ceedling/{file_finder.rb → filesystem/file_finder.rb} +177 -156
  88. data/lib/ceedling/filesystem/file_finder_helper.rb +154 -0
  89. data/lib/ceedling/filesystem/file_path_collection_utils.rb +183 -0
  90. data/lib/ceedling/{file_path_utils.rb → filesystem/file_path_utils.rb} +200 -167
  91. data/lib/ceedling/{file_system_wrapper.rb → filesystem/file_system_wrapper.rb} +6 -5
  92. data/lib/ceedling/filesystem/file_tree.rb +241 -0
  93. data/lib/ceedling/{file_wrapper.rb → filesystem/file_wrapper.rb} +149 -65
  94. data/lib/ceedling/filesystem/path_exclusions.rb +30 -0
  95. data/lib/ceedling/{path_matcher.rb → filesystem/path_matcher.rb} +48 -23
  96. data/lib/ceedling/{path_mirror.rb → filesystem/path_mirror.rb} +19 -18
  97. data/lib/ceedling/filesystem/path_spellings.rb +55 -0
  98. data/lib/ceedling/filesystem/project_paths.rb +184 -0
  99. data/lib/ceedling/filesystem/test_build_layout.rb +114 -0
  100. data/lib/ceedling/filesystem/win_long_paths.rb +153 -0
  101. data/lib/ceedling/filesystem/win_path_limit.rb +83 -0
  102. data/lib/ceedling/filesystem/win_path_prober.rb +52 -0
  103. data/lib/ceedling/filesystem/working_dir.rb +40 -0
  104. data/lib/ceedling/generators/generator.rb +32 -70
  105. data/lib/ceedling/generators/generator_helper.rb +0 -44
  106. data/lib/ceedling/generators/generator_mocks.rb +5 -0
  107. data/lib/ceedling/generators/generator_partials.rb +306 -244
  108. data/lib/ceedling/generators/generator_test_results_backtrace.rb +7 -7
  109. data/lib/ceedling/generators/generator_test_runner.rb +5 -8
  110. data/lib/ceedling/generators/partial_header_writer.rb +95 -0
  111. data/lib/ceedling/generators/partial_source_writer.rb +137 -0
  112. data/lib/ceedling/handoff.rb +121 -0
  113. data/lib/ceedling/includes/header_search.rb +225 -0
  114. data/lib/ceedling/includes/include_factory.rb +9 -12
  115. data/lib/ceedling/includes/include_pathinator.rb +112 -33
  116. data/lib/ceedling/includes/includes.rb +150 -38
  117. data/lib/ceedling/installation.rb +92 -0
  118. data/lib/ceedling/library_resolver.rb +99 -0
  119. data/lib/ceedling/objects.yml +112 -6
  120. data/lib/ceedling/partials/README.md +110 -16
  121. data/lib/ceedling/partials/carry_plan.rb +71 -0
  122. data/lib/ceedling/partials/definition_head.rb +74 -0
  123. data/lib/ceedling/partials/include_groups.rb +37 -0
  124. data/lib/ceedling/partials/interface_extras.rb +25 -0
  125. data/lib/ceedling/partials/partializer.rb +603 -124
  126. data/lib/ceedling/partials/partializer_config.rb +8 -1
  127. data/lib/ceedling/partials/partializer_helper.rb +851 -145
  128. data/lib/ceedling/partials/partializer_reconciler.rb +174 -0
  129. data/lib/ceedling/partials/partializer_utils.rb +89 -109
  130. data/lib/ceedling/partials/partials.rb +153 -10
  131. data/lib/ceedling/partials/type_macros.rb +126 -0
  132. data/lib/ceedling/plugins/report_log_writer_plugin.rb +3 -5
  133. data/lib/ceedling/preprocess/README.md +43 -33
  134. data/lib/ceedling/preprocess/preprocessinator.rb +100 -186
  135. data/lib/ceedling/preprocess/preprocessinator_code_finder.rb +65 -72
  136. data/lib/ceedling/preprocess/preprocessinator_file_assembler.rb +32 -76
  137. data/lib/ceedling/preprocess/preprocessinator_includes_handler.rb +1 -1
  138. data/lib/ceedling/preprocess/preprocessinator_line_marker_includes_extractor.rb +1 -1
  139. data/lib/ceedling/preprocess/preprocessinator_reconstructor.rb +51 -14
  140. data/lib/ceedling/rake_app/rakefile_component_resolver.rb +10 -17
  141. data/lib/ceedling/rakefile.rb +15 -1
  142. data/lib/ceedling/rakefiles/base/tasks_base.rake +1 -1
  143. data/lib/ceedling/rakefiles/release/rules_release.rake +4 -7
  144. data/lib/ceedling/release_invoker/release_build_executor.rb +33 -44
  145. data/lib/ceedling/release_invoker/release_build_planner.rb +14 -6
  146. data/lib/ceedling/reportinator.rb +3 -4
  147. data/lib/ceedling/setupinator.rb +104 -87
  148. data/lib/ceedling/test_context_extractor.rb +5 -1
  149. data/lib/ceedling/test_invoker/HEADER_COLLISIONS.md +21 -7
  150. data/lib/ceedling/test_invoker/PIPELINE.md +62 -19
  151. data/lib/ceedling/test_invoker/README.md +1 -1
  152. data/lib/ceedling/test_invoker/derived_search_path_notices.rb +45 -0
  153. data/lib/ceedling/test_invoker/mock_locator.rb +175 -10
  154. data/lib/ceedling/test_invoker/partial_files_preprocessinator.rb +181 -0
  155. data/lib/ceedling/test_invoker/partials_manager.rb +271 -302
  156. data/lib/ceedling/test_invoker/standin_headerinator.rb +19 -17
  157. data/lib/ceedling/test_invoker/test_bare_includes_extractinator.rb +26 -3
  158. data/lib/ceedling/test_invoker/test_build_executor.rb +358 -234
  159. data/lib/ceedling/test_invoker/test_build_planner.rb +46 -33
  160. data/lib/ceedling/test_invoker/test_build_setup.rb +43 -18
  161. data/lib/ceedling/test_invoker/test_build_validations.rb +35 -47
  162. data/lib/ceedling/test_invoker/test_derived_search_paths.rb +189 -0
  163. data/lib/ceedling/test_invoker/test_file_preprocessinator.rb +2 -3
  164. data/lib/ceedling/test_invoker/test_includes_reconcilinator.rb +1 -1
  165. data/lib/ceedling/test_invoker/test_invoker.rb +6 -1
  166. data/lib/ceedling/test_invoker/test_invoker_types.rb +28 -20
  167. data/lib/ceedling/test_invoker/test_pipeline_helpers.rb +6 -4
  168. data/lib/ceedling/test_invoker/test_pipeline_manager.rb +25 -8
  169. data/lib/ceedling/test_invoker/test_runner_generatinator.rb +31 -3
  170. data/lib/ceedling/test_invoker/test_search_paths.rb +30 -8
  171. data/lib/ceedling/test_invoker/test_source_file_directive_resolver.rb +40 -20
  172. data/lib/ceedling/test_invoker/test_substitutions.rb +72 -0
  173. data/lib/ceedling/tools/shell_quoting.rb +45 -0
  174. data/lib/ceedling/{tool_executor.rb → tools/tool_executor.rb} +9 -3
  175. data/lib/ceedling/tools/tool_quoting.rb +79 -0
  176. data/lib/ceedling/{tool_validator.rb → tools/tool_validator.rb} +18 -7
  177. data/lib/ceedling/yaml_wrapper.rb +3 -2
  178. data/lib/version.rb +1 -1
  179. data/plugins/bullseye/bullseye.rake +1 -3
  180. data/plugins/bullseye/config/defaults_bullseye.rb +1 -1
  181. data/plugins/bullseye/lib/bullseye.rb +24 -9
  182. data/plugins/command_hooks/lib/command_hooks.rb +1 -1
  183. data/plugins/cppcheck/config/defaults_cppcheck.rb +1 -1
  184. data/plugins/dependencies/config/defaults.yml +6 -6
  185. data/plugins/dependencies/dependencies.rake +4 -1
  186. data/plugins/dependencies/lib/dependencies.rb +18 -8
  187. data/plugins/dependencies/lib/dependency_spec.rb +17 -5
  188. data/plugins/fff/lib/fff.rb +79 -46
  189. data/plugins/fff/lib/fff_mock_generator.rb +12 -9
  190. data/plugins/fff/spec/fff_cmock_wrapper_spec.rb +262 -0
  191. data/plugins/fff/spec/fff_mock_header_generator_spec.rb +9 -0
  192. data/plugins/fff/spec/fff_mock_source_generator_spec.rb +20 -0
  193. data/plugins/gcov/config/defaults_gcov.rb +1 -1
  194. data/plugins/gcov/lib/console_reportinator.rb +28 -36
  195. data/plugins/gcov/lib/gcov.rb +9 -2
  196. data/plugins/gcov/lib/gcovr_reportinator.rb +8 -40
  197. data/plugins/gcov/lib/gcovr_thresholds.rb +74 -0
  198. data/plugins/gcov/lib/reportgenerator_reportinator.rb +3 -2
  199. data/plugins/module_generator/lib/module_generator.rb +3 -3
  200. data/plugins/report_tests_teamcity_stdout/lib/report_tests_teamcity_stdout.rb +53 -80
  201. data/plugins/sanitize/lib/sanitize_records.rb +3 -6
  202. data/plugins/valgrind/lib/valgrind.rb +14 -7
  203. data/site-local/404.html +2 -2
  204. data/site-local/assets/javascripts/{bundle.c21346df.min.js → bundle.a5f9d56c.min.js} +1 -1
  205. data/site-local/assets/javascripts/{bundle.c21346df.min.js.map → bundle.a5f9d56c.min.js.map} +2 -2
  206. data/site-local/configuration/environment-vars.html +2 -2
  207. data/site-local/configuration/global-collections.html +3 -3
  208. data/site-local/configuration/index.html +2 -2
  209. data/site-local/configuration/loading.html +2 -2
  210. data/site-local/configuration/mixins.html +2 -2
  211. data/site-local/configuration/parallel-builds.html +2 -2
  212. data/site-local/configuration/project-file.html +2 -2
  213. data/site-local/configuration/reference/cexception.html +2 -2
  214. data/site-local/configuration/reference/cmock.html +7 -3
  215. data/site-local/configuration/reference/defines.html +2 -2
  216. data/site-local/configuration/reference/environment.html +2 -2
  217. data/site-local/configuration/reference/extension.html +2 -2
  218. data/site-local/configuration/reference/files.html +65 -12
  219. data/site-local/configuration/reference/flags.html +2 -2
  220. data/site-local/configuration/reference/index.html +2 -2
  221. data/site-local/configuration/reference/libraries.html +23 -5
  222. data/site-local/configuration/reference/mixins.html +2 -2
  223. data/site-local/configuration/reference/partials.html +84 -2
  224. data/site-local/configuration/reference/paths.html +36 -8
  225. data/site-local/configuration/reference/plugins.html +2 -2
  226. data/site-local/configuration/reference/project.html +264 -12
  227. data/site-local/configuration/reference/release-build.html +4 -2
  228. data/site-local/configuration/reference/test-build.html +2 -2
  229. data/site-local/configuration/reference/test-runner.html +2 -2
  230. data/site-local/configuration/reference/tools.html +58 -4
  231. data/site-local/configuration/reference/unity.html +2 -2
  232. data/site-local/configuration/which-ceedling.html +379 -19
  233. data/site-local/development/index.html +2 -2
  234. data/site-local/development/plugins/configuration.html +2 -2
  235. data/site-local/development/plugins/index.html +2 -2
  236. data/site-local/development/plugins/plugin-subclass.html +5 -4
  237. data/site-local/development/plugins/rake-tasks.html +2 -2
  238. data/site-local/development/releases.html +7 -3
  239. data/site-local/development/workflow.html +50 -45
  240. data/site-local/getting-started/builds.html +4 -2
  241. data/site-local/getting-started/command-line.html +58 -6
  242. data/site-local/getting-started/example-projects/cipher-quest.html +2 -2
  243. data/site-local/getting-started/example-projects/index.html +2 -2
  244. data/site-local/getting-started/example-projects/temp-sensor.html +2 -2
  245. data/site-local/getting-started/example-projects/wondrous-forest.html +10 -2
  246. data/site-local/getting-started/index.html +2 -2
  247. data/site-local/getting-started/installation.html +2 -2
  248. data/site-local/getting-started/quick-start.html +2 -2
  249. data/site-local/help.html +2 -2
  250. data/site-local/index.html +2 -2
  251. data/site-local/overview/build-system.html +2 -2
  252. data/site-local/overview/index.html +2 -2
  253. data/site-local/overview/test-environments.html +2 -2
  254. data/site-local/overview/tools-and-frameworks.html +2 -2
  255. data/site-local/plugins/beep.html +2 -2
  256. data/site-local/plugins/bullseye/index.html +45 -38
  257. data/site-local/plugins/bullseye/licensing.html +2 -2
  258. data/site-local/plugins/command-hooks.html +4 -4
  259. data/site-local/plugins/compile-commands-json-db.html +2 -2
  260. data/site-local/plugins/cppcheck.html +2 -2
  261. data/site-local/plugins/dependencies.html +8 -5
  262. data/site-local/plugins/fff.html +58 -13
  263. data/site-local/plugins/gcov/examples.html +2 -2
  264. data/site-local/plugins/gcov/gcovr.html +23 -14
  265. data/site-local/plugins/gcov/index.html +2 -2
  266. data/site-local/plugins/gcov/overview.html +2 -2
  267. data/site-local/plugins/gcov/reportgenerator.html +18 -14
  268. data/site-local/plugins/gcov/reporting.html +2 -2
  269. data/site-local/plugins/gcov/setup.html +4 -3
  270. data/site-local/plugins/gcov/tool-versions.html +2 -2
  271. data/site-local/plugins/gcov/troubleshooting.html +2 -2
  272. data/site-local/plugins/index.html +2 -2
  273. data/site-local/plugins/module-generator.html +2 -2
  274. data/site-local/plugins/report-build-warnings-log.html +2 -2
  275. data/site-local/plugins/report-tests-gtestlike-stdout.html +2 -2
  276. data/site-local/plugins/report-tests-ide-stdout.html +2 -2
  277. data/site-local/plugins/report-tests-log-factory.html +2 -2
  278. data/site-local/plugins/report-tests-pretty-stdout.html +2 -2
  279. data/site-local/plugins/report-tests-raw-output-log.html +5 -3
  280. data/site-local/plugins/report-tests-teamcity-stdout.html +8 -5
  281. data/site-local/plugins/sanitize.html +9 -8
  282. data/site-local/plugins/valgrind.html +10 -9
  283. data/site-local/project/index.html +2 -2
  284. data/site-local/project/release-history.html +2 -2
  285. data/site-local/project/sbom.html +2 -2
  286. data/site-local/project/upgrade.html +5 -2
  287. data/site-local/reference/build-directives.html +2 -2
  288. data/site-local/reference/command-line.html +11 -4
  289. data/site-local/reference/environment-vars.html +2 -2
  290. data/site-local/reference/gcov-plugin.html +2 -2
  291. data/site-local/reference/global-collections.html +12 -12
  292. data/site-local/reference/index.html +2 -2
  293. data/site-local/reference/partials-macros.html +47 -2
  294. data/site-local/reference/project-configuration.html +2 -2
  295. data/site-local/sitemap.xml.gz +0 -0
  296. data/site-local/snapshot/examples/cipher_quest/index.html +2 -2
  297. data/site-local/snapshot/examples/temp_sensor/index.html +2 -2
  298. data/site-local/snapshot/examples/wondrous_forest/index.html +72 -15
  299. data/site-local/snapshot/plugins/bullseye/config/defaults_bullseye.rb +1 -1
  300. data/site-local/snapshot/plugins/gcov/config/defaults_gcov.rb +1 -1
  301. data/site-local/testing-guide/build-directives.html +2 -2
  302. data/site-local/testing-guide/conventions.html +113 -15
  303. data/site-local/testing-guide/frameworks.html +2 -2
  304. data/site-local/testing-guide/index.html +2 -2
  305. data/site-local/testing-guide/partials/configuration.html +31 -4
  306. data/site-local/testing-guide/partials/conventions.html +509 -8
  307. data/site-local/testing-guide/partials/directives.html +4 -3
  308. data/site-local/testing-guide/partials/example.html +2 -2
  309. data/site-local/testing-guide/partials/index.html +2 -2
  310. data/site-local/testing-guide/partials/overview.html +30 -12
  311. data/site-local/testing-guide/partials/variables.html +169 -4
  312. data/site-local/testing-guide/test-cases.html +2 -2
  313. data/site-local/testing-guide/test-sample.html +2 -2
  314. data/site-local/testing-guide/test-suite-anatomy.html +2 -2
  315. data/spec/integration/actionator_file_operations_spec.rb +91 -1
  316. data/spec/integration/build_step_doctor_spec.rb +270 -0
  317. data/spec/integration/c_extractor_composition_spec.rb +254 -4
  318. data/spec/integration/compile_commands_json_db_spec.rb +1 -1
  319. data/spec/integration/configurator_validation_spec.rb +1 -1
  320. data/spec/integration/dependencies/dependency_tracker_cache_hardening_spec.rb +26 -0
  321. data/spec/integration/dependencies/dependency_tracker_core_spec.rb +22 -0
  322. data/spec/integration/includes_extraction_spec.rb +27 -14
  323. data/spec/integration/launcher_handoff_spec.rb +297 -0
  324. data/spec/integration/mixin_loading_spec.rb +1 -1
  325. data/spec/integration/module_generator_spec.rb +3 -3
  326. data/spec/integration/nested_test_artifacts_spec.rb +99 -0
  327. data/spec/integration/partial_files_preprocessing_spec.rb +128 -0
  328. data/spec/integration/partials_carry_spec.rb +520 -0
  329. data/spec/integration/partials_declarations_spec.rb +655 -0
  330. data/spec/integration/partials_fallback_preprocessing_spec.rb +65 -0
  331. data/spec/integration/partials_function_pointers_spec.rb +277 -0
  332. data/spec/integration/partials_header_composition_spec.rb +268 -35
  333. data/spec/integration/partials_macro_decorators_spec.rb +267 -0
  334. data/spec/integration/partials_module_resolution_spec.rb +33 -23
  335. data/spec/integration/partials_symbol_linkage_spec.rb +13 -0
  336. data/spec/integration/path_intake_scenarios_spec.rb +101 -0
  337. data/spec/integration/path_length_reporting_spec.rb +64 -0
  338. data/spec/integration/path_scenarios_spec.rb +399 -0
  339. data/spec/integration/quote_include_isolator_spec.rb +57 -1
  340. data/spec/integration/report_build_warnings_log_spec.rb +1 -1
  341. data/spec/integration/report_tests_log_factory_spec.rb +1 -1
  342. data/spec/integration/test_build_parallel_barrier_spec.rb +1 -1
  343. data/spec/integration/test_executable_manifest_spec.rb +1 -1
  344. data/spec/integration/test_includes_extractinator_spec.rb +69 -3
  345. data/spec/integration/test_naming_spec.rb +201 -0
  346. data/spec/integration/test_source_file_checks_spec.rb +168 -0
  347. data/spec/integration/tool_executor_spec.rb +1 -1
  348. data/spec/integration/tool_validator_spec.rb +3 -3
  349. data/spec/integration/upgrade_docs_spec.rb +84 -0
  350. data/spec/integration/vendor_copy_transient_io_retry_spec.rb +74 -5
  351. data/spec/integration/win_long_paths_probe_spec.rb +46 -0
  352. data/spec/integration/win_path_limit_spec.rb +53 -0
  353. data/spec/integration/windows_registry_query_tool_spec.rb +41 -0
  354. data/spec/support/file_tree_helper.rb +88 -0
  355. data/spec/support/integration/configurator_integration_helper.rb +14 -9
  356. data/spec/support/integration/dependency_tracker_integration_helper.rb +1 -1
  357. data/spec/support/integration/partial_files_harness.rb +181 -0
  358. data/spec/support/integration/partials_generation_integration_helper.rb +239 -143
  359. data/spec/support/integration/path_scenario_harness.rb +175 -0
  360. data/spec/support/integration/spec_integration_helper.rb +9 -4
  361. data/spec/support/integration/test_includes_harness.rb +69 -37
  362. data/spec/support/integration/tool_executor_integration_helper.rb +14 -2
  363. data/spec/support/spec_helper.rb +2 -0
  364. data/spec/support/system/spec_system_helper.rb +7 -6
  365. data/spec/support/system/system_context.rb +21 -3
  366. data/spec/support/working_dir_tracking.rb +49 -0
  367. data/spec/system/build_output_mirroring_spec.rb +2 -2
  368. data/spec/system/bullseye_deployment_spec.rb +2 -0
  369. data/spec/system/conditional_mock_includes_spec.rb +1 -1
  370. data/spec/system/delta_builds_spec.rb +163 -23
  371. data/spec/system/encoding_stress_spec.rb +4 -4
  372. data/spec/system/example_wondrous_forest_spec.rb +2 -2
  373. data/spec/system/gcov_deployment_spec.rb +3 -0
  374. data/spec/system/header_include_path_validation_spec.rb +4 -4
  375. data/spec/system/header_search_paths_spec.rb +1083 -0
  376. data/spec/system/launcher_handoff_spec.rb +82 -0
  377. data/spec/system/mock_include_folders_spec.rb +212 -0
  378. data/spec/system/mockable_header_reassembly_spec.rb +184 -0
  379. data/spec/system/parent_directory_reference_spec.rb +5 -3
  380. data/spec/system/partials_carry_spec.rb +581 -0
  381. data/spec/system/partials_delta_builds_spec.rb +280 -0
  382. data/spec/system/partials_function_pointers_spec.rb +106 -0
  383. data/spec/system/partials_macro_decorators_spec.rb +127 -0
  384. data/spec/system/partials_module_disambiguation_spec.rb +125 -0
  385. data/spec/system/path_handling_probes_spec.rb +196 -0
  386. data/spec/system/pinned_thread_count_spec.rb +4 -4
  387. data/spec/system/preprocessing_fallback_conditionals_spec.rb +1 -1
  388. data/spec/system/preprocessing_parameterized_tests_spec.rb +1 -1
  389. data/spec/system/rake_release_task_path_disambiguation_spec.rb +6 -6
  390. data/spec/system/rake_test_task_path_disambiguation_spec.rb +85 -0
  391. data/spec/system/short_build_paths_spec.rb +87 -0
  392. data/spec/system/sibling_header_collision_spec.rb +30 -6
  393. data/spec/system/special_path_characters_spec.rb +86 -0
  394. data/spec/system/support/bullseye_common_test_cases.rb +42 -0
  395. data/spec/system/support/common_test_cases.rb +23 -21
  396. data/spec/system/support/gcov_common_test_cases.rb +37 -9
  397. data/spec/system/support/gcov_partials_test_cases.rb +48 -0
  398. data/spec/system/support/sanitize_common_test_cases.rb +2 -2
  399. data/spec/system/support/valgrind_common_test_cases.rb +12 -12
  400. data/spec/system/test_build_layout_spec.rb +209 -0
  401. data/spec/system/test_pipeline_stop_points_spec.rb +4 -4
  402. data/spec/system/test_runner_system_include_spec.rb +1 -1
  403. data/spec/system/test_source_file_directive_spec.rb +64 -5
  404. data/spec/units/bin/actionator_spec.rb +14 -17
  405. data/spec/units/bin/app_cfg_spec.rb +37 -0
  406. data/spec/units/bin/cli_handler_spec.rb +282 -6
  407. data/spec/units/bin/cli_helper_spec.rb +116 -45
  408. data/spec/units/bin/installation_selector_spec.rb +114 -0
  409. data/spec/units/bin/launchinator_spec.rb +171 -0
  410. data/spec/units/bin/path_validator_spec.rb +10 -0
  411. data/spec/units/bin/versionator_spec.rb +38 -6
  412. data/spec/units/build_log_writer_spec.rb +57 -0
  413. data/spec/units/c_extractor/c_extractor_code_text_spec.rb +67 -10
  414. data/spec/units/c_extractor/c_extractor_declarations_spec.rb +501 -4
  415. data/spec/units/c_extractor/c_extractor_declarator_spec.rb +245 -0
  416. data/spec/units/c_extractor/c_extractor_defined_type_spec.rb +45 -0
  417. data/spec/units/c_extractor/c_extractor_definitions_spec.rb +163 -3
  418. data/spec/units/c_extractor/c_extractor_functions_spec.rb +462 -21
  419. data/spec/units/c_extractor/c_extractor_preprocessing_spec.rb +39 -0
  420. data/spec/units/c_extractor/c_extractor_spec.rb +4 -4
  421. data/spec/units/c_extractor/c_extractor_types_spec.rb +163 -0
  422. data/spec/units/c_identifier_spec.rb +35 -0
  423. data/spec/units/config/build_root_policy_spec.rb +61 -0
  424. data/spec/units/config/configurator_builder_spec.rb +61 -6
  425. data/spec/units/config/configurator_paths_validator_spec.rb +292 -0
  426. data/spec/units/config/configurator_setup_spec.rb +80 -68
  427. data/spec/units/config/configurator_spec.rb +54 -6
  428. data/spec/units/config/configurator_validator_spec.rb +1 -172
  429. data/spec/units/dependencies/dependency_cache_store_spec.rb +98 -2
  430. data/spec/units/dependencies/dependency_debug_tree_spec.rb +1 -1
  431. data/spec/units/dependencies/dependency_hasher_spec.rb +42 -1
  432. data/spec/units/dependencies/dependency_path_normalizer_spec.rb +1 -1
  433. data/spec/units/dependencies/dependency_tracker_spec.rb +28 -1
  434. data/spec/units/dependencies/dependinator_spec.rb +17 -2
  435. data/spec/units/diagnostics/build_step_doctor_spec.rb +170 -0
  436. data/spec/units/diagnostics/duplicate_symbol_specialist_spec.rb +117 -0
  437. data/spec/units/diagnostics/header_collision_specialist_spec.rb +267 -0
  438. data/spec/units/diagnostics/include_depth_specialist_spec.rb +137 -0
  439. data/spec/units/diagnostics/missing_symbol_specialist_spec.rb +154 -0
  440. data/spec/units/diagnostics/partial_name_specialist_spec.rb +129 -0
  441. data/spec/units/diagnostics/toolchain_output_spec.rb +86 -0
  442. data/spec/units/encodinator_spec.rb +3 -4
  443. data/spec/units/filename_extension_spec.rb +11 -0
  444. data/spec/units/filesystem/build_roots_spec.rb +131 -0
  445. data/spec/units/filesystem/build_subpath_spec.rb +235 -0
  446. data/spec/units/filesystem/destination_collision_spec.rb +30 -0
  447. data/spec/units/{file_finder_helper_spec.rb → filesystem/file_finder_helper_spec.rb} +126 -1
  448. data/spec/units/filesystem/file_finder_spec.rb +845 -0
  449. data/spec/units/{file_path_collection_utils_spec.rb → filesystem/file_path_collection_utils_spec.rb} +181 -1
  450. data/spec/units/{file_path_utils_spec.rb → filesystem/file_path_utils_spec.rb} +435 -185
  451. data/spec/units/filesystem/file_system_wrapper_spec.rb +33 -0
  452. data/spec/units/filesystem/file_tree_spec.rb +511 -0
  453. data/spec/units/filesystem/file_tree_windows_spec.rb +78 -0
  454. data/spec/units/{file_wrapper_spec.rb → filesystem/file_wrapper_spec.rb} +286 -18
  455. data/spec/units/{path_matcher_spec.rb → filesystem/path_matcher_spec.rb} +48 -1
  456. data/spec/units/{path_mirror_spec.rb → filesystem/path_mirror_spec.rb} +32 -4
  457. data/spec/units/filesystem/project_paths_spec.rb +147 -0
  458. data/spec/units/filesystem/test_build_layout_spec.rb +216 -0
  459. data/spec/units/filesystem/win_long_paths_spec.rb +204 -0
  460. data/spec/units/filesystem/win_path_prober_spec.rb +158 -0
  461. data/spec/units/filesystem/working_dir_spec.rb +71 -0
  462. data/spec/units/generators/generator_helper_spec.rb +0 -60
  463. data/spec/units/generators/generator_mocks_spec.rb +13 -0
  464. data/spec/units/generators/generator_partials_spec.rb +656 -55
  465. data/spec/units/generators/generator_spec.rb +38 -6
  466. data/spec/units/generators/generator_test_results_backtrace_spec.rb +50 -46
  467. data/spec/units/generators/generator_test_results_spec.rb +1 -1
  468. data/spec/units/generators/generator_test_runner_spec.rb +9 -5
  469. data/spec/units/generators/partial_source_writer_spec.rb +129 -0
  470. data/spec/units/handoff_spec.rb +205 -0
  471. data/spec/units/includes/header_search_spec.rb +406 -0
  472. data/spec/units/includes/include_factory_spec.rb +23 -6
  473. data/spec/units/includes/include_pathinator_spec.rb +118 -8
  474. data/spec/units/includes/include_spec.rb +14 -0
  475. data/spec/units/includes/includes_spec.rb +176 -19
  476. data/spec/units/installation_spec.rb +228 -0
  477. data/spec/units/library_resolver_spec.rb +157 -0
  478. data/spec/units/loginator_spec.rb +31 -0
  479. data/spec/units/mock_locator_spec.rb +275 -6
  480. data/spec/units/partials/include_groups_spec.rb +42 -0
  481. data/spec/units/partials/partializer_config_spec.rb +32 -0
  482. data/spec/units/partials/partializer_helper_carry_spec.rb +661 -0
  483. data/spec/units/partials/partializer_helper_interface_extras_spec.rb +396 -0
  484. data/spec/units/partials/partializer_helper_spec.rb +529 -277
  485. data/spec/units/partials/partializer_reconciler_spec.rb +661 -0
  486. data/spec/units/partials/partializer_spec.rb +1579 -270
  487. data/spec/units/partials/partializer_utils_spec.rb +269 -232
  488. data/spec/units/partials/partials_rename_spec.rb +160 -0
  489. data/spec/units/partials_manager_spec.rb +561 -251
  490. data/spec/units/plugins/bullseye_spec.rb +49 -2
  491. data/spec/units/plugins/console_reportinator_spec.rb +73 -26
  492. data/spec/units/plugins/dependencies_spec.rb +33 -7
  493. data/spec/units/plugins/dependency_spec_spec.rb +17 -0
  494. data/spec/units/plugins/gcov_spec.rb +28 -3
  495. data/spec/units/plugins/gcovr_reportinator_spec.rb +19 -47
  496. data/spec/units/plugins/gcovr_thresholds_spec.rb +95 -0
  497. data/spec/units/plugins/module_generator_spec.rb +5 -5
  498. data/spec/units/plugins/report_build_warnings_log_spec.rb +3 -3
  499. data/spec/units/plugins/report_log_writer_plugin_spec.rb +10 -1
  500. data/spec/units/plugins/report_tests_raw_output_log_spec.rb +13 -2
  501. data/spec/units/plugins/report_tests_teamcity_stdout_spec.rb +77 -3
  502. data/spec/units/plugins/reportgenerator_reportinator_spec.rb +52 -4
  503. data/spec/units/plugins/sanitize_records_spec.rb +3 -1
  504. data/spec/units/plugins/sanitize_spec.rb +1 -1
  505. data/spec/units/plugins/valgrind_spec.rb +23 -8
  506. data/spec/units/preprocess/preprocessinator_code_finder_spec.rb +73 -10
  507. data/spec/units/preprocess/preprocessinator_comment_stripper_spec.rb +1 -1
  508. data/spec/units/preprocess/preprocessinator_file_assembler_spec.rb +125 -37
  509. data/spec/units/preprocess/preprocessinator_includes_handler_spec.rb +15 -0
  510. data/spec/units/preprocess/preprocessinator_reconstructor_spec.rb +197 -0
  511. data/spec/units/preprocess/preprocessinator_spec.rb +153 -95
  512. data/spec/units/rake_app/rakefile_component_resolver_spec.rb +21 -0
  513. data/spec/units/release_build_executor_spec.rb +53 -14
  514. data/spec/units/release_build_planner_spec.rb +15 -3
  515. data/spec/units/reportinator_spec.rb +5 -5
  516. data/spec/units/setupinator_spec.rb +51 -0
  517. data/spec/units/standin_headerinator_spec.rb +55 -9
  518. data/spec/units/test_build_executor_spec.rb +842 -166
  519. data/spec/units/test_build_planner_spec.rb +205 -15
  520. data/spec/units/test_build_setup_spec.rb +179 -30
  521. data/spec/units/test_context_extractor_spec.rb +36 -2
  522. data/spec/units/test_derived_search_paths_spec.rb +259 -0
  523. data/spec/units/test_file_preprocessinator_spec.rb +17 -1
  524. data/spec/units/test_includes_extractinator_spec.rb +61 -9
  525. data/spec/units/test_invoker/objects_wiring_spec.rb +24 -4
  526. data/spec/units/test_invoker/partial_files_preprocessinator_spec.rb +264 -0
  527. data/spec/units/test_invoker/test_substitutions_spec.rb +122 -0
  528. data/spec/units/test_invoker_spec.rb +14 -1
  529. data/spec/units/test_invoker_types_spec.rb +8 -7
  530. data/spec/units/test_pipeline_manager_spec.rb +54 -13
  531. data/spec/units/test_runner_generatinator_spec.rb +93 -1
  532. data/spec/units/test_search_paths_spec.rb +73 -5
  533. data/spec/units/test_source_file_directive_resolver_spec.rb +38 -7
  534. data/spec/units/tools/default_tools_quoting_spec.rb +117 -0
  535. data/spec/units/tools/shell_quoting_spec.rb +76 -0
  536. data/spec/units/{tool_executor_helper_spec.rb → tools/tool_executor_helper_spec.rb} +1 -1
  537. data/spec/units/{tool_executor_spec.rb → tools/tool_executor_spec.rb} +27 -1
  538. data/spec/units/{tool_validator_spec.rb → tools/tool_validator_spec.rb} +110 -1
  539. data/spec/units/windows_registry_query_tool_spec.rb +53 -0
  540. data/spec/units/yaml_wrapper_spec.rb +11 -0
  541. metadata +265 -36
  542. data/lib/ceedling/file_finder_helper.rb +0 -127
  543. data/lib/ceedling/file_path_collection_utils.rb +0 -164
  544. data/spec/units/file_finder_spec.rb +0 -495
  545. /data/lib/ceedling/{tool_executor_helper.rb → tools/tool_executor_helper.rb} +0 -0
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -4539,7 +4539,7 @@ uses fallback preprocessing instead.</p>
4539
4539
  <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
4540
4540
 
4541
4541
 
4542
- <script src="../../assets/javascripts/bundle.c21346df.min.js"></script>
4542
+ <script src="../../assets/javascripts/bundle.a5f9d56c.min.js"></script>
4543
4543
 
4544
4544
 
4545
4545
  </body>
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -4569,7 +4569,7 @@ an order-dependent failure without test case order moving around run to run).</p
4569
4569
  <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
4570
4570
 
4571
4571
 
4572
- <script src="../../assets/javascripts/bundle.c21346df.min.js"></script>
4572
+ <script src="../../assets/javascripts/bundle.a5f9d56c.min.js"></script>
4573
4573
 
4574
4574
 
4575
4575
  </body>
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -2597,7 +2597,18 @@
2597
2597
  </span>
2598
2598
  </a>
2599
2599
 
2600
- <nav class="md-nav" aria-label=":release_linker">
2600
+ </li>
2601
+
2602
+ <li class="md-nav__item">
2603
+ <a href="#windows_registry_query" class="md-nav__link">
2604
+ <span class="md-ellipsis">
2605
+
2606
+ :windows_registry_query
2607
+
2608
+ </span>
2609
+ </a>
2610
+
2611
+ <nav class="md-nav" aria-label=":windows_registry_query">
2601
2612
  <ul class="md-nav__list">
2602
2613
 
2603
2614
  <li class="md-nav__item">
@@ -4689,7 +4700,18 @@
4689
4700
  </span>
4690
4701
  </a>
4691
4702
 
4692
- <nav class="md-nav" aria-label=":release_linker">
4703
+ </li>
4704
+
4705
+ <li class="md-nav__item">
4706
+ <a href="#windows_registry_query" class="md-nav__link">
4707
+ <span class="md-ellipsis">
4708
+
4709
+ :windows_registry_query
4710
+
4711
+ </span>
4712
+ </a>
4713
+
4714
+ <nav class="md-nav" aria-label=":windows_registry_query">
4693
4715
  <ul class="md-nav__list">
4694
4716
 
4695
4717
  <li class="md-nav__item">
@@ -5054,6 +5076,20 @@ system will provide options for integrating alternative tools.</p>
5054
5076
  <li><code>${5}</code>: optional library path list</li>
5055
5077
  </ul>
5056
5078
  <p><strong>Default</strong>: <code>gcc</code></p>
5079
+ <h2 id="windows_registry_query"><code>:windows_registry_query</code></h2>
5080
+ <p>Reads one Windows registry value. It is not a build step. Ceedling adds this
5081
+ tool only on Windows, and only when <a href="project.html#win_path_limit"><code>:project</code> ↳ <code>:win_path_limit</code></a>
5082
+ is <code>:auto</code> or <code>:long_paths</code>. It runs only if Ceedling’s long path check fails,
5083
+ to tell whether long paths are disabled on the host or unavailable to Ruby.</p>
5084
+ <p>The tool is optional. If its executable is missing, Ceedling’s message says the
5085
+ registry could not be read, and the build goes on.</p>
5086
+ <ul>
5087
+ <li><code>${1}</code>: registry key</li>
5088
+ <li><code>${2}</code>: value name</li>
5089
+ </ul>
5090
+ <p><strong>Default</strong>: <code>reg</code> (as <code>reg query "${1}" /v ${2}</code>)</p>
5091
+ <p>A replacement must print its result as <code>reg query</code> does. Ceedling looks for a
5092
+ line such as <code>LongPathsEnabled REG_DWORD 0x1</code> in its output.</p>
5057
5093
  <h3 id="tool-definition-configurable-elements">Tool definition configurable elements</h3>
5058
5094
  <ol>
5059
5095
  <li>
@@ -5074,6 +5110,24 @@ the name quoted, add escaped quotes in the YAML:</p>
5074
5110
  <li>
5075
5111
  <p><code>:arguments</code> - List (array of strings) of command line arguments and
5076
5112
  substitutions (required).</p>
5113
+ <div class="admonition tip">
5114
+ <p class="admonition-title">Quote the paths your tools name</p>
5115
+ <p>Ceedling runs each tool’s command line through your system’s shell, which
5116
+ reads a space, an apostrophe, and other characters in a path as part of
5117
+ the command. Wrap each path argument in escaped quotes, as Ceedling’s
5118
+ own tools do, for example <code>"-c \"${1}\""</code>. Quoting protects most
5119
+ characters. On Linux and macOS, a path holding <code>"</code>, <code>$</code>, a backtick, or
5120
+ <code>\</code> can still break a command.</p>
5121
+ </div>
5122
+ <div class="admonition note">
5123
+ <p class="admonition-title">Each argument closes its own quotes</p>
5124
+ <p>Ceedling checks the quoting in <code>:executable</code> and in each argument when it
5125
+ validates a tool. A quote left open fails validation. Every argument must
5126
+ close quotes it opens; a quoted value can’t span two entries in the list.
5127
+ A typographic quote (e.g. <code>”</code>) pasted from elsewhere draws a warning. A
5128
+ shell treats it as an ordinary character. On Windows, <code>'</code> is an ordinary
5129
+ character too and is not checked.</p>
5130
+ </div>
5077
5131
  </li>
5078
5132
  <li>
5079
5133
  <p><code>:name</code> - Simple name (i.e. "nickname") of tool beyond its executable name.
@@ -5369,7 +5423,7 @@ that can be modified with this same hack.</p>
5369
5423
  <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
5370
5424
 
5371
5425
 
5372
- <script src="../../assets/javascripts/bundle.c21346df.min.js"></script>
5426
+ <script src="../../assets/javascripts/bundle.a5f9d56c.min.js"></script>
5373
5427
 
5374
5428
 
5375
5429
  </body>
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -4529,7 +4529,7 @@ ordering — see <a href="test-runner.html#test_runner-rng_seed"><code>:test_run
4529
4529
  <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
4530
4530
 
4531
4531
 
4532
- <script src="../../assets/javascripts/bundle.c21346df.min.js"></script>
4532
+ <script src="../../assets/javascripts/bundle.a5f9d56c.min.js"></script>
4533
4533
 
4534
4534
 
4535
4535
  </body>
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -1830,6 +1830,78 @@
1830
1830
  </span>
1831
1831
  </a>
1832
1832
 
1833
+ </li>
1834
+
1835
+ <li class="md-nav__item">
1836
+ <a href="#hand-off" class="md-nav__link">
1837
+ <span class="md-ellipsis">
1838
+
1839
+ Hand-off
1840
+
1841
+ </span>
1842
+ </a>
1843
+
1844
+ <nav class="md-nav" aria-label="Hand-off">
1845
+ <ul class="md-nav__list">
1846
+
1847
+ <li class="md-nav__item">
1848
+ <a href="#hand-off-by-condition" class="md-nav__link">
1849
+ <span class="md-ellipsis">
1850
+
1851
+ Hand-off by condition
1852
+
1853
+ </span>
1854
+ </a>
1855
+
1856
+ </li>
1857
+
1858
+ <li class="md-nav__item">
1859
+ <a href="#version" class="md-nav__link">
1860
+ <span class="md-ellipsis">
1861
+
1862
+ version
1863
+
1864
+ </span>
1865
+ </a>
1866
+
1867
+ </li>
1868
+
1869
+ <li class="md-nav__item">
1870
+ <a href="#older-launchers" class="md-nav__link">
1871
+ <span class="md-ellipsis">
1872
+
1873
+ Older launchers
1874
+
1875
+ </span>
1876
+ </a>
1877
+
1878
+ </li>
1879
+
1880
+ <li class="md-nav__item">
1881
+ <a href="#projects-vendored-by-110-through-121" class="md-nav__link">
1882
+ <span class="md-ellipsis">
1883
+
1884
+ Projects vendored by 1.1.0 through 1.2.1
1885
+
1886
+ </span>
1887
+ </a>
1888
+
1889
+ </li>
1890
+
1891
+ </ul>
1892
+ </nav>
1893
+
1894
+ </li>
1895
+
1896
+ <li class="md-nav__item">
1897
+ <a href="#ceedling-development" class="md-nav__link">
1898
+ <span class="md-ellipsis">
1899
+
1900
+ Ceedling development
1901
+
1902
+ </span>
1903
+ </a>
1904
+
1833
1905
  </li>
1834
1906
 
1835
1907
  </ul>
@@ -4305,6 +4377,78 @@
4305
4377
  </span>
4306
4378
  </a>
4307
4379
 
4380
+ </li>
4381
+
4382
+ <li class="md-nav__item">
4383
+ <a href="#hand-off" class="md-nav__link">
4384
+ <span class="md-ellipsis">
4385
+
4386
+ Hand-off
4387
+
4388
+ </span>
4389
+ </a>
4390
+
4391
+ <nav class="md-nav" aria-label="Hand-off">
4392
+ <ul class="md-nav__list">
4393
+
4394
+ <li class="md-nav__item">
4395
+ <a href="#hand-off-by-condition" class="md-nav__link">
4396
+ <span class="md-ellipsis">
4397
+
4398
+ Hand-off by condition
4399
+
4400
+ </span>
4401
+ </a>
4402
+
4403
+ </li>
4404
+
4405
+ <li class="md-nav__item">
4406
+ <a href="#version" class="md-nav__link">
4407
+ <span class="md-ellipsis">
4408
+
4409
+ version
4410
+
4411
+ </span>
4412
+ </a>
4413
+
4414
+ </li>
4415
+
4416
+ <li class="md-nav__item">
4417
+ <a href="#older-launchers" class="md-nav__link">
4418
+ <span class="md-ellipsis">
4419
+
4420
+ Older launchers
4421
+
4422
+ </span>
4423
+ </a>
4424
+
4425
+ </li>
4426
+
4427
+ <li class="md-nav__item">
4428
+ <a href="#projects-vendored-by-110-through-121" class="md-nav__link">
4429
+ <span class="md-ellipsis">
4430
+
4431
+ Projects vendored by 1.1.0 through 1.2.1
4432
+
4433
+ </span>
4434
+ </a>
4435
+
4436
+ </li>
4437
+
4438
+ </ul>
4439
+ </nav>
4440
+
4441
+ </li>
4442
+
4443
+ <li class="md-nav__item">
4444
+ <a href="#ceedling-development" class="md-nav__link">
4445
+ <span class="md-ellipsis">
4446
+
4447
+ Ceedling development
4448
+
4449
+ </span>
4450
+ </a>
4451
+
4308
4452
  </li>
4309
4453
 
4310
4454
  </ul>
@@ -4394,16 +4538,14 @@ in <code>lib/</code>. The code in <code>/bin</code> manages lots of startup deta
4394
4538
  configuration. Ultimately, it then launches the main application code from
4395
4539
  <code>lib/</code>.</p>
4396
4540
  <p>The features and conventions controlling <em>which ceedling</em> dictate which
4397
- application code the <code>ceedling</code> command line handler launches.</p>
4541
+ installation of Ceedling runs your command. When they select an
4542
+ installation other than the one whose <code>ceedling</code> command you ran, the launcher
4543
+ hands your command off to that installation’s own launcher. See
4544
+ <a href="#hand-off">Hand-off</a>.</p>
4398
4545
  <div class="admonition note">
4399
- <p class="admonition-title">Ceedling development in <code>bin/</code></p>
4400
- <p>Working on the code in Ceedling’s <code>bin/</code> and need to run it while a gem is
4401
- installed? You must take the additional step of specifying the path to the
4402
- <code>ceedling</code> launcher in your filesystem.</p>
4403
- <p>In Unix-like systems:
4404
- <code>&gt; my/ceedling/changes/bin/ceedling &lt;args&gt;</code>.</p>
4405
- <p>On Windows systems:
4406
- <code>&gt; ruby my\ceedling\changes\bin\ceedling &lt;args&gt;</code>.</p>
4546
+ <p class="admonition-title">Ceedling development</p>
4547
+ <p><em>Which ceedling</em> lets the <code>ceedling</code> command you have installed run your local
4548
+ Ceedling repository. See <a href="#ceedling-development">Ceedling development</a>.</p>
4407
4549
  </div>
4408
4550
  <h2 id="options-and-precedence">Options and precedence</h2>
4409
4551
  <p>When Ceedling starts up, it evaluates a handful of conditions to determine
@@ -4422,25 +4564,243 @@ which Ceedling location to launch.</p>
4422
4564
  <code>ceedling</code> launcher is running. In the typical case this is the default
4423
4565
  gem installation.</li>
4424
4566
  </ol>
4567
+ <p>A path in <code>WHICH_CEEDLING</code> or <code>:which_ceedling</code> may begin with <code>~</code> to name
4568
+ your home directory, as in <code>:which_ceedling: ~/ceedlings/1.2.0</code>.</p>
4425
4569
  <div class="admonition note">
4426
4570
  <p class="admonition-title">Configuration entry (2) does not make sense in some scenarios</p>
4427
- <p>When running <code>ceedling new</code>, <code>ceedling examples</code>, or <code>ceedling example</code>
4428
- there is no project file to read. Similarly, <code>ceedling upgrade</code> does not
4429
- load a project file; it merely works with the directory structure and
4430
- contents of a project. In these cases, the environment variable is your
4431
- only option to set which Ceedling to launch.</p>
4571
+ <p><code>ceedling new</code>, <code>ceedling examples</code>, <code>ceedling example</code>, <code>ceedling docs</code>,
4572
+ and <code>ceedling help</code> outside a project have no project file to read. They
4573
+ use the environment variable or a <code>vendor/ceedling</code> path in your working
4574
+ directory.</p>
4575
+ <p><code>ceedling upgrade</code> re-vendors a project from the Ceedling you run, or from
4576
+ the installation the environment variable names. It never selects a
4577
+ <code>vendor/ceedling</code> path, which inside a project is the copy being replaced.</p>
4578
+ <p><code>ceedling version</code> reads your project file when one is available. See
4579
+ <a href="#hand-off">Hand-off</a>.</p>
4432
4580
  </div>
4433
4581
  <h2 id="settings">Settings</h2>
4434
4582
  <p>The environment variable and configuration entry for <em>Which Ceedling</em> can
4435
4583
  contain two values:</p>
4436
4584
  <ol>
4437
- <li>The value <code>gem</code> indicates that the command line <code>ceedling</code> launcher
4438
- should run the application packaged alongside it in <code>lib/</code> (these
4585
+ <li>The value <code>gem</code>, in any case, indicates that the command line <code>ceedling</code>
4586
+ launcher should run the application packaged alongside it in <code>lib/</code> (these
4439
4587
  paths are typically found in the gem installation location).</li>
4440
4588
  <li>A relative or absolute path in your file system. Such a path should
4441
4589
  point to the top-level directory that contains Ceedling’s <code>bin/</code> and
4442
- <code>lib/</code> sub-directories.</li>
4590
+ <code>lib/</code> sub-directories. A relative path is relative to your working
4591
+ directory, not to your project file.</li>
4592
+ </ol>
4593
+ <h2 id="hand-off">Hand-off</h2>
4594
+ <p>When <em>which ceedling</em> selects an installation other than the one whose
4595
+ <code>ceedling</code> command you ran, every command except <code>version</code> runs in the selected
4596
+ installation. Its own launcher replaces the one you ran, in a new process,
4597
+ and receives your original command line. Your command then runs wholly on the
4598
+ selected installation’s code, whatever its version.</p>
4599
+ <p>One command falls back. A <code>--local</code> copy carries no documentation bundle, so
4600
+ <code>ceedling docs</code> with such a copy selected exports the documentation of the
4601
+ <code>ceedling</code> command you ran instead, with a notice naming both installations.</p>
4602
+ <p>Both sides log a notice, naming each installation and its version where
4603
+ it can be read:</p>
4604
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>NOTICE: Ceedling launcher 1.2.2 at /var/lib/gems/3.3.0/gems/ceedling-1.2.2/ is handing off to Ceedling 1.2.0 at /home/me/project/vendor/ceedling/, which runs in its own process.
4605
+ </code></pre></div>
4606
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>NOTICE: Ceedling 1.2.3 at /home/me/project/vendor/ceedling/ is now running, launched from Ceedling 1.2.2 at /var/lib/gems/3.3.0/gems/ceedling-1.2.2/.
4607
+ </code></pre></div>
4608
+ <p>The second notice comes only from Ceedling 1.2.2 or later. Commands that
4609
+ quiet logging, such as <code>help</code> and <code>dumpconfig</code>, show neither.</p>
4610
+ <p>A hand-off adds about 0.2 seconds to a command.</p>
4611
+ <h3 id="hand-off-by-condition">Hand-off by condition</h3>
4612
+ <p>The table names one of five mechanisms per condition:</p>
4613
+ <ul>
4614
+ <li><strong>In-process:</strong> the <code>ceedling</code> command you run does the work itself.</li>
4615
+ <li><strong>Hand-off:</strong> the selected installation’s own launcher runs the command, in a new process.</li>
4616
+ <li><strong>Restart:</strong> an application loaded by an older launcher restarts in its own process.</li>
4617
+ <li><strong>Report:</strong> the <code>ceedling</code> command you run reports on both installations without running the selected one.</li>
4618
+ <li><strong>Stop:</strong> the <code>ceedling</code> command you run stops with advice.</li>
4619
+ </ul>
4620
+ <table>
4621
+ <thead>
4622
+ <tr>
4623
+ <th>Condition</th>
4624
+ <th>Example</th>
4625
+ <th>Mechanism</th>
4626
+ <th>Behavior in 1.2.2+</th>
4627
+ </tr>
4628
+ </thead>
4629
+ <tbody>
4630
+ <tr>
4631
+ <td>The selection is the installation you run</td>
4632
+ <td><code>ceedling test:all</code> with the gem and <code>:which_ceedling: gem</code></td>
4633
+ <td>In-process</td>
4634
+ <td>Runs as before 1.2.2, with no notice</td>
4635
+ </tr>
4636
+ <tr>
4637
+ <td>The selection is the same installation by another path</td>
4638
+ <td><code>:which_ceedling</code> names a symlink to the gem’s directory</td>
4639
+ <td>In-process</td>
4640
+ <td>Paths are compared after resolving links, so nothing is handed off</td>
4641
+ </tr>
4642
+ <tr>
4643
+ <td>The selection is another installation</td>
4644
+ <td>The gem’s <code>ceedling test:all</code> in a <code>--local</code> project</td>
4645
+ <td>Hand-off</td>
4646
+ <td>The vendored copy runs the build whole, whatever its version. Both sides log a notice.</td>
4647
+ </tr>
4648
+ <tr>
4649
+ <td>A command without a project selects another installation</td>
4650
+ <td><code>ceedling new</code> with <code>WHICH_CEEDLING</code> set</td>
4651
+ <td>Hand-off</td>
4652
+ <td>The selected installation creates the project with its own code and files</td>
4653
+ </tr>
4654
+ <tr>
4655
+ <td>The selection is a development checkout</td>
4656
+ <td>The gem’s <code>ceedling test:all</code> with <code>:which_ceedling: /home/me/dev/ceedling</code></td>
4657
+ <td>Hand-off</td>
4658
+ <td>The checkout’s own <code>bin/</code> and <code>lib/</code> run the command, so every change takes effect</td>
4659
+ </tr>
4660
+ <tr>
4661
+ <td><code>docs</code> selects a <code>--local</code> copy</td>
4662
+ <td><code>ceedling docs out/</code> in a <code>--local</code> project</td>
4663
+ <td>In-process</td>
4664
+ <td>Exports the documentation of the <code>ceedling</code> command you run, with a notice</td>
4665
+ </tr>
4666
+ <tr>
4667
+ <td><code>version</code> with a selection</td>
4668
+ <td><code>ceedling version</code> in a <code>--local</code> project</td>
4669
+ <td>Report</td>
4670
+ <td>Lists <code>Ceedling Launcher =&gt;</code> and <code>Ceedling App =&gt;</code>, each with its own version</td>
4671
+ </tr>
4672
+ <tr>
4673
+ <td><code>upgrade</code> inside a <code>--local</code> project</td>
4674
+ <td><code>ceedling upgrade .</code></td>
4675
+ <td>Stop</td>
4676
+ <td>Refuses to upgrade the vendored copy from itself</td>
4677
+ </tr>
4678
+ <tr>
4679
+ <td>The selection is a copy vendored by 1.1.0 through 1.2.1</td>
4680
+ <td>The gem’s <code>ceedling test:all</code> in a project vendored by 1.2.0</td>
4681
+ <td>Stop</td>
4682
+ <td>Advises re-vendoring with <code>ceedling upgrade</code></td>
4683
+ </tr>
4684
+ <tr>
4685
+ <td>A launcher before 1.2.2 selects a 1.2.2+ application</td>
4686
+ <td>A 1.2.1 gem <code>ceedling test:all</code> in a project vendoring 1.2.2</td>
4687
+ <td>Restart</td>
4688
+ <td>Logs a warning, then the application runs whole. If it can’t restart, it warns and continues in the older launcher’s process.</td>
4689
+ </tr>
4690
+ <tr>
4691
+ <td>A launcher before 1.2.2 runs a command without a project</td>
4692
+ <td>A 1.2.1 gem <code>ceedling new</code> with <code>WHICH_CEEDLING</code> naming 1.2.2</td>
4693
+ <td>In-process</td>
4694
+ <td>The older launcher’s own code runs the command. Upgrade the <code>ceedling</code> command you run.</td>
4695
+ </tr>
4696
+ </tbody>
4697
+ </table>
4698
+ <h4 id="example-scenarios">Example scenarios</h4>
4699
+ <p>These show when the conditions above come into play, and which goal each
4700
+ serves.</p>
4701
+ <p><strong>Pin a team’s project to one Ceedling version.</strong> Create the project with
4702
+ <code>ceedling new --local</code>, and commit <code>vendor/ceedling/</code>. Each teammate can then
4703
+ run the project with whatever 1.2.2+ gem they have installed. The gem hands
4704
+ each command off to the vendored copy, so everyone builds with the same
4705
+ version. <code>ceedling version</code> confirms it under <code>Ceedling App =&gt;</code>.</p>
4706
+ <p><strong>Keep an older project on its version while you upgrade the gem.</strong> A
4707
+ project vendoring 1.2.0 still builds with 1.2.0 after you install the 1.2.2
4708
+ gem, because the gem hands off to the vendored copy. If the copy was vendored
4709
+ by 1.1.0 through 1.2.1, the gem stops instead. Re-vendor it as below, or
4710
+ copy Unity’s <code>test/targets/</code> into the copy to keep its version.</p>
4711
+ <p><strong>Upgrade a vendored project.</strong> Run <code>upgrade</code> with the Ceedling you want,
4712
+ from outside the project:</p>
4713
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="w"> </span>&gt;<span class="w"> </span>ceedling<span class="w"> </span>upgrade<span class="w"> </span>my_project
4714
+ </code></pre></div>
4715
+ <p>To re-vendor with an installation other than the one you run, name it in
4716
+ <code>WHICH_CEEDLING</code>. Run from inside the project, <code>upgrade</code> stops, because the
4717
+ vendored copy would be both source and destination.</p>
4718
+ <p><strong>Create a project with a version you haven’t installed as a gem.</strong> Point
4719
+ <code>WHICH_CEEDLING</code> at an unpacked copy or a checkout of that version. <code>new</code>
4720
+ hands off to it, so the project, its vendored files, and its recorded
4721
+ <code>:ceedling_version:</code> all come from that version:</p>
4722
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="w"> </span>&gt;<span class="w"> </span><span class="nv">WHICH_CEEDLING</span><span class="o">=</span>~/ceedlings/1.2.0<span class="w"> </span>ceedling<span class="w"> </span>new<span class="w"> </span>--local<span class="w"> </span>my_project
4723
+ </code></pre></div>
4724
+ <p><strong>Compare versions, or find where a behavior changed.</strong> Set <code>WHICH_CEEDLING</code>
4725
+ for each run instead of editing the project file. It overrides
4726
+ <code>:which_ceedling</code> and a <code>vendor/ceedling/</code> copy, so a CI job can build one
4727
+ project with several versions:</p>
4728
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="w"> </span>&gt;<span class="w"> </span><span class="nv">WHICH_CEEDLING</span><span class="o">=</span>~/ceedlings/1.2.0<span class="w"> </span>ceedling<span class="w"> </span>test:all
4729
+ <a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span>&gt;<span class="w"> </span><span class="nv">WHICH_CEEDLING</span><span class="o">=</span>~/ceedlings/1.2.2<span class="w"> </span>ceedling<span class="w"> </span>test:all
4730
+ </code></pre></div>
4731
+ <p><strong>Run a 1.2.2 project in a CI image with an older gem.</strong> A Docker image
4732
+ shipping a 1.2.1 gem loads the vendored 1.2.2 application into its own
4733
+ process. The application restarts itself, with a warning. To avoid the
4734
+ restart, run the project’s <code>./ceedling</code> launch script, or upgrade the image.</p>
4735
+ <p><strong>Develop Ceedling itself.</strong> Point <code>:which_ceedling</code> at your local
4736
+ repository and keep running the installed gem. See
4737
+ <a href="#ceedling-development">Ceedling development</a>.</p>
4738
+ <div class="admonition note">
4739
+ <p class="admonition-title">The launcher you run still parses your command line</p>
4740
+ <p>The <code>ceedling</code> command you run reads your command line before it hands off, so it
4741
+ rejects an option that only the selected installation knows. Run the
4742
+ selected installation’s own launcher instead, such as <code>./ceedling</code> in a
4743
+ <code>--local</code> project.</p>
4744
+ </div>
4745
+ <h3 id="version"><code>version</code></h3>
4746
+ <p><code>ceedling version</code> reports on both installations rather than hand off. It
4747
+ reads your project file when one is available, or the one <code>--project</code> names,
4748
+ along with any <code>--mixin</code>s. When the project selects another installation, it
4749
+ lists <code>Ceedling Launcher =&gt;</code> and <code>Ceedling App =&gt;</code> separately, each with its
4750
+ own version.</p>
4751
+ <h3 id="older-launchers">Older launchers</h3>
4752
+ <p>A launcher before 1.2.2 loads the selected installation’s application into
4753
+ its own process instead of handing off. A 1.2.2 or later application detects
4754
+ this, logs a warning, and restarts in its own process with your original
4755
+ command line. <code>new</code>, <code>example</code>, <code>examples</code>, <code>upgrade</code>, <code>docs</code>, and <code>help</code>
4756
+ without a project never load the application, so these still run the older
4757
+ launcher’s own code. Upgrade the <code>ceedling</code> command you run to avoid this.</p>
4758
+ <h3 id="projects-vendored-by-110-through-121">Projects vendored by 1.1.0 through 1.2.1</h3>
4759
+ <p><code>ceedling new --local</code> in Ceedling 1.1.0 through 1.2.1 left Unity’s built-in
4760
+ mixins out of the vendored copy, so that copy cannot run on its own. The
4761
+ <code>ceedling</code> command you run stops with advice instead of handing off to it. Re-vendor
4762
+ the project with <code>ceedling upgrade &lt;project path&gt;</code>.</p>
4763
+ <h2 id="ceedling-development">Ceedling development</h2>
4764
+ <p><em>Which ceedling</em> lets you run your local Ceedling repository on a project
4765
+ from the <code>ceedling</code> command you already have installed. Set <code>:project</code> ↳
4766
+ <code>:which_ceedling</code> in the project file, or <code>WHICH_CEEDLING</code>, to the path of
4767
+ your repository:</p>
4768
+ <div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">:project</span><span class="p">:</span>
4769
+ <a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span><span class="nt">:which_ceedling</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/home/me/dev/ceedling</span>
4770
+ </code></pre></div>
4771
+ <p>The installed <code>ceedling</code> command hands every command off to your repository’s own
4772
+ <code>bin/ceedling</code>. Your command runs wholly on your repository’s <code>bin/</code> and
4773
+ <code>lib/</code>, so changes in either take effect. <code>ceedling version</code> lists both
4774
+ installations, your repository with its <code>.dev</code> tag.</p>
4775
+ <p>Before 1.2.2, the installed <code>ceedling</code> command loaded your repository’s application
4776
+ into its own process. Any <code>lib/</code> file it had already loaded stayed the
4777
+ installed copy, so changes to those files were silently ignored.</p>
4778
+ <p>Keep in mind:</p>
4779
+ <ol>
4780
+ <li><strong>Your repository’s <code>bin/</code> runs as well as its <code>lib/</code>.</strong> The installed
4781
+ launcher never runs your repository’s application. To exercise a
4782
+ particular launcher, run its <code>bin/ceedling</code> directly.</li>
4783
+ <li><strong>The installed <code>ceedling</code> command parses your command line first.</strong> It rejects a
4784
+ command or option that exists only in your repository. Run your
4785
+ repository’s launcher directly for those.</li>
4786
+ <li><strong>Your repository must run on its own.</strong> It needs <code>bin/ceedling</code> and its
4787
+ checked-out Git submodules, including Unity’s <code>test/targets/</code>. Otherwise
4788
+ the installed <code>ceedling</code> command stops with advice.</li>
4789
+ <li><strong>A debugger or profiler loses the command at the hand-off.</strong> It attaches
4790
+ to the installed <code>ceedling</code> command, whose process the hand-off replaces. Attach
4791
+ it to your repository’s launcher directly instead.</li>
4792
+ <li><strong>A hand-off adds about 0.2 seconds</strong> to each command.</li>
4793
+ <li><strong><code>ceedling docs</code> exports the installed <code>ceedling</code> command’s documentation</strong> when
4794
+ your repository has no built <code>site-local/</code> bundle.</li>
4795
+ <li><strong>A path that resolves to the installation you run is not handed off.</strong>
4796
+ The plugin test suites’ <code>:which_ceedling: ../../../..</code> names the
4797
+ repository running them, so they run in-process.</li>
4443
4798
  </ol>
4799
+ <p>To run your repository’s launcher directly:</p>
4800
+ <ul>
4801
+ <li>In Unix-like systems: <code>&gt; ~/dev/ceedling/bin/ceedling &lt;args&gt;</code>.</li>
4802
+ <li>On Windows systems: <code>&gt; ruby %USERPROFILE%\dev\ceedling\bin\ceedling &lt;args&gt;</code>.</li>
4803
+ </ul>
4444
4804
  <p><br/><br/></p>
4445
4805
 
4446
4806
 
@@ -4512,7 +4872,7 @@ contain two values:</p>
4512
4872
  <script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
4513
4873
 
4514
4874
 
4515
- <script src="../assets/javascripts/bundle.c21346df.min.js"></script>
4875
+ <script src="../assets/javascripts/bundle.a5f9d56c.min.js"></script>
4516
4876
 
4517
4877
 
4518
4878
  </body>
@@ -21,7 +21,7 @@
21
21
 
22
22
 
23
23
  <link rel="icon" href="../assets/images/favicon.png">
24
- <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.0">
24
+ <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.8.2">
25
25
 
26
26
 
27
27
 
@@ -4404,7 +4404,7 @@ available build step hooks.</p>
4404
4404
  <script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.tabs", "navigation.sections", "navigation.top", "navigation.indexes", "navigation.path", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate"], "search": "../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"default": "latest", "provider": "mike"}}</script>
4405
4405
 
4406
4406
 
4407
- <script src="../assets/javascripts/bundle.c21346df.min.js"></script>
4407
+ <script src="../assets/javascripts/bundle.a5f9d56c.min.js"></script>
4408
4408
 
4409
4409
 
4410
4410
  </body>