WarningShot Dependency Resolution Framework

* Additional documentation @ http://github.com/coryodaniel/warningshot/wikis/

Installing WarningShot

WarningShot installs a little differently than most gems.  WarningShot itself has NO gem dependencies.  Gems become
a dependency based on what Plugins/Resolvers you have installed.  By default WarningShot will not install any additional gems.
When using WarningShot if a gem is missing that is needed for a feature you are using you will receive a warning that the gem
is missing.  Optionally you can list and build all of warningshots dependencies from the command line.

sudo gem install warningshot
warningshot --list-deps (list all resolvers and their dependencies)
warningshot --build-deps (install all gems that resolvers are dependent on)

This method provides a minimalist WarningShot.  WarningShot's dependencies essentially change depending on what you use
it for.  Thats neat, not a lot of extra gems that you don't need installed being installed.

Terminology

* Resolver
  A class that includes WarningShot::Resolver.  It should have the ability to test and resolve a type
  of dependency

* Configuration
  The current configuration the WarningShot instance is running under.
  Configurations can be created with WarningShot::Config

* Dependency
  A dependency is an entry in a machine recipe.  A dependency should consist of some means of identifying the
  dependency and optionally (but suggested) have some way of describing how it should be resolved.
    Ex: File Dependencies specify where the file should be located, and where WarningShot can download it if it
        does not exist

* Test
  Tests are blocks that are registered in resolver.  They are a means of determining if a dependency is met.  Multiple tests
  can be written, and may also have conditions as to whether they should run or not (a test could be environment
  specific for instance).  WarningShot will run the first test that it can based on any conditions provided.  
  Tests should always return a Boolean value

* Resolution
  Resolutions are like tests in every way except instead of determine if a dependency has been met, they actually
  repair or resolve the dependency.  The gem resolver can install missing gems and the file resolver can download
  missing files

* Machine Recipes / Application Recipes
  A machine recipe is one or more dependency branches, the default file type is YAML, but that is configurable
  within warningshot.  A machine recipe can specify the complete configuration of a computer/application or just one
  aspect of it.  Example:  warningshot --templates will create a separate machine recipe for each branch supported.
  In the wiki (http://github.com/coryodaniel/warningshot/wikis/example-merbnginx-app-recipe-once-aptquality-dependencies-are-supported)
  is an example of a machine recipe that specifies dependencies of files, gems, apt binaries, etc.

* DependencyTree
  After WarningShot locates all of the Machine Recipes they are parsed into the dependency tree.  The dependency
  tree is a large hash of branch names to raw hashes parsed from the Machine Recipes (YAML).

* DependencyBranch
  A specific type of dependency within the dependency tree.  Examples include, :file, :gem, :directory

How it works

* WarningShot - Factory class that creates and runs DependencyResolver
* DependencyResolver - Locates Resolver classes, creates a dependency tree, and matches resolvers to resolution branches
* Resolver - Class that can be included to create plugins.  Composed of tests and resolutions that can determine if a dependency was met, and if not, how to fix it

Command Line Examples

For a list of all flags do: warningshot –help

- Details on Resolvers warningshot –version - Loading specific resolvers warningshot –oload=gem,file # => Only gem and file resolvers will be run warningshot –pload=directory,file # => Only loads specified gems and loads in specified order warningshot –resolvers=/path/to/my/resolvers/*.rb # => Glob to find additional resolvers

- Creating Recipe templates warningshot –templates=./path/to/where/you/want/templates - Warningshot’s Dependencies warningshot –list-deps # => Depedencies per Resolver warningshot –build-deps # => Installs everything a full fledged warningshot needs

Ruby API

- Configuring WarningShot
config = WarningShot::Config.create do |c|
  c[:environment]  = 'development'
  c[:resolve]      = false
  c[:config_paths] = ['.'  / 'config' / 'warningshot']
  c[:application]  = '.'
  c[:log_path]     = '.' / 'log' / 'warningshot.log'
  c[:log_level]    = :debug
  c[:growl]        = false
  c[:verbose]      = true
  c[:colorize]     = true
  c[:]
end

- Interfacing with a DependencyResolver
dependency_resolver = WarningShot.fire!(config)
dependency_resolver.stats                       # => Hash of statistics

dependency_resolver.resolvers                   # => Array of all executed resolvers

dependency_resolver.resolvers.first.dependencies #=> Set of all loaded dependencies

dependency_resolver.resolver.first.passed     # => Array of passed dependencies
dependency_resolver.resolver.first.failed     # => Array of failed dependencies
dependency_resolver.resolver.first.unresolved # => Array of unresolved dependencies
dependency_resolver.resolver.first.resolved   # => Array of resolved dependencies

- Callbacks
WarningShot.before do 
  puts 'this would run before the DepenencyResolver was created in #fire!'
end

WarningShot.after do
  puts 'this would run after the DepenencyResolver was processed in #fire!'
end

WarningShot::AnyResolverYouWant.before :test do
  puts 'this would run before the #test! method on the chosen resolver'
end

WarningShot::AnotherFunResolver.after :test do
  puts 'this would run after the #test! method'
end

WarningShot::AnotherResolver.before :resolution do
  puts 'this would run before the #resolve! method'
end

WarningShot::AnotherResolver.after :resolution do
  puts 'this would run after the #resolve! method'
end

Components

* Ruby API
* Resolvers
* Config Files

Using Machine Recipes

* Coming Soon

How the dependency tree works

* Coming Soon

Extending WarningShot

* Writing a Resolver (Coming Soon)
   * Kernel#require vs Resolver#add_dependency
* Modifying Resolvers at run-time (Coming Soon)

Contributing

* Source available @: 
   https://github.com/coryodaniel/warningshot/tree

* Bug reports / feature requests @:
   http://warningshot.lighthouseapp.com/projects/17241-warningshot/overview

* Online Documentation available @:
   http://github.com/coryodaniel/warningshot/wikis

* RubyForge Project @:
   http://rubyforge.org/projects/warning-shot/

* All modifications should also have applicable rpsecs
   http://rspec.info/

* A dummy gem has been created for testing the GemResolver
   https://rubyforge.org/projects/ws-dummy/
   http://github.com/coryodaniel/ws-dummy/tree/master
   gem install ws-dummy

* All code should be documented using YARD
   http://yard.rubyforge.org/
   A template is available file://./yardoc_template.txt
   Generate Yardoc with: yardoc --output-dir ./doc/yard --private --protected --readme README