diff --git a/assets/project_as_gem.yml b/assets/project_as_gem.yml index 3288a7e8..1427b5cb 100644 --- a/assets/project_as_gem.yml +++ b/assets/project_as_gem.yml @@ -306,6 +306,29 @@ # :build_root: ./subprojectA/build # :defines: [] +# :command_hooks: +# :pre_mock_preprocess: +# :post_mock_preprocess: +# :pre_test_preprocess: +# :post_test_preprocess: +# :pre_mock_generate: +# :post_mock_generate: +# :pre_runner_generate: +# :post_runner_generate: +# :pre_compile_execute: +# :post_compile_execute: +# :pre_link_execute: +# :post_link_execute: +# :pre_test_fixture_execute: +# :post_test_fixture_execute: +# :pre_test: +# :post_test: +# :pre_release: +# :post_release: +# :pre_build: +# :post_build: +# :post_error: + ################################################################ # TOOLCHAIN CONFIGURATION ################################################################ @@ -375,25 +398,4 @@ # :arguments: [] # :name: # :optional: FALSE -# #These tools can be filled out when command_hooks plugin is enabled -# :pre_mock_preprocess -# :post_mock_preprocess -# :pre_mock_generate -# :post_mock_generate -# :pre_runner_preprocess -# :post_runner_preprocess -# :pre_runner_generate -# :post_runner_generate -# :pre_compile_execute -# :post_compile_execute -# :pre_link_execute -# :post_link_execute -# :pre_test_fixture_execute -# :pre_test -# :post_test -# :pre_release -# :post_release -# :pre_build -# :post_build -# :post_error ... diff --git a/assets/project_with_guts.yml b/assets/project_with_guts.yml index da92f4d3..f1067493 100644 --- a/assets/project_with_guts.yml +++ b/assets/project_with_guts.yml @@ -306,6 +306,29 @@ # :build_root: ./subprojectA/build # :defines: [] +# :command_hooks: +# :pre_mock_preprocess: +# :post_mock_preprocess: +# :pre_test_preprocess: +# :post_test_preprocess: +# :pre_mock_generate: +# :post_mock_generate: +# :pre_runner_generate: +# :post_runner_generate: +# :pre_compile_execute: +# :post_compile_execute: +# :pre_link_execute: +# :post_link_execute: +# :pre_test_fixture_execute: +# :post_test_fixture_execute: +# :pre_test: +# :post_test: +# :pre_release: +# :post_release: +# :pre_build: +# :post_build: +# :post_error: + ################################################################ # TOOLCHAIN CONFIGURATION ################################################################ @@ -376,25 +399,4 @@ # :arguments: [] # :name: # :optional: FALSE -# #These tools can be filled out when command_hooks plugin is enabled -# :pre_mock_preprocess -# :post_mock_preprocess -# :pre_mock_generate -# :post_mock_generate -# :pre_runner_preprocess -# :post_runner_preprocess -# :pre_runner_generate -# :post_runner_generate -# :pre_compile_execute -# :post_compile_execute -# :pre_link_execute -# :post_link_execute -# :pre_test_fixture_execute -# :pre_test -# :post_test -# :pre_release -# :post_release -# :pre_build -# :post_build -# :post_error ... diff --git a/docs/BreakingChanges.md b/docs/BreakingChanges.md index 4b3260a4..ab479cb5 100644 --- a/docs/BreakingChanges.md +++ b/docs/BreakingChanges.md @@ -160,6 +160,9 @@ In addition, a previously undocumented feature for merging a second configuratio Thorough documentation on Mixins and the new options for loading a project configuration can be found in _[CeedlingPacket](CeedlingPacket.md))_. +## `command_hooks` plugin tools configuration + +Previously, Command Hooks tools were defined under `:tools` section, now they must be defined under top-level `:command_hooks` section in project configuration. # Subprojects Plugin Replaced @@ -206,4 +209,4 @@ The above subproject definition will now look like the following: :defines: - DEFINE_JUST_FOR_THIS_FILE - AND_ANOTHER -``` \ No newline at end of file +``` diff --git a/examples/temp_sensor/project.yml b/examples/temp_sensor/project.yml index 8854affb..25138210 100644 --- a/examples/temp_sensor/project.yml +++ b/examples/temp_sensor/project.yml @@ -254,6 +254,29 @@ # :build_root: ./subprojectA/build # :defines: [] +# :command_hooks: +# :pre_mock_preprocess: +# :post_mock_preprocess: +# :pre_test_preprocess: +# :post_test_preprocess: +# :pre_mock_generate: +# :post_mock_generate: +# :pre_runner_generate: +# :post_runner_generate: +# :pre_compile_execute: +# :post_compile_execute: +# :pre_link_execute: +# :post_link_execute: +# :pre_test_fixture_execute: +# :post_test_fixture_execute: +# :pre_test: +# :post_test: +# :pre_release: +# :post_release: +# :pre_build: +# :post_build: +# :post_error: + ################################################################ # TOOLCHAIN CONFIGURATION ################################################################ @@ -324,25 +347,4 @@ # :arguments: [] # :name: # :optional: FALSE -# #These tools can be filled out when command_hooks plugin is enabled -# :pre_mock_preprocess -# :post_mock_preprocess -# :pre_mock_generate -# :post_mock_generate -# :pre_runner_preprocess -# :post_runner_preprocess -# :pre_runner_generate -# :post_runner_generate -# :pre_compile_execute -# :post_compile_execute -# :pre_link_execute -# :post_link_execute -# :pre_test_fixture_execute -# :pre_test -# :post_test -# :pre_release -# :post_release -# :pre_build -# :post_build -# :post_error ... diff --git a/plugins/command_hooks/README.md b/plugins/command_hooks/README.md index ffed24ff..9227e2d2 100644 --- a/plugins/command_hooks/README.md +++ b/plugins/command_hooks/README.md @@ -22,14 +22,14 @@ To connect a utilties or scripts to build step hooks, Ceedling tools must be def A Ceedling tool is just a YAML blob that gathers together a handful of settings and values that tell Ceedling how to build and execute a command line. Your tool can be a command line utility, a script, etc. -Example Ceedling tools follow. Their tool entry names correspond to the build step hooks listed later in this document. That's how this plugin works. When enabled, it ensures any tools you define are executed by the corresponding build step hook that shares their name. +Example Ceedling tools follow. Their tool entry names correspond to the build step hooks listed later in this document. That's how this plugin works. When enabled, it ensures any tools you define are executed by the corresponding build step hook that shares their name. The build step hook tool entry can be either a Ceedling tool or a list of them. -Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for `:tools` entries to understand how to craft your argument list and other tool options. +Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for [`:tools`](https://github.com/ThrowTheSwitch/Ceedling/blob/test/ceedling_0_32_rc/docs/CeedlingPacket.md#tools-configuring-command-line-tools-used-for-build-steps) entries to understand how to craft your argument list and other tool options. At present, this plugin only passes at most one runtime parameter for a given build step hook for use in a tool's argument list (from among the many processed by Ceedling's plugin framework). If available, this parameter can be referenced with a Ceedling tool argument expansion identifier `${1}`. That is, wherever you place `${1}` in your tool argument list, `${1}` will expand in the command line Ceedling constructs with the parameter this plugin provides for that build step hook. The list of build steps hooks below document any single parameters they provide at execution. ```yaml -:tools: +:command_hooks: # Called every time a mock is generated # Who knows what my_script.py does -- sky is the limit :pre_mock_generate: @@ -40,18 +40,26 @@ At present, this plugin only passes at most one runtime parameter for a given bu - ${1} # Replaced with the filepath of the header file that will be mocked # Called after each linking operation - # Here, we are converting a binary executable to S-record format + # Here, we are performing two task on the same build step hook, converting a + # binary executable to S-record format and then, zipping it along with some + # other files like linker's memory allocation/usage report and so on. :post_link_execute: - :executable: objcopy.exe - :arguments: - - ${1} # Replaced with the filepath to the linker's binary artifact output - - output.srec - - --strip-all + - :executable: objcopy.exe + :arguments: + - ${1} # Replaced with the filepath to the linker's binary artifact output + - output.srec + - --strip-all + - :executable: + :arguments: tar.exe + - -acf + - awesome_build.zip + - ${1} # Replaced with the filepath to the linker's binary artifact output + - memory_report.txt ``` # Available Build Step Hooks -Define any of the following entries within the `:tools:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps. +Define any of the following entries within the `:command_hooks:` section of your Ceedling project file to automagically connect utilities or scripts to build process steps. Some hooks are called for every file-related operation for which the hook is named. Other hooks are triggered by single build step for which the hook is named. diff --git a/plugins/command_hooks/lib/command_hooks.rb b/plugins/command_hooks/lib/command_hooks.rb index 7cc55aa7..d940a811 100755 --- a/plugins/command_hooks/lib/command_hooks.rb +++ b/plugins/command_hooks/lib/command_hooks.rb @@ -5,36 +5,64 @@ # SPDX-License-Identifier: MIT # ========================================================================= -require 'ceedling/plugin' require 'ceedling/constants' -class CommandHooks < Plugin +require 'ceedling/exceptions' +require 'ceedling/plugin' + +COMMAND_HOOKS_ROOT_NAME = 'command_hooks'.freeze +COMMAND_HOOKS_SYM = COMMAND_HOOKS_ROOT_NAME.to_sym - attr_reader :config +COMMAND_HOOKS_LIST = [ + :pre_mock_preprocess, + :post_mock_preprocess, + :pre_test_preprocess, + :post_test_preprocess, + :pre_mock_generate, + :post_mock_generate, + :pre_runner_generate, + :post_runner_generate, + :pre_compile_execute, + :post_compile_execute, + :pre_link_execute, + :post_link_execute, + :pre_test_fixture_execute, + :post_test_fixture_execute, + :pre_test, + :post_test, + :pre_release, + :post_release, + :pre_build, + :post_build, + :post_error, +].freeze + +class CommandHooks < Plugin def setup - @config = { - :pre_mock_preprocess => ((defined? TOOLS_PRE_MOCK_PREPROCESS) ? TOOLS_PRE_MOCK_PREPROCESS : nil ), - :post_mock_preprocess => ((defined? TOOLS_POST_MOCK_PREPROCESS) ? TOOLS_POST_MOCK_PREPROCESS : nil ), - :pre_test_preprocess => ((defined? TOOLS_PRE_TEST_PREPROCESS) ? TOOLS_PRE_TEST_PREPROCESS : nil ), - :post_test_preprocess => ((defined? TOOLS_POST_TEST_PREPROCESS) ? TOOLS_POST_TEST_PREPROCESS : nil ), - :pre_mock_generate => ((defined? TOOLS_PRE_MOCK_GENERATE) ? TOOLS_PRE_MOCK_GENERATE : nil ), - :post_mock_generate => ((defined? TOOLS_POST_MOCK_GENERATE) ? TOOLS_POST_MOCK_GENERATE : nil ), - :pre_runner_generate => ((defined? TOOLS_PRE_RUNNER_GENERATE) ? TOOLS_PRE_RUNNER_GENERATE : nil ), - :post_runner_generate => ((defined? TOOLS_POST_RUNNER_GENERATE) ? TOOLS_POST_RUNNER_GENERATE : nil ), - :pre_compile_execute => ((defined? TOOLS_PRE_COMPILE_EXECUTE) ? TOOLS_PRE_COMPILE_EXECUTE : nil ), - :post_compile_execute => ((defined? TOOLS_POST_COMPILE_EXECUTE) ? TOOLS_POST_COMPILE_EXECUTE : nil ), - :pre_link_execute => ((defined? TOOLS_PRE_LINK_EXECUTE) ? TOOLS_PRE_LINK_EXECUTE : nil ), - :post_link_execute => ((defined? TOOLS_POST_LINK_EXECUTE) ? TOOLS_POST_LINK_EXECUTE : nil ), - :pre_test_fixture_execute => ((defined? TOOLS_PRE_TEST_FIXTURE_EXECUTE) ? TOOLS_PRE_TEST_FIXTURE_EXECUTE : nil ), - :post_test_fixture_execute => ((defined? TOOLS_POST_TEST_FIXTURE_EXECUTE) ? TOOLS_POST_TEST_FIXTURE_EXECUTE : nil ), - :pre_test => ((defined? TOOLS_PRE_TEST) ? TOOLS_PRE_TEST : nil ), - :post_test => ((defined? TOOLS_POST_TEST) ? TOOLS_POST_TEST : nil ), - :pre_release => ((defined? TOOLS_PRE_RELEASE) ? TOOLS_PRE_RELEASE : nil ), - :post_release => ((defined? TOOLS_POST_RELEASE) ? TOOLS_POST_RELEASE : nil ), - :pre_build => ((defined? TOOLS_PRE_BUILD) ? TOOLS_PRE_BUILD : nil ), - :post_build => ((defined? TOOLS_POST_BUILD) ? TOOLS_POST_BUILD : nil ), - :post_error => ((defined? TOOLS_POST_ERROR) ? TOOLS_POST_ERROR : nil ), - } + project_config = @ceedling[:setupinator].config_hash + + config_exists = @ceedling[:configurator_validator].exists?( + project_config, + COMMAND_HOOKS_SYM + ) + + unless config_exists + name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM]) + error = "Missing configuration #{name}" + raise CeedlingException.new(error) + end + + @config = project_config[COMMAND_HOOKS_SYM] + + validate_config(@config) + + @config.each do |hook, tool| + if tool.is_a?(Array) + tool.each_index {|index| validate_hook_tool(project_config, hook, index)} + else + validate_hook_tool(project_config, hook) + end + end end def pre_mock_preprocess(arg_hash); run_hook( :pre_mock_preprocess, arg_hash[:header_file] ); end @@ -60,7 +88,62 @@ def post_build; run_hook( :post_build def post_error; run_hook( :post_error ); end private - + + ## + # Validate plugin configuration. + # + # :args: + # - config: :command_hooks section from project config hash + # + def validate_config(config) + unless config.is_a?(Hash) + name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM]) + error = "Expected configuration #{name} to be a Hash but found #{config.class}" + raise CeedlingException.new(error) + end + + unknown_hooks = config.keys - COMMAND_HOOKS_LIST + + unknown_hooks.each do |not_a_hook| + name = @ceedling[:reportinator].generate_config_walk([COMMAND_HOOKS_SYM, not_a_hook]) + error = "Unrecognized option: #{name}" + @ceedling[:loginator].log(error, Verbosity::ERRORS) + end + + unless unknown_hooks.empty? + error = "Unrecognized hooks have been found in project configuration" + raise CeedlingException.new(error) + end + end + + ## + # Validate given hook tool. + # + # :args: + # - config: Project configuration hash + # - keys: Key and index of hook inside :command_hooks configuration + # + def validate_hook_tool(config, *keys) + walk = [COMMAND_HOOKS_SYM, *keys] + name = @ceedling[:reportinator].generate_config_walk(walk) + hash = @ceedling[:config_walkinator].fetch_value(config, *walk) + + tool_exists = @ceedling[:configurator_validator].exists?(config, *walk) + + unless tool_exists + raise CeedlingException.new("Missing configuration #{name}") + end + + tool = hash[:value] + + unless tool.is_a?(Hash) + error = "Expected configuration #{name} to be a Hash but found #{tool.class}" + raise CeedlingException.new(error) + end + + @ceedling[:tool_validator].validate(tool: tool, name: name, boom: true) + end + ## # Run a hook if its available. # @@ -110,4 +193,3 @@ def run_hook(which_hook, name="") end end end -