ceedling 0.9.0 → 1.0.1

data/plugins/command_hooks/README.md

@@ -0,0 +1,241 @@
+# Ceedling Plugin: Command Hooks
+
+Easily run command line tools and scripts at various points in a Ceedling build.
+
+# Plugin Overview
+
+This plugin allows you to skip creating a full Ceedling plugin for many common use cases. It links Ceedling's programmatic `Plugin` code hooks to easily managed tool definitions. 
+
+# Setup
+
+To use this plugin, it must be enabled:
+
+```yaml
+:plugins:
+  :enabled:
+    - command_hooks
+```
+
+# Configuration
+
+## Overview
+
+To connect utilties or scripts to build step hooks, Ceedling tools must be defined.
+
+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. When enabled, this plugin ensures any tools you define are executed by the corresponding build step hook they are organized beneath. The configurtion of enabled hooks and tools happens in a top-level `:command_hooks:` block within your project configuration. One or more tools can be attached to a build step hook.
+
+## Tool lists
+
+A command hook can execute one or more tools.
+
+If only a single tool is needed, its hash keys and value can be organized as a YAML sub-hash beneath the hook key. Alternatively, a single tool can exist as the only entry in a YAML list.
+
+If multiple tools are needed, they must be organized as entries in a YAML list.
+
+See the commented examples below.
+
+## Tool definitions
+
+Each Ceedling tool requires an `:executable` string and an optional `:arguments` list. See _[CeedlingPacket][ceedling-packet]_ documentation for project configuration [`:tools`][tools-doc] entries to understand how to craft your argument list and other tool options.
+
+At present, this plugin passes at most one runtime parameter for use in a hook's tool argument list. 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.
+
+[tools-doc]: https://github.com/ThrowTheSwitch/Ceedling/blob/test/ceedling_0_32_rc/docs/CeedlingPacket.md#tools-configuring-command-line-tools-used-for-build-steps
+
+## Hook logging
+
+In addition to the standard Ceedling tool definition elements, a hook configuration entry may optionally include a `:logging` setting.
+
+`:logging` may be set to `TRUE` or `FALSE`. An omitted setting is equivalent to `FALSE`.
+
+When logging is enabled and logging conditions are appropriate, any output from the hook tool will be logged to the console with a brief header identifying the hook.
+
+* Explicit command hook output logging only occurs at verbosity levels Normal and Obnoxious.
+* Debug logging naturally displays hook output as part of normal tool execution logging. It is not duplicated by hook logging.
+* At Normal verbosity, blank hook output is not logged at all; Obnoxious verbosity will display blank output as `<empty>`.
+
+## Command Hooks example configuration YAML
+
+```yaml
+:command_hooks:
+  # Hook called every time a mock is generated
+  # Who knows what my_script.py does -- sky is the limit
+  :pre_mock_generate:
+    # This tool is organized as a sub-hash beneath the command hook key
+    :executable: python
+    :arguments:
+      - my_script.py
+      - --some-arg
+      - ${1} # Replaced with the filepath of the header file that will be mocked
+    :logging: TRUE # Log any tool output to console
+      
+  # Hook called for each linking operation
+  # Here, we are performing two tasks for the same build step hook, converting a
+  # binary executable to S-record format and, then, archiving with other artifacts.
+  :post_link_execute:
+    # These tools are organized in a YAML list beneath the command hook key
+    - :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 a top-level `: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 the single build step for which the hook is named.
+
+As an example, consider a Ceedling project with ten test files and seventeen mocks. The command line `ceedling test:all` would trigger:
+
+* 1 occurrence of the `:pre_build` hook.
+* 10 occurrences of the `:pre_test` and `:post_test` hooks.
+* 17 occurrences of the `:pre_mock_generate` and `:post_mock_generate` hooks.
+* 10 occurrences of the `:pre_test_runner_generate` and `:post_test_runner_generate` hooks.
+* 27(+) occurrences of the `:pre_compile` and `:post_compile` hooks. These hooks would be called 27 times for test file and mock file compilation. A test suite build will also include compilation of the source files under tests, Unity's source, CMock's source, and generated test runner C files -- easily more than another two dozen compilation hook calls.
+* 10 occurrences of the `:pre_link` and `:post_link` hooks for test executable creation.
+* 10 occurences of the `:pre_test_fixture_execute` and `:post_test_fixture_execute` hooks for running test executables and gathering the results of the tests cases they contain.
+* 1 occurence of the `:post_build` hook unless a build error occurred (`:post_error` would be called isntead).
+
+## `:pre_build`
+
+Called once just before Ceedling executes any tasks.
+
+No parameters are provided for a tool's argument list when the hook is called.
+
+## `:post_build`
+
+Called once just before Ceedling terminates.
+
+No parameters are provided for a tool's argument list when the hook is called.
+
+## `:post_error`
+
+Called once just after any build failure and just before Ceedling terminates.
+
+No parameters are provided for a tool's argument list when the hook is called.
+
+## `:pre_test`
+
+Called just before each test begins its build pipeline and just after all context for that build has been gathered.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+## `:post_test`
+
+Called just after each test completes its build and execution.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+## `:pre_release`
+
+Called once just before a release build begins.
+
+No parameters are provided for a tool's argument list when the hook is called.
+
+## `:post_release`
+
+Called once just after a release build finishes.
+
+No parameters are provided for a tool's argument list when the hook is called.
+
+## `:pre_mock_preprocess`
+
+If mocks are enabled and preprocessing is in use, this is called just before each header file to be mocked is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+
+[ceedling-packet]: ../docs/CeedlingPacket.md
+
+## `:post_mock_preprocess`
+
+If mocks are enabled and preprocessing is in use, this is called just after each header file to be mocked is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+## `:pre_mock_generate`
+
+If mocks are enabled, this is called just before each header file to be mocked is processed by mock generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+## `:post_mock_generate`
+
+If mocks are enabled, this is called just after each mock generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the header file to be mocked.
+
+## `:pre_test_preprocess`
+
+If preprocessing is in use, this is called just before each test file is preprocessed before runner generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+
+## `:post_test_preprocess`
+
+If preprocessing is in use, this is called just after each test file is preprocessed.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+See _[CeedlingPacket][ceedling-packet]_ for details on how Ceedling preprocessing operates.
+
+## `:pre_runner_generate`
+
+Called just before each test file is processed by test runner generation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+## `:post_runner_generate`
+
+Called just after each test runner is generated.
+
+The parameter available to a tool (`${1}`) when the hook is called is the test's filepath.
+
+## `:pre_compile_execute`
+
+Called just before each C or assembly file is compiled.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the file to be compiled.
+
+## `:post_compile_execute`
+
+Called just after each file compilation.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the input file that was compiled.
+
+## `:pre_link_execute`
+
+Called just before any binary artifact—test or release—is linked.
+
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+
+## `:post_link_execute`
+
+Called just after a binary artifact is linked.
+
+The parameter available to a tool (`${1}`) when the hook is called is the binary output artifact's filepath.
+
+## `:pre_test_fixture_execute`
+
+Called just before each test is executed in its corresponding test fixture.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact to be executed by the fixture.
+
+## `:post_test_fixture_execute`
+
+Called just after each test's fixture is executed and test results are collected.
+
+The parameter available to a tool (`${1}`) when the hook is called is the filepath of the binary artifact that was executed by the fixture.

