Module: Sprinkle::Package

Included in:
Defined in:



A package defines one or more things to provision onto the server. There is a lot of flexibility in a way a package is defined but let me give you a basic example:

package :ruby do
  description 'Ruby MRI'
  version '1.8.6'
  apt 'ruby'

  verify { has_executable 'ruby' }

The above would define a package named 'ruby' and give it a description and explicitly say its version. It is installed via apt and to verify the installation was successful sprinkle will check for the executable 'ruby' being availble. Pretty simple, right?

Note: Defining a package does not INSTALL it. To install a package, you must require it in a Sprinkle::Policy block.


Most packages have some sort of pre-requisites in order to be installed. Sprinkle allows you to define the requirements of the package, which will be installed before the package itself. An example below:

package :rubygems do
  source ''
  requires :ruby

In this case, when rubygems is being installed, Sprinkle will first provision the server with Ruby to make sure the requirements are met. In turn, if ruby has requirements, it installs those first, and so on.


Packages can be given defaults. These default options are available as a hash in opts.

package :deploy_user do
  defaults :username => 'deploy'
  add_user opts[:username]

Options given when requiring a package are merged over the defaults

requires :deploy_user, :username => 'deployer'


Most of the time its important to know whether the software you're attempting to install was installed successfully or not. For this, Sprinkle provides verifications. Verifications are one or more blocks which define rules with which Sprinkle can check if it installed the package successfully. If these verification blocks fail, then Sprinkle will gracefully stop the entire process. An example below:

package :rubygems do
  source ''
  requires :ruby

  verify { has_executable 'gem' }

In addition to verifying an installation was successfully, by default Sprinkle runs these verifications before the installation to check if the package is already installed. If the verifications pass before installing the package, it skips the package. To override this behavior, set the -f flag on the sprinkle script or set the :force option to true in Sprinkle::OPTIONS

For more information on verifications and to see all the available verifications, see Sprinkle::Verify

Virtual Packages

Sometimes, there are multiple packages available for a single task. An example is a database package. It can contain mySQL, postgres, or sqlite! This is where virtual packages come in handy. They are defined as follows:

package :sqlite3, :provides => :database do
  apt 'sqlite3'

The :provides option allows you to reference this package either by :sqlite3 or by :database. But whereas the package name is unique, multiple packages may share the same provision. If this is the case, when running Sprinkle, the script will ask you which provision you want to install. At this time, you can only install one.


A package doesn't require an installer. If you want to define a package which merely encompasses other packages, that is fine too. Example:

package :meta do
  requires :magic_beans
  requires :magic_sauce

– FIXME: Should probably document recommendations. ++

Defined Under Namespace

Modules: Rendering Classes: Chooser, Package, PackageRepository

Constant Summary collapse


Instance Method Summary collapse

Instance Method Details

#package(name, metadata = {}, &block) ⇒ Object

# File 'lib/sprinkle/package.rb', line 113

def package(name,  = {}, &block)
  package =, , &block)
  PACKAGES << package