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.
- checksums.yaml +4 -4
- data/GIT_COMMIT_SHA +1 -1
- data/README.md +11 -9
- data/Rakefile +2 -1
- data/assets/features/ceedling +1 -1
- data/assets/fixtures/test_source_file_duplicate_basenames/test_calc_typo.c +14 -0
- data/assets/fixtures/tests_with_duplicate_test_names/test_foo.c +21 -0
- data/assets/fixtures/tests_with_partials_coverage/src/private_macro.c +7 -0
- data/assets/fixtures/tests_with_partials_coverage/src/private_macro.h +5 -0
- data/assets/fixtures/tests_with_partials_coverage/src/tally.c +13 -0
- data/assets/fixtures/tests_with_partials_coverage/src/tally.h +4 -0
- data/assets/fixtures/tests_with_partials_coverage/test/test_private_macro.c +10 -0
- data/assets/fixtures/tests_with_partials_coverage/test/test_tally.c +9 -0
- data/bin/actionator.rb +6 -12
- data/bin/app_cfg.rb +14 -1
- data/bin/ceedling +13 -3
- data/bin/cli.rb +25 -6
- data/bin/cli_handler.rb +113 -73
- data/bin/cli_helper.rb +51 -78
- data/bin/installation_selector.rb +81 -0
- data/bin/launchinator.rb +69 -0
- data/bin/mixin_resolvinator.rb +26 -36
- data/bin/objects.yml +13 -0
- data/bin/path_validator.rb +25 -29
- data/bin/versionator.rb +47 -48
- data/ceedling.gemspec +19 -15
- data/docs/BreakingChanges.md +86 -1
- data/docs/Changelog.md +145 -3
- data/docs/KnownIssues.md +179 -6
- data/docs/ReleaseNotes.md +13 -0
- data/examples/wondrous_forest/README.md +29 -1
- data/examples/wondrous_forest/src/ForestUnits.h +23 -0
- data/examples/wondrous_forest/src/RainGauge.c +59 -0
- data/examples/wondrous_forest/src/RainGauge.h +39 -0
- data/examples/wondrous_forest/src/RainTipIsr.c +17 -0
- data/examples/wondrous_forest/src/RainTipIsr.h +14 -0
- data/examples/wondrous_forest/test/TestRainGauge.c +126 -0
- data/lib/ceedling/build_log_writer.rb +33 -0
- data/lib/ceedling/c_extractor/README.md +15 -7
- data/lib/ceedling/c_extractor/c_extractor.rb +25 -14
- data/lib/ceedling/c_extractor/c_extractor_code_text.rb +84 -54
- data/lib/ceedling/c_extractor/c_extractor_constants.rb +18 -7
- data/lib/ceedling/c_extractor/c_extractor_declarations.rb +319 -283
- data/lib/ceedling/c_extractor/c_extractor_declarator.rb +285 -0
- data/lib/ceedling/c_extractor/c_extractor_defined_type.rb +111 -0
- data/lib/ceedling/c_extractor/c_extractor_definitions.rb +174 -121
- data/lib/ceedling/c_extractor/c_extractor_functions.rb +191 -162
- data/lib/ceedling/c_extractor/c_extractor_preprocessing.rb +46 -55
- data/lib/ceedling/c_extractor/c_extractor_statement.rb +30 -0
- data/lib/ceedling/c_extractor/c_extractor_types.rb +63 -41
- data/lib/ceedling/c_extractor/c_module_edits.rb +48 -0
- data/lib/ceedling/c_identifier.rb +21 -0
- data/lib/ceedling/ceedling.h +8 -0
- data/lib/ceedling/config/build_root_policy.rb +70 -0
- data/lib/ceedling/config/configurator.rb +18 -19
- data/lib/ceedling/config/configurator_builder.rb +75 -28
- data/lib/ceedling/config/configurator_paths_validator.rb +179 -0
- data/lib/ceedling/config/configurator_plugins.rb +1 -1
- data/lib/ceedling/config/configurator_setup.rb +44 -33
- data/lib/ceedling/config/configurator_validator.rb +1 -110
- data/lib/ceedling/constants.rb +5 -1
- data/lib/ceedling/defaults.rb +35 -5
- data/lib/ceedling/dependencies/CACHE_SCHEMA.md +118 -0
- data/lib/ceedling/dependencies/README.md +18 -16
- data/lib/ceedling/dependencies/dependency_cache_store.rb +43 -21
- data/lib/ceedling/dependencies/dependency_hasher.rb +35 -1
- data/lib/ceedling/dependencies/dependency_tracker.rb +9 -3
- data/lib/ceedling/dependencies/dependinator.rb +13 -1
- data/lib/ceedling/diagnostics/DOCTOR.md +142 -0
- data/lib/ceedling/diagnostics/README.md +5 -0
- data/lib/ceedling/diagnostics/build_step_doctor.rb +110 -0
- data/lib/ceedling/diagnostics/duplicate_symbol_specialist.rb +108 -0
- data/lib/ceedling/diagnostics/guidance_phrases.rb +30 -0
- data/lib/ceedling/diagnostics/header_collision_guidance.rb +56 -0
- data/lib/ceedling/diagnostics/header_collision_specialist.rb +152 -0
- data/lib/ceedling/diagnostics/include_depth_specialist.rb +132 -0
- data/lib/ceedling/diagnostics/missing_symbol_specialist.rb +111 -0
- data/lib/ceedling/diagnostics/partial_name_specialist.rb +134 -0
- data/lib/ceedling/diagnostics/toolchain_output.rb +44 -0
- data/lib/ceedling/filename_extension.rb +7 -1
- data/lib/ceedling/filesystem/FILE_TREE.md +253 -0
- data/lib/ceedling/filesystem/PATH_HANDLING.md +360 -0
- data/lib/ceedling/filesystem/README.md +46 -0
- data/lib/ceedling/filesystem/build_roots.rb +105 -0
- data/lib/ceedling/filesystem/build_subpath.rb +187 -0
- data/lib/ceedling/filesystem/destination_collision.rb +25 -0
- data/lib/ceedling/{file_finder.rb → filesystem/file_finder.rb} +177 -156
- data/lib/ceedling/filesystem/file_finder_helper.rb +154 -0
- data/lib/ceedling/filesystem/file_path_collection_utils.rb +183 -0
- data/lib/ceedling/{file_path_utils.rb → filesystem/file_path_utils.rb} +200 -167
- data/lib/ceedling/{file_system_wrapper.rb → filesystem/file_system_wrapper.rb} +6 -5
- data/lib/ceedling/filesystem/file_tree.rb +241 -0
- data/lib/ceedling/{file_wrapper.rb → filesystem/file_wrapper.rb} +149 -65
- data/lib/ceedling/filesystem/path_exclusions.rb +30 -0
- data/lib/ceedling/{path_matcher.rb → filesystem/path_matcher.rb} +48 -23
- data/lib/ceedling/{path_mirror.rb → filesystem/path_mirror.rb} +19 -18
- data/lib/ceedling/filesystem/path_spellings.rb +55 -0
- data/lib/ceedling/filesystem/project_paths.rb +184 -0
- data/lib/ceedling/filesystem/test_build_layout.rb +114 -0
- data/lib/ceedling/filesystem/win_long_paths.rb +153 -0
- data/lib/ceedling/filesystem/win_path_limit.rb +83 -0
- data/lib/ceedling/filesystem/win_path_prober.rb +52 -0
- data/lib/ceedling/filesystem/working_dir.rb +40 -0
- data/lib/ceedling/generators/generator.rb +32 -70
- data/lib/ceedling/generators/generator_helper.rb +0 -44
- data/lib/ceedling/generators/generator_mocks.rb +5 -0
- data/lib/ceedling/generators/generator_partials.rb +306 -244
- data/lib/ceedling/generators/generator_test_results_backtrace.rb +7 -7
- data/lib/ceedling/generators/generator_test_runner.rb +5 -8
- data/lib/ceedling/generators/partial_header_writer.rb +95 -0
- data/lib/ceedling/generators/partial_source_writer.rb +137 -0
- data/lib/ceedling/handoff.rb +121 -0
- data/lib/ceedling/includes/header_search.rb +225 -0
- data/lib/ceedling/includes/include_factory.rb +9 -12
- data/lib/ceedling/includes/include_pathinator.rb +112 -33
- data/lib/ceedling/includes/includes.rb +150 -38
- data/lib/ceedling/installation.rb +92 -0
- data/lib/ceedling/library_resolver.rb +99 -0
- data/lib/ceedling/objects.yml +112 -6
- data/lib/ceedling/partials/README.md +110 -16
- data/lib/ceedling/partials/carry_plan.rb +71 -0
- data/lib/ceedling/partials/definition_head.rb +74 -0
- data/lib/ceedling/partials/include_groups.rb +37 -0
- data/lib/ceedling/partials/interface_extras.rb +25 -0
- data/lib/ceedling/partials/partializer.rb +603 -124
- data/lib/ceedling/partials/partializer_config.rb +8 -1
- data/lib/ceedling/partials/partializer_helper.rb +851 -145
- data/lib/ceedling/partials/partializer_reconciler.rb +174 -0
- data/lib/ceedling/partials/partializer_utils.rb +89 -109
- data/lib/ceedling/partials/partials.rb +153 -10
- data/lib/ceedling/partials/type_macros.rb +126 -0
- data/lib/ceedling/plugins/report_log_writer_plugin.rb +3 -5
- data/lib/ceedling/preprocess/README.md +43 -33
- data/lib/ceedling/preprocess/preprocessinator.rb +100 -186
- data/lib/ceedling/preprocess/preprocessinator_code_finder.rb +65 -72
- data/lib/ceedling/preprocess/preprocessinator_file_assembler.rb +32 -76
- data/lib/ceedling/preprocess/preprocessinator_includes_handler.rb +1 -1
- data/lib/ceedling/preprocess/preprocessinator_line_marker_includes_extractor.rb +1 -1
- data/lib/ceedling/preprocess/preprocessinator_reconstructor.rb +51 -14
- data/lib/ceedling/rake_app/rakefile_component_resolver.rb +10 -17
- data/lib/ceedling/rakefile.rb +15 -1
- data/lib/ceedling/rakefiles/base/tasks_base.rake +1 -1
- data/lib/ceedling/rakefiles/release/rules_release.rake +4 -7
- data/lib/ceedling/release_invoker/release_build_executor.rb +33 -44
- data/lib/ceedling/release_invoker/release_build_planner.rb +14 -6
- data/lib/ceedling/reportinator.rb +3 -4
- data/lib/ceedling/setupinator.rb +104 -87
- data/lib/ceedling/test_context_extractor.rb +5 -1
- data/lib/ceedling/test_invoker/HEADER_COLLISIONS.md +21 -7
- data/lib/ceedling/test_invoker/PIPELINE.md +62 -19
- data/lib/ceedling/test_invoker/README.md +1 -1
- data/lib/ceedling/test_invoker/derived_search_path_notices.rb +45 -0
- data/lib/ceedling/test_invoker/mock_locator.rb +175 -10
- data/lib/ceedling/test_invoker/partial_files_preprocessinator.rb +181 -0
- data/lib/ceedling/test_invoker/partials_manager.rb +271 -302
- data/lib/ceedling/test_invoker/standin_headerinator.rb +19 -17
- data/lib/ceedling/test_invoker/test_bare_includes_extractinator.rb +26 -3
- data/lib/ceedling/test_invoker/test_build_executor.rb +358 -234
- data/lib/ceedling/test_invoker/test_build_planner.rb +46 -33
- data/lib/ceedling/test_invoker/test_build_setup.rb +43 -18
- data/lib/ceedling/test_invoker/test_build_validations.rb +35 -47
- data/lib/ceedling/test_invoker/test_derived_search_paths.rb +189 -0
- data/lib/ceedling/test_invoker/test_file_preprocessinator.rb +2 -3
- data/lib/ceedling/test_invoker/test_includes_reconcilinator.rb +1 -1
- data/lib/ceedling/test_invoker/test_invoker.rb +6 -1
- data/lib/ceedling/test_invoker/test_invoker_types.rb +28 -20
- data/lib/ceedling/test_invoker/test_pipeline_helpers.rb +6 -4
- data/lib/ceedling/test_invoker/test_pipeline_manager.rb +25 -8
- data/lib/ceedling/test_invoker/test_runner_generatinator.rb +31 -3
- data/lib/ceedling/test_invoker/test_search_paths.rb +30 -8
- data/lib/ceedling/test_invoker/test_source_file_directive_resolver.rb +40 -20
- data/lib/ceedling/test_invoker/test_substitutions.rb +72 -0
- data/lib/ceedling/tools/shell_quoting.rb +45 -0
- data/lib/ceedling/{tool_executor.rb → tools/tool_executor.rb} +9 -3
- data/lib/ceedling/tools/tool_quoting.rb +79 -0
- data/lib/ceedling/{tool_validator.rb → tools/tool_validator.rb} +18 -7
- data/lib/ceedling/yaml_wrapper.rb +3 -2
- data/lib/version.rb +1 -1
- data/plugins/bullseye/bullseye.rake +1 -3
- data/plugins/bullseye/config/defaults_bullseye.rb +1 -1
- data/plugins/bullseye/lib/bullseye.rb +24 -9
- data/plugins/command_hooks/lib/command_hooks.rb +1 -1
- data/plugins/cppcheck/config/defaults_cppcheck.rb +1 -1
- data/plugins/dependencies/config/defaults.yml +6 -6
- data/plugins/dependencies/dependencies.rake +4 -1
- data/plugins/dependencies/lib/dependencies.rb +18 -8
- data/plugins/dependencies/lib/dependency_spec.rb +17 -5
- data/plugins/fff/lib/fff.rb +79 -46
- data/plugins/fff/lib/fff_mock_generator.rb +12 -9
- data/plugins/fff/spec/fff_cmock_wrapper_spec.rb +262 -0
- data/plugins/fff/spec/fff_mock_header_generator_spec.rb +9 -0
- data/plugins/fff/spec/fff_mock_source_generator_spec.rb +20 -0
- data/plugins/gcov/config/defaults_gcov.rb +1 -1
- data/plugins/gcov/lib/console_reportinator.rb +28 -36
- data/plugins/gcov/lib/gcov.rb +9 -2
- data/plugins/gcov/lib/gcovr_reportinator.rb +8 -40
- data/plugins/gcov/lib/gcovr_thresholds.rb +74 -0
- data/plugins/gcov/lib/reportgenerator_reportinator.rb +3 -2
- data/plugins/module_generator/lib/module_generator.rb +3 -3
- data/plugins/report_tests_teamcity_stdout/lib/report_tests_teamcity_stdout.rb +53 -80
- data/plugins/sanitize/lib/sanitize_records.rb +3 -6
- data/plugins/valgrind/lib/valgrind.rb +14 -7
- data/site-local/404.html +2 -2
- data/site-local/assets/javascripts/{bundle.c21346df.min.js → bundle.a5f9d56c.min.js} +1 -1
- data/site-local/assets/javascripts/{bundle.c21346df.min.js.map → bundle.a5f9d56c.min.js.map} +2 -2
- data/site-local/configuration/environment-vars.html +2 -2
- data/site-local/configuration/global-collections.html +3 -3
- data/site-local/configuration/index.html +2 -2
- data/site-local/configuration/loading.html +2 -2
- data/site-local/configuration/mixins.html +2 -2
- data/site-local/configuration/parallel-builds.html +2 -2
- data/site-local/configuration/project-file.html +2 -2
- data/site-local/configuration/reference/cexception.html +2 -2
- data/site-local/configuration/reference/cmock.html +7 -3
- data/site-local/configuration/reference/defines.html +2 -2
- data/site-local/configuration/reference/environment.html +2 -2
- data/site-local/configuration/reference/extension.html +2 -2
- data/site-local/configuration/reference/files.html +65 -12
- data/site-local/configuration/reference/flags.html +2 -2
- data/site-local/configuration/reference/index.html +2 -2
- data/site-local/configuration/reference/libraries.html +23 -5
- data/site-local/configuration/reference/mixins.html +2 -2
- data/site-local/configuration/reference/partials.html +84 -2
- data/site-local/configuration/reference/paths.html +36 -8
- data/site-local/configuration/reference/plugins.html +2 -2
- data/site-local/configuration/reference/project.html +264 -12
- data/site-local/configuration/reference/release-build.html +4 -2
- data/site-local/configuration/reference/test-build.html +2 -2
- data/site-local/configuration/reference/test-runner.html +2 -2
- data/site-local/configuration/reference/tools.html +58 -4
- data/site-local/configuration/reference/unity.html +2 -2
- data/site-local/configuration/which-ceedling.html +379 -19
- data/site-local/development/index.html +2 -2
- data/site-local/development/plugins/configuration.html +2 -2
- data/site-local/development/plugins/index.html +2 -2
- data/site-local/development/plugins/plugin-subclass.html +5 -4
- data/site-local/development/plugins/rake-tasks.html +2 -2
- data/site-local/development/releases.html +7 -3
- data/site-local/development/workflow.html +50 -45
- data/site-local/getting-started/builds.html +4 -2
- data/site-local/getting-started/command-line.html +58 -6
- data/site-local/getting-started/example-projects/cipher-quest.html +2 -2
- data/site-local/getting-started/example-projects/index.html +2 -2
- data/site-local/getting-started/example-projects/temp-sensor.html +2 -2
- data/site-local/getting-started/example-projects/wondrous-forest.html +10 -2
- data/site-local/getting-started/index.html +2 -2
- data/site-local/getting-started/installation.html +2 -2
- data/site-local/getting-started/quick-start.html +2 -2
- data/site-local/help.html +2 -2
- data/site-local/index.html +2 -2
- data/site-local/overview/build-system.html +2 -2
- data/site-local/overview/index.html +2 -2
- data/site-local/overview/test-environments.html +2 -2
- data/site-local/overview/tools-and-frameworks.html +2 -2
- data/site-local/plugins/beep.html +2 -2
- data/site-local/plugins/bullseye/index.html +45 -38
- data/site-local/plugins/bullseye/licensing.html +2 -2
- data/site-local/plugins/command-hooks.html +4 -4
- data/site-local/plugins/compile-commands-json-db.html +2 -2
- data/site-local/plugins/cppcheck.html +2 -2
- data/site-local/plugins/dependencies.html +8 -5
- data/site-local/plugins/fff.html +58 -13
- data/site-local/plugins/gcov/examples.html +2 -2
- data/site-local/plugins/gcov/gcovr.html +23 -14
- data/site-local/plugins/gcov/index.html +2 -2
- data/site-local/plugins/gcov/overview.html +2 -2
- data/site-local/plugins/gcov/reportgenerator.html +18 -14
- data/site-local/plugins/gcov/reporting.html +2 -2
- data/site-local/plugins/gcov/setup.html +4 -3
- data/site-local/plugins/gcov/tool-versions.html +2 -2
- data/site-local/plugins/gcov/troubleshooting.html +2 -2
- data/site-local/plugins/index.html +2 -2
- data/site-local/plugins/module-generator.html +2 -2
- data/site-local/plugins/report-build-warnings-log.html +2 -2
- data/site-local/plugins/report-tests-gtestlike-stdout.html +2 -2
- data/site-local/plugins/report-tests-ide-stdout.html +2 -2
- data/site-local/plugins/report-tests-log-factory.html +2 -2
- data/site-local/plugins/report-tests-pretty-stdout.html +2 -2
- data/site-local/plugins/report-tests-raw-output-log.html +5 -3
- data/site-local/plugins/report-tests-teamcity-stdout.html +8 -5
- data/site-local/plugins/sanitize.html +9 -8
- data/site-local/plugins/valgrind.html +10 -9
- data/site-local/project/index.html +2 -2
- data/site-local/project/release-history.html +2 -2
- data/site-local/project/sbom.html +2 -2
- data/site-local/project/upgrade.html +5 -2
- data/site-local/reference/build-directives.html +2 -2
- data/site-local/reference/command-line.html +11 -4
- data/site-local/reference/environment-vars.html +2 -2
- data/site-local/reference/gcov-plugin.html +2 -2
- data/site-local/reference/global-collections.html +12 -12
- data/site-local/reference/index.html +2 -2
- data/site-local/reference/partials-macros.html +47 -2
- data/site-local/reference/project-configuration.html +2 -2
- data/site-local/sitemap.xml.gz +0 -0
- data/site-local/snapshot/examples/cipher_quest/index.html +2 -2
- data/site-local/snapshot/examples/temp_sensor/index.html +2 -2
- data/site-local/snapshot/examples/wondrous_forest/index.html +72 -15
- data/site-local/snapshot/plugins/bullseye/config/defaults_bullseye.rb +1 -1
- data/site-local/snapshot/plugins/gcov/config/defaults_gcov.rb +1 -1
- data/site-local/testing-guide/build-directives.html +2 -2
- data/site-local/testing-guide/conventions.html +113 -15
- data/site-local/testing-guide/frameworks.html +2 -2
- data/site-local/testing-guide/index.html +2 -2
- data/site-local/testing-guide/partials/configuration.html +31 -4
- data/site-local/testing-guide/partials/conventions.html +509 -8
- data/site-local/testing-guide/partials/directives.html +4 -3
- data/site-local/testing-guide/partials/example.html +2 -2
- data/site-local/testing-guide/partials/index.html +2 -2
- data/site-local/testing-guide/partials/overview.html +30 -12
- data/site-local/testing-guide/partials/variables.html +169 -4
- data/site-local/testing-guide/test-cases.html +2 -2
- data/site-local/testing-guide/test-sample.html +2 -2
- data/site-local/testing-guide/test-suite-anatomy.html +2 -2
- data/spec/integration/actionator_file_operations_spec.rb +91 -1
- data/spec/integration/build_step_doctor_spec.rb +270 -0
- data/spec/integration/c_extractor_composition_spec.rb +254 -4
- data/spec/integration/compile_commands_json_db_spec.rb +1 -1
- data/spec/integration/configurator_validation_spec.rb +1 -1
- data/spec/integration/dependencies/dependency_tracker_cache_hardening_spec.rb +26 -0
- data/spec/integration/dependencies/dependency_tracker_core_spec.rb +22 -0
- data/spec/integration/includes_extraction_spec.rb +27 -14
- data/spec/integration/launcher_handoff_spec.rb +297 -0
- data/spec/integration/mixin_loading_spec.rb +1 -1
- data/spec/integration/module_generator_spec.rb +3 -3
- data/spec/integration/nested_test_artifacts_spec.rb +99 -0
- data/spec/integration/partial_files_preprocessing_spec.rb +128 -0
- data/spec/integration/partials_carry_spec.rb +520 -0
- data/spec/integration/partials_declarations_spec.rb +655 -0
- data/spec/integration/partials_fallback_preprocessing_spec.rb +65 -0
- data/spec/integration/partials_function_pointers_spec.rb +277 -0
- data/spec/integration/partials_header_composition_spec.rb +268 -35
- data/spec/integration/partials_macro_decorators_spec.rb +267 -0
- data/spec/integration/partials_module_resolution_spec.rb +33 -23
- data/spec/integration/partials_symbol_linkage_spec.rb +13 -0
- data/spec/integration/path_intake_scenarios_spec.rb +101 -0
- data/spec/integration/path_length_reporting_spec.rb +64 -0
- data/spec/integration/path_scenarios_spec.rb +399 -0
- data/spec/integration/quote_include_isolator_spec.rb +57 -1
- data/spec/integration/report_build_warnings_log_spec.rb +1 -1
- data/spec/integration/report_tests_log_factory_spec.rb +1 -1
- data/spec/integration/test_build_parallel_barrier_spec.rb +1 -1
- data/spec/integration/test_executable_manifest_spec.rb +1 -1
- data/spec/integration/test_includes_extractinator_spec.rb +69 -3
- data/spec/integration/test_naming_spec.rb +201 -0
- data/spec/integration/test_source_file_checks_spec.rb +168 -0
- data/spec/integration/tool_executor_spec.rb +1 -1
- data/spec/integration/tool_validator_spec.rb +3 -3
- data/spec/integration/upgrade_docs_spec.rb +84 -0
- data/spec/integration/vendor_copy_transient_io_retry_spec.rb +74 -5
- data/spec/integration/win_long_paths_probe_spec.rb +46 -0
- data/spec/integration/win_path_limit_spec.rb +53 -0
- data/spec/integration/windows_registry_query_tool_spec.rb +41 -0
- data/spec/support/file_tree_helper.rb +88 -0
- data/spec/support/integration/configurator_integration_helper.rb +14 -9
- data/spec/support/integration/dependency_tracker_integration_helper.rb +1 -1
- data/spec/support/integration/partial_files_harness.rb +181 -0
- data/spec/support/integration/partials_generation_integration_helper.rb +239 -143
- data/spec/support/integration/path_scenario_harness.rb +175 -0
- data/spec/support/integration/spec_integration_helper.rb +9 -4
- data/spec/support/integration/test_includes_harness.rb +69 -37
- data/spec/support/integration/tool_executor_integration_helper.rb +14 -2
- data/spec/support/spec_helper.rb +2 -0
- data/spec/support/system/spec_system_helper.rb +7 -6
- data/spec/support/system/system_context.rb +21 -3
- data/spec/support/working_dir_tracking.rb +49 -0
- data/spec/system/build_output_mirroring_spec.rb +2 -2
- data/spec/system/bullseye_deployment_spec.rb +2 -0
- data/spec/system/conditional_mock_includes_spec.rb +1 -1
- data/spec/system/delta_builds_spec.rb +163 -23
- data/spec/system/encoding_stress_spec.rb +4 -4
- data/spec/system/example_wondrous_forest_spec.rb +2 -2
- data/spec/system/gcov_deployment_spec.rb +3 -0
- data/spec/system/header_include_path_validation_spec.rb +4 -4
- data/spec/system/header_search_paths_spec.rb +1083 -0
- data/spec/system/launcher_handoff_spec.rb +82 -0
- data/spec/system/mock_include_folders_spec.rb +212 -0
- data/spec/system/mockable_header_reassembly_spec.rb +184 -0
- data/spec/system/parent_directory_reference_spec.rb +5 -3
- data/spec/system/partials_carry_spec.rb +581 -0
- data/spec/system/partials_delta_builds_spec.rb +280 -0
- data/spec/system/partials_function_pointers_spec.rb +106 -0
- data/spec/system/partials_macro_decorators_spec.rb +127 -0
- data/spec/system/partials_module_disambiguation_spec.rb +125 -0
- data/spec/system/path_handling_probes_spec.rb +196 -0
- data/spec/system/pinned_thread_count_spec.rb +4 -4
- data/spec/system/preprocessing_fallback_conditionals_spec.rb +1 -1
- data/spec/system/preprocessing_parameterized_tests_spec.rb +1 -1
- data/spec/system/rake_release_task_path_disambiguation_spec.rb +6 -6
- data/spec/system/rake_test_task_path_disambiguation_spec.rb +85 -0
- data/spec/system/short_build_paths_spec.rb +87 -0
- data/spec/system/sibling_header_collision_spec.rb +30 -6
- data/spec/system/special_path_characters_spec.rb +86 -0
- data/spec/system/support/bullseye_common_test_cases.rb +42 -0
- data/spec/system/support/common_test_cases.rb +23 -21
- data/spec/system/support/gcov_common_test_cases.rb +37 -9
- data/spec/system/support/gcov_partials_test_cases.rb +48 -0
- data/spec/system/support/sanitize_common_test_cases.rb +2 -2
- data/spec/system/support/valgrind_common_test_cases.rb +12 -12
- data/spec/system/test_build_layout_spec.rb +209 -0
- data/spec/system/test_pipeline_stop_points_spec.rb +4 -4
- data/spec/system/test_runner_system_include_spec.rb +1 -1
- data/spec/system/test_source_file_directive_spec.rb +64 -5
- data/spec/units/bin/actionator_spec.rb +14 -17
- data/spec/units/bin/app_cfg_spec.rb +37 -0
- data/spec/units/bin/cli_handler_spec.rb +282 -6
- data/spec/units/bin/cli_helper_spec.rb +116 -45
- data/spec/units/bin/installation_selector_spec.rb +114 -0
- data/spec/units/bin/launchinator_spec.rb +171 -0
- data/spec/units/bin/path_validator_spec.rb +10 -0
- data/spec/units/bin/versionator_spec.rb +38 -6
- data/spec/units/build_log_writer_spec.rb +57 -0
- data/spec/units/c_extractor/c_extractor_code_text_spec.rb +67 -10
- data/spec/units/c_extractor/c_extractor_declarations_spec.rb +501 -4
- data/spec/units/c_extractor/c_extractor_declarator_spec.rb +245 -0
- data/spec/units/c_extractor/c_extractor_defined_type_spec.rb +45 -0
- data/spec/units/c_extractor/c_extractor_definitions_spec.rb +163 -3
- data/spec/units/c_extractor/c_extractor_functions_spec.rb +462 -21
- data/spec/units/c_extractor/c_extractor_preprocessing_spec.rb +39 -0
- data/spec/units/c_extractor/c_extractor_spec.rb +4 -4
- data/spec/units/c_extractor/c_extractor_types_spec.rb +163 -0
- data/spec/units/c_identifier_spec.rb +35 -0
- data/spec/units/config/build_root_policy_spec.rb +61 -0
- data/spec/units/config/configurator_builder_spec.rb +61 -6
- data/spec/units/config/configurator_paths_validator_spec.rb +292 -0
- data/spec/units/config/configurator_setup_spec.rb +80 -68
- data/spec/units/config/configurator_spec.rb +54 -6
- data/spec/units/config/configurator_validator_spec.rb +1 -172
- data/spec/units/dependencies/dependency_cache_store_spec.rb +98 -2
- data/spec/units/dependencies/dependency_debug_tree_spec.rb +1 -1
- data/spec/units/dependencies/dependency_hasher_spec.rb +42 -1
- data/spec/units/dependencies/dependency_path_normalizer_spec.rb +1 -1
- data/spec/units/dependencies/dependency_tracker_spec.rb +28 -1
- data/spec/units/dependencies/dependinator_spec.rb +17 -2
- data/spec/units/diagnostics/build_step_doctor_spec.rb +170 -0
- data/spec/units/diagnostics/duplicate_symbol_specialist_spec.rb +117 -0
- data/spec/units/diagnostics/header_collision_specialist_spec.rb +267 -0
- data/spec/units/diagnostics/include_depth_specialist_spec.rb +137 -0
- data/spec/units/diagnostics/missing_symbol_specialist_spec.rb +154 -0
- data/spec/units/diagnostics/partial_name_specialist_spec.rb +129 -0
- data/spec/units/diagnostics/toolchain_output_spec.rb +86 -0
- data/spec/units/encodinator_spec.rb +3 -4
- data/spec/units/filename_extension_spec.rb +11 -0
- data/spec/units/filesystem/build_roots_spec.rb +131 -0
- data/spec/units/filesystem/build_subpath_spec.rb +235 -0
- data/spec/units/filesystem/destination_collision_spec.rb +30 -0
- data/spec/units/{file_finder_helper_spec.rb → filesystem/file_finder_helper_spec.rb} +126 -1
- data/spec/units/filesystem/file_finder_spec.rb +845 -0
- data/spec/units/{file_path_collection_utils_spec.rb → filesystem/file_path_collection_utils_spec.rb} +181 -1
- data/spec/units/{file_path_utils_spec.rb → filesystem/file_path_utils_spec.rb} +435 -185
- data/spec/units/filesystem/file_system_wrapper_spec.rb +33 -0
- data/spec/units/filesystem/file_tree_spec.rb +511 -0
- data/spec/units/filesystem/file_tree_windows_spec.rb +78 -0
- data/spec/units/{file_wrapper_spec.rb → filesystem/file_wrapper_spec.rb} +286 -18
- data/spec/units/{path_matcher_spec.rb → filesystem/path_matcher_spec.rb} +48 -1
- data/spec/units/{path_mirror_spec.rb → filesystem/path_mirror_spec.rb} +32 -4
- data/spec/units/filesystem/project_paths_spec.rb +147 -0
- data/spec/units/filesystem/test_build_layout_spec.rb +216 -0
- data/spec/units/filesystem/win_long_paths_spec.rb +204 -0
- data/spec/units/filesystem/win_path_prober_spec.rb +158 -0
- data/spec/units/filesystem/working_dir_spec.rb +71 -0
- data/spec/units/generators/generator_helper_spec.rb +0 -60
- data/spec/units/generators/generator_mocks_spec.rb +13 -0
- data/spec/units/generators/generator_partials_spec.rb +656 -55
- data/spec/units/generators/generator_spec.rb +38 -6
- data/spec/units/generators/generator_test_results_backtrace_spec.rb +50 -46
- data/spec/units/generators/generator_test_results_spec.rb +1 -1
- data/spec/units/generators/generator_test_runner_spec.rb +9 -5
- data/spec/units/generators/partial_source_writer_spec.rb +129 -0
- data/spec/units/handoff_spec.rb +205 -0
- data/spec/units/includes/header_search_spec.rb +406 -0
- data/spec/units/includes/include_factory_spec.rb +23 -6
- data/spec/units/includes/include_pathinator_spec.rb +118 -8
- data/spec/units/includes/include_spec.rb +14 -0
- data/spec/units/includes/includes_spec.rb +176 -19
- data/spec/units/installation_spec.rb +228 -0
- data/spec/units/library_resolver_spec.rb +157 -0
- data/spec/units/loginator_spec.rb +31 -0
- data/spec/units/mock_locator_spec.rb +275 -6
- data/spec/units/partials/include_groups_spec.rb +42 -0
- data/spec/units/partials/partializer_config_spec.rb +32 -0
- data/spec/units/partials/partializer_helper_carry_spec.rb +661 -0
- data/spec/units/partials/partializer_helper_interface_extras_spec.rb +396 -0
- data/spec/units/partials/partializer_helper_spec.rb +529 -277
- data/spec/units/partials/partializer_reconciler_spec.rb +661 -0
- data/spec/units/partials/partializer_spec.rb +1579 -270
- data/spec/units/partials/partializer_utils_spec.rb +269 -232
- data/spec/units/partials/partials_rename_spec.rb +160 -0
- data/spec/units/partials_manager_spec.rb +561 -251
- data/spec/units/plugins/bullseye_spec.rb +49 -2
- data/spec/units/plugins/console_reportinator_spec.rb +73 -26
- data/spec/units/plugins/dependencies_spec.rb +33 -7
- data/spec/units/plugins/dependency_spec_spec.rb +17 -0
- data/spec/units/plugins/gcov_spec.rb +28 -3
- data/spec/units/plugins/gcovr_reportinator_spec.rb +19 -47
- data/spec/units/plugins/gcovr_thresholds_spec.rb +95 -0
- data/spec/units/plugins/module_generator_spec.rb +5 -5
- data/spec/units/plugins/report_build_warnings_log_spec.rb +3 -3
- data/spec/units/plugins/report_log_writer_plugin_spec.rb +10 -1
- data/spec/units/plugins/report_tests_raw_output_log_spec.rb +13 -2
- data/spec/units/plugins/report_tests_teamcity_stdout_spec.rb +77 -3
- data/spec/units/plugins/reportgenerator_reportinator_spec.rb +52 -4
- data/spec/units/plugins/sanitize_records_spec.rb +3 -1
- data/spec/units/plugins/sanitize_spec.rb +1 -1
- data/spec/units/plugins/valgrind_spec.rb +23 -8
- data/spec/units/preprocess/preprocessinator_code_finder_spec.rb +73 -10
- data/spec/units/preprocess/preprocessinator_comment_stripper_spec.rb +1 -1
- data/spec/units/preprocess/preprocessinator_file_assembler_spec.rb +125 -37
- data/spec/units/preprocess/preprocessinator_includes_handler_spec.rb +15 -0
- data/spec/units/preprocess/preprocessinator_reconstructor_spec.rb +197 -0
- data/spec/units/preprocess/preprocessinator_spec.rb +153 -95
- data/spec/units/rake_app/rakefile_component_resolver_spec.rb +21 -0
- data/spec/units/release_build_executor_spec.rb +53 -14
- data/spec/units/release_build_planner_spec.rb +15 -3
- data/spec/units/reportinator_spec.rb +5 -5
- data/spec/units/setupinator_spec.rb +51 -0
- data/spec/units/standin_headerinator_spec.rb +55 -9
- data/spec/units/test_build_executor_spec.rb +842 -166
- data/spec/units/test_build_planner_spec.rb +205 -15
- data/spec/units/test_build_setup_spec.rb +179 -30
- data/spec/units/test_context_extractor_spec.rb +36 -2
- data/spec/units/test_derived_search_paths_spec.rb +259 -0
- data/spec/units/test_file_preprocessinator_spec.rb +17 -1
- data/spec/units/test_includes_extractinator_spec.rb +61 -9
- data/spec/units/test_invoker/objects_wiring_spec.rb +24 -4
- data/spec/units/test_invoker/partial_files_preprocessinator_spec.rb +264 -0
- data/spec/units/test_invoker/test_substitutions_spec.rb +122 -0
- data/spec/units/test_invoker_spec.rb +14 -1
- data/spec/units/test_invoker_types_spec.rb +8 -7
- data/spec/units/test_pipeline_manager_spec.rb +54 -13
- data/spec/units/test_runner_generatinator_spec.rb +93 -1
- data/spec/units/test_search_paths_spec.rb +73 -5
- data/spec/units/test_source_file_directive_resolver_spec.rb +38 -7
- data/spec/units/tools/default_tools_quoting_spec.rb +117 -0
- data/spec/units/tools/shell_quoting_spec.rb +76 -0
- data/spec/units/{tool_executor_helper_spec.rb → tools/tool_executor_helper_spec.rb} +1 -1
- data/spec/units/{tool_executor_spec.rb → tools/tool_executor_spec.rb} +27 -1
- data/spec/units/{tool_validator_spec.rb → tools/tool_validator_spec.rb} +110 -1
- data/spec/units/windows_registry_query_tool_spec.rb +53 -0
- data/spec/units/yaml_wrapper_spec.rb +11 -0
- metadata +265 -36
- data/lib/ceedling/file_finder_helper.rb +0 -127
- data/lib/ceedling/file_path_collection_utils.rb +0 -164
- data/spec/units/file_finder_spec.rb +0 -495
- /data/lib/ceedling/{tool_executor_helper.rb → tools/tool_executor_helper.rb} +0 -0
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
# Path Handling
|
|
2
|
+
|
|
3
|
+
Ceedling spells every path one way, compares places by whole directories, and places every build file by its source's path from the project root. Three guarantees follow. No build file lands outside the build root. No two inputs share one build file. A build file's own path leads back to exactly one input.
|
|
4
|
+
|
|
5
|
+
This document is for developers and coding agents changing code that reads, compares, collects, or places paths. It begins with orientation and ends with detail. The orientation explains why paths need one spelling, the rules that govern them, the modules involved, and the invariants a change must keep. The later sections trace each rule to its methods, data structures, and specs.
|
|
6
|
+
|
|
7
|
+
## Orientation
|
|
8
|
+
|
|
9
|
+
### Why paths need one spelling
|
|
10
|
+
|
|
11
|
+
A project names one place in many spellings. A `:paths` entry may read `src/**`, `./src/**`, `../app/src/**`, `~/sdk/include`, `C:\Keil_v5\Include`, or a path through a symlink. Collection returns files relative to the working directory. Some lookups use absolute paths.
|
|
12
|
+
|
|
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
|
+
|
|
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
|
+
|
|
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.
|
|
18
|
+
|
|
19
|
+
### The rules
|
|
20
|
+
|
|
21
|
+
Five rules govern path handling. Each later section expands one of them.
|
|
22
|
+
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
28
|
+
|
|
29
|
+
### The project root
|
|
30
|
+
|
|
31
|
+
The project root is the working directory. It is where `ceedling` runs, and every relative path in configuration resolves against it. Mixins also search the project file's directory, but resolved paths are still relative to the working directory. `ProjectPaths.working_dir` is that directory with its symlinks resolved.
|
|
32
|
+
|
|
33
|
+
`WorkingDir` reads the working directory once and remembers it. A build resolves paths against it tens of thousands of times, and each read from the operating system costs tens of microseconds on macOS. Ceedling code changes directory only through `WorkingDir.chdir`, which forgets the remembered directory as it enters its block and again as it leaves. Paths resolved inside the block resolve against the new directory, and paths resolved after it against the old one. The Dependencies plugin's commands and `FileSystemWrapper#cd` go through it. A plain `Dir.chdir` leaves the remembered directory unchanged. The spec suite's `spec/support/working_dir_tracking.rb` forgets it on every `Dir.chdir`, because specs change directory in-process.
|
|
34
|
+
|
|
35
|
+
### Code organization
|
|
36
|
+
|
|
37
|
+
The path modules sit in `lib/ceedling/filesystem/`, whose [README](README.md) lists every file there. Most are pure module functions with no DIY dependency, so the launcher in `bin/` can use them too. Paths below are relative to that directory.
|
|
38
|
+
|
|
39
|
+
| File | Module or class | Role |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| `project_paths.rb` | `ProjectPaths` | Spelling, absolute and relative forms, containment |
|
|
42
|
+
| `working_dir.rb` | `WorkingDir` | The working directory, read once, and the one way to change it |
|
|
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 |
|
|
45
|
+
| `path_spellings.rb` | `PathSpellings` | A place's listed and real spellings, and distances between places |
|
|
46
|
+
| `path_exclusions.rb` | `PathExclusions` | The three kinds of exclusion collection applies |
|
|
47
|
+
| `path_mirror.rb` | `PathMirror` | A file's subdirectory below the most specific containing root |
|
|
48
|
+
| `path_matcher.rb` | `PathMatcher` | Resolving `..` in a query, and matching trailing segments |
|
|
49
|
+
| `destination_collision.rb` | `DestinationCollision` | Stopping a build when two inputs map to one output |
|
|
50
|
+
| `file_path_collection_utils.rb` | `FilePathCollectionUtils` | Collecting `:paths` directories and `:files` revisions |
|
|
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 |
|
|
53
|
+
| `file_finder.rb` | `FileFinder` | Finding a build file's input from the build file's path |
|
|
54
|
+
| `../config/build_root_policy.rb` | `BuildRootPolicy` | What a build root may be, and what Ceedling creates in it |
|
|
55
|
+
| `../config/configurator_builder.rb` | `ConfiguratorBuilder` | Building collections with the exclusions applied |
|
|
56
|
+
| `../test_invoker/mock_locator.rb` | `MockLocator` | Where a mock is generated and how its test reaches it |
|
|
57
|
+
|
|
58
|
+
### Invariants
|
|
59
|
+
|
|
60
|
+
Every change to path code must keep these invariants. Specs pin each one.
|
|
61
|
+
|
|
62
|
+
- A build file lies below the build root. No subpath holds `..` or begins at a filesystem root.
|
|
63
|
+
- Two distinct inputs never share one output. `DestinationCollision` stops the build when they would.
|
|
64
|
+
- `BuildSubpath.decode( BuildSubpath.encode( dir, roots: t ), roots: t )` returns `dir` in intake's spelling, for any table `t`, including none.
|
|
65
|
+
- A collection holds each place once, however many entries or spellings reach it.
|
|
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.
|
|
68
|
+
- Comparison folds case on Windows only. Stored spellings never change case.
|
|
69
|
+
|
|
70
|
+
## Spelling paths: `ProjectPaths`
|
|
71
|
+
|
|
72
|
+
`ProjectPaths` gives every path one spelling and answers containment between spellings. Its functions are pure over strings except where noted. The ones that read the disk say so.
|
|
73
|
+
|
|
74
|
+
### Functions
|
|
75
|
+
|
|
76
|
+
| Function | Result | Reads disk |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `working_dir` | `Dir.pwd` with symlinks resolved, remembered by `WorkingDir` | Once |
|
|
79
|
+
| `standardize(path)` | Trimmed, `/`-separated, no trailing separator, `~` expanded, `+:`/`-:` decorator kept | No |
|
|
80
|
+
| `absolute(path)` | Absolute, with `.` and `..` resolved against `working_dir`, drive letter upper case | No |
|
|
81
|
+
| `real_absolute(path)` | `absolute` with the symlinks of its longest existing prefix resolved | Yes |
|
|
82
|
+
| `canonical(path)` | `relative( real_absolute( path ) )`, the intake spelling | Yes |
|
|
83
|
+
| `relative(absolute)` | Relative to `working_dir`, `.` for the directory itself, absolute when no relative form exists | No |
|
|
84
|
+
| `contains?(root, path)` | Whether `path` is `root` or lies below it | No |
|
|
85
|
+
| `subdir_below(root, path)` | The directories from `root` down to `path`, `''` for `root` itself, nil for outside | No |
|
|
86
|
+
| `segments(path)` | Segments split on either separator, `.` and empty segments dropped | No |
|
|
87
|
+
| `same?(a, b)`, `starts_with?(path, prefix)` | Text comparison that folds case on Windows | No |
|
|
88
|
+
|
|
89
|
+
### Standardizing
|
|
90
|
+
|
|
91
|
+
`standardize` is the first step for any path read from configuration or the command line. It trims whitespace and converts backslashes. It drops trailing separators but keeps a bare root such as `/` or `C:/`. It expands `~` and `~/…` to `Dir.home`, also after a `+:` or `-:` decorator. A `~user` path stays literal and names a directory called `~user`. `FilePathUtils.standardize_in_place` applies it across configuration. `bin/path_validator.rb` applies it in the launcher.
|
|
92
|
+
|
|
93
|
+
### Absolute form and its memo
|
|
94
|
+
|
|
95
|
+
`absolute` resolves a path without touching the disk. A path that is already clean and absolute returns unchanged through `clean_absolute?`. Any other result is memoized per `[working_dir, Dir.home, path]` and frozen. A build asks for the same few roots thousands of times, so the memo keeps placement and lookup cheap. A `~user` path is prefixed with `./` before `File.expand_path`, so Ruby never reads it as a user's home.
|
|
96
|
+
|
|
97
|
+
### Canonical form
|
|
98
|
+
|
|
99
|
+
`canonical` is the spelling intake records. It resolves symlinks only along the longest existing prefix, through the private `real`. A path that does not exist yet keeps its missing tail as written. Collection resolves each entry's base this way. It never resolves every directory a glob yields, since an `#include` reaches a directory by its listed spelling.
|
|
100
|
+
|
|
101
|
+
### Containment
|
|
102
|
+
|
|
103
|
+
`subdir_below` compares absolute forms at a `/` boundary. `src` therefore never contains `src2`. The subdirectory it returns never holds `..` and is never absolute. `PathMirror.containing_subdir` builds on it and picks the shortest subdirectory, which is the most specific containing root.
|
|
104
|
+
|
|
105
|
+
## Placing build files: `BuildSubpath`
|
|
106
|
+
|
|
107
|
+
`BuildSubpath` turns a source's directory into the subpath its build files take below a build output root. The subpath is the directory's path from the project root, rewritten so it never climbs and never goes absolute.
|
|
108
|
+
|
|
109
|
+
### Markers
|
|
110
|
+
|
|
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.
|
|
112
|
+
|
|
113
|
+
| Marker | Stands for | Example directory | Encoded subpath |
|
|
114
|
+
| --- | --- | --- | --- |
|
|
115
|
+
| none | A directory inside the project | `src/drv` | `src/drv` |
|
|
116
|
+
| `_up_` | One `..` segment | `../shared/src` | `_up_/shared/src` |
|
|
117
|
+
| `_abs_` | A path with no relative form, on another Windows drive | `D:/sdk/inc` | `_abs_/D/sdk/inc` |
|
|
118
|
+
| `_unc_` | A Windows UNC share | `//server/share/inc` | `_unc_/server/share/inc` |
|
|
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_` |
|
|
122
|
+
|
|
123
|
+
The project root itself encodes as `''`. Its files sit directly below the output root.
|
|
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
|
+
|
|
139
|
+
### Choosing a marker
|
|
140
|
+
|
|
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.
|
|
142
|
+
|
|
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.
|
|
144
|
+
|
|
145
|
+
### Escaping a marker-named directory
|
|
146
|
+
|
|
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.
|
|
157
|
+
|
|
158
|
+
### Decoding
|
|
159
|
+
|
|
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.
|
|
161
|
+
|
|
162
|
+
### Memo
|
|
163
|
+
|
|
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.
|
|
165
|
+
|
|
166
|
+
## Placement rules: `FilePathUtils`
|
|
167
|
+
|
|
168
|
+
`FilePathUtils#form_build_subpath(file, generated_roots:)` is the one placement rule. Every object, preprocessed file, dependencies file, and list file takes its subpath from it.
|
|
169
|
+
|
|
170
|
+
### The rule
|
|
171
|
+
|
|
172
|
+
The rule has three cases, tried in order.
|
|
173
|
+
|
|
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.
|
|
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.
|
|
176
|
+
3. Any other file lands at `BuildSubpath.of_directory( File.dirname( file ), roots: build_roots )`.
|
|
177
|
+
|
|
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`.
|
|
179
|
+
|
|
180
|
+
### Forming paths
|
|
181
|
+
|
|
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.
|
|
183
|
+
|
|
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."
|
|
185
|
+
|
|
186
|
+
These callers use the rule.
|
|
187
|
+
|
|
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.
|
|
189
|
+
- `form_release_build_objects_filelist` and `form_release_dependencies_filelist` place release objects and their `.d` files.
|
|
190
|
+
- `form_release_dependencies_filepath` mirrors a release object's own subpath below the release dependencies directory.
|
|
191
|
+
- `preprocessed_file_subpath` places preprocessed headers and sources below each test's preprocessing directories.
|
|
192
|
+
- The gcov and Bullseye plugins call `form_test_object_filepath` with their own context. Their untested sources land below `build/<plugin>/out/` by the same rule.
|
|
193
|
+
|
|
194
|
+
### Test names
|
|
195
|
+
|
|
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.
|
|
216
|
+
|
|
217
|
+
### The Dependencies plugin
|
|
218
|
+
|
|
219
|
+
The Dependencies plugin places objects by a different root. `Dependencies#prepared_object` takes the source's subdirectory below the dependency's own `:source` path through `ProjectPaths.subdir_below`. A dependency builds from its own tree, so its project root is that tree.
|
|
220
|
+
|
|
221
|
+
## Mocks: `MockLocator`
|
|
222
|
+
|
|
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.
|
|
224
|
+
|
|
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.
|
|
226
|
+
|
|
227
|
+
`MockLocator#placement(mocks_root:, subdir:, include_path:)` returns a `MockPlacement` struct with four fields.
|
|
228
|
+
|
|
229
|
+
- `folder` is the `#include` text's directory when `:cmock` ↳ `:mock_name_include_folder` is on, otherwise nil.
|
|
230
|
+
- `directory` is where the mock's files are generated.
|
|
231
|
+
- `root` is the mock path CMock is configured with. CMock writes the mock at `folder` below it, which leads to `directory`.
|
|
232
|
+
- `reach` is the search path from which the test's `#include` text reaches `directory`.
|
|
233
|
+
|
|
234
|
+
An `#include` folder that climbs with `..` needs one more step. `written_spot` places the mock below `mocks_root/_up_/…` and sets `reach` to an anchor of `_up_` segments. The `#include` then climbs from that anchor back down to the mock, and the mock never leaves the test's mock directory. `MockLocator#search_directories` gives the test `[directory, reach].uniq` as search paths. `StandinHeaderinator` creates `reach` when it lies outside `directory`.
|
|
235
|
+
|
|
236
|
+
## Finding inputs from build files: `FileFinder`
|
|
237
|
+
|
|
238
|
+
A lookup from a build file inverts placement exactly. It finds the input by path before it matches by name, so a same-named file elsewhere never interferes.
|
|
239
|
+
|
|
240
|
+
`mirrored_query(filepath, release:, test:, context:)` turns an object path into a source query.
|
|
241
|
+
|
|
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.
|
|
243
|
+
2. Inside the build root, `placement_root` names the release output root or the test's build path.
|
|
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.
|
|
245
|
+
|
|
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.
|
|
247
|
+
|
|
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.
|
|
251
|
+
|
|
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.
|
|
253
|
+
|
|
254
|
+
## Collecting paths: `FilePathCollectionUtils`
|
|
255
|
+
|
|
256
|
+
Collection turns `:paths` entries into directories and `:files` revisions into files. Each place is collected once and spelled through its entry's real base. Exclusions are judged by distance between places, never by text.
|
|
257
|
+
|
|
258
|
+
### Spellings and distance
|
|
259
|
+
|
|
260
|
+
`PathSpellings` holds the tools collection compares with. `PathSpellings.of(paths)` is the Set of both spellings of each path, absolute and real, as compared. `PathSpellings.key` folds case on Windows only. `PathSpellings.through_real(paths, base)` respells paths found below `base` through `base`'s real path, so a project reached through a symlink never collects one directory twice. `PathSpellings.nearer(spellings, spelled)` walks up from a place and counts the steps to the nearest place in `spelled`. It returns 0 for the place itself and infinity for none.
|
|
261
|
+
|
|
262
|
+
### Directories from `:paths`
|
|
263
|
+
|
|
264
|
+
`collect_paths(paths, exclude:, reserved:)` collects directories in three steps.
|
|
265
|
+
|
|
266
|
+
1. `named_directories` lists every directory each additive entry names. `entry_directories` globs the entry, adds Ceedling's parent directories for a `/**` or `/*` tail, and respells the results through the entry's real base. A bracket in a path is literal, never glob syntax.
|
|
267
|
+
2. Each directory becomes a `Named` struct of `spelled`, `spellings`, and `distance`. `distance` is how far below the nearest base of the entries naming it the directory lies. A directory reached by two entries keeps its first spelling and its smallest distance.
|
|
268
|
+
3. A `PathExclusions` decides which directories stay. The kept ones return relative to the working directory.
|
|
269
|
+
|
|
270
|
+
### The three exclusions
|
|
271
|
+
|
|
272
|
+
`PathExclusions` is a Struct of three spelling sets, built by `PathExclusions.of(minus, excluded, reserved)`. `keeps?(spellings, distance)` keeps a place only if all three tests pass.
|
|
273
|
+
|
|
274
|
+
| Set | Source | A place stays when |
|
|
275
|
+
| --- | --- | --- |
|
|
276
|
+
| `minus` | `-:` entries | It lies strictly nearer its entry's base than any `-:` place above it |
|
|
277
|
+
| `excluded` | The build root | It lies no farther from its entry's base than the build root above it |
|
|
278
|
+
| `reserved` | `BuildRootPolicy.reserved` | No reserved directory lies at or above it |
|
|
279
|
+
|
|
280
|
+
The `minus` rule lets `+:src/legacy/keep` survive beside `-:src/legacy`, because its own entry names it more closely. The `excluded` rule lets `../**` or `./**` sweep the project without reaching into `build/`. An entry based at or below the build root, such as `build/gen/**`, still collects there. The `reserved` rule has no override, so no entry collects Ceedling's own output.
|
|
281
|
+
|
|
282
|
+
### Files from `:files`
|
|
283
|
+
|
|
284
|
+
`revise_filelist(list, revisions, exclude:, reserved:)` adds and removes files. `revision_files` globs each revision and respells it through its real base. `added_files` keeps an additive revision's file only if `PathExclusions#keeps?` passes. The distance is measured from the revision's own base, so `+:**/*.c` adds nothing from `build/`, and `+:build/gen/*.c` adds what it names. `kept_files` then drops duplicates and subtracted files by `real_key`, which compares a file through its directory's real path. The result is a literal FileList, so no entry is read as a glob again.
|
|
285
|
+
|
|
286
|
+
### Mirror roots
|
|
287
|
+
|
|
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).
|
|
289
|
+
|
|
290
|
+
## The build root: `BuildRootPolicy`
|
|
291
|
+
|
|
292
|
+
`BuildRootPolicy` says what a build root may be and what in it collection must never return. `clobber` empties the directories Ceedling creates there, so the policy protects the project from them.
|
|
293
|
+
|
|
294
|
+
- `problem(root)` refuses an empty build root, the project directory, or any directory above it. It compares canonical spellings, so a symlinked spelling of the project is refused too. `ConfiguratorPathsValidator#validate_build_root` logs `message(root, problem)` as an error.
|
|
295
|
+
- `entries_within(root, config)` lists each additive `:paths` and `:files` entry whose base lies in the build root. `warnings` turns each into a COMPLAIN message. Such entries collect, but the warning names them.
|
|
296
|
+
- `reserved(config)` lists the directories Ceedling creates. It reads the settings in `CREATED`: the artifacts, test, release, vendor, and cache directories, the log path, and the mock path. It adds `<build_root>/<plugin>` for each enabled plugin. An empty setting names nothing, so the project directory is never reserved by accident.
|
|
297
|
+
|
|
298
|
+
`ConfiguratorBuilder#build_exclusions` passes the build root as `exclude:` and `reserved` as `reserved:` to every `:paths` collection and every `:files` revision. `ConfiguratorBuilder#without_tests` then removes test files from the source collection after revisions, with a warning. It removes them from the release build input without a second warning.
|
|
299
|
+
|
|
300
|
+
A `-:` entry that matches nothing is never an error. `ConfiguratorPathsValidator#subtracts_nothing` warns of one outside the build root and stays silent below it. Below the build root nothing exists before a first build.
|
|
301
|
+
|
|
302
|
+
## Other intake points
|
|
303
|
+
|
|
304
|
+
Several settings reach paths outside `:paths` and `:files`. Each spells its paths through `ProjectPaths` at intake.
|
|
305
|
+
|
|
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.
|
|
307
|
+
- `LibraryResolver#search_directories` collects `:paths` ↳ `:libraries` through `collect_paths` and memoizes the result. `search_path_arguments` forms the `-L` arguments from it.
|
|
308
|
+
- `ConfiguratorBuilder#set_release_target` standardizes `:release_build` ↳ `:output`. An absolute output names the artifact itself.
|
|
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.
|
|
310
|
+
- `RakefileComponentResolver.prepare_plugin_load_paths` standardizes `:plugins` ↳ `:load_paths` with the same expander `lib/` uses.
|
|
311
|
+
- `DependencySpec` in the Dependencies plugin standardizes each dependency's paths.
|
|
312
|
+
- `Setupinator` runs `Configurator#populate_cmock_helpers` after `standardize_paths`, so the Unity helper paths are already standardized.
|
|
313
|
+
|
|
314
|
+
## Platform differences
|
|
315
|
+
|
|
316
|
+
Paths behave differently on Windows, macOS, and other POSIX systems. The code handles each difference in one place. `ProjectPaths::WINDOWS` selects the Windows behavior from `RbConfig::CONFIG['host_os']`.
|
|
317
|
+
|
|
318
|
+
### Windows
|
|
319
|
+
|
|
320
|
+
- **Case.** Comparison folds case through `same?`, `starts_with?`, `PathSpellings.key`, and `IncludePathinator#rank_key`. Stored spellings keep their case.
|
|
321
|
+
- **Drive letters.** `absolute` upper-cases the drive letter. `ROOTED` requires one for a clean absolute path.
|
|
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>/…`.
|
|
323
|
+
- **UNC shares.** `unc?` is true only on Windows. `unc_absolute` resolves `..` but never climbs above `//server/share`. A share encodes under `_unc_`.
|
|
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`.
|
|
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.
|
|
329
|
+
- **Real-path casing.** Intake takes a path's on-disk casing from `File.realpath`, along the existing part of the path.
|
|
330
|
+
|
|
331
|
+
### macOS
|
|
332
|
+
|
|
333
|
+
- **Symlinked temporary directories.** `/tmp` and `/var` are symlinks into `/private`. `working_dir` and `canonical` resolve them, so `/tmp/proj` and `/private/tmp/proj` compare as one place.
|
|
334
|
+
- **Case-insensitive volumes.** APFS and HFS+ usually ignore case, but Ceedling compares case exactly outside Windows. Two spellings that differ only by case count as two places. `MARKER_NAMED` ignores case so that `_UP_` is still escaped.
|
|
335
|
+
|
|
336
|
+
### Linux and other POSIX systems
|
|
337
|
+
|
|
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.
|
|
339
|
+
- **Doubled separators.** A leading `//` is the filesystem root, not a share. `absolute` squeezes it to `/`.
|
|
340
|
+
|
|
341
|
+
## Changing path code
|
|
342
|
+
|
|
343
|
+
A change to path code keeps the invariants by following the patterns above. These checks catch the usual mistakes.
|
|
344
|
+
|
|
345
|
+
- Compare places with `ProjectPaths.contains?` or `subdir_below`. Never compare path text with `start_with?` or `include?`.
|
|
346
|
+
- Spell configured paths with `standardize` at intake and `canonical` where a symlinked spelling matters.
|
|
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`.
|
|
349
|
+
- Run a new list of outputs through `DestinationCollision`.
|
|
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.
|
|
353
|
+
|
|
354
|
+
## Specs
|
|
355
|
+
|
|
356
|
+
Each tier pins a different layer of this design.
|
|
357
|
+
|
|
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.
|
|
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.
|
|
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.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Files and Paths
|
|
2
|
+
|
|
3
|
+
This directory holds the code that spells, compares, collects, places, and finds paths, and the code that reads, writes, and copies files. Everything else in Ceedling reaches the filesystem through it.
|
|
4
|
+
|
|
5
|
+
The pure modules depend on no DIY object or configuration, so the launcher in `bin/` uses them too. The DIY objects are built from `lib/ceedling/objects.yml`, and the launcher builds `FileWrapper` from `bin/objects.yml`. Code requires any file here as `ceedling/filesystem/<name>`. Unit specs mirror this directory in `spec/units/filesystem/`.
|
|
6
|
+
|
|
7
|
+
Two design documents sit beside the code. [PATH_HANDLING.md](PATH_HANDLING.md) covers path spelling, containment, and build file placement. [FILE_TREE.md](FILE_TREE.md) covers walking and copying file trees without `lstat`.
|
|
8
|
+
|
|
9
|
+
## Path spelling and placement
|
|
10
|
+
|
|
11
|
+
Pure modules with no state beyond memos.
|
|
12
|
+
|
|
13
|
+
| File | Module | Role |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| [`project_paths.rb`](project_paths.rb) | `ProjectPaths` | One spelling for every path. Absolute, relative, and canonical forms, and containment by whole directories |
|
|
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. 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 |
|
|
19
|
+
| [`path_spellings.rb`](path_spellings.rb) | `PathSpellings` | A place's listed and real spellings, and how far one place lies below another |
|
|
20
|
+
| [`path_exclusions.rb`](path_exclusions.rb) | `PathExclusions` | What collection leaves out: `-:` entries, excluded places, and reserved places |
|
|
21
|
+
| [`path_mirror.rb`](path_mirror.rb) | `PathMirror` | A file's subdirectory below the most specific configured root that contains it |
|
|
22
|
+
| [`path_matcher.rb`](path_matcher.rb) | `PathMatcher` | Resolving `..` in a query, and matching a query's trailing segments against a collection |
|
|
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 |
|
|
26
|
+
|
|
27
|
+
## Path services
|
|
28
|
+
|
|
29
|
+
DIY objects that apply the modules above to a project's configuration.
|
|
30
|
+
|
|
31
|
+
| File | Class | Role |
|
|
32
|
+
| --- | --- | --- |
|
|
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 |
|
|
35
|
+
| [`file_path_collection_utils.rb`](file_path_collection_utils.rb) | `FilePathCollectionUtils` | Collecting `:paths` directories and `:files` revisions, with exclusions applied |
|
|
36
|
+
| [`file_finder.rb`](file_finder.rb) | `FileFinder` | Finding a build file's input from the build file's own path |
|
|
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 |
|
|
39
|
+
|
|
40
|
+
## File I/O
|
|
41
|
+
|
|
42
|
+
| File | Module or class | Role |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| [`file_wrapper.rb`](file_wrapper.rb) | `FileWrapper` | The DIY object most code uses to read, write, list, and copy files. It checks path lengths, retries transient I/O errors, and replaces files whole; this class is mocked for unit testing against |
|
|
45
|
+
| [`file_tree.rb`](file_tree.rb) | `FileTree` | A pure module that walks a tree classifying entries by `stat`, and brings a copy up to date, replacing entries of the wrong type. See [FILE_TREE.md](FILE_TREE.md) |
|
|
46
|
+
| [`file_system_wrapper.rb`](file_system_wrapper.rb) | `FileSystemWrapper` | Changing the working directory for the length of a block, through `WorkingDir` |
|
|
@@ -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
|