ceedling 0.29.1 → 0.30.0

data/plugins/colour_report/README.md

@@ -0,0 +1,20 @@
+ceedling-colour-report
+======================
+
+## Overview
+
+The colour_report replaces the normal ceedling "pretty" output with 
+a colorized variant, in order to make the results easier to read from
+a standard command line. This is very useful on developer machines, but
+can occasionally cause problems with parsing on CI servers.
+
+## Setup
+
+Enable the plugin in your project.yml by adding `colour_report`
+to the list of enabled plugins.
+
+``` YAML
+:plugins:
+  :enabled:
+    - colour_report
+```

data/plugins/colour_report/lib/colour_report.rb

@@ -1,16 +1,16 @@
-require 'ceedling/plugin'
-require 'ceedling/streaminator'
-require 'ceedling/constants'
-
-class ColourReport < Plugin
-
-  def setup
-    @ceedling[:stream_wrapper].stdout_override(&ColourReport.method(:colour_stdout))
-  end
-
-  def self.colour_stdout(string)
-    require 'colour_reporter.rb'
-    report string
-  end
-
-end
+require 'ceedling/plugin'
+require 'ceedling/streaminator'
+require 'ceedling/constants'
+
+class ColourReport < Plugin
+
+  def setup
+    @ceedling[:stream_wrapper].stdout_override(&ColourReport.method(:colour_stdout))
+  end
+
+  def self.colour_stdout(string)
+    require 'colour_reporter.rb'
+    report string
+  end
+
+end

data/plugins/command_hooks/README.md

@@ -1,53 +1,53 @@
-ceedling-command-hooks
-======================
-
-Plugin for easily calling command line tools at various points in the build process
-
-Define any of these sections in :tools: to provide additional hooks to be called on demand:
-
-```
-    :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
-    :pre_test
-    :post_test
-    :pre_release
-    :post_release
-    :pre_build
-    :post_build
-```
-
-Each of these tools can support an :executable string and an :arguments list, like so:
-
-```
-:tools:
-  :post_link_execute:
-    :executable: objcopy.exe
-    :arguments:
-      - ${1} #This is replaced with the executable name
-      - output.srec
-      - --strip-all
-```
-
-You may also specify an array of executables to be called in a particular place, like so:
-
-```
-:tools:
-  :post_test:
-    -  :executable: echo
-       :arguments: "${1} was glorious!"
-    -  :executable: echo
-       :arguments:
-         - it kinda made me cry a little.
-         - you?
-```
-
-Please note that it varies which arguments are being parsed down to the
-hooks. For now see `command_hooks.rb` to figure out which suits you best.
-Happy Tweaking!
+ceedling-command-hooks
+======================
+
+Plugin for easily calling command line tools at various points in the build process
+
+Define any of these sections in :tools: to provide additional hooks to be called on demand:
+
+```
+    :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
+    :pre_test
+    :post_test
+    :pre_release
+    :post_release
+    :pre_build
+    :post_build
+```
+
+Each of these tools can support an :executable string and an :arguments list, like so:
+
+```
+:tools:
+  :post_link_execute:
+    :executable: objcopy.exe
+    :arguments:
+      - ${1} #This is replaced with the executable name
+      - output.srec
+      - --strip-all
+```
+
+You may also specify an array of executables to be called in a particular place, like so:
+
+```
+:tools:
+  :post_test:
+    -  :executable: echo
+       :arguments: "${1} was glorious!"
+    -  :executable: echo
+       :arguments:
+         - it kinda made me cry a little.
+         - you?
+```
+
+Please note that it varies which arguments are being parsed down to the
+hooks. For now see `command_hooks.rb` to figure out which suits you best.
+Happy Tweaking!

data/plugins/command_hooks/lib/command_hooks.rb

