ceedling 0.31.0 → 1.0.0

data/lib/ceedling.rb

@@ -1,99 +1,14 @@
-##
-# This module defines the interface for interacting with and loading a project
-# with Ceedling.
-module Ceedling
-  ##
-  # Returns the location where the gem is installed.
-  # === Return
-  # _String_ - The location where the gem lives.
-  def self.location
-    File.join( File.dirname(__FILE__), '..')
-  end
-
-  ##
-  # Return the path to the "built-in" plugins.
-  # === Return
-  # _String_ - The path where the default plugins live.
-  def self.load_path
-    File.join( self.location, 'plugins')
-  end
-
-  ##
-  # Return the path to the Ceedling Rakefile
-  # === Return
-  # _String_
-  def self.rakefile
-    File.join( self.location, 'lib', 'ceedling', 'rakefile.rb' )
-  end
-
-  ##
-  # This method selects the project file that Ceedling will use by setting the
-  # CEEDLING_MAIN_PROJECT_FILE environment variable before loading the ceedling
-  # rakefile. A path supplied as an argument to this method will override the
-  # current value of the environment variable. If no path is supplied as an
-  # argument then the existing value of the environment variable is used. If
-  # the environment variable has not been set and no argument has been supplied
-  # then a default path of './project.yml' will be used.
-  #
-  # === Arguments
-  # +options+ _Hash_::
-  #   A hash containing the options for ceedling. Currently the following
-  #   options are supported:
-  #   * +config+ - The path to the project YAML configuration file.
-  #   * +root+ - The root of the project directory.
-  #   * +prefix+ - A prefix to prepend to plugin names in order to determine the
-  #     corresponding gem name.
-  #   * +plugins+ - The list of ceedling plugins to load
-  def self.load_project(options = {})
-    # Make sure our path to the yaml file is setup
-    if options.has_key? :config
-      ENV['CEEDLING_MAIN_PROJECT_FILE'] = options[:config]
-    elsif ENV['CEEDLING_MAIN_PROJECT_FILE'].nil?
-      ENV['CEEDLING_MAIN_PROJECT_FILE'] = './project.yml'
-    end
-
-    # Register the plugins
-    if options.has_key? :plugins
-      options[:plugins].each do |plugin|
-        register_plugin( plugin, options[:prefix] )
-      end
-    end
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
 
-    # Define the root of the project if specified
-    Object.const_set('PROJECT_ROOT', options[:root]) if options.has_key? :root
-
-    # Load ceedling
-    load "#{self.rakefile}"
-  end
-
-  ##
-  # Register a plugin for ceedling to use when a project is loaded. This method
-  # *must* be called prior to calling the _load_project_ method.
-  #
-  # This method is intended to be used for loading plugins distributed via the
-  # RubyGems mechanism. As such, the following gem structure is assumed for
-  # plugins.
-  #
-  # * The gem name must be prefixed with 'ceedling-' followed by the plugin
-  #   name (ex. 'ceedling-bullseye')
-  #
-  # * The contents of the plugin must be isntalled into a subdirectory of
-  #   the gem with the same name as the plugin (ex. 'bullseye/')
-  #
-  # === Arguments
-  # +name+ _String_:: The name of the plugin to load.
-  # +prefix+ _String_::
-  #   (optional, default = nil) The prefix to use for the full gem name.
-  def self.register_plugin(name, prefix=nil)
-    # Figure out the full name of the gem and location
-    prefix   ||= 'ceedling-'
-    gem_name   = prefix + name
-    gem_dir    = Gem::Specification.find_by_name(gem_name).gem_dir()
-
-    # Register the plugin with Ceedling
-    require 'ceedling/defaults'
-    DEFAULT_CEEDLING_CONFIG[:plugins][:enabled]    << name
-    DEFAULT_CEEDLING_CONFIG[:plugins][:load_paths] << gem_dir
-  end
-end
+# This file exists solely for `require 'ceedling'` and any backwards compatibility.
+# All path loading and related is handled from bin/ceedling.
+# There is no shareable, library-worth code in lib/.
 
+module Ceedling
+  # Emtpy
+end

data/lib/version.rb

@@ -0,0 +1,24 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+##
+## version.rb is run as:
+##  1. An executable script for a Ceedling tag used in the release build process
+##     `ruby Ceedling/lib/version.rb`
+##  2. As a code module of constants consumed by Ruby's gem building process
+##
+
+module Ceedling
+  module Version
+    # Convenience constants for gem building, etc.
+    GEM = '1.0.0'
+    TAG = GEM
+
+    # If run as a script print Ceedling's version to $stdout
+    puts( TAG ) if (__FILE__ == $0)
+  end
+end

data/license.txt

@@ -1,31 +1,24 @@
- Copyright (c) 2007-2019 Mike Karlesky, Mark VanderVoord, Greg Williams
+The MIT License (MIT)
 
