crafterm-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).
@@ -60,13 +66,14 @@ remote hosts. Currently Sprinkle supports the use of Capistrano or Vlad to issue
 but could also be extended to use any other command transport mechanism or be used to simply issue installation
 commands on the local system.
 
-An full example Sprinkle deployment script for deploying Rails (via gems), MySQL (via APT), and Apache (via source):
+An full example Sprinkle deployment script for deploying Rails (via gems), MySQL (via APT), Apache (via source) 
+and Git (via source with dependencies from APT):
 
     # Sprinkle Rails deployment script
     #
-    # This is an example Sprinkle script, configured to install Rails from gems, Apache and Ruby from source,
-    # and mysql from apt on an Ubuntu system. Installation is configured to run via Capistrano (and
-    # an accompanying deploy.rb recipe script). Source based packages are downloaded and built into
+    # This is an example Sprinkle script, configured to install Rails from gems, Apache, Ruby and Git from source,
+    # and mysql and Git dependencies from apt on an Ubuntu system. Installation is configured to run via 
+    # Capistrano (and an accompanying deploy.rb recipe script). Source based packages are downloaded and built into
     # /usr/local on the remote system.
     #
     # A sprinkle script is separated into 3 different sections. Packages, policies and deployment.
@@ -148,6 +155,18 @@ An full example Sprinkle deployment script for deploying Rails (via gems), MySQL
       version '1.0.5'
       requires :mongrel
     end
+    
+    package :git, :provides => :scm do
+      description 'Git Distributed Version Control'
+      version '1.5.6.3'
+      source "http://kernel.org/pub/software/scm/git/git-#{version}.tar.gz"
+      requires :git_dependencies
+    end
+
+    package :git_dependencies do
+      description 'Git Build Dependencies'
+      apt 'git', :dependencies_only => true
+    end
 
     # Policies
 
@@ -161,6 +180,7 @@ An full example Sprinkle deployment script for deploying Rails (via gems), MySQL
       requires :appserver
       requires :database
       requires :webserver
+      requires :scm
     end
 
     # Deployment

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/examples/rails/rails.rb

@@ -2,8 +2,8 @@
 
 # Annotated Example Sprinkle Rails deployment script
 #
-# This is an example Sprinkle script configured to install Rails from gems, Apache, Ruby and
-# Sphinx from source, and mysql from apt on an Ubuntu system.
+# This is an example Sprinkle script configured to install Rails from gems, Apache, Ruby,
+# Sphinx and Git from source, and mysql and Git dependencies from apt on an Ubuntu system.
 #
 # Installation is configured to run via capistrano (and an accompanying deploy.rb recipe script).
 # Source based packages are downloaded and built into /usr/local on the remote system.
@@ -22,6 +22,7 @@ require 'packages/rails'
 require 'packages/database'
 require 'packages/server'
 require 'packages/search'
+require 'packages/scm'
 
 
 # Policies
@@ -39,6 +40,7 @@ policy :rails, :roles => :app do
   requires :database
   requires :webserver
   requires :search
+  requires :scm
 end
 
 

data/lib/sprinkle.rb

@@ -10,17 +10,23 @@ Dependencies.load_paths << File.dirname(__FILE__)
 
 # Load up extensions to existing classes
 Dir[File.dirname(__FILE__) + '/sprinkle/extensions/*.rb'].each { |e| require e }
+# Load up the verifiers so they can register themselves
+Dir[File.dirname(__FILE__) + '/sprinkle/verifiers/*.rb'].each { |e| require e }
 
 # Configuration options
 module Sprinkle
-  OPTIONS = { :testing => false, :verbose => false }
+  OPTIONS = { :testing => false, :verbose => false, :force => false }
 end
 
+# Object is extended to give the package, policy, and deployment methods. To
+# read about each method, see the corresponding module which is included.
+#--
 # Define a logging target and understand packages, policies and deployment DSL
+#++
 class Object
   include Sprinkle::Package, Sprinkle::Policy, Sprinkle::Deployment
 
-  def logger
+  def logger # :nodoc:
     @@__log__ ||= ActiveSupport::BufferedLogger.new($stdout, ActiveSupport::BufferedLogger::Severity::INFO)
   end
 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