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