data/plugins/command_hooks/lib/command_hooks.rb

@@ -0,0 +1,231 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+require 'ceedling/plugin'
+
+COMMAND_HOOKS_ROOT_NAME = 'command_hooks'.freeze
+COMMAND_HOOKS_SYM       = COMMAND_HOOKS_ROOT_NAME.to_sym
+
+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
+    # Get a copy of the project configuration
+    project_config = @ceedling[:setupinator].config_hash
+
+    # Convenience object references
+    @loginator = @ceedling[:loginator]
+    @reportinator = @ceedling[:reportinator]
+    @walkinator = @ceedling[:config_walkinator]
+    @tool_validator = @ceedling[:tool_validator]
+    @tool_executor = @ceedling[:tool_executor]
+    @verbosinator = @ceedling[:verbosinator]
+    @configurator_validator = @ceedling[:configurator_validator]
+    
+    # Look up if the accompanying `:command_hooks` configuration block exists
+    config_exists = @configurator_validator.exists?(
+      project_config,
+      COMMAND_HOOKS_SYM
+    )
+
+    # Go boom if the required configuration block does not exist
+    unless config_exists
+      name = @reportinator.generate_config_walk([COMMAND_HOOKS_SYM])
+      error = "Command Hooks plugin is enabled but is missing a required configuration block `#{name}`"
+      raise CeedlingException.new(error)
+    end
+    
+    @config = project_config[COMMAND_HOOKS_SYM]
+    
+    # Validate the command hook keys (look out for typos)
+    validate_config( @config )
+    
+    # Validate the tools beneath the keys
+    @config.each do |hook, tool|
+      if tool.is_a?(Array)
+        tool.each_index {|index| validate_hook( project_config, hook, index )}
+      else
+        validate_hook( project_config, hook )
+      end
+    end
+  end
+
+  def pre_mock_preprocess(arg_hash);       run_hook( :pre_mock_preprocess,       arg_hash[:header_file] ); end
+  def post_mock_preprocess(arg_hash);      run_hook( :post_mock_preprocess,      arg_hash[:header_file] ); end
+  def pre_test_preprocess(arg_hash);       run_hook( :pre_test_preprocess,       arg_hash[:test_file]   ); end
+  def post_test_preprocess(arg_hash);      run_hook( :post_test_preprocess,      arg_hash[:test_file]   ); end
+  def pre_mock_generate(arg_hash);         run_hook( :pre_mock_generate,         arg_hash[:header_file] ); end
+  def post_mock_generate(arg_hash);        run_hook( :post_mock_generate,        arg_hash[:header_file] ); end
+  def pre_runner_generate(arg_hash);       run_hook( :pre_runner_generate,       arg_hash[:source]      ); end
+  def post_runner_generate(arg_hash);      run_hook( :post_runner_generate,      arg_hash[:runner_file] ); end
+  def pre_compile_execute(arg_hash);       run_hook( :pre_compile_execute,       arg_hash[:source_file] ); end
+  def post_compile_execute(arg_hash);      run_hook( :post_compile_execute,      arg_hash[:object_file] ); end
+  def pre_link_execute(arg_hash);          run_hook( :pre_link_execute,          arg_hash[:executable]  ); end
+  def post_link_execute(arg_hash);         run_hook( :post_link_execute,         arg_hash[:executable]  ); end
+  def pre_test_fixture_execute(arg_hash);  run_hook( :pre_test_fixture_execute,  arg_hash[:executable]  ); end
+  def post_test_fixture_execute(arg_hash); run_hook( :post_test_fixture_execute, arg_hash[:executable]  ); end
+  def pre_test(test);                      run_hook( :pre_test,                  test                   ); end
+  def post_test(test);                     run_hook( :post_test,                 test                   ); end
+  def pre_release;                         run_hook( :pre_release                                       ); end
+  def post_release;                        run_hook( :post_release                                      ); end
+  def pre_build;                           run_hook( :pre_build                                         ); end
+  def post_build;                          run_hook( :post_build                                        ); end
+  def post_error;                          run_hook( :post_error                                        ); end
+
+  ### Private
+
+  private
+  
+  ##
+  # Validate plugin configuration.
+  #
+  # :args:
+  #   - config: :command_hooks section from project config hash
+  #
+  def validate_config(config)
+    unless config.is_a?(Hash)
+      name = @reportinator.generate_config_walk([COMMAND_HOOKS_SYM])
+      error = "Expected configuration #{name} to be a Hash but found #{config.class}"
+      raise CeedlingException.new(error)
+    end
+    
+    unrecognized_hooks = config.keys - COMMAND_HOOKS_LIST
+    
+    unrecognized_hooks.each do |not_a_hook|
+      name = @reportinator.generate_config_walk( [COMMAND_HOOKS_SYM, not_a_hook] )
+      error = "Unrecognized Command Hook: #{name}"
+      @loginator.log( error, Verbosity::ERRORS )
+    end
+    
+    unless unrecognized_hooks.empty?
+      error = "Unrecognized hooks found in Command Hooks plugin configuration"
+      raise CeedlingException.new(error)
+    end
+  end
+  
+  ##
+  # Validate given hook
+  #
+  # :args:
+  #   - config: Project configuration hash
+  #   - keys: Key and index of hook inside :command_hooks configuration
+  #
+  def validate_hook(config, *keys)
+    walk = [COMMAND_HOOKS_SYM, *keys]
+    name = @reportinator.generate_config_walk( walk )
+    entry, _ = @walkinator.fetch_value( *walk, hash:config )
+
+    if entry.nil?
+      raise CeedlingException.new( "Missing Command Hook plugin configuration for #{name}" )
+    end
+        
+    unless entry.is_a?(Hash)
+      error = "Expected configuration #{name} for Command Hooks plugin to be a Hash but found #{entry.class}"
+      raise CeedlingException.new( error )
+    end
+
+    # Validate the Ceedling tool components of the hook entry config
+    @tool_validator.validate( tool: entry, name: name, boom: true )
+
+    # Default logging configuration
+    config[:logging] = false if config[:logging].nil?
+  end
+  
+  ##
+  # Run a hook if its available.
+  #
+  # If __which_hook__ is an array, run each of them sequentially.
+  #
+  # :args:
+  #   - which_hook: Name of the hook to run
+  #   - name: Name of file
+  #
+  def run_hook(which_hook, name="")
+    if (@config[which_hook])
+      msg = "Running Command Hook :#{which_hook}"
+      msg = @reportinator.generate_progress( msg )
+      @loginator.log( msg )
+      
+      # Single tool config
+      if (@config[which_hook].is_a? Hash)
+        run_hook_step( which_hook, @config[which_hook], name )
+      
+      # Multiple tool configs
+      elsif (@config[which_hook].is_a? Array)
+        @config[which_hook].each do |hook|
+          run_hook_step( which_hook, hook, name )
+        end
+      
+      # Tool config is bad
+      else
+        msg = "The tool config for Command Hook #{which_hook} was poorly formed and not run"
+        @loginator.log( msg, Verbosity::COMPLAIN )
+      end
+    end
+  end
+
+  ##
+  # Run a hook if its available.
+  #
+  # :args:
+  #   - hook: Name of the hook to run
+  #   - name: Name of file (default: "")
+  #
+  # :return:
+  #    shell_result.
+  #
+  def run_hook_step(which_hook, hook, name="")
+    if (hook[:executable])
+      # Handle argument replacemant ({$1}), and get commandline
+      cmd = @ceedling[:tool_executor].build_command_line( hook, [], name )
+      shell_result = @ceedling[:tool_executor].exec( cmd )
+
+      # If hook logging is enabled
+      if hook[:logging]
+        # Skip debug logging -- allow normal tool debug logging to do its thing
+        return if @verbosinator.should_output?( Verbosity::DEBUG )
+
+        output = shell_result[:output].strip
+
+        # Set empty output to empty string if we're in OBNOXIOUS logging mode
+        output = '<empty>' if output.empty? and @verbosinator.should_output?( Verbosity::OBNOXIOUS )
+
+        # Don't add to logging output if there's nothing to output
+        return if output.empty?
+
+        # NORMAL and OBNOXIOUS logging
+        @loginator.log( "Command Hook :#{which_hook} output >> #{output}" )
+      end
+    end
+  end
+
+end

