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,142 @@
|
|
|
1
|
+
# The Build Step Doctor
|
|
2
|
+
|
|
3
|
+
The build step doctor explains a failed build step to the test developer. When a test's compilation or linking fails, the doctor reads the tool's output and the inputs it ran with, recognizes failures with a known cause, and logs guidance beside the tool's own error. The error is still raised, so the guidance only adds to it.
|
|
4
|
+
|
|
5
|
+
## Why it exists
|
|
6
|
+
|
|
7
|
+
Some toolchain errors have causes that only Ceedling's conventions explain. A redeclaration error can mean a mocked header's real content reached the compilation a second way. A missing symbol most often means a test's `#include` directives left out a source it needs. A duplicate symbol can mean a mock was linked beside the source it stands in for. An `#include` nested too deeply most often means a header that includes its own filename found itself first. The raw error names none of this. A developer reading only the compiler's words may spend a long time finding a cause Ceedling could have pointed to.
|
|
8
|
+
|
|
9
|
+
Each kind of guidance follows the same pattern:
|
|
10
|
+
|
|
11
|
+
1. **Match the output.** The failed step's output shows a known error, in any of the wordings different toolchains use.
|
|
12
|
+
2. **Examine the case.** The step's inputs, such as the test's mocks, its search paths, the headers its `.d` file lists, or the objects it linked, confirm the cause applies. Each case that applies writes its own guidance, so one failure can draw several.
|
|
13
|
+
|
|
14
|
+
The doctor holds that pattern once. Each kind of guidance is a small diagnosis written against it.
|
|
15
|
+
|
|
16
|
+
## The mechanism
|
|
17
|
+
|
|
18
|
+
`BuildStepDoctor` (`build_step_doctor.rb`) is the engine. It knows nothing about Ceedling. Specialists hold the knowledge, and the doctor gathers their diagnoses once, in `setup`.
|
|
19
|
+
|
|
20
|
+
- **`Diagnosis`** is a struct a specialist builds. It has a `name`, the `steps` it covers (`:preprocess`, `:compile`, `:link`), the `outcomes` it covers (`:failure` by default, or `:warning`), its `symptoms`, and its `examination`.
|
|
21
|
+
- **Symptoms** are a Regexp, or an Array of them with one per toolchain family. Any match makes the case a candidate.
|
|
22
|
+
- **The examination** is a callable that takes a `Case` and returns a prescription (a String), several (an Array), or nil when the case turns out not to be its own.
|
|
23
|
+
- **`Case`** holds the `step`, the `outcome`, the tool's `output`, the `symptoms` MatchData, and the step's `inputs` Hash.
|
|
24
|
+
- **`BuildStepDoctor#diagnose(step:, output:, inputs:, outcome: :failure)`** runs every diagnosis whose steps, outcomes, and symptoms fit, in the order the specialists were composed. It logs each prescription at `Verbosity::ERRORS` with `LogLabels::NOTICE`, and returns them.
|
|
25
|
+
- **`BuildStepDoctor#attend(step:, inputs:) { … }`** runs a step's block. A `ShellException` the block raises goes to `diagnose` with the tool's output, and is then raised again.
|
|
26
|
+
|
|
27
|
+
An examination that raises is a bug in guidance, never a reason to hide a build's real failure. The doctor logs the error at DEBUG and runs the remaining diagnoses. A step or outcome the doctor doesn't know raises `ArgumentError`, at `setup` or at `diagnose`, so a typo can't silently disable a diagnosis.
|
|
28
|
+
|
|
29
|
+
`ToolchainOutput` (`toolchain_output.rb`) reads the header and object paths an output mentions. A path is any token ending in a wanted extension, quoted or not, so one reader serves every location format below. A stray match is harmless, because each specialist compares paths against files it already knows.
|
|
30
|
+
|
|
31
|
+
### Specialists
|
|
32
|
+
|
|
33
|
+
| Specialist | Step | Diagnoses |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| `HeaderCollisionSpecialist` | compilation | `:substituted_header_collision`: a header the test mocks or Partializes collides with its own real content. `:shared_directory_collision`: a header collides in a directory it shares with other headers, none of them substituted (see `test_invoker/HEADER_COLLISIONS.md`). |
|
|
36
|
+
| `MissingSymbolSpecialist` | linking | `:missing_symbols`: a symbol no linked object defines. |
|
|
37
|
+
| `DuplicateSymbolSpecialist` | linking | `:duplicate_symbols`: a symbol more than one linked object defines. The guidance names a mock linked beside the source it stands in for. |
|
|
38
|
+
| `IncludeDepthSpecialist` | preprocessing, compilation | `:include_nested_too_deeply`: `#include` directives nested past the compiler's limit. The guidance names a header that includes its own filename and reaches itself first. It tells an angled `#include`, which the search path order decides, from a quoted one, which reaches its own directory first whatever that order. |
|
|
39
|
+
| `PartialNameSpecialist` | compilation | `:partial_local_var` and `:partial_type`: a name that `PARTIAL_LOCAL_VAR()`, or `PARTIAL_TYPE()` or `PARTIAL_LOCAL_TYPE()`, builds and nothing declares, in the test file of a build with Partials. The guidance lists the names the test's generated Partial headers provide. |
|
|
40
|
+
|
|
41
|
+
`TestSubstitutions` (`test_invoker/test_substitutions.rb`) answers two questions both sibling-header isolation and the collision diagnoses ask: which real headers a test substitutes, and which directories hold Ceedling's own generated content.
|
|
42
|
+
|
|
43
|
+
### Where the doctor is connected
|
|
44
|
+
|
|
45
|
+
The doctor sees a failure just before it is raised, at four places:
|
|
46
|
+
|
|
47
|
+
- **`TestBuildExecutor#compile_test_component`**, for a C compilation, with `tool`, `source`, `object`, `search_paths`, `flags`, `defines`, `testable`, and `dependencies`. `dependencies` is the first attempt's `.d` file, whose paths are the real headers, even when an isolated retry produced the failure. This site calls `diagnose` itself, after any isolated retry has failed too.
|
|
48
|
+
- **`TestBuildExecutor#generate_executable`**, for a link, with `tool`, `objects`, `executable`, `flags`, `lib_args`, `lib_paths`, and `testable`. The link runs under `attend`.
|
|
49
|
+
- **`PreprocessinatorFileAssembler`'s full expansions of a test file and of a header to be mocked**, with `tool`, `source`, `search_paths`, `flags`, and `defines`. Both run under `attend`. Neither has a fallback, so a failure there ends the build.
|
|
50
|
+
|
|
51
|
+
Compilation and linking failures are where guidance helps a test developer most. Ceedling runs the preprocessor many times per test. Most of those runs are expected to fail at times and fall back by design, so they aren't connected. A misplaced prescription there would only add noise. The full expansions of a test file and of a header to be mocked are the exception, since their failure stops the build. Assembly and release builds aren't connected either. The engine accepts a `:warning` outcome, so connecting more needs only a call site.
|
|
52
|
+
|
|
53
|
+
### Sharing the doctor without a lock
|
|
54
|
+
|
|
55
|
+
Every compilation thread in a test build shares one doctor. That needs no lock, because the doctor fixes its diagnoses in `setup` and `diagnose` only reads them. Specialists keep no state between examinations either. Adding a diagnosis after `setup`, or giving a specialist mutable state, would break this guarantee.
|
|
56
|
+
|
|
57
|
+
The doctor composes its specialists, rather than each specialist registering itself, because DIY builds an object only when something references it.
|
|
58
|
+
|
|
59
|
+
## Adding a diagnosis
|
|
60
|
+
|
|
61
|
+
1. Add a `Diagnosis` to an existing specialist's `diagnoses`, or write a new specialist and compose it into `build_step_doctor` in `objects.yml`.
|
|
62
|
+
2. Give it symptoms for each toolchain family you can, ending in a generic net. Err toward matching, since the examination decides whether the case applies.
|
|
63
|
+
3. Write its examination against the `Case` inputs. Return nil when the inputs show the cause doesn't apply.
|
|
64
|
+
4. Write its prescription in the shared shape:
|
|
65
|
+
- a tentative opening, such as "The linker output appears to report…", since no matcher reads every toolchain perfectly;
|
|
66
|
+
- a blank line, then a heading such as `HOW THIS HAPPENS:` over `•` bullets on the C mechanics, mentioning Ceedling only briefly;
|
|
67
|
+
- a blank line, then `OPTIONS:` over a numbered list of ways to resolve the problem;
|
|
68
|
+
- every line left-justified, so a narrow terminal wraps it cleanly. The loginator turns `•` into `*` when decorators are off.
|
|
69
|
+
- adapted to the project, read from the configurator at examination time. A cause tied to a feature, such as mocks, Partials, or test preprocessing, appears only when the project's settings make it possible. A remedy that mocks or Partializes a header appears either way, and names the setting that turns on a disabled feature (`GuidancePhrases`).
|
|
70
|
+
5. Cover it in a unit spec under `spec/units/diagnostics/`, with one case per wording, and in `spec/integration/build_step_doctor_spec.rb` when a real compiler can produce the failure.
|
|
71
|
+
|
|
72
|
+
## Known toolchain wordings
|
|
73
|
+
|
|
74
|
+
Each table lists what the symptoms match, family by family. The evidence column states how each wording is known:
|
|
75
|
+
|
|
76
|
+
- **real toolchain:** produced by a real compiler or linker in `spec/integration/build_step_doctor_spec.rb`, which runs on GCC 14, Apple Clang 15, and CI's compilers;
|
|
77
|
+
- **vendor forums:** quoted from build logs posted in vendor support forums;
|
|
78
|
+
- **expected:** the toolchain's documented message format, not yet observed in this project.
|
|
79
|
+
|
|
80
|
+
### Collisions at compilation
|
|
81
|
+
|
|
82
|
+
| Family | Wordings | Evidence |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| GCC | `redefinition of`, `redeclaration of`, `conflicting types for`, `previous definition of`, `previous declaration of`, `redeclared as different kind of symbol` | real toolchain |
|
|
85
|
+
| Clang, armclang, Microchip XC8 v2 and later | `redefinition of`, `typedef redefinition with different types`, `previous definition is here`, `conflicting types for` | real toolchain (Clang) |
|
|
86
|
+
| IAR | `Error[Pe101]: … has already been declared in the current scope`, `Pe147` `declaration is incompatible with`, `Pe256` `invalid redeclaration of type name` | vendor forums (Pe101), expected (Pe147, Pe256) |
|
|
87
|
+
| Arm armcc | `Error: #101: … has already been declared in the current scope` | vendor forums |
|
|
88
|
+
| TI, Green Hills | `error #101`, `error #147`, `error #256`, with the EDG texts above | expected |
|
|
89
|
+
| MSVC | `C2011` type redefinition, `C2084` function already has a body, `C2370` and `C2371` `redefinition; different` | expected |
|
|
90
|
+
| TASKING, SDCC, others | generic: `redefin`, `redeclar`, `already declared`, `already defined`, `duplicate definition`, `duplicate declaration` | expected |
|
|
91
|
+
|
|
92
|
+
Header paths are read in each location format: `a.h:12:3` (GCC, Clang), `"a.h",12` (IAR), `"a.h", line 12` (Arm armcc, TI, Green Hills), `a.h(12)` (MSVC), and prose such as `declared at line 5 of "a.h"`.
|
|
93
|
+
|
|
94
|
+
### Missing symbols at link time
|
|
95
|
+
|
|
96
|
+
| Family | Wordings | Evidence |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| GNU ld, Microchip XC16 and XC32 | `undefined reference to` | real toolchain (CI's Linux jobs) |
|
|
99
|
+
| Apple ld | `Undefined symbols for architecture`, `symbol(s) not found` | real toolchain |
|
|
100
|
+
| LLD | `undefined symbol:` | expected |
|
|
101
|
+
| MSVC | `LNK2019`, `LNK2001`, `unresolved external symbol` | expected |
|
|
102
|
+
| IAR ILINK | `Error[Li005]: no definition for` | vendor forums |
|
|
103
|
+
| Arm armlink | `Error: L6218E: Undefined symbol` | vendor forums |
|
|
104
|
+
| TI | `undefined first referenced` table header, `unresolved symbols remain` | vendor forums |
|
|
105
|
+
| Green Hills, TASKING, SDCC, others | generic: `undefined global`, `undefined external`, `unresolved external`, `unresolved symbol` | expected |
|
|
106
|
+
|
|
107
|
+
### Duplicate symbols at link time
|
|
108
|
+
|
|
109
|
+
| Family | Wordings | Evidence |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| GNU ld | `multiple definition of`, `first defined here` | real toolchain (CI's Linux jobs) |
|
|
112
|
+
| Apple ld | `duplicate symbol` | real toolchain |
|
|
113
|
+
| LLD | `duplicate symbol:` | expected |
|
|
114
|
+
| MSVC | `LNK2005` `already defined in`, `LNK1169` | expected |
|
|
115
|
+
| IAR ILINK | `Error[Li006]: duplicate definitions for` | vendor forums |
|
|
116
|
+
| Arm armlink | `Error: L6200E: Symbol … multiply defined` | vendor forums |
|
|
117
|
+
| TI | `error #10056: symbol … redefined: first defined in` | vendor forums |
|
|
118
|
+
| Green Hills, TASKING, SDCC, others | generic: `multiple definition`, `multiply defined`, `duplicate symbol`, `duplicate definition`, `already defined` | expected |
|
|
119
|
+
|
|
120
|
+
### Undeclared names at compilation
|
|
121
|
+
|
|
122
|
+
A wording alone matches any undeclared name, so `PartialNameSpecialist` also asks for a name its macros build, `partial_…` or `ceedling_partial_…_t`, or for a note naming one of the macros.
|
|
123
|
+
|
|
124
|
+
| Family | Wordings | Evidence |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| GCC, Microchip XC16 and XC32 | `'x' undeclared (first use in this function)`, `unknown type name` | real toolchain |
|
|
127
|
+
| Clang, armclang, Microchip XC8 v2 and later | `use of undeclared identifier`, `unknown type name` | real toolchain (Clang) |
|
|
128
|
+
| IAR | `Error[Pe020]: identifier "x" is undefined` | expected |
|
|
129
|
+
| Arm armcc, TI, Green Hills | `error #20: identifier "x" is undefined` | expected |
|
|
130
|
+
| MSVC | `C2065` `undeclared identifier`, `C2061`, `C4430`, `C2146` | expected |
|
|
131
|
+
| SDCC | `Undefined identifier` | expected |
|
|
132
|
+
| TASKING, others | generic: `undefined identifier`, `not declared`, `unknown type`, `is not a type` | expected |
|
|
133
|
+
|
|
134
|
+
### Nested includes at preprocessing or compilation
|
|
135
|
+
|
|
136
|
+
| Family | Wordings | Evidence |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| GCC 10 and later | `#include nested depth 200 exceeds maximum of 200`, with the directive quoted as `'#include'` or `‘#include’` in newer releases | real toolchain (GCC 14 unquoted, MSYS2 UCRT GCC quoted) |
|
|
139
|
+
| Clang, armclang, GCC before 10 | `#include nested too deeply` | real toolchain (Clang) |
|
|
140
|
+
| MSVC | `C1014` `too many include files` | expected |
|
|
141
|
+
| IAR, Arm armcc, TI, Green Hills | `#include file … includes itself`, `include file nesting` | expected |
|
|
142
|
+
| TASKING, SDCC, others | generic: `include depth`, `include nesting`, `nested include`, `nested too deep`, `too many include` | expected |
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Diagnostics
|
|
2
|
+
|
|
3
|
+
This directory explains failed build steps to the test developer, from the failed tool's output and the inputs it ran with.
|
|
4
|
+
|
|
5
|
+
- **`DOCTOR.md`** -- why the build step doctor exists, how `BuildStepDoctor`, its specialists, and their diagnoses fit together, how to add a diagnosis, and the toolchain wordings each diagnosis matches.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# =========================================================================
|
|
2
|
+
# Ceedling - Test-Centered Build System for C
|
|
3
|
+
# ThrowTheSwitch.org
|
|
4
|
+
# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
|
|
5
|
+
# SPDX-License-Identifier: MIT
|
|
6
|
+
# =========================================================================
|
|
7
|
+
|
|
8
|
+
require 'ceedling/constants'
|
|
9
|
+
require 'ceedling/exceptions'
|
|
10
|
+
|
|
11
|
+
# Explains a failed build step from its output and inputs (see DOCTOR.md).
|
|
12
|
+
#
|
|
13
|
+
# Specialists teach the doctor diagnoses. A diagnosis names the steps and outcomes it
|
|
14
|
+
# covers, the symptoms its output must show, and an examination that decides whether
|
|
15
|
+
# the case is really its own. Every diagnosis that applies writes a prescription, so
|
|
16
|
+
# one failure can draw several. The doctor logs each at ERRORS as a notice. The failure
|
|
17
|
+
# is still raised, so guidance never takes the place of the tool's own error.
|
|
18
|
+
#
|
|
19
|
+
# The doctor gathers its diagnoses once, in setup, and only reads them afterward. That
|
|
20
|
+
# is what lets every compilation thread share one doctor without a lock. Adding a
|
|
21
|
+
# diagnosis after setup would break it.
|
|
22
|
+
class BuildStepDoctor
|
|
23
|
+
# Build steps a diagnosis may cover. Compilation, linking, and the full expansions of a test
|
|
24
|
+
# file and of a header to be mocked are connected, since none of them has a fallback. The
|
|
25
|
+
# other preprocessor runs fail by design and fall back, so none of them is.
|
|
26
|
+
STEPS = [:preprocess, :compile, :link].freeze
|
|
27
|
+
OUTCOMES = [:failure, :warning].freeze
|
|
28
|
+
|
|
29
|
+
# What a specialist teaches the doctor. `symptoms` is a Regexp, or several, any of
|
|
30
|
+
# which marks the case as a candidate. `examination` takes a Case and returns a
|
|
31
|
+
# prescription, several, or nil when the case is not this diagnosis's after all.
|
|
32
|
+
Diagnosis = Struct.new( :name, :steps, :outcomes, :symptoms, :examination, keyword_init: true ) do
|
|
33
|
+
def initialize(outcomes: [:failure], **fields)
|
|
34
|
+
super
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# The first symptom match, or nil
|
|
38
|
+
def symptom_in(output)
|
|
39
|
+
Array( symptoms ).each do |symptom|
|
|
40
|
+
match = symptom.match( output )
|
|
41
|
+
return match if match
|
|
42
|
+
end
|
|
43
|
+
nil
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# One failure as the doctor sees it. `symptoms` is the diagnosis's MatchData, and
|
|
48
|
+
# `inputs` holds whatever the step ran with, such as its tool, source, and search paths.
|
|
49
|
+
Case = Struct.new( :step, :outcome, :output, :symptoms, :inputs, keyword_init: true )
|
|
50
|
+
|
|
51
|
+
constructor :loginator, :header_collision_specialist, :missing_symbol_specialist, :duplicate_symbol_specialist, :partial_name_specialist,
|
|
52
|
+
:include_depth_specialist
|
|
53
|
+
|
|
54
|
+
def setup()
|
|
55
|
+
specialists = [
|
|
56
|
+
@header_collision_specialist, @missing_symbol_specialist, @duplicate_symbol_specialist, @partial_name_specialist,
|
|
57
|
+
@include_depth_specialist
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
@diagnoses = specialists.flat_map( &:diagnoses ).freeze
|
|
61
|
+
@diagnoses.each { |diagnosis| check_scope( diagnosis.steps, diagnosis.outcomes, diagnosis.name ) }
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
# Logs every prescription the case draws, and returns them
|
|
65
|
+
def diagnose(step:, output:, inputs:, outcome: :failure)
|
|
66
|
+
check_scope( [step], [outcome], 'diagnosis request' )
|
|
67
|
+
return [] if output.nil?
|
|
68
|
+
|
|
69
|
+
return @diagnoses.flat_map do |diagnosis|
|
|
70
|
+
next [] unless diagnosis.steps.include?( step ) && diagnosis.outcomes.include?( outcome )
|
|
71
|
+
|
|
72
|
+
prescriptions = examine( diagnosis, output: output, step: step, outcome: outcome, inputs: inputs )
|
|
73
|
+
prescriptions.each { |prescription| @loginator.log( prescription, Verbosity::ERRORS, LogLabels::NOTICE ) }
|
|
74
|
+
end
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# Runs a step's block, and diagnoses a tool failure it raises before raising it again. The
|
|
78
|
+
# step is checked first, so a typo can't replace a real failure with its own error.
|
|
79
|
+
def attend(step:, inputs:)
|
|
80
|
+
check_scope( [step], [:failure], 'attend request' )
|
|
81
|
+
|
|
82
|
+
return yield
|
|
83
|
+
rescue ShellException => e
|
|
84
|
+
diagnose( step: step, output: e.shell_result[:output], inputs: inputs )
|
|
85
|
+
raise
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
### Private ###
|
|
89
|
+
|
|
90
|
+
private
|
|
91
|
+
|
|
92
|
+
# An examination that raises is a bug in guidance, never a reason to hide the build's
|
|
93
|
+
# real failure. It is noted for debugging, and the other diagnoses still run.
|
|
94
|
+
def examine(diagnosis, output:, **case_fields)
|
|
95
|
+
match = diagnosis.symptom_in( output )
|
|
96
|
+
return [] if match.nil?
|
|
97
|
+
|
|
98
|
+
return Array( diagnosis.examination.call( Case.new( output: output, symptoms: match, **case_fields ) ) ).compact
|
|
99
|
+
rescue StandardError => e
|
|
100
|
+
@loginator.log( "Diagnosis #{diagnosis.name} failed to examine its case: #{e.class}: #{e.message}", Verbosity::DEBUG )
|
|
101
|
+
return []
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
def check_scope(steps, outcomes, name)
|
|
105
|
+
unknown = (steps - STEPS) + (outcomes - OUTCOMES)
|
|
106
|
+
return if unknown.empty?
|
|
107
|
+
|
|
108
|
+
raise ::ArgumentError, "#{name} names unknown build steps or outcomes: #{unknown.join( ', ' )}"
|
|
109
|
+
end
|
|
110
|
+
end
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# =========================================================================
|
|
2
|
+
# Ceedling - Test-Centered Build System for C
|
|
3
|
+
# ThrowTheSwitch.org
|
|
4
|
+
# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
|
|
5
|
+
# SPDX-License-Identifier: MIT
|
|
6
|
+
# =========================================================================
|
|
7
|
+
|
|
8
|
+
require 'ceedling/diagnostics/build_step_doctor'
|
|
9
|
+
require 'ceedling/diagnostics/toolchain_output'
|
|
10
|
+
require 'ceedling/diagnostics/guidance_phrases'
|
|
11
|
+
|
|
12
|
+
# Explains linker errors for symbols more than one linked object defines.
|
|
13
|
+
#
|
|
14
|
+
# Most duplicates come from C itself: a definition in a header, or a test redefining a
|
|
15
|
+
# function its source under test defines. One comes from Ceedling's conventions: a mock
|
|
16
|
+
# defines every function its header declares, so a test that links a mock beside the
|
|
17
|
+
# source it stands in for defines each of them twice. The pair is named when the linked
|
|
18
|
+
# objects hold one, among the objects the output names if it names any.
|
|
19
|
+
class DuplicateSymbolSpecialist
|
|
20
|
+
|
|
21
|
+
# Each family's wording for a symbol defined twice, ending in a generic net
|
|
22
|
+
DUPLICATE_SYMBOL_SYMPTOMS = [
|
|
23
|
+
# GNU ld
|
|
24
|
+
/multiple definition of|first defined here/i,
|
|
25
|
+
# LLD and Apple ld
|
|
26
|
+
/duplicate symbol/i,
|
|
27
|
+
# MSVC
|
|
28
|
+
/\bLNK(?:2005|1169)\b|already defined in/i,
|
|
29
|
+
# IAR ILINK
|
|
30
|
+
/\bLi006\b|duplicate definitions for/i,
|
|
31
|
+
# Arm armlink
|
|
32
|
+
/\bL6200E\b|multiply defined/i,
|
|
33
|
+
# TI
|
|
34
|
+
/symbol .* redefined|first defined in/i,
|
|
35
|
+
# Green Hills, TASKING, SDCC, and other linkers
|
|
36
|
+
/multipl(?:e|y) defin|duplicate (?:symbol|definition)|already defined/i
|
|
37
|
+
].freeze
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
# Each joins the end of the line before it, when the project uses mocks
|
|
41
|
+
MOCK_CAUSE = "\n• A mock defines every function its header declares; linking a mock and the source it stands in for duplicates them."
|
|
42
|
+
MOCK_OPTION = "\n4. Don't #include both a mock and its real header in one test and don't name a mocked module's source in TEST_SOURCE_FILE()."
|
|
43
|
+
|
|
44
|
+
GUIDANCE = <<~GUIDANCE.freeze
|
|
45
|
+
HOW THIS HAPPENS:
|
|
46
|
+
• A program may define each function and each global variable only once across all its object files.
|
|
47
|
+
• A definition in a header, a function body or a variable without extern, is repeated in every source that #includes the header.
|
|
48
|
+
• A test file that defines a function the source under test also defines places two definitions in one executable.%{mock_cause}
|
|
49
|
+
|
|
50
|
+
OPTIONS:
|
|
51
|
+
1. Declare header variables extern, and define each one in a single source file.
|
|
52
|
+
2. Make functions defined in headers static inline, or move their bodies into one source file.
|
|
53
|
+
3. Remove a test's own definition of a function the linked source already provides, or mock the source's header instead.%{mock_requirement}%{mock_option}
|
|
54
|
+
GUIDANCE
|
|
55
|
+
|
|
56
|
+
constructor :configurator
|
|
57
|
+
|
|
58
|
+
def diagnoses()
|
|
59
|
+
return [
|
|
60
|
+
BuildStepDoctor::Diagnosis.new(
|
|
61
|
+
name: :duplicate_symbols,
|
|
62
|
+
steps: [:link],
|
|
63
|
+
symptoms: DUPLICATE_SYMBOL_SYMPTOMS,
|
|
64
|
+
examination: method( :examine )
|
|
65
|
+
)
|
|
66
|
+
]
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
### Private ###
|
|
70
|
+
|
|
71
|
+
private
|
|
72
|
+
|
|
73
|
+
def examine(kase)
|
|
74
|
+
lead = 'The linker output appears to report a symbol defined more than once.'
|
|
75
|
+
pair = mock_and_source( kase.output, kase.inputs[:objects] || [] )
|
|
76
|
+
lead += " This test links both '#{pair[0]}' and '#{pair[1]}', which may define the same functions." if pair
|
|
77
|
+
|
|
78
|
+
return "#{lead}\n\n#{guidance()}"
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
# Mock causes and remedies appear only as the project's mocking allows
|
|
82
|
+
def guidance()
|
|
83
|
+
mocks = @configurator.project_use_mocks
|
|
84
|
+
|
|
85
|
+
return format( GUIDANCE,
|
|
86
|
+
mock_cause: mocks ? MOCK_CAUSE : '',
|
|
87
|
+
mock_requirement: GuidancePhrases.requirements( mocks: mocks ),
|
|
88
|
+
mock_option: mocks ? MOCK_OPTION : ''
|
|
89
|
+
)
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
# A mock object and its source's object, by basename, or nil
|
|
93
|
+
def mock_and_source(output, objects)
|
|
94
|
+
return nil unless @configurator.project_use_mocks
|
|
95
|
+
|
|
96
|
+
candidates = candidate_objects( output, objects.map { |object| File.basename( object ) } )
|
|
97
|
+
prefix = @configurator.cmock_mock_prefix
|
|
98
|
+
|
|
99
|
+
mock = candidates.find { |object| object.start_with?( prefix ) && candidates.include?( object.delete_prefix( prefix ) ) }
|
|
100
|
+
return mock && [mock, mock.delete_prefix( prefix )]
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
# The linked objects the output names, or every linked object when it names none
|
|
104
|
+
def candidate_objects(output, linked)
|
|
105
|
+
named = ToolchainOutput.objects( output, extension: @configurator.extension_object.primary ).map { |object| File.basename( object ) }
|
|
106
|
+
return (named & linked).then { |both| both.empty? ? linked : both }
|
|
107
|
+
end
|
|
108
|
+
end
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# =========================================================================
|
|
2
|
+
# Ceedling - Test-Centered Build System for C
|
|
3
|
+
# ThrowTheSwitch.org
|
|
4
|
+
# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
|
|
5
|
+
# SPDX-License-Identifier: MIT
|
|
6
|
+
# =========================================================================
|
|
7
|
+
|
|
8
|
+
# Wording the specialists share when a remedy relies on a Ceedling feature.
|
|
9
|
+
#
|
|
10
|
+
# A remedy that mocks or Partializes a header is worth offering even when the project
|
|
11
|
+
# has that feature off, as long as the prescription says which setting turns it on.
|
|
12
|
+
module GuidancePhrases
|
|
13
|
+
MOCKS_SETTING = ':project ↳ :use_mocks'
|
|
14
|
+
PARTIALS_SETTING = ':project ↳ :use_partials'
|
|
15
|
+
|
|
16
|
+
# "Mock or Partialize", followed by `rest`, then a sentence naming any setting the
|
|
17
|
+
# remedy needs that the project has off
|
|
18
|
+
def self.substitute(rest, mocks:, partials:)
|
|
19
|
+
return "Mock or Partialize #{rest}#{requirements( mocks: mocks, partials: partials )}"
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
# Sentences naming the settings that turn on whichever feature is off, or ''
|
|
23
|
+
def self.requirements(mocks:, partials: true)
|
|
24
|
+
needs = []
|
|
25
|
+
needs << "Mocking requires #{MOCKS_SETTING}." unless mocks
|
|
26
|
+
needs << "Partializing requires #{PARTIALS_SETTING}." unless partials
|
|
27
|
+
|
|
28
|
+
return needs.empty? ? '' : " #{needs.join( ' ' )}"
|
|
29
|
+
end
|
|
30
|
+
end
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# =========================================================================
|
|
2
|
+
# Ceedling - Test-Centered Build System for C
|
|
3
|
+
# ThrowTheSwitch.org
|
|
4
|
+
# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
|
|
5
|
+
# SPDX-License-Identifier: MIT
|
|
6
|
+
# =========================================================================
|
|
7
|
+
|
|
8
|
+
require 'ceedling/diagnostics/guidance_phrases'
|
|
9
|
+
|
|
10
|
+
# The education and options that follow each HeaderCollisionSpecialist prescription's
|
|
11
|
+
# lead sentence. Each opens with how C produces the collision, then numbers the ways to
|
|
12
|
+
# resolve it, every line left-justified so a narrow terminal wraps it cleanly. A remedy
|
|
13
|
+
# that mocks or Partializes a header names the setting a disabled feature needs.
|
|
14
|
+
module HeaderCollisionGuidance
|
|
15
|
+
|
|
16
|
+
# Follows the lead of a substituted-header prescription
|
|
17
|
+
SUBSTITUTED_HEADER = <<~GUIDANCE.freeze
|
|
18
|
+
HOW THIS HAPPENS:
|
|
19
|
+
• A %{substitute} replaces a header only where an #include names it and the search paths find the substitute first.
|
|
20
|
+
• A quoted #include looks in the including file's own directory before any search path, so a neighbor of the real header reaches it directly.
|
|
21
|
+
• A substitute is usually a separate file with its own include guard; the guard does not keep the real header out.
|
|
22
|
+
• Ceedling isolates the real header's direct neighbors, one level deep. A chain that passes through further headers or directories is beyond that isolation.
|
|
23
|
+
|
|
24
|
+
OPTIONS:
|
|
25
|
+
1. Trace the #include chain that brings in the real header.
|
|
26
|
+
2. %{substitution}
|
|
27
|
+
3. Change the source's #include so it reaches the header the way the test does.
|
|
28
|
+
GUIDANCE
|
|
29
|
+
|
|
30
|
+
# Follows the lead of a shared-directory prescription
|
|
31
|
+
SHARED_DIRECTORY = <<~GUIDANCE.freeze
|
|
32
|
+
HOW THIS HAPPENS:
|
|
33
|
+
• One translation unit may define a type, a tag, or an enum value only once, and every declaration of a name must agree.
|
|
34
|
+
• An include guard keeps a header out the second time only when both arrivals are the same file. Two copies of a header, or two headers that declare one name, pass every guard.
|
|
35
|
+
• A quoted #include looks in the including file's own directory before any search path. A header there reaches its neighbor directly, whatever order the search paths set.
|
|
36
|
+
• Ceedling isolates a header's neighbors only when the header is mocked or Partialized. No header in this directory is, so no isolation applies here.
|
|
37
|
+
• Isolation reaches only one level: a neighbor that #includes a substituted header directly. A chain that passes through further headers or directories is beyond this isolation.
|
|
38
|
+
|
|
39
|
+
OPTIONS:
|
|
40
|
+
1. Trace the #include chains into this directory to the declaration that arrives twice or to the two declarations that disagree.
|
|
41
|
+
2. %{substitution}
|
|
42
|
+
3. Change the #include or the search path that brings in the second copy.
|
|
43
|
+
4. Add or fix the include guard of a header that arrives twice.
|
|
44
|
+
GUIDANCE
|
|
45
|
+
|
|
46
|
+
# `substitute` is 'mock' or 'Partial', whichever this test made of the header
|
|
47
|
+
def self.substituted_header(substitute:, mocks:, partials:)
|
|
48
|
+
remedy = 'the intermediate header that #includes it, without necessarily using it, to break the chain.'
|
|
49
|
+
return format( SUBSTITUTED_HEADER, substitute: substitute, substitution: GuidancePhrases.substitute( remedy, mocks: mocks, partials: partials ) )
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
def self.shared_directory(mocks:, partials:)
|
|
53
|
+
remedy = 'the header whose content should be substituted so that Ceedling isolates its neighbors.'
|
|
54
|
+
return format( SHARED_DIRECTORY, substitution: GuidancePhrases.substitute( remedy, mocks: mocks, partials: partials ) )
|
|
55
|
+
end
|
|
56
|
+
end
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# =========================================================================
|
|
2
|
+
# Ceedling - Test-Centered Build System for C
|
|
3
|
+
# ThrowTheSwitch.org
|
|
4
|
+
# Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
|
|
5
|
+
# SPDX-License-Identifier: MIT
|
|
6
|
+
# =========================================================================
|
|
7
|
+
|
|
8
|
+
require 'ceedling/diagnostics/build_step_doctor'
|
|
9
|
+
require 'ceedling/diagnostics/toolchain_output'
|
|
10
|
+
require 'ceedling/diagnostics/header_collision_guidance'
|
|
11
|
+
|
|
12
|
+
# Explains compiler errors where one translation unit declares a name twice or two ways.
|
|
13
|
+
#
|
|
14
|
+
# A mock or Partial substitutes a header only through the #include directives a test
|
|
15
|
+
# names and the order of its search paths. A header's real content can still reach a
|
|
16
|
+
# compilation another way, and its declarations then collide with the substitute's (see
|
|
17
|
+
# HEADER_COLLISIONS.md). Headers that share a directory can collide the same way with no
|
|
18
|
+
# substitute involved, since a quoted #include finds its neighbor before any search path.
|
|
19
|
+
#
|
|
20
|
+
# Compilers word the collision differently, and no list of wordings is complete. The
|
|
21
|
+
# symptoms below cover the families DOCTOR.md lists and end in a generic net, since a
|
|
22
|
+
# missed collision costs more than guidance that turns out not to apply.
|
|
23
|
+
class HeaderCollisionSpecialist
|
|
24
|
+
|
|
25
|
+
COLLISION_SYMPTOMS = [
|
|
26
|
+
# GCC
|
|
27
|
+
/redefinition of|redeclaration of|conflicting types|previous (?:definition|declaration)|redeclared as different kind/i,
|
|
28
|
+
# Clang, armclang, and Microchip XC8 v2 and later
|
|
29
|
+
/typedef redefinition|previous definition is here/i,
|
|
30
|
+
# EDG front ends: IAR (Pe101), Arm armcc (#101), TI and Green Hills (error #101)
|
|
31
|
+
/has already been (?:declared|defined)|invalid redeclaration|declaration is incompatible|(?:\bPe|#)0*(?:101|147|256)\b/i,
|
|
32
|
+
# MSVC
|
|
33
|
+
/\bC(?:2011|2084|2370|2371)\b|redefinition; different/,
|
|
34
|
+
# TASKING, SDCC, and other compilers
|
|
35
|
+
/redefin|redeclar|already (?:been )?(?:declared|defined)|duplicate (?:definition|declaration)/i
|
|
36
|
+
].freeze
|
|
37
|
+
|
|
38
|
+
constructor :configurator, :test_substitutions, :gcc_dependency_parser, :file_wrapper
|
|
39
|
+
|
|
40
|
+
def diagnoses()
|
|
41
|
+
return [
|
|
42
|
+
diagnosis( :substituted_header_collision, method( :examine_substituted_header ) ),
|
|
43
|
+
diagnosis( :shared_directory_collision, method( :examine_shared_directory ) )
|
|
44
|
+
]
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
### Private ###
|
|
48
|
+
|
|
49
|
+
private
|
|
50
|
+
|
|
51
|
+
def diagnosis(name, examination)
|
|
52
|
+
return BuildStepDoctor::Diagnosis.new( name: name, steps: [:compile], symptoms: COLLISION_SYMPTOMS, examination: examination )
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# A header the output names that is also one the test substitutes means the real
|
|
56
|
+
# header's content reached the compilation beside its substitute
|
|
57
|
+
def examine_substituted_header(kase)
|
|
58
|
+
testable = kase.inputs[:testable]
|
|
59
|
+
culprit = substituted_culprit( testable, ToolchainOutput.headers( kase.output ) )
|
|
60
|
+
return nil if culprit.nil?
|
|
61
|
+
|
|
62
|
+
substitute = @test_substitutions.partialized?( testable, culprit.last ) ? 'Partial' : 'mock'
|
|
63
|
+
return substituted_header_prescription( *culprit, substitute: substitute )
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# The substituted header, as `[basename, real path]`, that a mentioned path names
|
|
67
|
+
def substituted_culprit(testable, mentioned)
|
|
68
|
+
return @test_substitutions.real_headers( testable ).find do |basename, real_path|
|
|
69
|
+
mentioned.any? { |m| File.basename( m ) == basename && File.expand_path( m ) == File.expand_path( real_path ) }
|
|
70
|
+
end
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# A named header beside other headers, none of them substituted, may have reached its
|
|
74
|
+
# neighbor through a quoted #include. Isolation acts only around a substituted header,
|
|
75
|
+
# so its directory and Ceedling's own are left out. The headers the first attempt's .d
|
|
76
|
+
# file lists are what this test reaches. A toolchain that writes no .d file leaves
|
|
77
|
+
# only the directory's listing, which may overstate the risk.
|
|
78
|
+
def examine_shared_directory(kase)
|
|
79
|
+
reached = reached_headers( kase.inputs[:dependencies] )
|
|
80
|
+
excluded = excluded_dirs( kase.inputs[:testable] )
|
|
81
|
+
|
|
82
|
+
return named_by_directory( kase.output ).filter_map do |dir, headers|
|
|
83
|
+
next if within?( dir, excluded ) || !neighbors?( dir, headers, reached )
|
|
84
|
+
|
|
85
|
+
shared_directory_prescription( headers, reached: !reached.nil? )
|
|
86
|
+
end
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# The headers the output names, grouped by their expanded directory
|
|
90
|
+
def named_by_directory(output)
|
|
91
|
+
return ToolchainOutput.headers( output ).group_by { |header| File.dirname( File.expand_path( header ) ) }
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
def within?(dir, roots)
|
|
95
|
+
return roots.any? { |root| dir == root || dir.start_with?( root + '/' ) }
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
# Every header the .d file lists, expanded, or nil without a .d file
|
|
99
|
+
def reached_headers(dependencies)
|
|
100
|
+
return nil if dependencies.nil? || !@file_wrapper.exist?( dependencies )
|
|
101
|
+
|
|
102
|
+
files = @gcc_dependency_parser.parse( @file_wrapper.read( dependencies ) ).values.flatten
|
|
103
|
+
return files.select { |file| header?( file ) }.map { |file| File.expand_path( file ) }.uniq
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
def excluded_dirs(testable)
|
|
107
|
+
substituted = @test_substitutions.real_headers( testable ).values.map { |real_path| File.dirname( File.expand_path( real_path ) ) }
|
|
108
|
+
return substituted + @test_substitutions.generated_dirs( testable ).map { |dir| File.expand_path( dir ) }
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
def neighbors?(dir, headers, reached)
|
|
112
|
+
beside = reached ? reached.select { |header| File.dirname( header ) == dir } : listed_headers( dir )
|
|
113
|
+
return (beside | headers.map { |header| File.expand_path( header ) }).size > 1
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
def listed_headers(dir)
|
|
117
|
+
return [] unless @file_wrapper.directory?( dir )
|
|
118
|
+
|
|
119
|
+
return @file_wrapper.directory_entries( dir ).select { |name| header?( name ) }.map { |name| File.join( dir, name ) }
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
def header?(filepath)
|
|
123
|
+
return ToolchainOutput::HEADER_EXTENSIONS.include?( File.extname( filepath ).delete_prefix( '.' ).downcase )
|
|
124
|
+
end
|
|
125
|
+
|
|
126
|
+
def substituted_header_prescription(basename, real_path, substitute:)
|
|
127
|
+
guidance = HeaderCollisionGuidance.substituted_header( substitute: substitute, **features )
|
|
128
|
+
|
|
129
|
+
return "The compiler output appears to report a redeclaration or conflicting types in '#{basename}'. " \
|
|
130
|
+
"If so, this test's #{substitute} of '#{basename}' may be colliding with its real content ('#{real_path}'), " \
|
|
131
|
+
"which can reach this compilation through a second #include chain that bypasses the #{substitute}.\n" \
|
|
132
|
+
"\n" + guidance
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
# The substitution features the project has on, which decide how remedies are worded
|
|
136
|
+
def features()
|
|
137
|
+
return { mocks: @configurator.project_use_mocks, partials: @configurator.project_use_partials }
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
# The directory is spelled as the output spelled it
|
|
141
|
+
def shared_directory_prescription(headers, reached:)
|
|
142
|
+
dir = File.dirname( headers.first )
|
|
143
|
+
names = headers.map { |header| "'#{File.basename( header )}'" }
|
|
144
|
+
listing = names.size == 1 ? names.first : "#{names[0..-2].join( ', ' )} and #{names.last}"
|
|
145
|
+
subject = names.size == 1 ? 'This header shares' : 'Each of these headers shares'
|
|
146
|
+
company = reached ? "other headers this test's compilation reaches" : 'other headers'
|
|
147
|
+
|
|
148
|
+
return "The compiler output appears to report a redeclaration or conflicting types involving #{listing}. " \
|
|
149
|
+
"If so, the cause may lie in how headers reach this compilation. #{subject} the directory '#{dir}' with #{company}.\n" \
|
|
150
|
+
"\n" + HeaderCollisionGuidance.shared_directory( **features )
|
|
151
|
+
end
|
|
152
|
+
end
|