- Permission is hereby granted, free of charge, to any person
- obtaining a copy of this software and associated documentation
- files (the "Software"), to deal in the Software without
- restriction, including without limitation the rights to use,
- copy, modify, merge, publish, distribute, sublicense, and/or sell
- copies of the Software, and to permit persons to whom the
- Software is furnished to do so, subject to the following
- conditions:
+Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
 
- The above copyright notice and this permission notice shall be
- included in all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
 
- The end-user documentation included with the redistribution, if
- any, must include the following acknowledgment: "This product
- includes software developed for the Unity Project, by Mike Karlesky,
- Mark VanderVoord, and Greg Williams and other contributors", in
- the same place and form as other third-party acknowledgments.
- Alternately, this acknowledgment may appear in the software
- itself, in the same form and location as other such third-party
- acknowledgments.
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
- HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
- OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/out.fail

@@ -1,7 +1,8 @@
 ---
 :source:
-  :path: some/place
-  :file: test_example.c
+  :file: some/place/test_example.c
+  :dirname: some/place
+  :basename: test_example.c
 :successes: []
 :failures:
 - :test: test_one

data/plugins/beep/README.md

@@ -1,22 +1,133 @@
-ceedling-beep
-=============
+# Ceedling Plugin: Beep
 
-This is a simple plugin that just beeps at the end of a build and/or test sequence. Are you getting too distracted surfing
-the internet, chatting with coworkers, or swordfighting while it's building or testing? The friendly beep will let you know
+Hear a useful beep at the end of a build.
+
+# Plugin Overview
+
+Are you getting too distracted surfing the internet, chatting with coworkers, or swordfighting while a long build runs? A friendly beep will let you know
 it's time to pay attention again.
 
-This plugin has very few configuration options. At this time it can beep on completion of a task and/or on an error condition.
-For each of these, you can configure the method that it should beep.
+# Setup
 
+To use this plugin, it must be enabled:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
 ```
-:tools:
-  :beep_on_done: :bell
-  :beep_on_error: :bell
+
+# Configuration
+
+Beep includes a default configuration. By just enabling the plugin, the simplest cross-platform sound mechanism (`:bell` below) is automatically enabled for both
+build completion and build error events.
+
+If you would like to customize your beeps, the following explains your options.
+
+## Events
+
+When this plugin is enabled, a beep is sounded when:
+
+* A test build or release build finish successfully.
+* An error condition breaks a build.
+
+To change the default sound for each event, define `:on_done` and `:on_error` beneath a top-level `:beep` entry in your configuration file. See example below.
+
+## Sound options
+
+The following options are fixed. At present, this plugin does not expose customization settings.
+
+* `:bell`
+
+  `:bell` is the simplest and most widely available option for beeping. This option simply `echo`s the unprintable [ASCII bell character][ascii-bel-character] to a command terminal. This option is generally available on all platforms, including Windows.
+
+  [ascii-bel-character]: https://en.wikipedia.org/wiki/Bell_character
+
+* `:tput`
+
+  [`tput`][tput] is a command line utility widely availble among Unix derivatives, including Linux and macOS. The `tput` utility uses the terminfo database to make the values of terminal-dependent capabilities (including the [ASCII bell character][ascii-bel-character]) and terminal information available to the shell.
+
+  If the `echo`-based method used by the `:bell` option is not successful, `:tput` is a good backup option (except on Windows).
+
+  [tput]: https://linux.die.net/man/1/tput
+
+* `:beep`
+
+  [`beep`][beep] is an old but widely available Linux package for tone generation using the PC speaker.
+
+  `beep` requires isntallation and the possibility of a complementary kernel module.
+
+  The original audio device in a PC before sound cards was a simple and limited speaker directly wired to a motherboard. Rarely, modern systems still have this device. More commonly, its functions are routed to a default mode of modern audio hardware. `beep` may not work on modern Linux systems. If it is a viable option, this utility is typically dependent on a PC speaker kernel module and related configuration.
+
+  [beep]: https://linux.die.net/man/1/beep
+
+* `:speaker_test`
+
+  [`speaker-test`][speaker-test] is a Linux package commonly available for tone generation using a system's audio features.
+
+  `speaker-test` requires installation as well as audio subsystem configuration.
+
+  _Note:_ `speaker-test` typically mandates a 4 second minimum run, even if the configured sound plays for less than this minimum. Options to limit `speaker-test`'s minimum time are likely possible but would require combining advanced Ceedling features.
+
+  [speaker-test]: https://linux.die.net/man/1/speaker-test
+
+* `:say`
+
+  macOS includes a built-in text-to-speech command line application, [`say`][say]. When Ceedling is running on macOS and this beep option is selected, Ceedling events will be verbally announced.
+
+  [say]: https://ss64.com/mac/say.html
+
+## Adding arguments to a beep tool
+
+Each of the sound options above map to a command line tool that Ceedling executes.
+
+The `:beep`, `:speaker_test`, and `:say` tools can accept additional command line arguments to modify their behavior and sound ouput.
+
+The `:speaker_test` tool is preconfigured with its `-t`, `-f`, and `-l` arguments to generate a 1 second 1000 Hz sine wave. Any additional arguments added through configuration will follow these (and could conflict).
+
+To add additional arguments, a feature of Ceedling's project file handling allows you to merge a partial tool definition with tools already fully defined.
+
+```yaml
+:tools_beep_<sound option>: # Fill in <sound option> as from the list above
+  :arguments:
+    - ...                   # Add any aguments as a list of strings
+```
+
+## Example beep configurations in YAML
+
+Enabling the plugin and event handlers with beep tool selections:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
+
+# The following is the default configuration.
+# It is shown for completeness, but it need not be duplicated in your project file 
+# if the default settings work for you.
+:beep:
+  :on_done: :bell
+  :on_error: :bell
+```
+
+Adding an argument to a beep tool:
+
+```yaml
+:plugins:
+  :enabled:
+    - beep
+
+:beep:
+  :on_done: :say # Choose the macOS `say` tool for build done events
+                 # `:bell` remains the default for :on_error:
+
+:tools_beep_say:
+  :arguments:
+    - -v daniel  # Change `say` command line to use Daniel voice
+
 ```
 
