Plugin Option 2: `Plugin` Subclass

Naming and location conventions:

<plugin_name>/lib/<plugin_name>.rb
The plugin's class name must be the camelized version (a.k.a. "bumpy case") of the plugin filename — whiz_bang.rb ➡️ WhizBang.

This plugin option allows full programmatic ability connected to any of a number of predefined Ceedling build steps.

The contents of <plugin_name>.rb must implement a class that subclasses Plugin, Ceedling's plugin base class.

Example `Plugin` subclass

An incomplete Plugin subclass follows to illustrate the basics.

# whiz_bang/lib/whiz_bang.rb
require 'ceedling/plugin'

class WhizBang < Plugin
  def setup
    # ...
  end

  # Build step hook
  def pre_test(test)
    # ...
  end

  # Build step hook
  def post_test(test)
    # ...
  end
end

Example programmatic plugin layout

Project configuration file:

:plugins:
  :load_paths:
    - support/plugins
  :enabled:
    - whiz_bang

Ceedling project directory structure:

project/
├── project.yml
└── support/
    └── plugins/
        └── whiz_bang/
            └── lib/
                └── whiz_bang.rb

It is possible and often convenient to add more .rb files to the containing lib/ directory to allow good organization of plugin code. No Ceedling conventions exist for these supplemental code files. Only standard Ruby constraints exist for these filenames and content.

`Plugin` instance variables

Each Plugin subclass has access to the following instance variables:

@name
@ceedling

@name is self explanatory. @ceedling is a hash containing every object within the Ceedling application; its keys are the filenames of the objects minus file extension.

Objects commonly used in plugins include:

@ceedling[:configurator] — Project configuration
@ceedling[:streaminator] — Logging
@ceedling[:reportinator] — String formatting for logging
@ceedling[:file_wrapper] — File operations
@ceedling[:plugin_reportinator] — Various needs including gathering test results

`Plugin` method `setup()`

If your plugin defines this method, it will be called during plugin creation at Ceedling startup. It is effectively your constructor for your custom Plugin subclass.

`Plugin` hook methods `pre_` and `post_` conventions & concerns

Multi-threaded protections

Because Ceedling can run build operations in multiple threads, build step hook handlers must be thread safe. Practically speaking, this generally requires a Mutex object synchronize()d around any code that writes to or reads from a common data structure instantiated within a plugin.

A common example is collecting test results filepaths from the post_test_fixture_execute() hook. A hash or array accumulating these filepaths as text executables complete their runs must have appropriate threading protections.

Command line tool shell results

Pre and post build step hooks are often called on either side of a command line tool operation. If a command line tool is executed for a build step (e.g. test compilation), the arg_hash will be the same for the pre and post hooks with one difference.

In the post_ hook, the arg_hash parameter will contain a shell_result key whose associated value is itself a hash with the following contents:

{
  :output => "<Console output>", # String holding any $stdout / redirected $stderr output
  :status => <Process::Status>,  # Ruby object of type Process::Status
  :exit_code => <int>,           # Command line exit code (extracted from :status object)
  :time => <float>               # Seconds elapsed for shell operation
}

Preprocessing Hook Limitations

Test preprocessing steps are quite sophisticated and involve various combinations of tool executions. The post_ preprocessing hooks do not include shell results. Future updates to Ceedling's plugin system will create a more robust means of attaching custom behaviors to test preprocessing or connecting your own preprocessing pipeline with toolchains other than GCC.

`Plugin` hook methods `pre_mock_preprocess(arg_hash)` and `post_mock_preprocess(arg_hash)`

These methods are called before and after execution of preprocessing for header files to be mocked (see Conventions & Behaviors for preprocessing details). If a project does not enable preprocessing or a build does not include tests, these are not called. This pair of methods is called a number of times equal to the number of mocks in a test build.