crafterm-sprinkle 0.1.5 → 0.1.6

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,23 +1,50 @@
 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)
-        super parent, &block
+      def initialize(parent, *packages, &block) #:nodoc:
         packages.flatten!
         
         options = { :dependencies_only => false }
         options.update(packages.pop) if packages.last.is_a?(Hash)
         
-        @command = options[:dependencies_only] ? 'build-dep' : 'install'
+        super parent, options, &block
+        
         @packages = packages
       end
 
       protected
 
-        def install_commands
-          "DEBCONF_TERSE='yes' DEBIAN_PRIORITY='critical' DEBIAN_FRONTEND=noninteractive apt-get -qyu #{@command} #{@packages.join(' ')}"
+        def install_commands #:nodoc:
+          command = @options[:dependencies_only] ? 'build-dep' : 'install'
+          "DEBCONF_TERSE='yes' DEBIAN_PRIORITY='critical' DEBIAN_FRONTEND=noninteractive apt-get -qyu #{command} #{@packages.join(' ')}"
         end
 
     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

data/lib/sprinkle/installers/rake.rb

@@ -1,14 +1,27 @@
 module Sprinkle
   module Installers
+    # = Rake Installer
+    #
+    # This installer runs a rake command.
+    # 
+    # == Example Usage
+    #
+    # The following example runs the command "rake spec" on
+    # the remote server.
+    #
+    #   package :spec do
+    #     rake 'spec'
+    #   end
+    # 
     class Rake < Installer
-      def initialize(parent, commands = [], &block)
+      def initialize(parent, commands = [], &block) #:nodoc:
         super parent, &block
         @commands = commands
       end
 
       protected
 
-        def install_commands
+        def install_commands #:nodoc:
           "rake #{@commands.join(' ')}"
         end
 

data/lib/sprinkle/installers/rpm.rb

@@ -1,9 +1,26 @@
 module Sprinkle
   module Installers
+    # = RPM Package Installer
+    #
+    # The RPM package installer installs RPM packages.
+    # 
+    # == Example Usage
+    #
+    # Installing the magic_beans RPM. Its all the craze these days.
+    #
+    #   package :magic_beans do
+    #     rpm 'magic_beans'
+    #   end
+    #
+    # You may also specify multiple rpms as an array:
+    #
+    #   package :magic_beans do
+    #     rpm %w(magic_beans magic_sauce)
+    #   end
     class Rpm < Installer
-      attr_accessor :packages
+      attr_accessor :packages #:nodoc:
 
-      def initialize(parent, packages, &block)
+      def initialize(parent, packages, &block) #:nodoc:
         super parent, &block
         packages = [packages] unless packages.is_a? Array
         @packages = packages
@@ -11,7 +28,7 @@ module Sprinkle
 
       protected
 
-        def install_commands
+        def install_commands #:nodoc:
           "rpm -Uvh #{@packages.join(' ')}"
         end
 

data/lib/sprinkle/installers/source.rb

@@ -1,16 +1,72 @@
 module Sprinkle
   module Installers
+    # = Source Package Installer
+    #
+    # The source package installer installs software from source.
+    # It handles downloading, extracting, configuring, building, 
+    # and installing software. 
+    #
+    # == Configuration Options
+    #
+    # The source installer has many configuration options:
+    # * <b>prefix</b> - The prefix directory that is configured to.
+    # * <b>archives</b> - The location all the files are downloaded to.
+    # * <b>builds</b> - The directory the package is extracted to to configure and install
+    #
+    # == Pre/Post Hooks
+    #
+    # The source installer defines a myriad of new stages which can be hooked into:
+    # * <b>prepare</b> - Prepare is the stage which all the prefix, archives, and build directories are made.
+    # * <b>download</b> - Download is the stage which the software package is downloaded.
+    # * <b>extract</b> - Extract is the stage which the software package is extracted.
+    # * <b>configure</b> - Configure is the stage which the ./configure script is run.
+    # * <b>build</b> - Build is the stage in which `make` is called.
+    # * <b>install</b> - Install is the stage which `make install` is called.
+    # 
+    # == Example Usage
+    #
+    # First, a simple package, no configuration:
+    #
+    #   package :magic_beans do
+    #     source 'http://magicbeansland.com/latest-1.1.1.tar.gz'
+    #   end
+    #
+    # Second, specifying exactly where I want my files:
+    #
+    #   package :magic_beans do
+    #     source 'http://magicbeansland.com/latest-1.1.1.tar.gz' do
+    #       prefix    '/usr/local'
+    #       archives  '/tmp'
+    #       builds    '/tmp/builds'
+    #     end
+    #   end
+    #
+    # Third, specifying some hooks:
+    #
+    #   package :magic_beans do
+    #     source 'http://magicbeansland.com/latest-1.1.1.tar.gz' do
+    #       prefix    '/usr/local'
+    #       
+    #       pre :prepare { 'echo "Here we go folks."' }
+    #       post :extract { 'echo "I believe..."' }
+    #       pre :build { 'echo "Cross your fingers!"' }
+    #     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 Source < Installer
-      attr_accessor :source
+      attr_accessor :source #:nodoc:
 