-Each of these have the following options:
+# Notes
 
-  - :bell - this option uses the ASCII bell character out stdout
-  - :speaker_test - this uses the linux speaker-test command if installed
+* Some terminal emulators intercept and/or silence beeps. Remote terminal sessions can add further complication. Be sure to check relevant configuration options to accomplish what you want.
 
-Very likely, we'll be adding to this list if people find this to be useful.

data/plugins/beep/config/defaults.yml

@@ -0,0 +1,12 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+---
+:beep:
+  :on_done: :bell
+  :on_error: :bell
+...

data/plugins/beep/config/defaults_beep.rb

@@ -0,0 +1,67 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Most generic beep option across all platforms -- echo the ASCII bell character
+DEFAULT_BEEP_BELL_TOOL = {
+  :executable => 'echo'.freeze,                     # Using `echo` shell command / command line application
+  :optional => true.freeze,
+  :name => 'default_beep_bell'.freeze,
+  :arguments => [
+    *('-n'.freeze unless SystemWrapper.windows?),   # No trailing newline for Unix-style echo (argument omitted on Windows)
+    "\x07".freeze                                   # Unprintable ASCII bell character, escaped in Ruby string
+    ].freeze
+  }
+
+# Terminal put the bell character on Unix-derived platforms
+DEFAULT_BEEP_TPUT_TOOL = {
+  :executable => 'tput'.freeze,                     # `tput` command line application
+  :optional => true.freeze,
+  :name => 'default_beep_tput'.freeze,
+  :arguments => [
+    "bel".freeze                                    # `tput` argument for bell character (named 'bel' in ASCII standard)
+    ].freeze
+  }
+
+# Old but widely available `beep` tone generator package for Unix-derived platforms (not macOS) 
+DEFAULT_BEEP_BEEP_TOOL = {
+  :executable => 'beep'.freeze,                     # `beep` command line application
+  :optional => true.freeze,
+  :name => 'default_beep_beep'.freeze,
+  :arguments => [].freeze                           # Default beep (no arguments)
+  }
+  
+# Widely available tone generator package for Unix-derived platforms (not macOS)
+DEFAULT_BEEP_SPEAKER_TEST_TOOL = {
+  :executable => 'speaker-test'.freeze,             # `speaker-test` command line application
+  :optional => true.freeze,
+  :name => 'default_beep_speaker_test'.freeze,
+  :arguments => [                                   # 1000 hz sine wave frequency
+    '-t sine'.freeze,
+    '-f 1000'.freeze,
+    '-l 1'.freeze
+    ].freeze
+  }
+
+# macOS text-to-speech tool
+DEFAULT_BEEP_SAY_TOOL = {
+  :executable => 'say'.freeze,                      # macOS `say` command line application
+  :optional => true.freeze,
+  :name => 'default_beep_say'.freeze,
+  :arguments => [
+    "\"${1}\""                                      # Replacement argument for text
+    ].freeze
+  }
+
+def get_default_config
+  return :tools => {
+    :beep_bell => DEFAULT_BEEP_BELL_TOOL,
+    :beep_tput => DEFAULT_BEEP_TPUT_TOOL,
+    :beep_beep => DEFAULT_BEEP_BEEP_TOOL,
+    :beep_speaker_test => DEFAULT_BEEP_SPEAKER_TEST_TOOL,
+    :beep_say => DEFAULT_BEEP_SAY_TOOL
+  }
+end