data/plugins/compile_commands_json_db/README.md

@@ -0,0 +1,40 @@
+# Ceedling Plugin: JSON Compilation Database
+
+Language Server Protocol (LSP) support for Clang tooling.
+
+# Background
+
+Syntax highlighting and code completion are hard. Historically each editor or IDE has implemented their own and then competed amongst themselves to offer the best experience for developers. Good syntax highlighting can be so valuable as to outweigh the consideration of alternate editors. If implementing sytnax highlighting and related features in a tool is hard for one language — and it is — imagine doing it for dozens of them. Further, on the flip side, imagine the complexities involved for a developer working with multiple languages at once.
+
+In June of 2016, Microsoft with Red Hat and Codenvy got together to create the [Language Server Protocol (LSP)][lsp-microsoft] ([community site][lsp-community]). The idea was simple. By standardizing, any conforming IDE or editor would only need to support LSP instead of custom plugins for each language. In turn, the backend code that performs syntax highlighting and similar features can be written once and used by any IDE that supports LSP. Today, [Many editors support LSP][lsp-tools].
+
+[lsp-microsoft]: https://microsoft.github.io/language-server-protocol/
+[lsp-community]: https://langserver.org/
+[lsp-tools]: https://microsoft.github.io/language-server-protocol/implementors/tools/
+
+# Plugin Overview
+
+For C and C++ projects, perhaps the most popular LSP server is the [`clangd`][clangd] backend. In order to provide features like _go to definition_, `clangd` needs to understand how to build a project so that it can discover all the pieces to the puzzle. Because of the various flavors of builds Ceedling supports and especially because of the complexities of test suite builds, components of a build can easily go missing from the view of `clangd`.
+
+This plugin gives `clangd` — or any tool that understands a [JSON compilation database][json-compilation-database] — full visibility into a Ceedling build.
+
+Once enabled, this plugin generates the database as `<build root>/artifacts/compile_commands.json` for each new build. Tools that understand JSON Compilation Database files can then process it to make their features fully available to you.
+
+[clangd]: https://clangd.llvm.org
+[json-compilation-database]: https://clang.llvm.org/docs/JSONCompilationDatabase.html
+
+# Setup
+
+Enable the plugin in your Ceedling project file by adding `compile_commands_json_db` to the list of enabled plugins.
+
+``` YAML
+:plugins:
+  :enabled:
+    - compile_commands_json_db
+```
+
+# Configuration
+
+There is no additional configuration necessary to run this plugin.
+
+`clangd` will search your build directory for the JSON compilation database, but in some instances on Unix-asbed platforms it can be easier and necessary to symlink the file into the root directory of your project (e.g. `ln -s ./build/artifacts/compile_commands.json .`).

