ceedling 0.29.1 → 0.30.0

data/plugins/dependencies/config/defaults.yml

@@ -0,0 +1,5 @@
+---
+:dependencies:
+  :libraries: []
+
+...

data/plugins/dependencies/dependencies.rake

@@ -0,0 +1,144 @@
+
+DEPENDENCIES_LIBRARIES.each do |deplib|
+
+  # Look up the name of this dependency library
+  deplib_name = @ceedling[DEPENDENCIES_SYM].get_name(deplib)
+
+  # Make sure the required working directories exists
+  # (don't worry about the subdirectories. That's the job of the dep's build tool)
+  paths = @ceedling[DEPENDENCIES_SYM].get_working_paths(deplib)
+  paths.each {|path| directory(path) }
+  task :directories => paths
+
+  all_deps = @ceedling[DEPENDENCIES_SYM].get_static_libraries_for_dependency(deplib) +
+             @ceedling[DEPENDENCIES_SYM].get_dynamic_libraries_for_dependency(deplib) +
+             @ceedling[DEPENDENCIES_SYM].get_include_directories_for_dependency(deplib) +
+             @ceedling[DEPENDENCIES_SYM].get_source_files_for_dependency(deplib)
+
+  # Add a rule for building the actual libraries from dependency list
+  (@ceedling[DEPENDENCIES_SYM].get_static_libraries_for_dependency(deplib) +
+   @ceedling[DEPENDENCIES_SYM].get_dynamic_libraries_for_dependency(deplib)
+  ).each do |libpath|
+    file libpath do |filetask|
+      path = filetask.name
+
+      # We double-check that it doesn't already exist, because this process sometimes
+      # produces multiple files, but they may have already been flagged as invoked
+      unless (File.exists?(path))
+
+        # Set Environment Variables, Fetch, and Build
+        @ceedling[DEPENDENCIES_SYM].set_env_if_required(path)
+        @ceedling[DEPENDENCIES_SYM].fetch_if_required(path)
+        @ceedling[DEPENDENCIES_SYM].build_if_required(path)
+      end
+    end
+  end
+
+  # Add a rule for building the source and includes from dependency list
+  (@ceedling[DEPENDENCIES_SYM].get_include_directories_for_dependency(deplib) +
+   @ceedling[DEPENDENCIES_SYM].get_source_files_for_dependency(deplib)
+  ).each do |libpath|
+    task libpath do |filetask|
+      path = filetask.name
+
+      unless (File.file?(path) || File.directory?(path))
+
+        # Set Environment Variables, Fetch, and Build
+        @ceedling[DEPENDENCIES_SYM].set_env_if_required(path)
+        @ceedling[DEPENDENCIES_SYM].fetch_if_required(path)
+        @ceedling[DEPENDENCIES_SYM].build_if_required(path)
+      end
+    end
+  end
+
+  # Give ourselves a way to trigger individual dependencies
+  namespace DEPENDENCIES_SYM do
+    namespace :deploy do
+      # Add task to directly just build this dependency
+      task(deplib_name => @ceedling[DEPENDENCIES_SYM].get_dynamic_libraries_for_dependency(deplib)) do |t,args|
+        @ceedling[DEPENDENCIES_SYM].deploy_if_required(deplib_name)
+      end
+    end
+
+    namespace :make do
+      # Add task to directly just build this dependency
+      task(deplib_name => all_deps)
+    end
+
+    namespace :clean do
+      # Add task to directly clobber this dependency
+      task(deplib_name) do
+        @ceedling[DEPENDENCIES_SYM].clean_if_required(deplib_name)
+      end
+    end
+
+    namespace :fetch do
+      # Add task to directly clobber this dependency
+      task(deplib_name) do
+        @ceedling[DEPENDENCIES_SYM].fetch_if_required(deplib_name)
+      end
+    end
+  end
+
+  # Add source files to our list of things to build during release
+  source_files = @ceedling[DEPENDENCIES_SYM].get_source_files_for_dependency(deplib)
+  task PROJECT_RELEASE_BUILD_TARGET => source_files
+
+  # Finally, add the static libraries to our RELEASE build dependency list
+  static_libs = @ceedling[DEPENDENCIES_SYM].get_static_libraries_for_dependency(deplib)
+  task RELEASE_SYM => static_libs
+
+  # Add the dynamic libraries to our RELEASE task dependency list so that they will be copied automatically
+  dynamic_libs = @ceedling[DEPENDENCIES_SYM].get_dynamic_libraries_for_dependency(deplib)
+  task RELEASE_SYM => dynamic_libs
+
+  # Add the include dirs / files to our list of dependencies for release
+  headers = @ceedling[DEPENDENCIES_SYM].get_include_directories_for_dependency(deplib)
+  task RELEASE_SYM => headers
+
+  # Paths to Libraries need to be Added to the Lib Path List
+  all_libs = static_libs + dynamic_libs
+  PATHS_LIBRARIES ||= []
+  all_libs.each {|lib| PATHS_LIBRARIES << File.dirname(lib) }
+  PATHS_LIBRARIES.uniq!
+  PATHS_LIBRARIES.reject!{|s| s.empty?}
+
+  # Libraries Need to be Added to the Library List
+  LIBRARIES_SYSTEM ||= []
+  all_libs.each {|lib| LIBRARIES_SYSTEM << File.basename(lib,'.*').sub(/^lib/,'') }
+  LIBRARIES_SYSTEM.uniq!
+  LIBRARIES_SYSTEM.reject!{|s| s.empty?}
+end
+
+# Add any artifact:include or :source folders to our release & test includes paths so linking and mocking work.
+@ceedling[DEPENDENCIES_SYM].add_headers_and_sources()
+
+# Add tasks for building or cleaning ALL depencies
+namespace DEPENDENCIES_SYM do
+  desc "Deploy missing dependencies."
+  task :deploy => DEPENDENCIES_LIBRARIES.map{|deplib| "#{DEPENDENCIES_SYM}:deploy:#{@ceedling[DEPENDENCIES_SYM].get_name(deplib)}"}
+
+  desc "Build any missing dependencies."
+  task :make => DEPENDENCIES_LIBRARIES.map{|deplib| "#{DEPENDENCIES_SYM}:make:#{@ceedling[DEPENDENCIES_SYM].get_name(deplib)}"}
+
+  desc "Clean all dependencies."
+  task :clean => DEPENDENCIES_LIBRARIES.map{|deplib| "#{DEPENDENCIES_SYM}:clean:#{@ceedling[DEPENDENCIES_SYM].get_name(deplib)}"}
+
+  desc "Fetch all dependencies."
+  task :fetch => DEPENDENCIES_LIBRARIES.map{|deplib| "#{DEPENDENCIES_SYM}:fetch:#{@ceedling[DEPENDENCIES_SYM].get_name(deplib)}"}
+end
+
+namespace :files do
+  desc "List all collected dependency libraries."
+  task :dependencies do
+    puts "dependency files:"
+    deps = []
+    DEPENDENCIES_LIBRARIES.each do |deplib|
+      deps << @ceedling[DEPENDENCIES_SYM].get_static_libraries_for_dependency(deplib)
+      deps << @ceedling[DEPENDENCIES_SYM].get_dynamic_libraries_for_dependency(deplib)
+    end
+    deps.flatten!
+    deps.sort.each {|dep| puts " - #{dep}"}
+    puts "file count: #{deps.size}"
+  end
+end

