Blogfoon

Blogfoon is a personal space for thoughtful notes on technology, coding, travel, and ordinary life.

  • Published:

A Gemfile records the gems a Ruby application depends on and the conditions under which each one should be available. Bundler reads it to decide what to install and what to load, so the declarations directly shape the application's runtime.

Choosing gem sources

Use source to tell Bundler where gems can be fetched. More than one source can appear:

source "https://rubygems.org"
source "http://gems.github.com"
source "http://ruby.taobao.com"

When several sources are listed, later entries have higher priority. In mainland China, the Taobao mirror has traditionally been a practical choice when access to rubygems.org is slow.

Pinning the Ruby runtime

If the application depends on a particular Ruby version or implementation, declare it in the Gemfile:

ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"

The engine and engine_version options are optional.

Declaring gems

gem is the most flexible directive. Only the gem name is required:

gem "nokogiri"

Everything else is optional, and the remaining options can be combined as needed.

Version constraints

You can request a specific version or a version range:

gem 'rails', '3.0.0.beta3'
gem 'rack',  '>=1.0'
gem 'thin',  '~>1.1'

>= asks for the newest version at or above the stated one. The ~> operator is more restrictive: ~> 1.1 means at least 1.1 but below 2.0, while ~> 2.0.3 means at least 2.0.3 but below 2.1. It keeps a gem within a release range instead of allowing any later major version.

Requiring a different entry point

If the gem's main file has a different name from the gem itself, use require to point at the right file:

gem 'rspec', :require => 'spec'

Setting require to false prevents Bundler from requiring the gem automatically at runtime:

gem "webmock", :require => false

Grouping gems by environment

Some gems are only useful in development, such as wirble; others are only needed in test, such as rspec; production may need a different set. Groups let Bundler skip what a particular environment does not need:

gem "rspec", :group => :test
gem "wirble", :groups => [:development, :test]

Then bundle install can omit groups:

bundle install --without development test

Git repositories, GitHub, and local paths

Sometimes a gem must come from somewhere other than a gem server: a fork, a branch, an unreleased commit, or a local working copy. git, github, and path cover those cases:

gem 'nokogiri', :git => 'git://github.com/tenderlove/nokogiri.git', :branch => '1.4'
gem 'nokogiri', :path => '~/sw/gems/nokogiri'
gem "rails", :github => "rails/rails"

path points to a directory on disk. git and github point to a repository; branch, tag, and ref select a specific revision.

Platform-specific gems

platforms narrows a dependency to a particular Ruby implementation or operating system. This is common for gems that only work on JRuby, MRI 1.8, or another runtime:

gem "weakling",   :platforms => :jruby
gem "ruby-debug", :platforms => :mri_18
gem "nokogiri", :platforms => [:mri_18, :jruby]

Applying options to several gems at once

Block forms of group, git, path, and platforms apply the same setting to every gem inside the block:

git "git://github.com/rails/rails.git" do
  gem "activesupport"
  gem "actionpack"
end

platforms :ruby do
  gem "ruby-debug"
  gem "sqlite3"
end

group :development do
  gem "wirble"
  gem "faker"
end

Used this way, a Gemfile stays readable even when many gems share the same source, platform, or environment constraint.

Related Posts