@@ -1,92 +1,92 @@
-require 'ceedling/plugin'
-require 'ceedling/constants'
-class CommandHooks < Plugin
-
-  attr_reader :config
-
-  def setup
-    @config = {
-      :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 ),
-    }
-    @plugin_root = File.expand_path(File.join(File.dirname(__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
-
-  ##
-  # 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(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[:line], cmd[:options])
-    end
-  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])
-      @ceedling[:streaminator].stdout_puts("Running Hook #{which_hook}...", Verbosity::NORMAL)
-      if (@config[which_hook].is_a? Array)
-        @config[which_hook].each do |hook|
-          run_hook_step(hook, name)
-        end
-      elsif (@config[which_hook].is_a? Hash)
-        run_hook_step( @config[which_hook], name )
-      else
-        @ceedling[:streaminator].stdout_puts("Hook #{which_hook} was poorly formed", Verbosity::COMPLAINT)
-      end
-    end
-  end
-end
-
+require 'ceedling/plugin'
+require 'ceedling/constants'
+class CommandHooks < Plugin
+
+  attr_reader :config
+
+  def setup
+    @config = {
+      :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 ),
+    }
+    @plugin_root = File.expand_path(File.join(File.dirname(__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
+
+  ##
+  # 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(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[:line], cmd[:options])
+    end
+  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])
+      @ceedling[:streaminator].stdout_puts("Running Hook #{which_hook}...", Verbosity::NORMAL)
+      if (@config[which_hook].is_a? Array)
+        @config[which_hook].each do |hook|
+          run_hook_step(hook, name)
+        end
+      elsif (@config[which_hook].is_a? Hash)
+        run_hook_step( @config[which_hook], name )
+      else
+        @ceedling[:streaminator].stdout_puts("Hook #{which_hook} was poorly formed", Verbosity::COMPLAINT)
+      end
+    end
+  end
+end
+

data/plugins/compile_commands_json/README.md

@@ -0,0 +1,29 @@
+compile_commands_json
+=====================
+
+## Overview
+
+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. Often developers would still to an IDE that felt cumbersome and slow just because it had the best syntax highlighting on the market. If doing it for one language is hard (and it is) imagine doing it for dozens of them. Imagine a full stack developer who has to work with CSS, HTML, JavaScript and some Ruby - they need excellent support in all those languages which just made things even harder.
+
+In June of 2016, Microsoft with Red Hat and Codenvy got together to create a standard called the Language Server Protocol (LSP). The idea was simple, by standardising on one protocol, all the IDEs and editors out there would only have to support LSP, and not have custom plugins for each language. In turn, the backend code that actually does the highlighting can be written once and used by any IDE that supports LSP. Many editors already support it such as Sublime Text, vim and emacs. This means that if you're using a crufty old IDE or worse, you're using a shiny new editor without code completion, then this could be just the upgrade you're looking for!
+
+For C and C++ projects, many people use the `clangd` backend. So that it can do things like "go to definition", `clangd` needs to know how to build the project so that it can figure out all the pieces to the puzzle. There are manual tools such as `bear` which can be run with `gcc` or `clang` to extract this information it has a big limitation in that if run with `ceedling release` you won't get any auto completion for Unity and you'll also get error messages reported by your IDE because of what it perceives as missing headers. If you do the same with `ceedling test` now you get Unity but you might miss things that are only seen in the release build.
+
+This plugin resolves that issue. As it is run by Ceedling, it has access to all the build information it needs to create the perfect `compile_commands.json`. Once enabled, this plugin will generate that file and place it in `./build/artifacts/compile_commands.json`. `clangd` will search your project for this file, but it is easier to symlink it into the root directory (for example `ln -s ./build/artifacts/compile_commands.json`. 
+
+For more information on LSP and to find out if your editor supports it, check out https://langserver.org/
+
+## Setup
+
+Enable the plugin in your project.yml by adding `compile_commands_json` to the list
+of enabled plugins.
+
+``` YAML
+:plugins:
+  :enabled:
+    - compile_commands_json
+```
+
+## Configuration
+
+There is no additional configuration necessary to run this plugin.

data/plugins/compile_commands_json/lib/compile_commands_json.rb

@@ -0,0 +1,35 @@
+require 'ceedling/plugin'
+require 'ceedling/constants'
+require 'json'
+
+class CompileCommandsJson < Plugin
+  def setup
+    @fullpath = File.join(PROJECT_BUILD_ARTIFACTS_ROOT, "compile_commands.json")
+    @database = if (File.exists?(@fullpath))
+                  JSON.parse( File.read(@fullpath) )
+                else
+                  []
+                end
+  end
+
+  def post_compile_execute(arg_hash)
+
+    # Create the new Entry
+    value = {
+      "directory" => Dir.pwd,
+      "command" => arg_hash[:shell_command],
+      "file" => arg_hash[:source]
+    }
+
+    # 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
+
+    # Update the Actual compile_commands.json file
+    File.open(@fullpath,'w') {|f| f << JSON.pretty_generate(@database)}
+  end
+end

data/plugins/dependencies/README.md

@@ -0,0 +1,254 @@
+ceedling-dependencies
+=====================
+
+Plugin for supporting release dependencies. It's rare for an embedded project to
+be built completely free of other libraries and modules. Some of these may be
+standard internal libraries. Some of these may be 3rd party libraries. In either
+case, they become part of the project's ecosystem.
+
+This plugin is intended to make that relationship easier. It allows you to specify
+a source for dependencies. If required, it will automatically grab the appropriate
+version of that dependency.
+
+Most 3rd party libraries have a method of building already in place. While we'd
+love to convert the world to a place where everything downloads with a test suite
+in Ceedling, that's not likely to happen anytime soon. Until then, this plugin
+will allow the developer to specify what calls Ceedling should make to oversee
+the build process of those third party utilities. Are they using Make? CMake? A
+custom series of scripts that only a mad scientist could possibly understand? No
+matter. Ceedling has you covered. Just specify what should be called, and Ceedling
+will make it happen whenever it notices that the output artifacts are missing.
+
+Output artifacts? Sure! Things like static and dynamic libraries, or folders
+containing header files that might want to be included by your release project.
+
+So how does all this magic work?
+
+First, you need to add the `:dependencies` plugin to your list. Then, we'll add a new
+section called :dependencies. There, you can list as many dependencies as you desire. Each
+has a series of fields which help Ceedling to understand your needs. Many of them are
+optional. If you don't need that feature, just don't include it! In the end, it'll look
+something like this:
+
+```
+:dependencies:
+  :libraries:
+    - :name: WolfSSL
+      :source_path:   third_party/wolfssl/source
+      :build_path:    third_party/wolfssl/build
+      :artifact_path: third_party/wolfssl/install
+      :fetch:
+        :method: :zip
+        :source: \\shared_drive\third_party_libs\wolfssl\wolfssl-4.2.0.zip
+      :environment:
+        - CFLAGS+=-DWOLFSSL_DTLS_ALLOW_FUTURE
+      :build:
+        - "autoreconf -i"
+        - "./configure --enable-tls13 --enable-singlethreaded"
+        - make
+        - make install
+      :artifacts:
+        :static_libraries:
+          - lib/wolfssl.a
+        :dynamic_libraries:
+          - lib/wolfssl.so
+        :includes:
+          - include/**
+```
+
+Let's take a deeper look at each of these features.
+
+The Starting Dash & Name
+------------------------
+
+Yes, that opening dash tells the dependencies plugin that the rest of these fields
+belong to our first dependency. If we had a second dependency, we'd have another
+dash, lined up with the first, and followed by all the fields indented again.
+
+By convention, we use the `:name` field as the first field for each tool. Ceedling
+honestly doesn't care which order the fields are given... but as humans, it makes
+it easier for us to see the name of each dependency with starting dash.
+
+The name field is only used to print progress while we're running Ceedling. You may
+call the name of the field whatever you wish.
+
+Working Folders
+---------------
+
+The `:source_path` field allows us to specify where the source code for each of our
+dependencies is stored. If fetching the dependency from elsewhere, it will be fetched
+to this location. All commands to build this dependency will be executed from
+this location (override this by specifying a `:build_path`). Finally, the output
+artifacts will be referenced to this location (override this by specifying a `:artifact_path`)
+
+If unspecified, the `:source_path` will be `dependencies\dep_name` where `dep_name`
+is the name specified in `:name` above (with special characters removed). It's best,
+though, if you specify exactly where you want your dependencies to live.
+
+If the dependency is directly included in your project (you've specified `:none` as the
+`:method` for fetching), then `:source_path` should be where your Ceedling can find the
+source for your dependency in you repo.
+
+All artifacts are relative to the `:artifact_path` (which defaults to be the same as
+`:source_path`)
+
+Fetching Dependencies
+---------------------
+
+The `:dependencies` plugin supports the ability to automatically fetch your dependencies
+for you... using some common methods of fetching source. This section contains only a
+couple of fields:
+
+- `:method` -- This is the method that this dependency is fetched.
+  - `:none` -- This tells Ceedling that the code is already included in the project.
+  - `:zip` -- This tells Ceedling that we want to unpack a zip file to our source path.
+  - `:git` -- This tells Ceedling that we want to clone a git repo to our source path.
+  - `:svn` -- This tells Ceedling that we want to checkout a subversion repo to our source path.
+  - `:custom` -- This tells Ceedling that we want to use a custom command or commands to fetch the code.
+- `:source` -- This is the path or url to fetch code when using the zip or git method.
+- `:tag`/`:branch` -- This is the specific tag or branch that you wish to retrieve (git only. optional).
+- `:hash` -- This is the specific SHA1 hash you want to fetch (git only. optional).
+- `:revision` -- This is the specific revision you want to fetch (svn only. optional).
+- `:executable` -- This is a list of commands to execute when using the `:custom` method
+
+
+Environment Variables
+---------------------
+
+Many build systems support customization through environment variables. By specifying
+an array of environment variables, Ceedling will customize the shell environment before
+calling the build process.
+
+Environment variables may be specified in three ways. Let's look at one of each:
+
+```
+  :environment:
+    - ARCHITECTURE=ARM9
+    - CFLAGS+=-DADD_AWESOMENESS
+    - CFLAGS-=-DWASTE
+```
+
+In the first example, you see the most straightforward method. The environment variable
+`ARCHITECTURE` is set to the value `ARM9`. That's it. Simple.
+
+The next two options modify an existing symbol. In the first one, we use `+=`, which tells
+Ceedling to add the define `ADD_AWESOMENESS` to the environment variable `CFLAGS`. The second
+tells Ceedling to remove the define `WASTE` from the same environment variable.
+
+There are a couple of things to note here.
+
+First, when adding to a variable, Ceedling has no way of knowing
+what delimiter you are expecting. In this example you can see we manually added some whitespace.
+If we had been modifying `PATH` instead, we might have had to use a `:` on a unux or `;` on
+Windows.
+
+Second, removing an argument will have no effect on the argument if that argument isn't found
+precisely. It's case sensitive and the entire string must match. If symbol doesn't already exist,
+it WILL after executing this command... however it will be assigned to nothing.
+
+Building Dependencies
+---------------------
+
+The heart of the `:dependencies` plugin is the ability for you, the developer, to specify the
+build process for each of your dependencies. You will need to have any required tools installed
+before using this feature.
+
+The steps are specified as an array of strings. Ceedling will execute those steps in the order
+specified, moving from step to step unless an error is encountered. By the end of the process,
+the artifacts should have been created by your process... otherwise an error will be produced.
+
+Artifacts
+---------
+
+These are the outputs of the build process. There are there types of artifacts. Any dependency
+may have none or some of these. Calling out these files tells Ceedling that they are important.
+Your dependency's build process may produce many other files... but these are the files that
+Ceedling understands it needs to act on.
+
+### `static_libraries`
+
+Specifying one or more static libraries will tell Ceedling where it should find static libraries
+output by your build process. These libraries are automatically added to the list of dependencies
+and will be linked with the rest of your code to produce the final release.
+
+If any of these libraries don't exist, Ceedling will trigger your build process in order for it
+to produce them.
+
+### `dynamic_libraries`
+
+Specifying one or more dynamic libraries will tell Ceedling where it should find dynamic libraries
+output by your build process. These libraries are automatically copied to the same folder as your
+final release binary.
+
+If any of these libraries don't exist, Ceedling will trigger your build process in order for it
+to produce them.
+
+### `includes`
+
+Often when libraries are built, the same process will output a collection of includes so that
+your release code knows how to interact with that library. It's the public API for that library.
+By specifying the directories that will contain these includes (don't specify the files themselves,
+Ceedling only needs the directories), Ceedling is able to automatically add these to its internal
+include list. This allows these files to be used while building your release code, as well we making
+them mockable during unit testing.
+
+### `source`
+
+It's possible that your external dependency will just produce additional C files as its output.
+In this case, Ceedling is able to automatically add these to its internal source list. This allows
+these files to be used while building your release code.
+
+Tasks
+-----
+
+Once configured correctly, the `:dependencies` plugin should integrate seamlessly into your
+workflow and you shouldn't have to think about it. In the real world, that doesn't always happen.
+Here are a number of tasks that are added or modified by this plugin.
+
+### `ceedling dependencies:clean`
+
+This can be issued in order to completely remove the dependency from its source path. On the
+next build, it will be refetched and rebuilt from scratch. This can also apply to a particular
+dependency. For example, by specifying `dependencies:clean:DepName`.
+
+### `ceedling dependencies:fetch`
+
+This can be issued in order to fetch each dependency from its origin. This will have no effect on
+dependencies that don't have fetch instructions specified. This can also apply to a particular
+dependency. For example, by specifying `dependencies:fetch:DepName`.
+
+### `ceedling dependencies:make`
+
+This will force the dependencies to all build. This should happen automatically when a release
+has been triggered... but if you're just getting your dependency configured at this moment, you
+may want to just use this feature instead. A single dependency can also be built by specifying its
+name, like `dependencies:make:MyTunaBoat`.
+
+### `ceedling dependencies:deploy`
+
+This will force any dynamic libraries produced by your dependencies to be copied to your release
+build directory... just in case you clobbered them.
+
+### `paths:include`
+
+Maybe you want to verify that all the include paths are correct. If you query Ceedling with this
+request, it will list all the header file paths that it's found, including those produced by
+dependencies.
+
+### `files:include`
+
+Maybe you want to take that query further and actually get a list of ALL the header files
+Ceedling has found, including those belonging to your dependencies.
+
+Testing
+=======
+
+Hopefully all your dependencies are fully tested... but we can't always depend on that.
+In the event that they are tested with Ceedling, you'll probably want to consider using
+the `:subprojects` plugin instead of this one. The purpose of this plugin is to pull in
+third party code for release... and to provide a mockable interface for Ceedling to use
+during its tests of other modules.
+
+If that's what you're after... you've found the right plugin!
+
+Happy Testing!