class Sprinkle::Installers::Installer

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 installation 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. There are three ways to specify a pre/post hook.

Note about sudo: When using the Capistrano actor all commands by default are run using sudo (unless your Capfile includes “set :use_sudo, false”). If you wish to use sudo periodically with “set :user_sudo, false” or with an actor other than Capistrano then you can just append it to your command. Some installers (transfer) also support a :sudo option, so check each installer for details.

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.

Public Class Methods

api(&block) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 76
def api(&block)
  Sprinkle::Package::Package.add_api(&block)
end
inherited(base) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 84
def inherited(base)
  subclasses << base
end
subclasses() click to toggle source
# File lib/sprinkle/installers/installer.rb, line 72
def subclasses
  @subclasses ||= []
end
verify_api(&block) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 80
def verify_api(&block)
  Sprinkle::Verify.class_eval(&block)
end

Public Instance Methods

announce() click to toggle source

Called right before an installer is exected, can be used for logging and announcing what is about to happen

# File lib/sprinkle/installers/installer.rb, line 139
def announce; end
commands_from_block(block) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 113
def commands_from_block(block)
  return [] unless block
  out = nil
  diff = @package.with_private_install_queue { out = block.call }
  diff.each {|x| x.delivery = self.delivery }
  diff.empty? ? out : diff.map {|x| x.install_sequence }
end
defer(block) click to toggle source

defer execution of command block until the package is being processed

# File lib/sprinkle/installers/installer.rb, line 109
def defer(block)
  p = Proc.new { self.commands_from_block(block) }
end
escape_shell_arg(str) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 89
def escape_shell_arg(str)
  str.gsub("'", "'\\\\''").gsub("\n", '\n')
end
install_sequence() click to toggle source

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).

# File lib/sprinkle/installers/installer.rb, line 157
def install_sequence
  commands = pre_commands(:install) + [ install_commands ] + post_commands(:install)
  flatten commands
end
method_missing(method, *args, &block) click to toggle source
Calls superclass method
# File lib/sprinkle/installers/installer.rb, line 121
def method_missing(method, *args, &block)
  if package.class.installer_methods.include?(method)
    @package.send(method, *args, &block)
  else
    super(method, *args, &block)
  end
end
per_host?() click to toggle source
# File lib/sprinkle/installers/installer.rb, line 129
def per_host?
  return false
end
post(stage, *commands, &block) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 100
def post(stage, *commands, &block)
  @post[stage] ||= []
  @post[stage] += commands
  @post[stage] << defer(block) if block_given?
  @post[stage]
end
post_process() click to toggle source

Called right after processing, can be used for local cleanup such as removing any temporary files created on the local system, etc

# File lib/sprinkle/installers/installer.rb, line 135
def post_process; end
pre(stage, *commands, &block) click to toggle source
# File lib/sprinkle/installers/installer.rb, line 93
def pre(stage, *commands, &block)
  @pre[stage] ||= []
  @pre[stage] += commands
  @pre[stage] << defer(block) if block_given?
  @pre[stage]
end

Protected Instance Methods

dress(commands, stage) click to toggle source

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.

# File lib/sprinkle/installers/installer.rb, line 200
def dress(commands, stage); commands; end
install_commands() click to toggle source

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.

Overriding this method is required.

# File lib/sprinkle/installers/installer.rb, line 176
def install_commands
  raise 'Concrete installers implement this to specify commands to run to install their respective packages'
end