data/plugins/dependencies/lib/dependencies.rb

@@ -0,0 +1,231 @@
+require 'ceedling/plugin'
+require 'ceedling/constants'
+
+DEPENDENCIES_ROOT_NAME         = 'dependencies'
+DEPENDENCIES_TASK_ROOT         = DEPENDENCIES_ROOT_NAME + ':'
+DEPENDENCIES_SYM               = DEPENDENCIES_ROOT_NAME.to_sym
+
+class Dependencies < Plugin
+
+  def setup
+    @plugin_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+    # Set up a fast way to look up dependencies by name or static lib path
+    @dependencies = {}
+    @dynamic_libraries = []
+    DEPENDENCIES_LIBRARIES.each do |deplib|
+
+      @dependencies[ deplib[:name] ] = deplib.clone
+      all_deps = get_static_libraries_for_dependency(deplib) +
+                 get_dynamic_libraries_for_dependency(deplib) +
+                 get_include_directories_for_dependency(deplib) +
+                 get_source_files_for_dependency(deplib)
+      all_deps.each do |key|
+        @dependencies[key] = @dependencies[ deplib[:name] ]
+      end
+
+      @dynamic_libraries += get_dynamic_libraries_for_dependency(deplib)
+    end
+  end
+
+  def config
+    updates = {
+      :collection_paths_include => COLLECTION_PATHS_INCLUDE,
+      :collection_all_headers => COLLECTION_ALL_HEADERS,
+    }
+
+    @ceedling[DEPENDENCIES_SYM].get_include_directories_for_dependency(deplib).each do |incpath|
+      updates[:collection_paths_include] << incpath
+      Dir[ File.join(incpath, "*#{EXTENSION_HEADER}") ].each do |f|
+        updates[:collection_all_headers] << f
+      end
+    end
+
+    return updates
+  end
+
+  def get_name(deplib)
+    raise "Each dependency must have a name!" if deplib[:name].nil?
+    return deplib[:name].gsub(/\W*/,'')
+  end
+
+  def get_source_path(deplib)
+    return deplib[:source_path] || File.join('dependencies', get_name(deplib))
+  end
+
+  def get_build_path(deplib)
+    return deplib[:build_path] || deplib[:source_path] || File.join('dependencies', get_name(deplib))
+  end
+
+  def get_artifact_path(deplib)
+    return deplib[:artifact_path] || deplib[:source_path] || File.join('dependencies', get_name(deplib))
+  end
+
+  def get_working_paths(deplib)
+    paths = [deplib[:source_path], deplib[:build_path], deplib[:artifact_paths]].compact.uniq
+    paths = [ File.join('dependencies', get_name(deplib)) ] if (paths.empty?)
+    return paths
+  end
+
+  def get_static_libraries_for_dependency(deplib)
+    (deplib[:artifacts][:static_libraries] || []).map {|path| File.join(get_artifact_path(deplib), path)}
+  end
+
+  def get_dynamic_libraries_for_dependency(deplib)
+    (deplib[:artifacts][:dynamic_libraries] || []).map {|path| File.join(get_artifact_path(deplib), path)}
+  end
+
+  def get_source_files_for_dependency(deplib)
+    (deplib[:artifacts][:source] || []).map {|path| File.join(get_artifact_path(deplib), path)}
+  end
+
+  def get_include_directories_for_dependency(deplib)
+    paths = (deplib[:artifacts][:includes] || []).map {|path| File.join(get_artifact_path(deplib), path)}
+    @ceedling[:file_system_utils].collect_paths(paths)
+  end
+
+  def set_env_if_required(lib_path)
+    blob = @dependencies[lib_path]
+    raise "Could not find dependency '#{lib_path}'" if blob.nil?
+    return if (blob[:environment].nil?)
+    return if (blob[:environment].empty?)
+
+    blob[:environment].each do |e|
+      m = e.match(/^(\w+)\s*(\+?\-?=)\s*(.*)$/)
+      unless m.nil?
+        case m[2]
+        when "+="
+          ENV[m[1]] = (ENV[m[1]] || "") + m[3]
+        when "-="
+          ENV[m[1]] = (ENV[m[1]] || "").gsub(m[3],'')
+        else
+          ENV[m[1]] = m[3]
+        end
+      end
+    end
+  end
+
+  def fetch_if_required(lib_path)
+    blob = @dependencies[lib_path]
+    raise "Could not find dependency '#{lib_path}'" if blob.nil?
+    return if (blob[:fetch].nil?)
+    return if (blob[:fetch][:method].nil?)
+    return if (directory(blob[:source_path]) && !Dir.empty?(blob[:source_path]))
+
+    steps = case blob[:fetch][:method]
+            when :none
+              return
+            when :zip
+              [ "gzip -d #{blob[:fetch][:source]}" ]
+            when :git
+              branch = blob[:fetch][:tag] || blob[:fetch][:branch] || ''
+              branch = ("-b " + branch) unless branch.empty?
+              retval = [ "git clone #{branch} --depth 1 #{blob[:fetch][:source]} ." ]
+              retval << "git checkout #{blob[:fetch][:hash]}" unless blob[:fetch][:hash].nil?
+              retval
+            when :svn
+              revision = blob[:fetch][:revision] || ''
+              revision = ("--revision " + branch) unless branch.empty?
+              retval = [ "svn checkout #{revision} #{blob[:fetch][:source]} ." ]
+              retval
+            when :custom
+              blob[:fetch][:executable]
+            else
+              raise "Unknown fetch method '#{blob[:fetch][:method].to_s}' for dependency '#{blob[:name]}'"
+            end
+
+    # Perform the actual fetching
+    @ceedling[:streaminator].stdout_puts("Fetching dependency #{blob[:name]}...", Verbosity::NORMAL)
+    Dir.chdir(get_source_path(blob)) do
+      steps.each do |step|
+        @ceedling[:tool_executor].exec( step )
+      end
+    end
+  end
+
+  def build_if_required(lib_path)
+    blob = @dependencies[lib_path]
+    raise "Could not find dependency '#{lib_path}'" if blob.nil?
+
+    # We don't clean anything unless we know how to fetch a new copy
+    if (blob[:build].nil? || blob[:build].empty?)
+      @ceedling[:streaminator].stdout_puts("Nothing to build for dependency #{blob[:name]}", Verbosity::NORMAL)
+      return
+    end
+
+    # Perform the build
+    @ceedling[:streaminator].stdout_puts("Building dependency #{blob[:name]}...", Verbosity::NORMAL)
+    Dir.chdir(get_build_path(blob)) do
+      blob[:build].each do |step|
+        @ceedling[:tool_executor].exec( step )
+      end
+    end
+  end
+
+  def clean_if_required(lib_path)
+    blob = @dependencies[lib_path]
+    raise "Could not find dependency '#{lib_path}'" if blob.nil?
+
+    # We don't clean anything unless we know how to fetch a new copy
+    if (blob[:fetch].nil? || blob[:fetch][:method].nil? || (blob[:fetch][:method] == :none))
+      @ceedling[:streaminator].stdout_puts("Nothing to clean for dependency #{blob[:name]}", Verbosity::NORMAL)
+      return
+    end
+
+    # Perform the actual Cleaning
+    @ceedling[:streaminator].stdout_puts("Cleaning dependency #{blob[:name]}...", Verbosity::NORMAL)
+    get_working_paths(blob).each do |path|
+      FileUtils.rm_rf(path) if File.directory?(path)
+    end
+  end
+
+  def deploy_if_required(lib_path)
+    blob = @dependencies[lib_path]
+    raise "Could not find dependency '#{lib_path}'" if blob.nil?
+
+    # We don't need to deploy anything if there isn't anything to deploy
+    if (blob[:artifacts].nil? || blob[:artifacts][:dynamic_libraries].nil?  || blob[:artifacts][:dynamic_libraries].empty?)
+      @ceedling[:streaminator].stdout_puts("Nothing to deploy for dependency #{blob[:name]}", Verbosity::NORMAL)
+      return
+    end
+
+    # Perform the actual Deploying
+    @ceedling[:streaminator].stdout_puts("Deploying dependency #{blob[:name]}...", Verbosity::NORMAL)
+    FileUtils.cp( lib_path, File.dirname(PROJECT_RELEASE_BUILD_TARGET) )
+  end
+
+  def add_headers_and_sources()
+    # Search for header file paths and files to add to our collections
+    DEPENDENCIES_LIBRARIES.each do |deplib|
+      get_include_directories_for_dependency(deplib).each do |header|
+        cfg = @ceedling[:configurator].project_config_hash
+        cfg[:collection_paths_include] << header
+        cfg[:collection_paths_source_and_include] << header
+        cfg[:collection_paths_test_support_source_include] << header
+        cfg[:collection_paths_test_support_source_include_vendor] << header
+        cfg[:collection_paths_release_toolchain_include] << header
+        Dir[ File.join(header, "*#{EXTENSION_HEADER}") ].each do |f|
+          cfg[:collection_all_headers] << f
+        end
+      end
+
+      get_source_files_for_dependency(deplib).each do |source|
+        cfg = @ceedling[:configurator].project_config_hash
+        cfg[:collection_paths_source_and_include] << source
+        cfg[:collection_paths_test_support_source_include] << source
+        cfg[:collection_paths_test_support_source_include_vendor] << source
+        cfg[:collection_paths_release_toolchain_include] << source
+        Dir[ File.join(source, "*#{EXTENSION_SOURCE}") ].each do |f|
+          cfg[:collection_all_source] << f
+        end
+      end
+    end
+
+    # Make all these updated files findable by Ceedling
+    @ceedling[:file_finder].prepare_search_sources()
+  end
+end
+
+# end blocks always executed following rake run
+END {
+}