data/plugins/beep/lib/beep.rb

@@ -1,40 +1,85 @@
+# =========================================================================
+#   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 'ceedling/exceptions'
+
+BEEP_ROOT_NAME = 'beep'.freeze
+BEEP_SYM       = BEEP_ROOT_NAME.to_sym
 
 class Beep < Plugin
+  
+  # `Plugin` setup()
+  def setup
+    # Get non-flattenified project configuration
+    project_config = @ceedling[:setupinator].config_hash
+    
+    # Get beep configuration hash
+    beep_config = project_config[BEEP_SYM]
 
-  attr_reader :config
+    # Get tools hash
+    tools = project_config[:tools]
 
-  def setup
-    @config = {
-      :on_done  => ((defined? TOOLS_BEEP_ON_DONE)  ? TOOLS_BEEP_ON_DONE  : :bell  ),
-      :on_error => ((defined? TOOLS_BEEP_ON_ERROR) ? TOOLS_BEEP_ON_ERROR : :bell  ),
+    # Lookup and capture the selected beep tools
+    @tools = {
+      :beep_on_done => tools["beep_#{beep_config[:on_done]}".to_sym],
+      :beep_on_error => tools["beep_#{beep_config[:on_error]}".to_sym]
     }
+    
+    # Ensure configuration option is an actual tool
+    if @tools[:beep_on_done].nil?
+      error = "Option :#{beep_config[:on_done]} for :beep ↳ :on_done plugin configuration does not map to a tool."
+      raise CeedlingException.new( error )
+    end
+    
+    # Ensure configuration option is an actual tool
+    if @tools[:beep_on_error].nil?
+      error = "Option :#{beep_config[:on_done]} for :beep ↳ :on_error plugin configuration does not map to a tool."
+      raise CeedlingException.new( error )
+    end
+
+    # Validate the selected beep tools
+    # Do not validate the `:bell` tool as it relies on `echo` that could be a shell feature rather than executable
+    @ceedling[:tool_validator].validate(
+      tool: @tools[:beep_on_done],
+      boom: true
+    ) if tools[:on_done] != :bell
+
+    @ceedling[:tool_validator].validate(
+      tool: @tools[:beep_on_error],
+      boom: true
+    ) if tools[:on_error] != :bell
   end
 
+  # `Plugin` build step hook  
   def post_build
-    beep @config[:on_done]
-  end
+    command = @ceedling[:tool_executor].build_command_line(
+      @tools[:beep_on_done],
+      [],
+      # Only used by tools with `${1}` replacement argument
+      'ceedling build done'
+    )
 
-  def post_error
-    beep @config[:on_error]
+
+    # Verbosity is enabled to allow shell output (primarily for sake of the bell character)
+    @ceedling[:system_wrapper].shell_system( command: command[:line], verbose: true )
   end
+  
+  # `Plugin` build step hook
+  def post_error
+    command = @ceedling[:tool_executor].build_command_line(
+      @tools[:beep_on_error],
+      [],
+      # Only used by tools with `${1}` replacement argument
+      'ceedling build error'
+    )
 
-  private
-
-  def beep(method = :none)
-    case method
-    when :bell
-      if (SystemWrapper.windows?)
-        puts "echo '\007'"
-      else
-        puts "echo -ne '\007'"
-      end
-    when :speaker_test
-      `speaker-test -t sine -f 1000 -l 1`
-    else
-      #do nothing with illegal or :none
-    end
+    # Verbosity is enabled to allow shell output (primarily for sake of the bell character)
+    @ceedling[:system_wrapper].shell_system( command: command[:line], verbose: true )
   end
+  
 end
-

data/plugins/bullseye/README.md

@@ -1,5 +1,12 @@
-ceedling-bullseye
-=================
+Bullseye Code Coverage Plugin
+=============================
+
+# June 1, 2024 Bullseye Plugin Disabled
+
+Until the Bullseye Plugin can be updated for compatibility with Ceedling >= 1.0.0,
+it has been disabled.
+
+(The key hurdle is access to a license for the proprietary Bullseye coverage tooling.)
 
 # Plugin Overview
 
@@ -55,7 +62,6 @@ by Ceedling. The following is a typical configuration example:
       - -w140
   :bullseye_report_covfn:
     :executable: covfn
-    :stderr_redirect: :auto
     :arguments:
       - '--file $': ENVIRONMENT_COVFILE
       - --width 120
@@ -63,7 +69,6 @@ by Ceedling. The following is a typical configuration example:
       - '"${1}"'
   :bullseye_browser:
     :executable: CoverageBrowser
-    :background_exec: :auto
     :optional: TRUE
     :arguments:
       - '"$"': ENVIRONMENT_COVFILE