data/plugins/compile_commands_json_db/lib/compile_commands_json_db.rb

@@ -0,0 +1,51 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/plugin'
+require 'ceedling/constants'
+require 'json'
+
+class CompileCommandsJsonDb < Plugin
+  
+  # `Plugin` setup()
+  def setup
+    @fullpath = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, "compile_commands.json")
+    
+    @database = []
+    
+    if (File.exist?(@fullpath) && File.size(@fullpath) > 0)
+      @database = JSON.parse( File.read(@fullpath) )
+    end
+
+    @mutex = Mutex.new()
+  end
+
+  # `Plugin` build step hook
+  def post_compile_execute(arg_hash)
+
+    # Create new Entry from compilation
+    value = {
+      "directory" => Dir.pwd, # TODO: Replace with Ceedling project root when it exists
+      "file" => arg_hash[:source],
+      "command" => arg_hash[:shell_command],
+      "output" => arg_hash[:object]
+    }
+
+    @mutex.synchronize do
+      # Determine if we're updating an existing file description or adding a new one
+      index = @database.index {|h| h["file"] == arg_hash[:source]}
+      if index
+        @database[index] = value
+      else
+        @database << value
+      end
+
+      # Rewrite the compile_commands.json file
+      File.open(@fullpath,'w') {|f| f << JSON.pretty_generate(@database)}
+    end
+  end
+end