-      def initialize(parent, source, options = {}, &block)
+      def initialize(parent, source, options = {}, &block) #:nodoc:
         @source = source
         super parent, options, &block
       end
 
       protected
 
-        def install_sequence
+        def install_sequence #:nodoc:
           prepare + download + extract + configure + build + install
         end
 
@@ -20,7 +76,7 @@ module Sprinkle
           end
         end
 
-        def prepare_commands
+        def prepare_commands #:nodoc:
           raise 'No installation area defined' unless @options[:prefix]
           raise 'No build area defined' unless @options[:builds]
           raise 'No source download area defined' unless @options[:archives]
@@ -30,15 +86,15 @@ module Sprinkle
             "mkdir -p #{@options[:archives]}" ]
         end
 
-        def download_commands
+        def download_commands #:nodoc:
           [ "wget -cq --directory-prefix='#{@options[:archives]}' #{@source}" ]
         end
 
-        def extract_commands
+        def extract_commands #:nodoc:
           [ "bash -c 'cd #{@options[:builds]} && #{extract_command} #{@options[:archives]}/#{archive_name}'" ]
         end
 
-        def configure_commands
+        def configure_commands #:nodoc:
           return [] if custom_install?
 
           command = "bash -c 'cd #{build_dir} && ./configure --prefix=#{@options[:prefix]} "
@@ -53,38 +109,40 @@ module Sprinkle
           [ command << " > #{@package.name}-configure.log 2>&1'" ]
         end
 
-        def build_commands
+        def build_commands #:nodoc:
           return [] if custom_install?
           [ "bash -c 'cd #{build_dir} && make > #{@package.name}-build.log 2>&1'" ]
         end
 
-        def install_commands
+        def install_commands #:nodoc:
           return custom_install_commands if custom_install?
           [ "bash -c 'cd #{build_dir} && make install > #{@package.name}-install.log 2>&1'" ]
         end
 
-        def custom_install?
+        def custom_install? #:nodoc:
           !! @options[:custom_install]
         end
 
         # REVISIT: must be better processing of custom install commands somehow? use splat operator?
-        def custom_install_commands
+        def custom_install_commands #:nodoc:
           dress @options[:custom_install], :install
         end
 
       protected
 
+        # dress is overriden from the base Sprinkle::Installers::Installer class so that the command changes
+        # directory to the build directory first. Also, the result of the command is logged.
         def dress(commands, stage)
           commands.collect { |command| "bash -c 'cd #{build_dir} && #{command} >> #{@package.name}-#{stage}.log 2>&1'" }
         end
 
       private
 
-        def create_options(key, prefix)
+        def create_options(key, prefix) #:nodoc:
           @options[key].inject(' ') { |m, option| m << "#{prefix}-#{option} "; m }
         end
 
-        def extract_command
+        def extract_command #:nodoc:
           case @source
           when /(tar.gz)|(tgz)$/
             'tar xzf'
@@ -99,17 +157,17 @@ module Sprinkle
           end
         end
 
-        def archive_name
+        def archive_name #:nodoc:
           name = @source.split('/').last
           raise "Unable to determine archive name for source: #{source}, please update code knowledge" unless name
           name
         end
 
-        def build_dir
+        def build_dir #:nodoc:
           "#{@options[:builds]}/#{options[:custom_dir] || base_dir}"
         end
 
-        def base_dir
+        def base_dir #:nodoc:
           if @source.split('/').last =~ /(.*)\.(tar\.gz|tgz|tar\.bz2|tb2)/
             return $1
           end