sprinkle 0.1.5 → 0.1.6

data/CREDITS

@@ -13,4 +13,5 @@ Matt Allen         (http://blog.allen.com.au)
 Eric Hodel         (http://blog.segment7.net)
 Pete Yandell       (http://notahat.com)
 Adam Meehan        (http://duckpunching.com)
-Mitchell Hashimoto (http://mitchellhashimoto.com)
+Mitchell Hashimoto (http://mitchellhashimoto.com)
+Ari Lerner         (http://www.citrusbyte.com)

data/Manifest.txt

@@ -2,12 +2,11 @@ CREDITS
 History.txt
 MIT-LICENSE
 Manifest.txt
-README.rdoc
+README.txt
 Rakefile
 bin/sprinkle
 config/hoe.rb
 config/requirements.rb
-examples/merb/deploy.rb
 examples/rails/README
 examples/rails/deploy.rb
 examples/rails/packages/database.rb
@@ -18,8 +17,10 @@ examples/rails/packages/server.rb
 examples/rails/rails.rb
 examples/sprinkle/sprinkle.rb
 lib/sprinkle.rb
+lib/sprinkle/actors/actors.rb
 lib/sprinkle/actors/capistrano.rb
 lib/sprinkle/actors/vlad.rb
+lib/sprinkle/configurable.rb
 lib/sprinkle/deployment.rb
 lib/sprinkle/extensions/arbitrary_options.rb
 lib/sprinkle/extensions/array.rb
@@ -36,6 +37,13 @@ lib/sprinkle/installers/source.rb
 lib/sprinkle/package.rb
 lib/sprinkle/policy.rb
 lib/sprinkle/script.rb
+lib/sprinkle/verifiers/directory.rb
+lib/sprinkle/verifiers/executable.rb
+lib/sprinkle/verifiers/file.rb
+lib/sprinkle/verifiers/process.rb
+lib/sprinkle/verifiers/ruby.rb
+lib/sprinkle/verifiers/symlink.rb
+lib/sprinkle/verify.rb
 lib/sprinkle/version.rb
 script/destroy
 script/generate
@@ -54,6 +62,7 @@ spec/sprinkle/package_spec.rb
 spec/sprinkle/policy_spec.rb
 spec/sprinkle/script_spec.rb
 spec/sprinkle/sprinkle_spec.rb
+spec/sprinkle/verify_spec.rb
 sprinkle.gemspec
 tasks/deployment.rake
 tasks/environment.rake

data/{README.rdoc → README.txt}

@@ -20,10 +20,16 @@ An example package description follows:
       version '1.8.6'
       source "ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-#{version}-p111.tar.gz"
       requires :ruby_dependencies
+      
+      verify do
+        has_file '/usr/bin/ruby'
+      end
     end
 
 This defines a package called 'ruby', that uses the source based installer to build Ruby 1.8.6 from source,
-installing the package 'ruby_dependencies' beforehand.
+installing the package 'ruby_dependencies' beforehand. Additionally, the package verifies it was installed
+correctly by verifying the file '/usr/bin/ruby' exists after installation. If this verification fails, the
+sprinkle script will gracefully stop.
 
 Reasonable defaults are set by sprinkle, such as the install prefix, download area, etc, but can be customized
 globally or per package (see below for an example).

data/bin/sprinkle

@@ -46,6 +46,8 @@ BANNER
           "Verbose output") { |OPTIONS[:verbose]| }
   opts.on("-c", "--cloud",
           "Show powder cloud, ie. package hierarchy and installation order") { |OPTIONS[:cloud]| }
+  opts.on("-f", "--force",
+          "Force installation of all packages even if it is detected that it has been previously installed") { |OPTIONS[:force]| }
   opts.on("-h", "--help",
           "Show this help message.") { puts opts; exit }
   opts.parse!(ARGV)
@@ -55,6 +57,10 @@ BANNER
   end
 end
 
+def force_mode(options)
+  Sprinkle::OPTIONS[:force] = OPTIONS[:force] || false
+end
+
 def operation_mode(options)
   Sprinkle::OPTIONS[:testing] = OPTIONS[:testing] || false
 end
@@ -72,6 +78,7 @@ require 'sprinkle'
 powder = OPTIONS[:path]
 raise "Sprinkle script is not readable: #{powder}" unless File.readable?(powder)
 
+force_mode(OPTIONS)
 operation_mode(OPTIONS)
 powder_cloud(OPTIONS)
 log_level(OPTIONS)

data/config/hoe.rb

@@ -35,7 +35,7 @@ VERS = Sprinkle::VERSION::STRING + (REV ? ".#{REV}" : "")
 RDOC_OPTS = ['--quiet', '--title', 'sprinkle documentation',
     "--opname", "index.html",
     "--line-numbers", 
-    "--main", "README",
+    "--main", "README.txt",
     "--inline-source"]
 
 class Hoe
@@ -59,7 +59,7 @@ hoe = Hoe.new(GEM_NAME, VERS) do |p|
   # == Optional
   p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
   p.extra_deps = [ ['activesupport', '>= 2.0.2'], ['highline', '>= 1.4.0'], ['capistrano', '>= 2.2.0'] ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
-  
+
   #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
   
 end

data/lib/sprinkle/actors/actors.rb

@@ -0,0 +1,17 @@
+#--
+# The only point of this file is to give RDoc a definition for
+# Sprinkle::Actors. This file in production is never actually included
+# since ActiveSupport only on-demand loads classes which are needed
+# and this module is never explicitly needed.
+#++
+
+module Sprinkle
+  # An actor is a method of command delivery to a remote machine. It is the
+  # layer between sprinkle and the SSH connection to run commands. This gives
+  # you the flexibility to define custom actors, for whatever purpose you need.
+  #
+  # 99% of the time, however, the two built-in actors Sprinkle::Actors::Capistrano
+  # and Sprinkle::Actors::Vlad will be enough.
+  module Actors
+  end
+end

data/lib/sprinkle/actors/capistrano.rb

@@ -2,10 +2,26 @@ require 'capistrano/cli'
 
 module Sprinkle
   module Actors
+    # = Capistrano Delivery Method
+    #
+    # Capistrano is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the capistrano gem install, you may use
+    # this delivery. The only configuration option available, and which is 
+    # mandatory to include is +recipes+. An example:
+    #
+    #   deployment do
+    #     delivery :capistrano do
+    #       recipes 'deploy'
+    #     end
+    #   end
+    #
+    # Recipes is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled. 
     class Capistrano
-      attr_accessor :config, :loaded_recipes
+      attr_accessor :config, :loaded_recipes #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         @config = ::Capistrano::Configuration.new
         @config.logger.level = Sprinkle::OPTIONS[:verbose] ? ::Capistrano::Logger::INFO : ::Capistrano::Logger::IMPORTANT
         @config.set(:password) { ::Capistrano::CLI.password_prompt }
@@ -16,20 +32,41 @@ module Sprinkle
         end
       end
 
+      # Defines a recipe file which will be included by capistrano. Use these
+      # recipe files to set capistrano specific configurations. Default recipe
+      # included is "deploy." But if any other recipe is specified, it will
+      # include that instead. Multiple recipes may be specified through multiple
+      # recipes calls, an example:
+      #
+      #   deployment do
+      #     delivery :capistrano do
+      #       recipes 'deploy'
+      #       recipes 'magic_beans'
+      #     end
+      #   end
       def recipes(script)
         @loaded_recipes ||= []
         @config.load script
         @loaded_recipes << script
       end
 
-      def process(name, commands, roles)
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
         define_task(name, roles) do
           via = fetch(:run_method, :sudo)
           commands.each do |command|
             invoke_command command, :via => via
           end
         end
-        run(name)
+        
+        begin
+          run(name)
+          return true
+        rescue ::Capistrano::CommandError => e
+          return false if suppress_and_return_failures
+          
+          # Reraise error if we're not suppressing it
+          raise
+        end
       end
 
       private

data/lib/sprinkle/actors/vlad.rb

@@ -1,23 +1,58 @@
 module Sprinkle
   module Actors
+    # = Vlad Delivery Method
+    #
+    # Vlad is one of the delivery method options available out of the
+    # box with Sprinkle. If you have the vlad the deployer gem install, you 
+    # may use this delivery. The only configuration option available, and 
+    # which is mandatory to include is +script+. An example:
+    #
+    #   deployment do
+    #     delivery :vlad do
+    #       script 'deploy'
+    #     end
+    #   end
+    #
+    # script is given a list of files which capistrano will include and load.
+    # These recipes are mainly to set variables such as :user, :password, and to 
+    # set the app domain which will be sprinkled.
     class Vlad
       require 'vlad'
-      attr_accessor :loaded_recipes
+      attr_accessor :loaded_recipes #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         self.instance_eval &block if block
       end
 
+      # Defines a script file which will be included by vlad. Use these
+      # script files to set vlad specific configurations. Multiple scripts
+      # may be specified through multiple script calls, an example:
+      #
+      #   deployment do
+      #     delivery :vlad do
+      #       script 'deploy'
+      #       script 'magic_beans'
+      #     end
+      #   end
       def script(name)
         @loaded_recipes ||= []
         self.load name
         @loaded_recipes << script
       end
 
-      def process(name, commands, roles)
+      def process(name, commands, roles, suppress_and_return_failures = false) #:nodoc:
         commands = commands.join ' && ' if commands.is_a? Array
         t = remote_task(task_sym(name), :roles => roles) { run commands }
-        t.invoke
+        
+        begin
+          t.invoke
+          return true
+        rescue ::Vlad::CommandFailedError => e
+          return false if suppress_and_return_failures
+          
+          # Reraise error if we're not suppressing it
+          raise
+        end
       end
 
       private

data/lib/sprinkle/configurable.rb

@@ -0,0 +1,31 @@
+module Sprinkle
+  #--
+  # TODO: Possible documentation?
+  #++
+  module Configurable #:nodoc:
+    attr_accessor :delivery
+    
+    def defaults(deployment)
+      defaults = deployment.defaults[self.class.name.split(/::/).last.downcase.to_sym]
+      self.instance_eval(&defaults) if defaults
+      @delivery = deployment.style
+    end
+    
+    def assert_delivery
+      raise 'Unknown command delivery target' unless @delivery
+    end
+    
+    def method_missing(sym, *args, &block)
+      unless args.empty? # mutate if not set
+        @options ||= {}
+        @options[sym] = *args unless @options[sym]
+      end
+
+      @options[sym] || @package.send(sym, *args, &block) # try the parents options if unknown
+    end
+    
+    def option?(sym)
+      !@options[sym].nil?
+    end
+  end
+end

data/lib/sprinkle/deployment.rb

@@ -1,29 +1,69 @@
 module Sprinkle
+  # Deployment blocks specify deployment specific information about a 
+  # sprinkle script. An example:
+  #
+  #   deployment do
+  #     # mechanism for deployment
+  #     delivery :capistrano do
+  #       recipes 'deploy'
+  #     end
+  # 
+  #     # source based package installer defaults
+  #     source do
+  #       prefix   '/usr/local'
+  #       archives '/usr/local/sources'
+  #       builds   '/usr/local/build'
+  #     end
+  #   end
+  #
+  # What the above example does is tell sprinkle that we will be using
+  # *capistrano* (Sprinkle::Actors::Capistrano) for deployment and
+  # everything within the block is capistrano specific configuration.
+  # For more information on what options are available, check the corresponding
+  # Sprinkle::Actors doc page.
+  #
+  # In addition to what delivery mechanism we're using, we specify some
+  # configuration options for the "source" command. The only things
+  # configurable, at this time, in the deployment block other than
+  # the delivery method are installers. If installers are configurable,
+  # they will say so on their corresponding documentation page. See
+  # Sprinkle::Installers
+  #
+  # <b>Only one deployment block is on any given sprinkle script</b>
   module Deployment
+    # The method outlined above which specifies deployment specific information
+    # for a sprinkle script. For more information, read the header of this module.
     def deployment(&block)
       @deployment = Deployment.new(&block)
     end
 
     class Deployment
-      attr_accessor :style, :defaults
+      attr_accessor :style, :defaults #:nodoc:
 
-      def initialize(&block)
+      def initialize(&block) #:nodoc:
         @defaults = {}
         self.instance_eval(&block)
         raise 'No delivery mechanism defined' unless @style
       end
 
-      def delivery(type, &block)
+      # Specifies which Sprinkle::Actors to use for delivery. Although all
+      # actors jobs are the same: to run remote commands on a server, you
+      # may have a personal preference. The block you pass is used to configure
+      # the actor. For more information on what configuration options are
+      # available, view the corresponding Sprinkle::Actors page.
+      def delivery(type, &block) #:doc:
         @style = Actors.const_get(type.to_s.titleize).new &block
       end
 
-      def method_missing(sym, *args, &block)
+      def method_missing(sym, *args, &block) #:nodoc:
         @defaults[sym] = block
       end
 
-      def respond_to?(sym); !!@defaults[sym]; end
+      def respond_to?(sym) #:nodoc:
+        !!@defaults[sym]
+      end
 
-      def process
+      def process #:nodoc:
         POLICIES.each do |policy|
           policy.process(self)
         end

data/lib/sprinkle/extensions/arbitrary_options.rb

@@ -1,4 +1,4 @@
-module ArbitraryOptions
+module ArbitraryOptions #:nodoc:
   def self.included(base)
     base.alias_method_chain :method_missing, :arbitrary_options
   end

data/lib/sprinkle/extensions/array.rb

@@ -1,7 +1,5 @@
-class Array
-  
+class Array #:nodoc:
   def to_task_name
     collect(&:to_task_name).join('_')
   end
-  
 end

data/lib/sprinkle/extensions/blank_slate.rb

@@ -1,4 +1,4 @@
-class BlankSlate
+class BlankSlate #:nodoc:
   instance_methods.each do |m| 
     undef_method(m) unless %w( __send__ __id__ send class inspect instance_eval instance_variables ).include?(m)
   end

data/lib/sprinkle/extensions/dsl_accessor.rb

@@ -1,4 +1,4 @@
-class Module
+class Module #:nodoc:
   def dsl_accessor(*symbols)
     symbols.each do |sym|
       class_eval %{

data/lib/sprinkle/extensions/string.rb

@@ -1,4 +1,4 @@
-class String
+class String #:nodoc:
   
   # REVISIT: what chars shall we allow in task names?
   def to_task_name

data/lib/sprinkle/extensions/symbol.rb

@@ -1,4 +1,4 @@
-class Symbol
+class Symbol #:nodoc:
   
   def to_task_name
     to_s.to_task_name

data/lib/sprinkle/installers/apt.rb

@@ -1,9 +1,35 @@
 module Sprinkle
   module Installers
+    # = Apt Package Installer
+    #
+    # The Apt package installer uses the +apt-get+ command to install
+    # packages. The apt installer has only one option which can be
+    # modified which is the +dependencies_only+ option. When this is
+    # set to true, the installer uses +build-dep+ instead of +install+
+    # to only build the dependencies.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans package:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     apt 'magic_beans_package'
+    #   end
+    #
+    # Second, only build the magic_beans dependencies:
+    #
+    #   package :magic_beans_depends do
+    #     apt 'magic_beans_package' { dependencies_only true }
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
     class Apt < Installer
-      attr_accessor :packages
+      attr_accessor :packages #:nodoc:
 
-      def initialize(parent, *packages, &block)
+      def initialize(parent, *packages, &block) #:nodoc:
         super parent, &block
         packages.flatten!
         
@@ -16,7 +42,7 @@ module Sprinkle
 
       protected
 
-        def install_commands
+        def install_commands #:nodoc:
           "DEBCONF_TERSE='yes' DEBIAN_PRIORITY='critical' DEBIAN_FRONTEND=noninteractive apt-get -qyu #{@command} #{@packages.join(' ')}"
         end
 

data/lib/sprinkle/installers/gem.rb

@@ -1,14 +1,42 @@
 module Sprinkle
   module Installers
+    # = Ruby Gem Package Installer
+    #
+    # The gem package installer installs ruby gems.
+    #
+    # The installer has a single optional configuration: source.
+    # By changing source you can specify a given ruby gems
+    # repository from which to install.
+    # 
+    # == Example Usage
+    #
+    # First, a simple installation of the magic_beans gem:
+    #
+    #   package :magic_beans do
+    #     description "Beans beans they're good for your heart..."
+    #     gem 'magic_beans'
+    #   end
+    #
+    # Second, install magic_beans gem from github:
+    #
+    #   package :magic_beans do
+    #     gem 'magic_beans_package' do
+    #       source 'http://gems.github.com'
+    #     end
+    #   end
+    #
+    # As you can see, setting options is as simple as creating a
+    # block and calling the option as a method with the value as 
+    # its parameter.
     class Gem < Installer
-      attr_accessor :gem
+      attr_accessor :gem #:nodoc:
 
-      def initialize(parent, gem, options = {}, &block)
+      def initialize(parent, gem, options = {}, &block) #:nodoc:
         super parent, options, &block
         @gem = gem
       end
 
-      def source(location = nil)
+      def source(location = nil) #:nodoc:
         # package defines an installer called source so here we specify a method directly
         # rather than rely on the automatic options processing since packages' method missing
         # won't be run
@@ -20,14 +48,14 @@ module Sprinkle
 
         # rubygems 0.9.5+ installs dependencies by default, and does platform selection
 
-        def install_commands
+        def install_commands #:nodoc:
           cmd = "gem install #{gem}"
           cmd << " --version '#{version}'" if version
           cmd << " --source #{source}" if source
-          cmd << " --install-dir #{repository}" if repository
+          cmd << " --install-dir #{repository}" if option?(:repository)
           cmd
         end
-
+        
     end
   end
 end

data/lib/sprinkle/installers/installer.rb

@@ -1,9 +1,49 @@
 module Sprinkle
   module Installers
+    # The base class which all installers must subclass, this class makes
+    # sure all installers share some general features, which are outlined
+    # below. 
+    #
+    # = Pre/Post Installation Hooks
+    # 
+    # With all intallation methods you have the ability to specify multiple
+    # pre/post installation hooks. This gives you the ability to specify
+    # commands to run before and after an installation takes place. All 
+    # commands by default are sudo'd so there is no need to include "sudo"
+    # in the command itself. There are three ways to specify a pre/post hook.
+    # 
+    # First, a single command:
+    #
+    #   pre :install, 'echo "Hello, World!"'
+    #   post :install, 'rm -rf /'
+    #
+    # Second, an array of commands:
+    #
+    #   commands = ['echo "First"', 'echo "Then Another"']
+    #   pre :install, commands
+    #   post :install, commands
+    #
+    # Third, a block which returns either a single or multiple commands:
+    #
+    #   pre :install do
+    #     amount = 7 * 3
+    #     "echo 'Before we install, lets plant #{amount} magic beans...'"
+    #   end
+    #   post :install do
+    #     ['echo "Now... let's hope they sprout!", 'echo "Indeed they have!"']
+    #   end
+    #
+    # = Other Pre/Post Hooks
+    #
+    # Some installation methods actually grant you more fine grained
+    # control of when commands are run rather than a blanket pre :install
+    # or post :install. If this is the case, it will be documented on
+    # the installation method's corresponding documentation page. 
     class Installer
-      attr_accessor :delivery, :package, :options, :pre, :post
+      include Sprinkle::Configurable
+      attr_accessor :delivery, :package, :options, :pre, :post #:nodoc:
 
-      def initialize(package, options = {}, &block)
+      def initialize(package, options = {}, &block) #:nodoc:
         @package = package
         @options = options
         @pre = {}; @post = {}
@@ -13,21 +53,17 @@ module Sprinkle
       def pre(stage, *commands)
         @pre[stage] ||= []
         @pre[stage] += commands
+        @pre[stage] += [yield] if block_given?
       end
 
       def post(stage, *commands)
         @post[stage] ||= []
         @post[stage] += commands
+        @post[stage] += [yield] if block_given?
       end
 
-      def defaults(deployment)
-        defaults = deployment.defaults[self.class.name.split(/::/).last.downcase.to_sym]
-        self.instance_eval(&defaults) if defaults
-        @delivery = deployment.style
-      end
-
-      def process(roles)
-        raise 'Unknown command delivery target' unless @delivery
+      def process(roles) #:nodoc:
+        assert_delivery
 
         if logger.debug?
           sequence = install_sequence; sequence = sequence.join('; ') if sequence.is_a? Array
@@ -40,44 +76,43 @@ module Sprinkle
         end
       end
 
-      def method_missing(sym, *args, &block)
-        unless args.empty? # mutate if not set
-          @options[sym] = *args unless @options[sym]
-        end
-
-        @options[sym] || @package.send(sym, *args, &block) # try the parents options if unknown
-      end
-
       protected
-
-        # Installation is separated into two styles that concrete derivative installer classes
-        # can implement.
-        #
-        # Simple installers that issue a single or set of commands can overwride
-        # install_commands (eg. apt, gem, rpm). Pre/post install commands are included in this
-        # style for free.
-        #
         # More complicated installers that have different stages, and require pre/post commands
         # within stages can override install_sequence and take complete control of the install
         # command sequence construction (eg. source based installer).
-
         def install_sequence
           commands = pre_commands(:install) + [ install_commands ] + post_commands(:install)
           commands.flatten
         end
 
+        # A concrete installer (subclass of this virtual class) must override this method
+        # and return the commands it needs to run as either a string or an array. 
+        #
+        # <b>Overriding this method is required.</b>
         def install_commands
           raise 'Concrete installers implement this to specify commands to run to install their respective packages'
         end
 
-        def pre_commands(stage)
+        def pre_commands(stage) #:nodoc:
           dress @pre[stage] || [], :pre
         end
 
-        def post_commands(stage)
+        def post_commands(stage) #:nodoc:
           dress @post[stage] || [], :post
         end
 
+        # Concrete installers (subclasses of this virtual class) can override this method to
+        # specify stage-specific (pre-installation, post-installation, etc.) modifications
+        # of commands. 
+        #
+        # An example usage of overriding this would be to prefix all commands for a 
+        # certain stage to change to a certain directory. An example is given below:
+        #
+        #   def dress(commands, stage)
+        #     commands.collect { |x| "cd #{magic_beans_path} && #{x}" }
+        #   end
+        #
+        # By default, no modifications are made to the commands.
         def dress(commands, stage); commands; end
 
     end