data/plugins/fake_function_framework/README.md

@@ -1,250 +1,250 @@
-# A Fake Function Framework Plug-in for Ceedling
-
-This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
-
-Using fff provides less strict mocking than CMock, and allows for more loosely-coupled tests.
-And, when tests fail -- since you get the actual line number of the failure -- it's a lot easier to figure out what went wrong.
-
-## Installing the plug-in
-
-To use the plugin you need to 1) get the contents of this repo and 2) configure your project to use it.
-
-### Get the source
-
-The easiest way to get the source is to just clone this repo into the Ceedling plugin folder for your existing Ceedling project.
-(Don't have a Ceedling project already? [Here are instructions to create one.](http://www.electronvector.com/blog/try-embedded-test-driven-development-right-now-with-ceedling))
-From within `<your-project>/vendor/ceedling/plugins`, run:
-
-`git clone https://github.com/ElectronVector/fake_function_framework.git`
-
-This will create a new folder named `fake_function_framework` in the plugins folder.
-
-### Enable the plug-in.
-
-The plug-in is enabled from within your project.yml file.
-
-In the `:plugins` configuration, add `fake_function_framework` to the list of enabled plugins:
-
-```yaml
-:plugins:
-  :load_paths:
-    - vendor/ceedling/plugins
-  :enabled:
-    - stdout_pretty_tests_report
-    - module_generator
-    - fake_function_framework
-```
-*Note that you could put the plugin source in some other loaction.
-In that case you'd need to add a new path the `:load_paths`.*
-
-## How to use it
-
-You use fff with Ceedling the same way you used to use CMock.
-Modules can still be generated with the default module generator: `rake module:create[my_module]`.
-If you want to "mock" `some_module.h` in your tests, just `#include "mock_some_module.h"`.
-This creates a fake function for each of the functions defined in `some_module.h`.
-
-The name of each fake is the original function name with an appended `_fake`.
-For example, if we're generating fakes for a stack module with `push` and `pop` functions, we would have the fakes `push_fake` and `pop_fake`.
-These fakes are linked into our test executable so that any time our unit under test calls `push` or `pop` our fakes are called instead.
-
-Each of these fakes is actually a structure containing information about how the function was called, and what it might return.
-We can use Unity to inspect these fakes in our tests, and verify the interactions of our units.
-There is also a global structure named `fff` which we can use to check the sequence of calls.
-
-The fakes can also be configured to return particular values, so you can exercise the unit under test however you want.
-
-The examples below explain how to use fff to test a variety of module interactions.
-Each example uses fakes for a "display" module, created from a display.h file with `#include "mock_display.h"`. The `display.h` file must exist and must contain the prototypes for the functions to be faked.
-
-### Test that a function was called once
-
-```c
-void
-test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
-{
-    // When
-    event_deviceReset();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
-}
-```
-
-### Test that a function was NOT called
-
-```c
-void
-test_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
-{
-    // When
-    event_powerReadingUpdate(4);
-
-    // Then
-    TEST_ASSERT_EQUAL(0, display_turnOnStatusLed_fake.call_count);
-}
-```
-
-## Test that a single function was called with the correct argument
-
-```c
-void
-test_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
-{
-    // When
-    event_volumeKnobMaxed();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_setVolume_fake.call_count);
-    TEST_ASSERT_EQUAL(11, display_setVolume_fake.arg0_val);
-}
-```
-
-## Test that calls are made in a particular sequence
-
-```c
-void
-test_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
-{
-    // When
-    event_modeSelectButtonPressed();
-    event_modeSelectButtonPressed();
-    event_modeSelectButtonPressed();
-
-    // Then
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMinimum, fff.call_history[0]);
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMaximum, fff.call_history[1]);
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToAverage, fff.call_history[2]);
-}
-```
-
-## Fake a return value from a function
-
-```c
-void
-test_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredDown(void)
-{
-    // Given
-    display_isError_fake.return_val = true;
-
-    // When
-    event_devicePoweredOn();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
-}
-```
-
-## Fake a function with a value returned by reference
-
-```c
-void
-test_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPoweredDown(void)
-{
-    // Given
-    char mockedEntry[] = "sleep";
-    void return_mock_value(char * entry, int length)
-    {
-        if (length > strlen(mockedEntry))
-        {
-            strncpy(entry, mockedEntry, length);
-        }
-    }
-    display_getKeyboardEntry_fake.custom_fake = return_mock_value;
-
-    // When
-    event_keyboardCheckTimerExpired();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
-}
-```
-
-## Fake a function with a function pointer parameter
-
-```
-void
-test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
-{
-    // A mock function for capturing the callback handler function pointer.
-    void(*registeredCallback)(void) = 0;
-    void mock_display_updateData(int data, void(*callback)(void))
-    {
-        //Save the callback function.
-        registeredCallback = callback;
-    }
-    display_updateData_fake.custom_fake = mock_display_updateData;
-
-    // Given
-    event_newDataAvailable(10);
-
-    // When
-    if (registeredCallback != 0)
-    {
-        registeredCallback();
-    }
-
-    // Then
-    TEST_ASSERT_EQUAL(true, eventProcessor_isLastEventComplete());
-}
-```
-
-## Helper macros
-
-For convenience, there are also some helper macros that create new Unity-style asserts:
-
-- `TEST_ASSERT_CALLED(function)`: Asserts that a function was called once.
-- `TEST_ASSERT_NOT_CALLED(function)`: Asserts that a function was never called.
-- `TEST_ASSERT_CALLED_TIMES(times, function)`: Asserts that a function was called a particular number of times.
-- `TEST_ASSERT_CALLED_IN_ORDER(order, function)`: Asserts that a function was called in a particular order.
-
-Here's how you might use one of these instead of simply checking the call_count value:
-
-```c
-void
-test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
-{
-    // When
-    event_deviceReset();
-
-    // Then
-    // This how to directly use fff...
-    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
-    // ...and this is how to use the helper macro.
-    TEST_ASSERT_CALLED(display_turnOffStatusLed);
-}
-```
-
-## Test setup
-
-All of the fake functions, and any fff global state are all reset automatically between each test.
-
-## CMock configuration
-
-Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.
-
-```yaml
-:cmock:
-    :mock_prefix: mock_
-        :includes:
-            -
-        :includes_h_pre_orig_header:
-            -
-        :includes_h_post_orig_header:
-            -
-        :includes_c_pre_header:
-            -
-        :includes_c_post_header:
-```
-
-## Running the tests
-
-There are unit and integration tests for the plug-in itself.
-These are run with the default `rake` task.
-The integration test runs the tests for the example project in examples/fff_example.
-For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.
-
-## More examples
-
-There is an example project in examples/fff_example.
-It shows how to use the plug-in with some full-size examples.
+# A Fake Function Framework Plug-in for Ceedling
+
+This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
+
+Using fff provides less strict mocking than CMock, and allows for more loosely-coupled tests.
+And, when tests fail -- since you get the actual line number of the failure -- it's a lot easier to figure out what went wrong.
+
+## Installing the plug-in
+
+To use the plugin you need to 1) get the contents of this repo and 2) configure your project to use it.
+
+### Get the source
+
+The easiest way to get the source is to just clone this repo into the Ceedling plugin folder for your existing Ceedling project.
+(Don't have a Ceedling project already? [Here are instructions to create one.](http://www.electronvector.com/blog/try-embedded-test-driven-development-right-now-with-ceedling))
+From within `<your-project>/vendor/ceedling/plugins`, run:
+
+`git clone https://github.com/ElectronVector/fake_function_framework.git`
+
+This will create a new folder named `fake_function_framework` in the plugins folder.
+
+### Enable the plug-in.
+
+The plug-in is enabled from within your project.yml file.
+
+In the `:plugins` configuration, add `fake_function_framework` to the list of enabled plugins:
+
+```yaml
+:plugins:
+  :load_paths:
+    - vendor/ceedling/plugins
+  :enabled:
+    - stdout_pretty_tests_report
+    - module_generator
+    - fake_function_framework
+```
+*Note that you could put the plugin source in some other loaction.
+In that case you'd need to add a new path the `:load_paths`.*
+
+## How to use it
+
+You use fff with Ceedling the same way you used to use CMock.
+Modules can still be generated with the default module generator: `rake module:create[my_module]`.
+If you want to "mock" `some_module.h` in your tests, just `#include "mock_some_module.h"`.
+This creates a fake function for each of the functions defined in `some_module.h`.
+
+The name of each fake is the original function name with an appended `_fake`.
+For example, if we're generating fakes for a stack module with `push` and `pop` functions, we would have the fakes `push_fake` and `pop_fake`.
+These fakes are linked into our test executable so that any time our unit under test calls `push` or `pop` our fakes are called instead.
+
+Each of these fakes is actually a structure containing information about how the function was called, and what it might return.
+We can use Unity to inspect these fakes in our tests, and verify the interactions of our units.
+There is also a global structure named `fff` which we can use to check the sequence of calls.
+
+The fakes can also be configured to return particular values, so you can exercise the unit under test however you want.
+
+The examples below explain how to use fff to test a variety of module interactions.
+Each example uses fakes for a "display" module, created from a display.h file with `#include "mock_display.h"`. The `display.h` file must exist and must contain the prototypes for the functions to be faked.
+
+### Test that a function was called once
+
+```c
+void
+test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
+{
+    // When
+    event_deviceReset();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
+}
+```
+
+### Test that a function was NOT called
+
+```c
+void
+test_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
+{
+    // When
+    event_powerReadingUpdate(4);
+
+    // Then
+    TEST_ASSERT_EQUAL(0, display_turnOnStatusLed_fake.call_count);
+}
+```
+
+## Test that a single function was called with the correct argument
+
+```c
+void
+test_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
+{
+    // When
+    event_volumeKnobMaxed();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_setVolume_fake.call_count);
+    TEST_ASSERT_EQUAL(11, display_setVolume_fake.arg0_val);
+}
+```
+
+## Test that calls are made in a particular sequence
+
+```c
+void
+test_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
+{
+    // When
+    event_modeSelectButtonPressed();
+    event_modeSelectButtonPressed();
+    event_modeSelectButtonPressed();
+
+    // Then
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMinimum, fff.call_history[0]);
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMaximum, fff.call_history[1]);
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToAverage, fff.call_history[2]);
+}
+```
+
+## Fake a return value from a function
+
+```c
+void
+test_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredDown(void)
+{
+    // Given
+    display_isError_fake.return_val = true;
+
+    // When
+    event_devicePoweredOn();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
+}
+```
+
+## Fake a function with a value returned by reference
+
+```c
+void
+test_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPoweredDown(void)
+{
+    // Given
+    char mockedEntry[] = "sleep";
+    void return_mock_value(char * entry, int length)
+    {
+        if (length > strlen(mockedEntry))
+        {
+            strncpy(entry, mockedEntry, length);
+        }
+    }
+    display_getKeyboardEntry_fake.custom_fake = return_mock_value;
+
+    // When
+    event_keyboardCheckTimerExpired();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
+}
+```
+
+## Fake a function with a function pointer parameter
+
+```
+void
+test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
+{
+    // A mock function for capturing the callback handler function pointer.
+    void(*registeredCallback)(void) = 0;
+    void mock_display_updateData(int data, void(*callback)(void))
+    {
+        //Save the callback function.
+        registeredCallback = callback;
+    }
+    display_updateData_fake.custom_fake = mock_display_updateData;
+
+    // Given
+    event_newDataAvailable(10);
+
+    // When
+    if (registeredCallback != 0)
+    {
+        registeredCallback();
+    }
+
+    // Then
+    TEST_ASSERT_EQUAL(true, eventProcessor_isLastEventComplete());
+}
+```
+
+## Helper macros
+
+For convenience, there are also some helper macros that create new Unity-style asserts:
+
+- `TEST_ASSERT_CALLED(function)`: Asserts that a function was called once.
+- `TEST_ASSERT_NOT_CALLED(function)`: Asserts that a function was never called.
+- `TEST_ASSERT_CALLED_TIMES(times, function)`: Asserts that a function was called a particular number of times.
+- `TEST_ASSERT_CALLED_IN_ORDER(order, function)`: Asserts that a function was called in a particular order.
+
+Here's how you might use one of these instead of simply checking the call_count value:
+
+```c
+void
+test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
+{
+    // When
+    event_deviceReset();
+
+    // Then
+    // This how to directly use fff...
+    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
+    // ...and this is how to use the helper macro.
+    TEST_ASSERT_CALLED(display_turnOffStatusLed);
+}
+```
+
+## Test setup
+
+All of the fake functions, and any fff global state are all reset automatically between each test.
+
+## CMock configuration
+
+Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.
+
+```yaml
+:cmock:
+    :mock_prefix: mock_
+        :includes:
+            -
+        :includes_h_pre_orig_header:
+            -
+        :includes_h_post_orig_header:
+            -
+        :includes_c_pre_header:
+            -
+        :includes_c_post_header:
+```
+
+## Running the tests
+
+There are unit and integration tests for the plug-in itself.
+These are run with the default `rake` task.
+The integration test runs the tests for the example project in examples/fff_example.
+For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.
+
+## More examples
+
+There is an example project in examples/fff_example.
+It shows how to use the plug-in with some full-size examples.