ceedling 0.12.2 → 0.13.0.rc1

data/.gitignore

@@ -1,15 +1,6 @@
-*.gem
-.bundle
+.*.swp
+.swp
 Gemfile.lock
-pkg/*
-doc
-.yardoc
-*.sublime-workspace
-
-new_project_template/vendor/ceedling/docs/CeedlingPacket.pdf
-new_project_template/vendor/ceedling/vendor/unity/auto/colour_prompt.rb
-new_project_template/vendor/ceedling/vendor/unity/auto/colour_reporter.rb
-new_project_template/vendor/ceedling/vendor/unity/auto/generate_config.yml
-new_project_template/vendor/ceedling/vendor/unity/auto/generate_module.rb
-new_project_template/vendor/ceedling/vendor/unity/auto/test_file_filter.rb
-new_project_template/vendor/ceedling/vendor/unity/auto/unity_test_summary.rb
+tags
+ceedling.sublime-project
+ceedling.sublime-workspace

data/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "vendor/c_exception"]
+	path = vendor/c_exception
+	url = git://github.com/ThrowTheSwitch/CException.git
+[submodule "vendor/unity"]
+	path = vendor/unity
+	url = git://github.com/ThrowTheSwitch/Unity.git
+[submodule "vendor/cmock"]
+	path = vendor/cmock
+	url = git://github.com/ThrowTheSwitch/CMock.git

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -1,3 +1,11 @@
-source :rubygems
+source "http://rubygems.org/"
 
-gemspec
+gem "bundler", "~> 1.1.rc.7"
+gem "rake", ">= 0.9.2.2"
+
+gem "rspec"
+gem "require_all"
+gem "constructor"
+gem "diy"
+gem "rr"
+gem "thor"

data/README.md

@@ -1,67 +1,97 @@
-Description
-===========
-[Ceedling](http://throwtheswitch.org/) is a set of tools and libraries for testing and building C applications. This gem is the distribution mechanism for ceedling. Be aware that gem is *not* ceedling itself.
-
-Usage
-=====
-
-New project
------------
-
-    ceedling new PROJECT
-
-Creates a new directory named PROJECT and deposits ceedling into the new directory.
-
-Update project
---------------
-
-    ceedling update DIRECTORY
-
-Updates an existing project with the newest ceedling code in the gem. To update, follow these steps:
-
-1. Remove the vendor/ceedling directory. Take care when doing this; make sure you do it in a way that your version control system can handle.
-1. Run ceedling update. Pass it the name of the directory that vendor/ceedling should go into.
-
-    `ceedling update .`
-
-   will copy ceedling to ./vendor/ceedling.
-1. Add the new directory to your version control system.
-
-List example project
---------------------
-
-    ceedling examples
-
-List the available example projects.
-
-Create example project
-----------------------
-
-    ceedling example PROJECT_NAME [DEST]
-
-Creates the specified example project in the current directory (or in destination directoy, if specified).
-
-Valid PROJECT_NAMEs
-
-* temp_sensor
-
-Print ceedling versions
------------------------
-
-    ceedling version
-
-This will print the version of the ceedling gem and all of the ceedling components it packages (Ceedling, Unity, CMock, CException).
-
-Resources
-=========
-Ceedling, Unity, CMock, and CException are all available at [throwtheswitch](http://throwtheswitch.org/).
-
-Authors
-=======
-* Mike Karlesky (michael@karlesky.net)
-* Mark VanderVoord (mvandervoord@gmail.com)
-* Greg Williams (williams@atomicembedded.com)
-* Matt Fletcher (fletcher@atomicobject.com)
-* Nick Christensen (nick.christensen@atomicembedded)
-* 
-* © 2012 [ThrowTheSwitch](http://throwtheswitch.org/
+Using Ceedling inside of a project
+==================================
+
+Ceedling can deploy all of its guts into a folder. This allows it
+to be used without having to worry about external dependencies.
+
+    ceedling new [your new project name]
+
+Using Ceedling outside of a project as a gem (EXPERIMENTAL AND AWKWARD)
+=======================================================================
+
+Ceedling can also be used as a gem. The following Rakefile is the
+bare minimum required in order to use Ceedling this way:
+
+    require 'ceedling'
+
+Additionally, a project.yml is required. Here is one to get you
+started:
+
+    ---
+    :project:
+      :use_exceptions: FALSE
+      :use_test_preprocessor: TRUE
+      :use_auxiliary_dependencies: TRUE
+      :build_root: build
+    #  :release_build: TRUE
+      :test_file_prefix: test_
+    
+    #:release_build:
+    #  :output: MyApp.out
+    #  :use_assembly: FALSE
+    
+    :environment:
+    
+    :extension:
+      :executable: .out
+    
+    :paths:
+      :test:
+        - +:test/**
+        - -:test/support
+      :source:
+        - src/**
+      :support:
+        - test/support
+    
+    :defines:
+      # in order to add common defines:
+      #  1) remove the trailing [] from the :common: section
+      #  2) add entries to the :common: section (e.g. :test: has TEST defined)
+      :commmon: &common_defines []
+      :test:
+        - *common_defines
+        - TEST
+      :test_preprocess:
+        - *common_defines
+        - TEST
+    
+    :cmock:
+      :when_no_prototypes: :warn
+      :enforce_strict_ordering: TRUE
+      :plugins:
+        - :ignore
+      :treat_as:
+        uint8:    HEX8
+        uint16:   HEX16
+        uint32:   UINT32
+        int8:     INT8
+        bool:     UINT8
+    
+    #:tools:
+    # Ceedling defaults to using gcc for compiling, linking, etc.
+    # As [:tools] is blank, gcc will be used (so long as it's in your system path)
+    # See documentation to configure a given toolchain for use
+    
+    :plugins:
+      :load_paths:
+        # This is required to use builtin ceedling plugins
+        - "#{builtin_ceedling_plugins_path}"
+        # Uncomment this and create the directory in order to use your own 
+        # custom ceedling plugins
+        # - ceedling_plugins
+      :enabled:
+        # These two plugins ship with Ceedling.
+        - stdout_pretty_tests_report
+        - module_generator
+    ...
+
+Finally, you'll need to create something like the following directory structure. This one matches the project.yml
+defined above:
+
+    ./test
+    ./test/support
+    ./src
+    ./project.yml
+    ./Rakefile
+    ./build

data/bin/ceedling

@@ -1,71 +1,104 @@
 #!/usr/bin/env ruby
-require "rubygems"
-require "thor"
-require "ceedling"
-require "fileutils"
+
+require 'rubygems'
+require 'fileutils'
+require 'thor'
+
+def here
+  File.dirname(__FILE__) + "/.."
+end
 
 class CeedlingTasks < Thor
   include Thor::Actions
 
-  def self.source_root
-    File.dirname(__FILE__) + "/.."
-  end
-
-  desc "new PROJECT_NAME", "create a new ceedling project"
+  desc "new PROJECT_NAME", "new a new ceedling project"
   method_option :nodocs, :type => :boolean, :default => false, :desc => "No docs in vendor directory"
-  def new(name)
-    directory Ceedling::NEW_PROJECT_DIR, name
-    remove_dir "#{name}/vendor/ceedling/docs" if options[:nodocs]
-    puts "\n"
-    puts "Project '#{name}' created!"
-    puts " - Tool documentation is located in vendor/ceedling/docs" if not options[:nodocs]
-    puts " - Execute 'rake -T' to view available test & build tasks"
-    puts ''
-  end
+  def new(name, silent = false)
+    ceedling_path     = File.join(name, 'vendor', 'ceedling')
+    source_path       = File.join(name, 'src')
+    test_path         = File.join(name, 'test')
+    test_support_path = File.join(name, 'test/support')
+    build_path        = File.join(name, 'build')
+
+    [ceedling_path, source_path, test_path, test_support_path, build_path].each do |d|
+      FileUtils.mkdir_p d
+    end
 
-  desc "update DIRECTORY", "update the vendor/ceedling directory under the given project root"
-  long_desc <<-d
-  copies the newest ceedling code into the vendor/ceedling directory under the given project root.
+    folders = %w{plugins lib release}
+    folders << 'docs' unless options[:nodocs]
 
-  NOTE: this task assumes the vendor/ceedling directory has already been deleted
+    folders.map do |f|
+      {:src => f, :dst => File.join(ceedling_path, f)}
+    end.each do |f|
+      directory f[:src], f[:dst]
+    end
 
-  Example: [ceedling update .] will deposit the latest ceedling files to ./vendor/ceedling 
-  d
-  method_option :nodocs, :type => :boolean, :default => false, :desc => "No docs in vendor directory"
-  def update(project_dir)
-    directory "new_project_template/vendor", "#{project_dir}/vendor"
-    remove_dir "#{project_dir}/vendor/ceedling/docs" if options[:nodocs]
+    sub_components = [
+      {:src => 'vendor/c_exception/lib/',     :dst => 'vendor/c_exception/lib'},
+      {:src => 'vendor/c_exception/release/', :dst => 'vendor/c_exception/release'},
+      {:src => 'vendor/cmock/config/',        :dst => 'vendor/cmock/config'},
+      {:src => 'vendor/cmock/lib/',           :dst => 'vendor/cmock/lib'},
+      {:src => 'vendor/cmock/release/',       :dst => 'vendor/cmock/release'},
+      {:src => 'vendor/cmock/src/',           :dst => 'vendor/cmock/src'},
+      {:src => 'vendor/constructor/lib/',     :dst => 'vendor/constructor/lib'},
+      {:src => 'vendor/deep_merge/lib/',      :dst => 'vendor/deep_merge/lib'},
+      {:src => 'vendor/diy/lib',              :dst => 'vendor/diy/lib'},
+      {:src => 'vendor/unity/auto/',          :dst => 'vendor/unity/auto'},
+      {:src => 'vendor/unity/release/',       :dst => 'vendor/unity/release'},
+      {:src => 'vendor/unity/src/',           :dst => 'vendor/unity/src'},
+    ]
+
+    sub_components.each do |c|
+      directory c[:src], File.join(ceedling_path, c[:dst]) 
+    end
+
+    files = %w{rakefile.rb project.yml}
+    files.each do |f|
+      copy_file File.join('assets', f), File.join(name, f)
+    end
+
+    unless silent
+      puts "\n"
+      puts "Project '#{name}' created!"
+      puts " - Tool documentation is located in vendor/ceedling/docs" if not options[:nodocs]
+      puts " - Execute 'rake -T' to view available test & build tasks"
+      puts ''
+    end
   end
 
   desc "examples", "list available example projects"
   def examples()
     puts "Available sample projects:"
-    FileUtils.cd(File.dirname(__FILE__) + "/../examples") do
+    FileUtils.cd(File.join(here, "examples")) do
       Dir["*"].each {|proj| puts "  #{proj}"}
     end
   end
 
-  desc "example PROJ_NAME [DEST]", "create specified example project (in DEST, if specified)"
+  desc "example PROJ_NAME [DEST]", "new specified example project (in DEST, if specified)"
   def example(proj_name, dest=nil)
-    dest = proj_name if !dest
-    directory Ceedling::NEW_PROJECT_DIR, dest
-    remove_file "#{dest}/project.yml"
-    remove_file "#{dest}/rakefile.rb"
-    directory "examples/#{proj_name}", dest
+    if dest.nil? then dest = proj_name end
+
+    invoke :new, [dest, true]
+
+    dest_src      = File.join(dest,'src')
+    dest_test     = File.join(dest,'test')
+    dest_rakefile = File.join(dest,'rakefile.rb')
+    dest_project  = File.join(dest,'project.yml')
+
+    directory "examples/#{proj_name}/src",         dest_src
+    directory "examples/#{proj_name}/test",        dest_test
+    remove_file dest_rakefile
+    remove_file dest_project
+    copy_file "examples/#{proj_name}/rakefile.rb", dest_rakefile
+    copy_file "examples/#{proj_name}/project.yml", dest_project
+
     puts "\n"
     puts "Example project '#{proj_name}' created!"
     puts " - Tool documentation is located in vendor/ceedling/docs"
     puts " - Execute 'rake -T' to view available test & build tasks"
     puts ''
   end
-
-  desc "version", "print all ceedling gem and library versions"
-  def version
-    puts "       Gem:: #{Ceedling::Version::GEM}"
-    puts "  Ceedling:: #{Ceedling::Version::CEEDLING}"
-    puts "CException:: #{Ceedling::Version::CEXCEPTION}"
-    puts "     CMock:: #{Ceedling::Version::CMOCK}"
-    puts "     Unity:: #{Ceedling::Version::UNITY}"
-  end
 end
+
+CeedlingTasks.source_root here
 CeedlingTasks.start

data/ceedling.gemspec

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), 'lib'))
 require "ceedling/version"
 
 Gem::Specification.new do |s|
@@ -9,16 +9,29 @@ Gem::Specification.new do |s|
   s.authors     = ["Mike Karlesky, Mark VanderVoord", "Greg Williams", "Matt Fletcher"]
   s.email       = ["michael@karlesky.net, mvandervoord@gmail.com, williams@atomicembedded.com, fletcher@atomicobject.com"]
   s.homepage    = "http://throwtheswitch.org/"
-  s.summary     = %q{Gemified version of the Ceedling C testing / build environment}
-  s.description = %q{Gemified version of the Ceedling C testing / build environment}
+  s.summary     = %q{Ceedling is a set of tools for the automation of builds and test running for C}
+  s.description = %q{Ceedling provides a set of tools to deploy its guts in a folder or which can be required in a Rakefile}
 
   s.rubyforge_project = "ceedling"
 
   s.add_dependency "thor", ">= 0.14.5"
   s.add_dependency "rake", ">= 0.8.7"
 
-  s.files         = `git ls-files`.split("\n")
+  # Files needed from submodules
+  s.files         = []
+  s.files        += `find vendor/cmock/lib           -name "*.rb"`.split("\n")
+  s.files        += `find vendor/cmock/config        -name "*.rb"`.split("\n")
+  s.files        += `find vendor/cmock/release       -name "*.info"`.split("\n")
+  s.files        += `find vendor/cmock/src           -name "*.[ch]"`.split("\n")
+  s.files        += `find vendor/c_exception/lib     -name "*.[ch]"`.split("\n")
+  s.files        += `find vendor/c_exception/release -name "*.info"`.split("\n")
+  s.files        += `find vendor/unity/auto          -name "*.rb"`.split("\n")
+  s.files        += `find vendor/unity/release       -name "*.info"`.split("\n")
+  s.files        += `find vendor/unity/src           -name "*.[ch]"`.split("\n")
+
+  s.files        += `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+
+  s.require_paths = ["lib", "vendor/cmock/lib"]
 end

data/config/test_environment.rb

@@ -0,0 +1,12 @@
+
+# Setup our load path:
+[ 
+  'lib',
+  'test',
+  'vendor/behaviors/lib',
+  'vendor/hardmock/lib',
+  'vendor/constructor/lib',
+  'vendor/deep_merge/lib',
+].each do |dir|
+  $LOAD_PATH.unshift( File.join( File.expand_path(File.dirname(__FILE__) + "/../"), dir) )
+end

data/docs/CeedlingPacket.md

@@ -0,0 +1,1934 @@
+[All code is copyright © 2010-2012 Ceedling Project 
+by Mike Karlesky, Mark VanderVoord, and Greg Williams.
+
+This Documentation Is Released Under a
+Creative Commons 3.0 Attribution Share-Alike License]
+
+What the What? 
+
+Assembling build environments for C projects - especially with 
+automated unit tests - is a pain. Whether it's Make or Rake or Premake 
+or what-have-you, set up with an all-purpose build environment 
+tool is tedious and requires considerable glue code to pull together 
+the necessary tools and libraries. Ceedling allows you to generate 
+an entire test and build environment for a C project from a single 
+YAML configuration file. Ceedling is written in Ruby and works 
+with the Rake build tool plus other goodness like Unity and CMock 
+- the unit testing and mocking frameworks for C. Ceedling and 
+its complementary tools can support the tiniest of embedded 
+processors, the beefiest 64 bit power houses available, and 
+everything in between. 
+
+For a build project including unit tests and using the default 
+toolchain gcc, the configuration file could be as simple as this: 
+
+    :project:
+      :build_root: project/build/
+      :release_build: TRUE
+    
+    :paths:
+      :test:
+        - tests/**
+      :source:
+        - source/**
+    
+
+From the command line, to build the release version of your project, 
+you would simply run `rake release`. To run all your unit tests, 
+you would run `rake test:all`. That's it! 
+
+Of course, many more advanced options allow you to configure 
+your project with a variety of features to meet a variety of needs. 
+Ceedling can work with practically any command line toolchain 
+and directory structure – all by way of the configuration file. 
+Further, because Ceedling piggy backs on Rake, you can add your 
+own Rake tasks to accomplish project tasks outside of testing 
+and release builds. A facility for plugins also allows you to 
+extend Ceedling's capabilities for needs such as custom code 
+metrics reporting and coverage testing. 
+
+What's with this Name? 
+
+Glad you asked. Ceedling is tailored for unit tested C projects 
+and is built upon / around Rake (Rake is a Make replacement implemented 
+in the Ruby scripting language). So, we've got C, our Rake, and 
+the fertile soil of a build environment in which to grow and tend 
+your project and its unit tests. Ta da - _Ceedling_. 
+
+What Do You Mean "tailored for unit tested C projects"? 
+
+Well, we like to write unit tests for our C code to make it lean and 
+mean (that whole [Test-Driven Development][tdd]
+thing). Along the way, this style of writing C code spawned two 
+tools to make the job easier: a unit test framework for C called 
+_Unity_ and a mocking library called _CMock_. And, though it's 
+not directly related to testing, a C framework for exception 
+handling called _CException_ also came along. 
+
+[tdd]: http://en.wikipedia.org/wiki/Test-driven_development
+
+These tools and frameworks are great, but they require quite 
+a bit of environment support to pull them all together in a convenient, 
+usable fashion. We started off with Rakefiles to assemble everything. 
+These ended up being quite complicated and had to be hand-edited 
+or created anew for each new project. Ceedling replaces all that 
+tedium and rework with a configuration file that ties everything 
+together. 
+
+Though Ceedling is tailored for unit testing, it can also go right ahead
+and build your final binary release artifact for you as well. Or,
+Ceedling and your tests can live alongside your existing release build
+setup. That said, Ceedling is more powerful as a unit test build
+environment than it is a general purpose release build environment;
+complicated projects including separate bootloaders or multiple library
+builds, etc. are not its strong suit.
+
+Hold on. Back up. Ruby? Rake? YAML? Unity? CMock? CException? 
+
+Seem overwhelming? It's not bad at all, and for the benefits tests 
+bring us, it's all worth it. 
+
+[Ruby][] is a handy scripting 
+language like Perl or Python. It's a modern, full featured language 
+that happens to be quite handy for accomplishing tasks like code 
+generation or automating one's workflow while developing in 
+a compiled language such as C. 
+
+[Ruby]: http://www.ruby-lang.org/en/
+
+[Rake][] is a utility written in Ruby 
+for accomplishing dependency tracking and task automation 
+common to building software. It's a modern, more flexible replacement 
+for [Make][]). 
+Rakefiles are Ruby files, but they contain build targets similar 
+in nature to that of Makefiles (but you can also run Ruby code in 
+your Rakefile). 
+
+[Rake]: http://rubyrake.org/
+[Make]: http://en.wikipedia.org/wiki/Make_(software)
+
+[YAML][] is a "human friendly data serialization standard for all
+programming languages." It's kinda like a markup language, but don't
+call it that. With a YAML library, you can [serialize][] data structures
+to and from the file system in a textual, human readable form. Ceedling
+uses a serialized data structure as its configuration input.
+
+[YAML]: http://en.wikipedia.org/wiki/Yaml
+[serialize]: http://en.wikipedia.org/wiki/Serialization
+
+[Unity] is a [unit test framework][test] for C. It provides facilities
+for test assertions, executing tests, and collecting / reporting test
+results. Unity derives its name from its implementation in a single C
+source file (plus two C header files) and from the nature of its
+implementation - Unity will build in any C toolchain and is configurable
+for even the very minimalist of processors.
+
+[Unity]: http://unity.sourceforge.net/
+[test]: http://en.wikipedia.org/wiki/Unit_testing
+
+[CMock] is a tool written in Ruby able to generate entire
+[mock functions][mock] in C code from a given C header file. Mock
+functions are invaluable in [interaction-based unit testing][ut].
+CMock's generated C code uses Unity.
+
+[CMock]: http://cmock.sourceforge.net/
+[mock]: http://en.wikipedia.org/wiki/Mock_object
+[ut]: http://martinfowler.com/articles/mocksArentStubs.html
+
+[CException] is a C source and header file that provide a simple
+[exception mechanism][exn] for C by way of wrapping up the
+[setjmp / longjmp][setjmp] standard library calls. Exceptions are a much
+cleaner and preferable alternative to managing and passing error codes
+up your return call trace.
+
+[CException]: http://cexception.sourceforge.net/
+[exn]: http://en.wikipedia.org/wiki/Exception_handling
+[setjmp]: http://en.wikipedia.org/wiki/Setjmp.h
+
+Notes
+-----
+
+* YAML support is included with Ruby - requires no special installation 
+  or configuration. 
+
+* Unity, CMock, and CException are bundled with Ceedling, and 
+  Ceedling is designed to glue them all together for your project 
+  as seamlessly as possible. 
+
+
+Installation & Setup: What Exactly Do I Need to Get Started? 
+------------------------------------------------------------
+
+As a [Ruby gem](http://docs.rubygems.org/read/chapter/1): 
+
+1. [Download and install Ruby](http://www.ruby-lang.org/en/downloads/) 
+
+2. Use Ruby's command line gem package manager to install Rake: 
+   `gem install rake` 
+
+3. Use Ruby's command line gem package manager to install Ceedling: 
+   `gem install ceedling` {text:line-break} (Unity, CMock, 
+   and CException come along with Ceedling for free) 
+
+4. Execute Ceedling at command line to create example project 
+   or an empty Ceedling project in your filesystem (executing 
+   `ceedling help` first is, well, helpful). 
+
+Gem install notes: 
+
+1. Steps 1-3 are a one time affair for your local environment. 
+   When steps 1-3 are completed once, only step 4 is needed for 
+   each new project. 
+
+
+
+Alternatively, from scratch: 
+
+1. [Download and install Ruby](http://www.ruby-lang.org/en/downloads/) 
+
+2. Use Ruby's command line gem package manager to install Rake: 
+   `gem install rake` 
+
+3. Grab the Ceedling package (from sourceforge as download 
+   or from svn) and place in your filesystem {text:line-break} 
+   (it already contains Unity, CMock, and CException) 
+
+4. Create an empty build directory for your project {text:line-break} 
+   (Ceedling will fill out the directory structure below the 
+   build root when executed) 
+
+5. Create a simple Rakefile (`rakefile.rb`) that contains 
+   a load call to Ceedling on your filesystem and a default task 
+   (tasks available to tie to `default` are listed in the next 
+   section):
+   
+    `load '<path>/ceedling/lib/rakefile.rb' 
+    # ex. run all tests & build release artifact
+    task :default => ['test:all', :release]
+         # namespaced tasks must be quoted 
+         # top-level tasks are Ruby symbols denoted by a leading ':'` 
+
+6. Create your project YAML file (more on this later in this document). 
+   `project.yml` is the default file name Ceedling recognizes 
+   in the working directory from which Rake is run (Rake is the 
+   tool we actually use to take advantage of what Ceedling provides). 
+
+
+From scratch install notes: 
+
+1. Steps 1-3 are a one time affair for your local environment. 
+   When steps 1-3 are completed once, only steps 4-6 are needed 
+   for each new project. 
+
+2. See the sample starter project for a working setup. When steps 
+   1-3 are complete and assuming you have gcc in your path (Ceedling's 
+   default toolchain), you will only need to edit the path within 
+   the sample Rakefile (see step 5 above) to yield a working, 
+   albeit simple, project. The default task need not be defined, 
+   but it's not a bad idea to do so. 
+
+
+
+General notes: 
+
+1. Certain advanced features of Ceedling rely on gcc and cpp 
+   as preprocessing tools. In most *nix systems, these tools 
+   are already available. For Windows environments, we recommend 
+   the [mingw project](http://www.mingw.org/) (Minimalist 
+   GNU for Windows). This represents an optional, additional 
+   setup / installation step to complement the list above. Upon 
+   installing mingw ensure your system path is updated or set 
+   [:environment][:path] in your `project.yml` file (see 
+   environment section later in this document). 
+
+2. To use a project file name other than the default `project.yml` 
+   or place the project file in a directory other than the one 
+   in which you'll run Rake, create an environment variable 
+   `CEEDLING_MAIN_PROJECT_FILE` with your desired project 
+   file path. 
+
+3. To better understand Rake conventions, Rake execution, 
+   and Rakefiles, consult the [Rake tutorial, examples, and 
+   user guide](http://rubyrake.org/). 
+
+
+
+Now What? How Do I Make It GO? 
+------------------------------
+
+We're getting a little ahead of ourselves here, but it's good 
+context on how to drive this bus. Everything is done via the command 
+line. We'll cover conventions and how to actually configure 
+your project in later sections. 
+
+To run tests, build your release artifact, etc., you will be interacting 
+with Rake on the command line. Ceedling works with Rake to present 
+you with named tasks that coordinate the file generation and 
+build steps needed to accomplish something useful. You can also 
+add your own independent Rake tasks or create plugins to extend 
+Ceedling (more on this later). 
+
+
+* `rake [no arguments]`:
+
+  Run the default Rake task (conveniently recognized by the name default
+  by Rake). Neither Rake nor Ceedling provide a default task. Rake will
+  abort if run without arguments when no default task is defined. You can
+  conveniently define a default task in the Rakefile discussed in the
+  preceding setup & installation section of this document.
+
+* `rake -T`:
+
+  List all available Rake tasks with descriptions (Rake tasks without
+  descriptions are not listed). -T is a command line switch for Rake and
+  not the same as tasks that follow.
+
+* `rake <tasks...> --trace`:
+
+  For advanced users troubleshooting a confusing build error, debug
+  Ceedling or a plugin, --trace provides a stack trace of dependencies
+  walked during task execution and any Ruby failures along the way. Note
+  that --trace is a command line switch for Rake and is not the same as
+  tasks that follow.
+  
+* `rake environment`:
+
+  List all configured environment variable names and string values. This
+  task is helpful in verifying the evaluatio of any Ruby expressions in
+  the [:environment] section of your config file.`: Note: Ceedling may
+  set some convenience environment variables by default.
+
+* `rake paths:*`:
+
+  List all paths collected from [:paths] entries in your YAML config
+  file where * is the name of any section contained in [:paths]. This
+  task is helpful in verifying the expansion of path wildcards / globs
+  specified in the [:paths] section of your config file.
+
+* `rake files:assembly`
+* `rake files:header`
+* `rake files:source`
+* `rake files:test`
+
+  List all files and file counts collected from the relevant search
+  paths specified by the [:paths] entries of your YAML config file. The
+  files:assembly task will only be available if assembly support is
+  enabled in the [:release_build] section of your configuration file.
+
+* `rake options:*`:
+
+  Load and merge configuration settings into the main project
+  configuration. Each task is named after a *.yml file found in the
+  configured options directory. See documentation for the configuration
+  setting [:project][:options_path] and for options files in advanced
+  topics.
+
+* `rake test:all`:
+
+  Run all unit tests (rebuilding anything that's changed along the way).
+
+* `rake test:delta`:
+
+  Run only those unit tests for which the source or test files have
+  changed (i.e. incremental build). Note: with the
+  [:project][:use_test_preprocessor] configuration file option set,
+  runner files are always regenerated limiting the total efficiency this
+  text execution option can afford.
+
+* `rake test:*`:
+
+  Execute the named test file or the named source file that has an
+  accompanying test. No path. Examples: rake test:foo.c or rake
+  test:test_foo.c
+
+* `rake test:pattern[*]`:
+
+  Execute any tests whose name and/or path match the regular expression
+  pattern (case sensitive). Example: rake "test:pattern[(I|i)nit]" will
+  execute all tests named for initialization testing. Note: quotes may
+  be necessary around the rake parameter to distinguish regex characters
+  from command line operators.
+
+* `rake test:path[*]`:
+
+  Execute any tests whose path contains the given string (case
+  sensitive). Example: rake test:path[foo/bar] will execute all tests
+  whose path contains foo/bar. Note: both directory separator characters
+  / and \ are valid.
+
+* `rake release`:
+
+  Build all source into a release artifact (if the release build option
+  is configured).
+
+* `rake release:compile:*`:
+
+  Sometimes you just need to compile a single file dagnabit. Example:
+  rake release:compile:foo.c
+
+* `rake release:assemble:*`:
+
+  Sometimes you just need to assemble a single file doggonit. Example:
+  rake release:assemble:foo.s
+
+* `rake logging <tasks...>`:
+
+  Enable logging to <build path>/logs. Must come before test and release
+  tasks to log their steps and output. Log names are a concatenation of
+  project, user, and option files loaded. User and option files are
+  documented in the advanced topics section of this document.
+
+* `rake verbosity[x] <tasks...>`:
+
+  Change the default verbosity level. [x] ranges from 0 (quiet) to 4
+  (obnoxious). Level [3] is the default. The verbosity task must precede
+  all tasks in the command line list for which output is desired to be
+  seen. Verbosity settings are generally most meaningful in conjunction
+  with test and release tasks.
+
+* `rake summary`:
+
+  If plugins are enabled, this task will execute the summary method of
+  any plugins supporting it. This task is intended to provide a quick
+  roundup of build artifact metrics without re-running any part of the
+  build.
+
+* `rake clean`:
+
+  Deletes all toolchain binary artifacts (object files, executables),
+  test results, and any temporary files. Clean produces no output at the
+  command line unless verbosity has been set to an appreciable level.
+
+* `rake clobber`:
+
+  Extends clean task's behavior to also remove generated files: test
+  runners, mocks, preprocessor output. Clobber produces no output at the
+  command line unless verbosity has been set to an appreciable level.
+
+To better understand Rake conventions, Rake execution, and 
+Rakefiles, consult the [Rake tutorial, examples, and user guide][guide].
+
+[guide]: http://rubyrake.org/
+
+At present, none of Ceedling's commands provide persistence. 
+That is, they must each be specified at the command line each time 
+they are needed. For instance, Ceedling's verbosity command 
+only affects output at the time it's run. 
+
+{text:soft-page-break} Individual test and release file tasks 
+are not listed in `-T` output. Because so many files may be present 
+it's unwieldy to list them all. 
+
+Multiple rake tasks can be executed at the command line (order 
+is executed as provided). For example, `rake 
+clobber test:all release` will removed all generated files; 
+build and run all tests; and then build all source - in that order. 
+If any Rake task fails along the way, execution halts before the 
+next task. 
+
+The `clobber` task removes certain build directories in the 
+course of deleting generated files. In general, it's best not 
+to add to source control any Ceedling generated directories 
+below the root of your top-level build directory. That is, leave 
+anything Ceedling & its accompanying tools generate out of source 
+control (but go ahead and add the top-level build directory that 
+holds all that stuff). Also, since Ceedling is pretty smart about 
+what it rebuilds and regenerates, you needn't clobber often. 
+
+Important Conventions 
+=====================
+
+Directory Structure, Filenames & Extensions 
+-------------------------------------------
+
+Much of Ceedling's functionality is driven by collecting files 
+matching certain patterns inside the paths it's configured 
+to search. See the documentation for the [:extensions] section 
+of your configuration file (found later in this document) to 
+configure the file extensions Ceedling uses to match and collect 
+files. Test file naming is covered later in this section. 
+
+Test files and source files must be segregated by directories. 
+Any directory structure will do. Tests can be held in subdirectories 
+within source directories, or tests and source directories 
+can be wholly separated at the top of your project's directory 
+tree. 
+
+Search Path Order 
+-----------------
+
+When Ceedling searches for files (e.g. looking for header files 
+to mock) or when it provides search paths to any of the default 
+gcc toolchain executables, it organizes / prioritizes its search 
+paths. The order is always: test paths, support paths, source 
+paths, and then include paths. This can be useful, for instance, 
+in certain testing scenarios where we desire Ceedling or a compiler 
+to find a stand-in header file in our support directory before 
+the actual source header file of the same name. 
+
+This convention only holds when Ceedling is using its default 
+tool configurations and / or when tests are involved. If you define 
+your own tools in the configuration file (see the [:tools] section 
+documented later in this here document), you have complete control 
+over what directories are searched and in what order. Further, 
+test and support directories are only searched when appropriate. 
+That is, when running a release build, test and support directories 
+are not used at all. 
+
+Source Files & Binary Release Artifacts 
+---------------------------------------
+
+Your binary release artifact results from the compilation and 
+linking of all source files Ceedling finds in the specified source 
+directories. At present only source files with a single (configurable) 
+extension are recognized. That is, *.c and *.cc files will not 
+both be recognized - only one or the other. See the configuration 
+options and defaults in the documentation for the [:extensions] 
+sections of your configuration file (found later in this document). 
+
+Test Files & Executable Test Fixtures 
+-------------------------------------
+
+Ceedling builds each individual test file with its accompanying 
+source file(s) into a single, monolithic test fixture executable. 
+Test files are recognized by a naming convention: a (configurable) 
+prefix such as "`test_`" in the file name with the same file extension 
+as used by your C source files. See the configuration options 
+and defaults in the documentation for the [:project] and [:extensions] 
+sections of your configuration file (found later in this document). 
+Depending on your configuration options, Ceedling can recognize 
+a variety of test file naming patterns in your test search paths. 
+For example: `test_some_super_functionality.c`, `TestYourSourceFile.cc`, 
+or `testing_MyAwesomeCode.C` could each be valid test file 
+names. Note, however, that Ceedling can recognize only one test 
+file naming convention per project. 
+
+Ceedling knows what files to compile and link into each individual 
+test executable by way of the #include list contained in each 
+test file. Any C source files in the configured search directories 
+that correspond to the header files included in a test file will 
+be compiled and linked into the resulting test fixture executable. 
+From this same #include list, Ceedling knows which files to mock 
+and compile and link into the test executable (if you use mocks 
+in your tests). That was a lot of clauses and information in a very 
+few sentences; the example that follows in a bit will make it clearer. 
+
+By naming your test functions according to convention, Ceedling 
+will extract and collect into a runner C file calls to all your 
+test case functions. This runner file handles all the execution 
+minutiae so that your test file can be quite simple and so that 
+you never forget to wire up a test function to be executed. In this 
+generated runner lives the `main()` entry point for the resulting 
+test executable. There are no configuration options for the 
+naming convention of your test case functions. A test case function 
+signature must have these three elements: void return, void 
+parameter list, and the function name prepended with lowercase 
+"`test`". In other words, a test function signature should look 
+like this: `void test``[any name you like]``(void)`. 
+
+A commented sample test file follows on the next page. Also, see 
+the sample project contained in the Ceedling documentation 
+bundle. 
+
+    // test_foo.c -----------------------------------------------
+    #include "unity.h"     // compile/link in Unity test framework
+    #include "types.h"     // header file with no *.c file -- no compilation/linking
+    #include "foo.h"       // source file foo.c under test
+    #include "mock_bar.h"  // bar.h will be found and mocked as mock_bar.c + compiled/linked in;
+                           // foo.c includes bar.h and uses functions declared in it
+    #include "mock_baz.h"  // baz.h will be found and mocked as mock_baz.c + compiled/linked in
+                           // foo.c includes baz.h and uses functions declared in it
+    
+    
+    void setUp(void) {}    // every test file requires this function;
+                           // setUp() is called by the generated runner before each test case function
+    
+    void tearDown(void) {} // every test file requires this function;
+                           // tearDown() is called by the generated runner before each test case function
+    
+    // a test case function
+    void test_Foo_Function1_should_Call_Bar_AndGrill(void)
+    {
+        Bar_AndGrill_Expect();                    // setup function from mock_bar.c that instructs our
+                                                  // framework to expect Bar_AndGrill() to be called once
+        TEST_ASSERT_EQUAL(0xFF, Foo_Function1()); // assertion provided by Unity
+                                                  // Foo_Function1() calls Bar_AndGrill() & returns a byte
+    }
+    
+    // another test case function
+    void test_Foo_Function2_should_Call_Baz_Tec(void)
+    {
+        Baz_Tec_ExpectAnd_Return(1);       // setup function provided by mock_baz.c that instructs our
+                                           // framework to expect Baz_Tec() to be called once and return 1
+        TEST_ASSERT_TRUE(Foo_Function2()); // assertion provided by Unity
+    }
+    
+    // end of test_foo.c ----------------------------------------
+    
+
+From the test file specified above Ceedling will generate `test_foo_runner.c`; 
+this runner file will contain `main()` and call both of the example 
+test case functions. 
+
+The final test executable will be `test_foo.exe` (for Windows 
+machines or `test_foo.out` for *nix systems - depending on default 
+or configured file extensions). Based on the #include list above, 
+the test executable will be the output of the linker having processed 
+`unity.o`, `foo.o`, `mock_bar.o`, `mock_baz.o`, `test_foo.o`, 
+and `test_foo_runner.o`. Ceedling finds the files, generates 
+mocks, generates a runner, compiles all the files, and links 
+everything into the test executable. Ceedling will then run 
+the test executable and collect test results from it to be reported 
+to the developer at the command line. 
+
+For more on the assertions and mocks shown, consult the documentation 
+for Unity and CMock. 
+
+The Magic of Dependency Tracking 
+--------------------------------
+
+Ceedling is pretty smart in using Rake to build up your project's 
+dependencies. This means that Ceedling automagically rebuilds 
+all the appropriate files in your project when necessary: when 
+your configuration changes, Ceedling or any of the other tools 
+are updated, or your source or test files change. For instance, 
+if you modify a header file that is mocked, Ceedling will ensure 
+that the mock is regenerated and all tests that use that mock are 
+rebuilt and re-run when you initiate a relevant testing task. 
+When you see things rebuilding, it's for a good reason. Ceedling 
+attempts to regenerate and rebuild only what's needed for a given 
+execution of a task. In the case of large projects, assembling 
+dependencies and acting upon them can cause some delay in executing 
+tasks. 
+
+With one exception, the trigger to rebuild or regenerate a file 
+is always a disparity in timestamps between a target file and 
+its source - if an input file is newer than its target dependency, 
+the target is rebuilt or regenerated. For example, if the C source 
+file from which an object file is compiled is newer than that object 
+file on disk, recompilation will occur (of course, if no object 
+file exists on disk, compilation will always occur). The one 
+exception to this dependency behavior is specific to your input 
+configuration. Only if your logical configuration changes 
+will a system-wide rebuild occur. Reorganizing your input configuration 
+or otherwise updating its file timestamp without modifying 
+the values within the file will not trigger a rebuild. This behavior 
+handles the various ways in which your input configuration can 
+change (discussed later in this document) without having changed 
+your actual project YAML file. 
+
+Ceedling needs a bit of help to accomplish its magic with deep 
+dependencies. Shallow dependencies are straightforward: 
+a mock is dependent on the header file from which it's generated, 
+a test file is dependent upon the source files it includes (see 
+the preceding conventions section), etc. Ceedling handles 
+these "out of the box." Deep dependencies are specifically a 
+C-related phenomenon and occur as a consequence of include statements 
+within C source files. Say a source file includes a header file 
+and that header file in turn includes another header file which 
+includes still another header file. A change to the deepest header 
+file should trigger a recompilation of the source file, a relinking 
+of all the object files comprising a test fixture, and a new execution 
+of that test fixture. 
+
+Ceedling can handle deep dependencies but only with the help 
+of a C preprocessor. Ceedling is quite capable, but a full C preprocessor 
+it ain't. Your project can be configured to use a C preprocessor 
+or not. Simple projects or large projects constructed so as to 
+be quite flat in their include structure generally don't need 
+deep dependency preprocessing - and can enjoy the benefits of 
+faster execution. Legacy code, on the other hand, will almost 
+always want to be tested with deep preprocessing enabled. Set 
+up of the C preprocessor is covered in the documentation for the 
+[:project] and [:tools] section of the configuration file (later 
+in this document). Ceedling contains all the configuration 
+necessary to use the gcc preprocessor by default. That is, as 
+long as gcc is in your system search path, deep preprocessing 
+of deep dependencies is available to you by simply enabling it 
+in your project configuration file. 
+
+Ceedling's Build Output 
+-----------------------
+
+Ceedling requires a top-level build directory for all the stuff 
+that it, the accompanying test tools, and your toolchain generate. 
+That build directory's location is configured in the [:project] 
+section of your configuration file (discussed later). There 
+can be a ton of generated files. By and large, you can live a full 
+and meaningful life knowing absolutely nothing at all about 
+the files and directories generated below the root build directory. 
+
+As noted already, it's good practice to add your top-level build 
+directory to source control but nothing generated beneath it. 
+You'll spare yourself headache if you let Ceedling delete and 
+regenerate files and directories in a non-versioned corner 
+of your project's filesystem beneath the top-level build directory. 
+
+The `artifacts` directory is the one and only directory you may 
+want to know about beneath the top-level build directory. The 
+subdirectories beneath `artifacts` will hold your binary release 
+target output (if your project is configured for release builds) 
+and will serve as the conventional location for plugin output. 
+This directory structure was chosen specifically because it 
+tends to work nicely with Continuous Integration setups that 
+recognize and list build artifacts for retrieval / download. 
+
+The Almighty Project Configuration File (in Glorious YAML) 
+----------------------------------------------------------
+
+Please consult YAML documentation for the finer points of format 
+and to understand details of our YAML-based configuration file. 
+We recommend [Wikipedia's entry on YAML](http://en.wikipedia.org/wiki/Yaml) 
+for this. A few highlights from that reference page: 
+
+* YAML streams are encoded using the set of printable Unicode 
+  characters, either in UTF-8 or UTF-16 
+
+* Whitespace indentation is used to denote structure; however 
+  tab characters are never allowed as indentation 
+
+* Comments begin with the number sign ( # ), can start anywhere 
+  on a line, and continue until the end of the line unless enclosed 
+  by quotes 
+
+* List members are denoted by a leading hyphen ( - ) with one member 
+  per line, or enclosed in square brackets ( [ ] ) and separated 
+  by comma space ( , ) 
+
+* Hashes are represented using the colon space ( : ) in the form 
+  key: value, either one per line or enclosed in curly braces 
+  ( { } ) and separated by comma space ( , ) 
+
+* Strings (scalars) are ordinarily unquoted, but may be enclosed 
+  in double-quotes ( " ), or single-quotes ( ' ) 
+
+* YAML requires that colons and commas used as list separators 
+  be followed by a space so that scalar values containing embedded 
+  punctuation can generally be represented without needing 
+  to be enclosed in quotes 
+
+* Repeated nodes are initially denoted by an ampersand ( & ) and 
+  thereafter referenced with an asterisk ( * ) 
+
+
+
+Notes on what follows: 
+
+* Each of the following sections represent top-level entries 
+  in the YAML configuration file. 
+
+* Unless explicitly specified in the configuration file, default 
+  values are used by Ceedling. 
+
+* These three settings, at minimum, must be specified: 
+  * [:project][:build_root] 
+  * [:paths][:source]
+  * [:paths][:test]
+
+* As much as is possible, Ceedling validates your settings in 
+  properly formed YAML. 
+
+* Improperly formed YAML will cause a Ruby error when the YAML 
+  is parsed. This is usually accompanied by a complaint with 
+  line and column number pointing into the project file. 
+
+* Certain advanced features rely on gcc and cpp as preprocessing 
+  tools. In most *nix systems, these tools are already available. 
+  For Windows environments, we recommend the [mingw project](http://www.mingw.org/) 
+  (Minimalist GNU for Windows). 
+
+* Ceedling is primarily meant as a build tool to support automated 
+  unit testing. All the heavy lifting is involved there. Creating 
+  a simple binary release build artifact is quite trivial in 
+  comparison. Consequently, most default options and the construction 
+  of Ceedling itself is skewed towards supporting testing though 
+  Ceedling can, of course, build your binary release artifact 
+  as well. Note that complex binary release artifacts (e.g. 
+  application + bootloader or multiple libraries) are beyond 
+  Ceedling's release build ability. 
+
+
+Conventions / features of Ceedling-specific YAML: 
+
+* Any second tier setting keys anywhere in YAML whose names end 
+  in `_path` or `_paths` are automagically processed like all 
+  Ceedling-specific paths in the YAML to have consistent directory 
+  separators (i.e. "/") and to take advantage of inline Ruby 
+  string expansion (see [:environment] setting below for further 
+  explanation of string expansion). 
+
+
+
+**Let's Be Careful Out There:** Ceedling performs validation 
+on the values you set in your configuration file (this assumes 
+your YAML is correct and will not fail format parsing, of course). 
+That said, validation is limited to only those settings Ceedling 
+uses and those that can be reasonably validated. Ceedling does 
+not limit what can exist within your configuration file. In this 
+way, you can take full advantage of YAML as well as add sections 
+and values for use in your own custom plugins (documented later). 
+The consequence of this is simple but important. A misspelled 
+configuration section name or value name is unlikely to cause 
+Ceedling any trouble. Ceedling will happily process that section 
+or value and simply use the properly spelled default maintained 
+internally - thus leading to unexpected behavior without warning. 
+
+project: global project settings 
+
+
+* `build_root`:
+
+  Top level directory into which generated path structure and files are
+  placed. Note: this is one of the handful of configuration values that
+  must be set. The specified path can be absolute or relative to your
+  working directory.
+
+  **Default**: (none)
+
+* `use_exceptions`:
+
+  Configures the build environment to make use of CException. Note that
+  if you do not use exceptions, there's no harm in leaving this as its
+  default value.
+
+  **Default**: TRUE
+
+* `use_mocks`:
+
+  Configures the build environment to make use of CMock. Note that if
+  you do not use mocks, there's no harm in leaving this setting as its
+  default value.
+
+  **Default**: TRUE
+
+* `use_test_preprocessor`:
+
+  This option allows Ceedling to work with test files that contain
+  conditional compilation statements (e.g. #ifdef) and header files you
+  wish to mock that contain conditional preprocessor statements and/or
+  macros.
+  
+  Ceedling and CMock are advanced tools with sophisticated parsers.
+  However, they do not include entire C language preprocessors.
+  Consequently, with this option enabled, Ceedling will use gcc's
+  preprocessing mode and the cpp preprocessor tool to strip down /
+  expand test files and headers to their applicable content which can
+  then be processed by Ceedling and CMock.
+  
+  With this option enabled, the gcc & cpp tools must exist in an
+  accessible system search path and test runner files are always
+  regenerated.
+
+  **Default**: FALSE
+
+* `use_deep_dependencies`:
+
+  The base rules and tasks that Ceedling creates using Rake capture most
+  of the dependencies within a standard project (e.g. when the source
+  file accompanying a test file changes, the corresponding test fixture
+  executable will be rebuilt when tests are re-run). However, deep
+  dependencies cannot be captured this way. If a typedef or macro
+  changes in a header file three levels of #include statements deep,
+  this option allows the appropriate incremental build actions to occur
+  for both test execution and release builds.
+  
+  This is accomplished by using the dependencies discovery mode of gcc.
+  With this option enabled, gcc must exist in an accessible system
+  search path.
+
+  **Default**: FALSE
+
+* `test_file_prefix`:
+
+  Ceedling collects test files by convention from within the test file
+  search paths. The convention includes a unique name prefix and a file
+  extension matching that of source files.
+  
+  Why not simply recognize all files in test directories as test files?
+  By using the given convention, we have greater flexibility in what we
+  do with C files in the test directories.
+
+  **Default**: "test_"
+
+* `options_paths`:
+
+  Just as you may have various build configurations for your source
+  codebase, you may need variations of your project configuration.
+  
+  By specifying options paths, Ceedling will search for other project
+  YAML files, make command line tasks available (rake options:variation
+  for a variation.yml file), and merge the project configuration of
+  these option files in with the main project file at runtime. See
+  advanced topics.
+  
+  Note these Rake tasks at the command line - like verbosity or logging
+  control - must come before the test or release task they are meant to
+  modify.
+
+  **Default**: [] (empty)
+
+* `release_build`:
+
+  When enabled, a release Rake task is exposed. This configuration
+  option requires a corresponding release compiler and linker to be
+  defined (gcc is used as the default).
+  
+  More release configuration options are available in the release_build
+  section.
+
+  **Default**: FALSE
+
+
+Example `[:project]` YAML blurb 
+
+    :project:
+      :build_root: project_awesome/build
+      :use_exceptions: FALSE
+      :use_test_preprocessor: TRUE
+      :use_deep_dependencies: TRUE
+      :options_paths:
+        - project/options
+        - external/shared/options
+      :release_build: TRUE
+
+Ceedling is primarily concerned with facilitating the somewhat 
+complicated mechanics of automating unit tests. The same mechanisms 
+are easily capable of building a final release binary artifact 
+(i.e. non test code; the thing that is your final working software 
+that you execute on target hardware). 
+
+
+* `output`:
+
+  The name of your release build binary artifact to be found in <build
+  path>/artifacts/release. Ceedling sets the default artifact file
+  extension to that as is explicitly specified in the [:extensions]
+  section or as is system specific otherwise.
+
+  **Default**: `project.exe` or `project.out`
+
+* `use_assembly`:
+
+  If assembly code is present in the source tree, this option causes
+  Ceedling to create appropriate build directories and use an assembler
+  tool (default is the GNU tool as - override available in the [:tools]
+  section.
+
+  **Default**: FALSE
+
+* `artifacts`:
+
+  By default, Ceedling copies to the <build path>/artifacts/release
+  directory the output of the release linker and (optionally) a map
+  file. Many toolchains produce other important output files as well.
+  Adding a file path to this list will cause Ceedling to copy that file
+  to the artifacts directory. The artifacts directory is helpful for
+  organizing important build output files and provides a central place
+  for tools such as Continuous Integration servers to point to build
+  output. Selectively copying files prevents incidental build cruft from
+  needlessly appearing in the artifacts directory. Note that inline Ruby
+  string replacement is available in the artifacts paths (see discussion
+  in the [:environment] section).
+
+  **Default**: [] (empty)
+
+Example `[:release_build]` YAML blurb 
+
+    :release_build:
+      :output: top_secret.bin
+      :use_assembly: TRUE
+      :artifacts:
+        - build/release/out/c/top_secret.s19
+
+**paths**: options controlling search paths for source and header 
+(and assembly) files 
+
+
+
+* `test`:
+
+  All C files containing unit test code. Note: this is one of the
+  handful of configuration values that must be set.
+
+  **Default**: [] (empty)
+
+* `source`:
+
+  All C files containing release code (code to be tested). Note: this is
+  one of the handful of configuration values that must be set.
+
+  **Default**: [] (empty)
+
+* `support`:
+
+  Any C files you might need to aid your unit testing. For example, on
+  occasion, you may need to create a header file containing a subset of
+  function signatures matching those elsewhere in your code (e.g. a
+  subset of your OS functions, a portion of a library API, etc.). Why?
+  To provide finer grained control over mock function substitution or
+  limiting the size of the generated mocks.
+
+  **Default**: [] (empty)
+
+* `include`:
+
+  Any header files not already in the source search path. Note there's
+    no practical distinction between this search path and the source
+    search path; it's merely to provide options or to support any
+    peculiar source tree organization.
+
+  **Default**: [] (empty)
+
+* `test_toolchain_include`:
+
+  System header files needed by the test toolchain - should your
+  compiler be unable to find them, finds the wrong system include search
+  path, or you need a creative solution to a tricky technical problem.
+  Note that if you configure your own toolchain in the [:tools] section,
+  this search path is largely meaningless to you. However, this is a
+  convenient way to control the system include path should you rely on
+  the default gcc tools.
+
+  **Default**: [] (empty)
+
+* `release_toolchain_include`:
+
+  Same as preceding albeit related to the release toolchain.
+  
+  **Default**: [] (empty)
+
+* `<custom>`
+
+  Any paths you specify for custom list. List is available to tool
+  configurations and/or plugins. Note a distinction. The preceding names
+  are recognized internally to Ceedling and the path lists are used to
+  build collections of files contained in those paths. A custom list is
+  just that - a custom list of paths.
+
+Notes on path grammar within the [:paths] section: 
+
+* Order of search paths listed in [:paths] is preserved when used by an
+  entry in the [:tools] section
+
+* Wherever multiple path lists are combined for use Ceedling prioritizes
+  path groups as follows: {text:line-break} test paths, support paths,
+  source paths, include paths. This can be useful, for instance, in
+  certain testing scenarios where we desire Ceedling or the compiler to
+  find a stand-in header file before the actual source header file of
+  the same name.
+
+* Paths:
+
+  1. can be absolute or relative 
+
+  2. can be singly explicit - a single fully specified path 
+
+  3. can include a glob operator (more on this below) 
+
+  4. can use inline Ruby string replacement (see [:environment] 
+     section for more) 
+
+  5. default as an addition to a specific search list (more on this 
+     in the examples) 
+
+  6. can act to subtract from a glob included in the path list (more 
+     on this in the examples) 
+
+
+[Globs](http://ruby.about.com/od/beginningruby/a/dir2.htm) 
+as used by Ceedling are wildcards for specifying directories 
+without the need to list each and every required search path. 
+Ceedling globs operate just as Ruby globs except that they are 
+limited to matching directories and not files. Glob operators 
+include the following * ** ? [-] {,} (note: this list is space separated 
+and not comma separated as commas are used within the bracket 
+operators). 
+
+* ` *`:
+
+  All subdirectories of depth 1 below the parent path and including the
+  parent path
+
+* ` **`:
+
+  All subdirectories recursively discovered below the parent path and
+  including the parent path
+
+* ` ?`:
+
+  Single alphanumeric character wildcard 
+
+* `[x-y]`:
+
+  Single alphanumeric character as found in the specified range
+
+* `{x,y}`:
+
+  Single alphanumeric character from the specified list 
+
+Example [:paths] YAML blurbs 
+
+    :paths:
+      :source:              #together the following comprise all source search paths
+        - project/source/*  #expansion yields all subdirectories of depth 1 plus parent directory
+        - project/lib       #single path
+      :test:                #all test search paths
+        - project/**/test?  #expansion yields any subdirectory found anywhere in the project that
+                            #begins with "test" and contains 5 characters
+    
+    :paths:
+      :source:                           #all source search paths
+        - +:project/source/**            #all subdirectories recursively discovered plus parent directory
+        - -:project/source/os/generated  #subtract os/generated directory from expansion of above glob
+                                         #note that '+:' notation is merely aesthetic; default is to add
+    
+      :test:                             #all test search paths
+        - project/test/bootloader        #explicit, single search paths (searched in the order specified)
+        - project/test/application
+        - project/test/utilities
+    
+      :custom:                           #custom path list
+        - "#{PROJECT_ROOT}/other"        #inline Ruby string expansion
+
+Globs and inline Ruby string expansion can require trial and 
+error to arrive at your intended results. Use the `rake paths:*` 
+command line options (documented in preceding section) to verify 
+your settings. 
+
+Ceedling relies on file collections automagically assembled 
+from paths, globs, and file extensions. File collections greatly 
+simplify project set up. However, sometimes you need to remove 
+from or add individual files to those collections. 
+
+
+* `test`:
+
+  Modify the collection of unit test C files.
+
+  **Default**: [] (empty)
+
+* `source`:
+
+  Modify the collection of all source files used in unit test builds and release builds.
+
+  **Default**: [] (empty)
+
+* `assembly`:
+
+  Modify the (optional) collection of assembly files used in release builds.
+
+  **Default**: [] (empty)
+
+* `include`:
+
+  Modify the collection of all source header files used in unit test builds (e.g. for mocking) and release builds.
+
+  **Default**: [] (empty)
+
+* `support`:
+
+  Modify the collection of supporting C files available to unit tests builds.
+
+  **Default**: [] (empty)
+
+
+Note: All path grammar documented in [:paths] section applies 
+to [:files] path entries - albeit at the file path level and not 
+the directory level. 
+
+Example [:files] YAML blurb 
+
+    :files:
+      :source:
+        - callbacks/comm.c        # entry defaults to file addition
+        - +:callbacks/comm*.c     # add all comm files matching glob pattern
+        - -:source/board/atm134.c # not our board
+      :test:
+        - -:test/io/test_output_manager.c # remove unit tests from test build
+    
+
+**environment:** inserts environment variables into the shell 
+instance executing configured tools 
+
+Ceedling creates environment variables from any key / value 
+pairs in the environment section. Keys become an environment 
+variable name in uppercase. The values are strings assigned 
+to those environment variables. These value strings are either 
+simple string values in YAML or the concatenation of a YAML array. 
+
+Ceedling is able to execute inline Ruby string substitution 
+code to set environment variables. This evaluation occurs when 
+the project file is first processed for any environment pair's 
+value string including the Ruby string substitution pattern 
+`#{…}`. Note that environment value strings that _begin_ with 
+this pattern should always be enclosed in quotes. YAML defaults 
+to processing unquoted text as a string; quoting text is optional. 
+If an environment pair's value string begins with the Ruby string 
+substitution pattern, YAML will interpret the string as a Ruby 
+comment (because of the `#`). Enclosing each environment value 
+string in quotes is a safe practice. 
+
+[:environment] entries are processed in the configured order 
+(later entries can reference earlier entries). 
+
+Special case: PATH handling 
+
+In the specific case of specifying an environment key named _path_, 
+an array of string values will be concatenated with the appropriate 
+platform-specific path separation character (e.g. ':' on *nix, 
+';' on Windows). All other instances of environment keys assigned 
+YAML arrays use simple concatenation. 
+
+Example [:environment] YAML blurb 
+
+    :environment:
+      - :license_server: gizmo.intranet        #LICENSE_SERVER set with value "gizmo.intranet"
+      - :license: "#{`license.exe`}"           #LICENSE set to string generated from shelling out to
+                                               #execute license.exe; note use of enclosing quotes
+    
+      - :path:                                 #concatenated with path separator (see special case above)
+         - Tools/gizmo/bin                     #prepend existing PATH with gizmo path
+         - "#{ENV['PATH']}"                    #pattern #{…} triggers ruby evaluation string substitution
+                                               #note: value string must be quoted because of '#'
+    
+      - :logfile: system/logs/thingamabob.log  #LOGFILE set with path for a log file
+
+
+**extension**: configure file name extensions used to collect lists of files searched in [:paths]
+
+* `header`:
+
+  C header files
+
+  **Default**: .h
+
+* `source`:
+
+  C code files (whether source or test files)
+
+  **Default**: .c
+
+* `assembly`:
+
+  Assembly files (contents wholly assembly instructions)
+
+  **Default**: .s
+
+* `object`:
+
+  Resulting binary output of C code compiler (and assembler)
+
+  **Default**: .o
+
+* `executable`:
+
+  Binary executable to be loaded and executed upon target hardware
+
+  **Default**: .exe or .out (Win or *nix)
+  
+* `testpass`:
+
+  Test results file (not likely to ever need a new value)
+
+  **Default**: .pass
+
+* `testfail`:
+
+  Test results file (not likely to ever need a new value)
+
+  **Default**: .fail
+
+* `dependencies`:
+
+  File containing make-style dependency rules created by gcc preprocessor
+
+  **Default**: .d
+
+
+Example [:extension] YAML blurb 
+
+    :extension:
+      :source: .cc
+      :executable: .bin
+
+**defines**: command line defines used in test and release compilation by configured tools
+
+* `test`:
+
+  Defines needed for testing. Useful for:
+  
+  1. test files containing conditional compilation statements (i.e.
+  tests active in only certain contexts)
+  
+  2. testing legacy source wherein the isolation of source under test
+  afforded by Ceedling and its complementary tools leaves certain
+  symbols unset when source files are compiled in isolation
+
+  **Default**: [] (empty)
+
+* `test_preprocess`:
+
+  If [:project][:use_test_preprocessor] or
+  [:project][:use_deep_dependencies] is set and code is structured in a
+  certain way, the gcc preprocessor may need symbol definitions to
+  properly preprocess files to extract function signatures for mocking
+  and extract deep dependencies for incremental builds.
+
+  **Default**: [] (empty)
+
+* `release`:
+
+  Defines needed for the release build binary artifact.
+  
+  **Default**: [] (empty)
+
+* `release_preprocess`:
+
+  If [:project][:use_deep_dependencies] is set and code is structured in
+  a certain way, the gcc preprocessor may need symbol definitions to
+  properly preprocess files for incremental release builds due to deep
+  dependencies.
+  
+  **Default**: [] (empty)
+
+
+Example [:defines] YAML blurb 
+
+    :defines:
+      :test:
+        - UNIT_TESTING  #for select cases in source to allow testing with a changed behavior or interface
+        - OFF=0
+        - ON=1
+        - FEATURE_X=ON
+      :source:
+        - FEATURE_X=ON
+
+**flags**: configure per-file compilation and linking flags
+
+Ceedling tools (see later [:tools] section) are used to configure
+compilation and linking of test and source files. These tool
+configurations are a one-size-fits-all approach. Should individual files
+require special compilation or linking flags, the settings in the
+[:flags] section work in conjunction with tool definitions by way of
+argument substitution to achieve this.
+
+* `release`:
+
+  [:compile] or [:link] flags for release build
+
+* `test`:
+
+  [:compile] or [:link] flags for test build
+
+Notes: 
+
+* Ceedling works with the [:release] and [:test] build contexts 
+  as-is; plugins can add additional contexts 
+
+* Only [:compile] and [:link] are recognized operations beneath 
+  a context 
+
+* File specifiers do not include a path or file extension 
+
+* File specifiers are case sensitive (must match original file 
+  name) 
+
+* '*' is a special (optional) file specifier to provide flags 
+  to all files not otherwise specified 
+
+
+Example [:flags] YAML blurb 
+
+    :flags:
+      :release:
+        :compile:
+          :main:       # add '-Wall' to compilation of main.c
+            - -Wall
+          :fan:        # add '--O2' to compilation of fan.c
+            - --O2
+          :*:          # add '-foo' to compilation of all files not main.c or fan.c
+            - -foo
+      :test:
+        :compile:
+          :main:       # add '--O1' to compilation of main.c as part of test builds including main.c
+            - --O1
+        :link:
+          :test_main:  # add '--bar --baz' to linking of test_main.exe
+            - --bar
+            - --baz
+
+Ceedling sets values for a subset of CMock settings. All CMock 
+options are available to be set, but only those options set by 
+Ceedling in an automated fashion are documented below. See CMock 
+documentation. 
+
+**cmock**: configure CMock's code generation options and set symbols used to modify CMock's compiled features
+Ceedling sets values for a subset of CMock settings. All CMock options are available to be set, but only those options set by Ceedling in an automated fashion are documented below. See CMock documentation.
+
+* `enforce_strict_ordering`:
+
+  Tests fail if expected call order is not same as source order
+
+  **Default**: TRUE
+
+* `mock_path`:
+
+  Path for generated mocks
+
+  **Default**: <build path>/tests/mocks
+
+* `defines`:
+
+  List of conditional compilation symbols used to configure CMock's
+  compiled features. See CMock documentation to understand available
+  options. No symbols must be set unless defaults are inappropriate for
+  your specific environment. All symbols are used only by Ceedling to
+  compile CMock C code; contents of [:defines] are ignored by CMock's
+  Ruby code when instantiated.
+
+  **Default**: [] (empty)
+
+* `verbosity`:
+
+  If not set, defaults to Ceedling's verbosity level
+
+* `plugins`:
+
+  If [:project][:use_exceptions] is enabled, the internal plugins list is pre-populated with 'cexception'.
+
+  Whether or not you have included [:cmock][:plugins] in your
+  configuration file, Ceedling automatically adds 'cexception' to the
+  plugin list if exceptions are enabled. To add to the list Ceedling
+  provides CMock, simply add [:cmock][:plugins] to your configuration
+  and specify your desired additional plugins.
+
+* `includes`:
+
+  If [:cmock][:unity_helper] set, pre-populated with unity_helper file
+  name (no path).
+
+  The [:cmock][:includes] list works identically to the plugins list
+  above with regard to adding additional files to be inserted within
+  mocks as #include statements.
+
+
+The last four settings above are directly tied to other Ceedling 
+settings; hence, why they are listed and explained here. The 
+first setting above, [:enforce_strict_ordering], defaults 
+to FALSE within CMock. It is set to TRUE by default in Ceedling 
+as our way of encouraging you to use strict ordering. It's a teeny 
+bit more expensive in terms of code generated, test execution 
+time, and complication in deciphering test failures. However, 
+it's good practice. And, of course, you can always disable it 
+by overriding the value in the Ceedling YAML configuration file. 
+
+
+**cexception**: configure symbols used to modify CException's compiled features
+
+* `defines`:
+
+  List of conditional compilation symbols used to configure CException's
+  features in its source and header files. See CException documentation
+  to understand available options. No symbols must be set unless the
+  defaults are inappropriate for your specific environment.
+
+  **Default**: [] (empty)
+
+
+**unity**: configure symbols used to modify Unity's compiled features
+
+* `defines`:
+
+  List of conditional compilation symbols used to configure Unity's
+  features in its source and header files. See Unity documentation to
+  understand available options. No symbols must be set unless the
+  defaults are inappropriate for your specific environment.
+
+  **Default**: [] (empty)
+
+
+Notes on Unity configuration: 
+
+* **Verification** - Ceedling does no verification of your configuration
+  values. In a properly configured setup, your Unity configuration
+  values are processed, collected together with any test define symbols
+  you specify elsewhere, and then passed to your toolchain during test
+  compilation. Unity's conditional compilation statements, your
+  toolchain's preprocessor, and/or your toolchain's compiler will
+  complain appropriately if your specified configuration values are
+  incorrect, incomplete, or incompatible.
+
+* **Routing $stdout** - Unity defaults to using `putchar()` in C's
+  standard library to display test results. For more exotic environments
+  than a desktop with a terminal (e.g. running tests directly on a
+  non-PC target), you have options. For example, you could create a
+  routine that transmits a character via RS232 or USB. Once you have
+  that routine, you can replace `putchar()` calls in Unity by overriding
+  the function-like macro `UNITY_OUTPUT_CHAR`. Consult your toolchain
+  and shell documentation.
+
+
+Example [:unity] YAML blurbs 
+
+    :unity: #itty bitty processor & toolchain with limited test execution options
+      :defines:
+        - UNITY_INT_WIDTH=16           #16 bit processor without support for 32 bit instructions
+        - UNITY_EXCLUDE_FLOAT          #no floating point unit
+            #let's say environment & tools provide no way to run tests on desktop so we gotta go on target
+            #replace putchar() with write_usart() via command line specified macro (gcc style)
+            #note escaped quotes for our hypothetical shell that doesn't like parens in arguments
+            #transformed into -D"UNITY_OUTPUT_CHAR(a)=write_usart(a)" at command line by [:tools] entry
+        - "\"UNITY_OUTPUT_CHAR(a)=write_usart(a)\""
+    
+    :unity: #great big gorilla processor that grunts and scratches
+      :defines:
+        - UNITY_SUPPORT_64                    #big memory, big counters, big registers
+        - UNITY_LINE_TYPE=\"unsigned int\"    #apparently we're using really long test files,
+        - UNITY_COUNTER_TYPE=\"unsigned int\" #and we've got a ton of test cases in those test files
+        - UNITY_FLOAT_TYPE=\"double\"         #you betcha
+    
+
+**tools**: a means for representing command line tools for use under 
+Ceedling's automation framework 
+
+Ceedling requires a variety of tools to work its magic. By default, 
+the GNU toolchain (gcc, cpp, as) are configured and ready for 
+use with no additions to the project configuration YAML file. 
+However, as most work will require a project-specific toolchain, 
+Ceedling provides a generic means for specifying / overriding 
+tools. 
+
+* `test_compiler`:
+
+  Compiler for test & source-under-test code
+  ${1}: input source ${2}: output object ${3}: optional output list ${4}: optional per-file flags
+
+  **Default**: gcc
+
+* `test_linker`:
+
+  Linker to generate test fixture executables
+  ${1}: input objects ${2}: output binary ${3}: optional output map ${4}: optional per-binary flags
+
+  **Default**: gcc
+
+* `test_fixture`:
+
+  Executable test fixture
+  ${1}: simulator as executable with ${1} as input binary file argument or native test executable
+
+  **Default**: ${1}
+
+* `test_includes_preprocessor`:
+
+  Extractor of #include statements
+  ${1}: input source file
+
+  **Default**: cpp
+
+* `test_file_preprocessor`:
+
+  Preprocessor of test files (macros, conditional compilation statements)
+  ${1}: input source file ${2}: preprocessed output source file
+
+  **Default**: gcc
+
+* `test_dependencies_generator`:
+
+  Discovers deep dependencies of source & test (for incremental builds)
+  ${1}: input source file ${2}: compiled object filepath ${3}: output dependencies file
+
+  **Default**: gcc
+
+* `release_compiler`:
+
+  Compiler for release source code
+  ${1}: input source ${2}: output object ${3}: optional output list ${4}: optional per-file flags
+
+  **Default**: gcc
+
+* `release_assembler`:
+
+  Assembler for release assembly code
+  ${1}: input assembly source file ${2}: output object file
+
+  **Default**: as
+
+* `release_linker`:
+
+  Linker for release source code
+  ${1}: input objects ${2}: output binary ${3}: optional output map ${4}: optional per-binary flags
+
+  **Default**: gcc
+
+* `release_dependencies_generator`:
+
+  Discovers deep dependencies of source files (for incremental builds)
+  ${1}: input source file ${2}: compiled object filepath ${3}: output dependencies file
+
+  **Default**: gcc
+
+
+A Ceedling tool has a handful of configurable elements: 
+
+1. [:executable] (required) - Command line executable having 
+   the form of: 
+
+2. [:arguments] (required) - List of command line arguments 
+   and substitutions 
+
+3. [:name] - Simple name (e.g. "nickname") of tool beyond its 
+   executable name (if not explicitly set then Ceedling will 
+   form a name from the tool's YAML entry name) 
+
+4. [:stderr_redirect] - Control of capturing $stderr messages 
+   {:none, :auto, :win, :unix, :tcsh}. {text:line-break} 
+   Defaults to :none if unspecified; create a custom entry by 
+   specifying a simple string instead of any of the available 
+   symbols. 
+
+5. [:background_exec] - Control execution as background process 
+   {:none, :auto, :win, :unix}. {text:line-break} Defaults 
+   to :none if unspecified. 
+
+
+Tool Element Runtime Substitution 
+---------------------------------
+
+To accomplish useful work on multiple files, a configured tool will most
+often require that some number of its arguments or even the executable
+itself change for each run. Consequently, every tool's argument list and
+executable field possess two means for substitution at runtime. Ceedling
+provides two kinds of inline Ruby execution and a notation for
+populating elements with dynamically gathered values within the build
+environment.
+
+Tool Element Runtime Substitution: Inline Ruby Execution 
+--------------------------------------------------------
+
+In-line Ruby execution works similarly to that demonstrated for the
+[:environment] section except that substitution occurs as the tool is
+executed and not at the time the configuration file is first scanned.
+
+* `#{...}`:
+
+  Ruby string substitution pattern wherein the containing string is
+  expanded to include the string generated by Ruby code between the
+  braces. Multiple instances of this expansion can occur within a single
+  tool element entry string. Note that if this string substitution
+  pattern occurs at the very beginning of a string in the YAML
+  configuration the entire string should be enclosed in quotes (see the
+  [:environment] section for further explanation on this point).
+
+* `{...} `:
+
+  If an entire tool element string is enclosed with braces, it signifies
+  that Ceedling should execute the Ruby code contained within those
+  braces. Say you have a collection of paths on disk and some of those
+  paths include spaces. Further suppose that a single tool that must use
+  those paths requires those spaces to be escaped, but all other uses of
+  those paths requires the paths to remain unchanged. You could use this
+  Ceedling feature to insert Ruby code that iterates those paths and
+  escapes those spaces in the array as used by the tool of this example.
+
+Tool Element Runtime Substitution: Notational Substitution 
+----------------------------------------------------------
+
+A Ceedling tool's other form of dynamic substitution relies on a '$'
+notation. These '$' operators can exist anywhere in a string and can be
+decorated in any way needed. To use a literal '$', escape it as '\\$'.
+
+* ` $`:
+
+  Simple substitution for value(s) globally available within the runtime
+  (most often a string or an array).
+
+* `${#}`:
+
+  When a Ceedling tool's command line is expanded from its configured
+  representation and used within Ceedling Ruby code, certain calls to
+  that tool will be made with a parameter list of substitution values.
+  Each numbered substitution corresponds to a position in a parameter
+  list. Ceedling Ruby code expects that configured compiler and linker
+  tools will contain ${1} and ${2} replacement arguments. In the case of
+  a compiler ${1} will be a C code file path, and ${2} will be the file
+  path of the resulting object file. For a linker ${1} will be an array
+  of object files to link, and ${2} will be the resulting binary
+  executable. For an executable test fixture ${1} is either the binary
+  executable itself (when using a local toolchain such as gcc) or a
+  binary input file given to a simulator in its arguments.
+
+
+
+Example [:tools] YAML blurbs 
+
+    :tools:
+      :test_compiler:
+         :executable: compiler              #exists in system search path
+         :name: 'acme test compiler'
+         :arguments:
+            - -I"$”: COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE               #expands to -I search paths
+            - -I"$”: COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR   #expands to -I search paths
+            - -D$: COLLECTION_TEST_DEFINES  #expands to all -D defined symbols
+            - --network-license             #simple command line argument
+            - -optimize-level 4             #simple command line argument
+            - "#{`args.exe -m acme.prj`}"   #in-line ruby sub to shell out & build string of arguments
+            - -c ${1}                       #source code input file (Ruby method call param list sub)
+            - -o ${2}                       #object file output (Ruby method call param list sub)
+      :test_linker:
+         :executable: /programs/acme/bin/linker.exe    #absolute file path
+         :name: 'acme test linker'
+         :arguments:
+            - ${1}               #list of object files to link (Ruby method call param list sub)
+            - -l$-lib:           #inline yaml array substitution to link in foo-lib and bar-lib
+               - foo
+               - bar
+            - -o ${2}            #executable file output (Ruby method call param list sub)
+      :test_fixture:
+         :executable: tools/bin/acme_simulator.exe  #relative file path to command line simulator
+         :name: 'acme test fixture'
+         :stderr_redirect: :win                     #inform Ceedling what model of $stderr capture to use
+         :arguments:
+            - -mem large   #simple command line argument
+            - -f "${1}"    #binary executable input file to simulator (Ruby method call param list sub)
+
+Resulting command line constructions from preceding example [:tools] YAML blurbs 
+
+    > compiler -I"/usr/include” -I”project/tests”
+      -I"project/tests/support” -I”project/source” -I”project/include”
+      -DTEST -DLONG_NAMES -network-license -optimize-level 4 arg-foo
+      arg-bar arg-baz -c project/source/source.c -o
+      build/tests/out/source.o
+
+[notes: (1.) "arg-foo arg-bar arg-baz" is a fabricated example 
+string collected from $stdout as a result of shell execution 
+of args.exe {text:line-break} (2.) the -c and -o arguments are 
+fabricated examples simulating a single compilation step for 
+a test; ${1} & ${2} are single files] 
+
+    > \programs\acme\bin\linker.exe thing.o unity.o
+      test_thing_runner.o test_thing.o mock_foo.o mock_bar.o -lfoo-lib
+      -lbar-lib -o build\tests\out\test_thing.exe
+
+[note: in this scenario ${1} is an array of all the object files 
+needed to link a test fixture executable] 
+
+    > tools\bin\acme_simulator.exe -mem large -f "build\tests\out\test_thing.bin 2>&1”
+
+[note: (1.) :executable could have simply been ${1} - if we were compiling
+and running native executables instead of cross compiling (2.) we're using
+$stderr redirection to allow us to capture simulator error messages to
+$stdout for display at the run's conclusion]
+
+
+Notes: 
+
+* The upper case names are Ruby global constants that Ceedling 
+  builds 
+
+* "COLLECTION_" indicates that Ceedling did some work to assemble 
+  the list. For instance, expanding path globs, {text:soft-page-break} 
+  combining multiple path globs into a convenient summation, 
+  etc. 
+
+* At present, $stderr redirection is primarily used to capture 
+  errors from test fixtures so that they can be displayed at the 
+  conclusion of a test run. For instance, if a simulator detects 
+  a memory access violation or a divide by zero error, this notice 
+  might go unseen in all the output scrolling past in a terminal. 
+
+* The preprocessing tools can each be overridden with non-gcc 
+  equivalents. However, this is an advanced feature not yet 
+  documented and requires that the replacement toolchain conform 
+  to the same conventions used by gcc. 
+
+**Ceedling Collection Used in Compilation**:
+
+* `COLLECTION_PATHS_TEST`:
+
+  All test paths
+
+* `COLLECTION_PATHS_SOURCE`:
+
+  All source paths
+
+* `COLLECTION_PATHS_INCLUDE`:
+
+  All include paths
+
+* `COLLECTION_PATHS_SUPPORT`:
+
+  All test support paths
+
+* `COLLECTION_PATHS_SOURCE_AND_INCLUDE`:
+
+  All source and include paths
+
+* `COLLECTION_PATHS_SOURCE_INCLUDE_VENDOR`:
+
+  All source and include paths + applicable vendor paths (e.g.
+  CException's source path if exceptions enabled)
+
+* `COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE`:
+
+  All test toolchain include paths
+
+* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE`:
+
+  All test, source, and include paths
+
+* `COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR`:
+
+  All test, source, include, and applicable vendor paths (e.g. Unity's
+  source path plus CMock and CException's source paths if mocks and
+  exceptions are enabled)
+
+* `COLLECTION_PATHS_RELEASE_TOOLCHAIN_INCLUDE`:
+
+  All release toolchain include paths
+
+* `COLLECTION_DEFINES_TEST_AND_VENDOR`:
+
+  All symbols specified in [:defines][:test] + symbols defined for
+  enabled vendor tools - e.g. [:unity][:defines], [:cmock][:defines],
+  and [:cexception][:defines]
+
+* `COLLECTION_DEFINES_RELEASE_AND_VENDOR`:
+
+  All symbols specified in [:defines][:release] plus symbols defined by
+[:cexception][:defines] if exceptions are ena bled
+
+
+Notes: 
+
+* Other collections exist within Ceedling. However, they are 
+  only useful for advanced features not yet documented. 
+
+* Wherever multiple path lists are combined for use Ceedling prioritizes
+  path groups as follows: {text:line-break} test paths, support paths,
+  source paths, include paths. This can be useful, for instance, in
+  certain testing scenarios where we desire Ceedling or the compiler to
+  find a stand-in header file before the actual source header file of
+  the same name.
+
+
+**plugins**: Ceedling extensions
+
+* `load_paths`:
+
+  Base paths to search for plugin subdirectories or extra ruby functionalit
+
+  **Default**: [] (empty)
+
+* `enabled`:
+
+  List of plugins to be used - a plugin's name is identical to the
+  subdirectory that contains it (and the name of certain files within
+  that subdirectory)
+
+  **Default**: [] (empty)
+
+
+Plugins can provide a variety of added functionality to Ceedling. In
+general use, it's assumed that at least one reporting plugin will be
+used to format test results. However, if no reporting plugins are
+specified, Ceedling will print to `$stdout` the (quite readable) raw
+test results from all test fixtures executed.
+
+Example [:plugins] YAML blurb 
+
+    :plugins:
+      :load_paths:
+        - project/tools/ceedling/plugins  #home to your collection of plugin directories
+        - project/support                 #maybe home to some ruby code your custom plugins share
+      :enabled:
+        - stdout_pretty_tests_report      #nice test results at your command line
+        - our_custom_code_metrics_report  #maybe you needed line count and complexity metrics, so you
+                                          #created a plugin to scan all your code and collect that info
+    
+
+* `stdout_pretty_tests_report`:
+
+  Prints to $stdout a well-formatted list of ignored and failed tests,
+  final test counts, and any extraneous output (e.g. printf statements
+  or simulator memory errors) collected from executing the test
+  fixtures. Meant to be used with runs at the command line.
+
+* `stdout_ide_tests_report`:
+
+  Prints to $stdout simple test results formatted such that an IDE
+  executing test-related Rake tasks can recognize file paths and line
+  numbers in test failures, etc. Thus, you can click a test result in
+  your IDE's execution window and jump to the failure (or ignored test)
+  in your test file (obviously meant to be used with an [IDE like
+  Eclipse][ide], etc).
+
+  [ide]: http://throwtheswitch.org/white-papers/using-with-ides.html
+
+* `xml_tests_report`:
+
+  Creates an XML file of test results in the xUnit format (handy for
+  Continuous Integration build servers or as input to other reporting
+  tools). Produces a file report.xml in <build root>/artifacts/tests.
+
+* `bullseye`:
+
+  Adds additional Rake tasks to execute tests with the commercial code
+  coverage tool provided by [Bullseye][]. See readme.txt inside the bullseye
+  plugin directory for configuration and use instructions. Note:
+  Bullseye only works with certain compilers and linkers (healthy list
+  of supported toolchains though).
+
+  [bullseye]: http://www.bullseye.com
+
+* `gcov`:
+
+  Adds additional Rake tasks to execute tests with the GNU code coverage
+  tool [gcov][]. See readme.txt inside the gcov directory for configuration
+  and use instructions. Only works with GNU compiler and linker.
+
+  [gcov]: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+
+* `warnings_report`:
+
+  Scans compiler and linker `$stdout / $stderr` output for the word
+  'warning' (case insensitive). All code warnings (or tool warnings) are
+  logged to a file warnings.log in the appropriate `<build
+  root>/artifacts` directory (e.g. test/ for test tasks, `release/` for a
+  release build, or even `bullseye/` for bullseye runs).
+
+
+Advanced Topics (Coming) 
+========================
+
+Modifying Your Configuration without Modifying Your Project File: Option Files & User Files 
+-------------------------------------------------------------------------------------------
+
+Modifying your project file without modifying your project file 
+
+Debugging and/or printf() 
+-------------------------
+
+When you gotta get your hands dirty... 
+
+Ceedling Plays Nice with Others - Using Ceedling for Tests Alongside Another Release Build Setup 
+------------------------------------------------------------------------------------------------
+
+You've got options. 
+
+Adding Handy Rake Tasks for Your Project (without Fancy Pants Custom Plugins) 
+-----------------------------------------------------------------------------
+
+Simple as snot. 
+
+Working with Non-Desktop Testing Environments 
+---------------------------------------------
+
+For those crazy platforms lacking command line simulators and for which
+cross-compiling on the desktop just ain't gonna get it done.
+
+Creating Custom Plugins 
+-----------------------
+
+Oh boy. This is going to take some explaining. 
+