Permalink
Fetching contributors…
Cannot retrieve contributors at this time
414 lines (341 sloc) 18 KB
.container.guide
#intro
If you just want to know our recommended workflow, and don't care about the rationale, feel
free to <a href="#summary">jump to the summary</a> below.
%br
#standalone
%h2#bundlers-purpose-and-rationale
Bundler's Purpose and Rationale
%p
First, you declare these dependencies in a file at the root of your application, called
<code>Gemfile</code>. It looks something like this:
:code
# lang: ruby
source 'https://rubygems.org'
gem 'rails', '4.1.0.rc2'
gem 'rack-cache'
gem 'nokogiri', '~> 1.6.1'
%p
This <code>Gemfile</code> says a few things. First, it says that bundler should look for gems
declared in the <code>Gemfile</code> at <code>https://rubygems.org</code> by default. If some
of your gems need to be fetched from a private gem server, this default source can be overridden
for those gems.
%p
Next, you declare a few dependencies:
%ul
%li on version <code>4.1.0.rc2</code> of <code>rails</code>
%li on any version of <code>rack-cache</code>
%li on a version of <code>nokogiri</code> that is <code>>= 1.6.1</code> but <code>< 1.7.0</code>
%p
After declaring your first set of dependencies, you tell bundler to go get them:
:code
$ bundle install # 'bundle' is a shortcut for 'bundle install'
%p
Bundler will connect to <code>rubygems.org</code> (and any other sources that you declared),
and find a list of all of the required gems that meet the requirements you specified. Because
all of the gems in your <code>Gemfile</code> have dependencies of their own (and some of
those have their own dependencies), running <code>bundle install</code> on the
<code>Gemfile</code> above will install quite a few gems.
:code
$ bundle install
Fetching gem metadata from https://rubygems.org/.........
Fetching additional metadata from https://rubygems.org/..
Resolving dependencies...
Using rake 10.3.1
Using json 1.8.1
Installing minitest 5.3.3
Installing i18n 0.6.9
Installing thread_safe 0.3.3
Installing builder 3.2.2
Installing rack 1.5.2
Installing erubis 2.7.0
Installing mime-types 1.25.1
Using bundler 1.6.2
Installing polyglot 0.3.4
Installing arel 5.0.1.20140414130214
Installing hike 1.2.3
Installing mini_portile 0.5.3
Installing multi_json 1.9.3
Installing thor 0.19.1
Installing tilt 1.4.1
Installing tzinfo 1.1.0
Installing rack-test 0.6.2
Installing rack-cache 1.2
Installing treetop 1.4.15
Installing sprockets 2.12.1
Installing activesupport 4.1.0.rc2
Installing mail 2.5.4
Installing actionview 4.1.0.rc2
Installing activemodel 4.1.0.rc2
Installing actionpack 4.1.0.rc2
Installing activerecord 4.1.0.rc2
Installing actionmailer 4.1.0.rc2
Installing sprockets-rails 2.0.1
Installing railties 4.1.0.rc2
Installing rails 4.1.0.rc2
Installing nokogiri 1.6.1
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.
%p
If any of the needed gems are already installed, Bundler will use them. After installing
any needed gems to your system, bundler writes a snapshot of all of the gems and
versions that it installed to <code>Gemfile.lock</code>.
%h2#setting-up-your-application-to-use-bundler
Setting Up Your Application to Use Bundler
%p
Bundler makes sure that Ruby can find all of the gems in the <code>Gemfile</code>
(and all of their dependencies). If your app is a Rails app, your default application
already has the code necessary to invoke bundler.
%p
For another kind of application (such as a Sinatra application), you will need to set up
bundler before trying to require any gems. At the top of the first file that your
application loads (for Sinatra, the file that calls <code>require 'sinatra'</code>), put
the following code:
:code
# lang: ruby
require 'rubygems'
require 'bundler/setup'
%p
This will automatically discover your <code>Gemfile</code>, and make all of the gems in
your <code>Gemfile</code> available to Ruby (in technical terms, it puts the gems "on the
load path"). You can think of it as an adding some extra powers to <code>require
'rubygems'</code>.
%p
Now that your code is available to Ruby, you can require the gems that you need. For
instance, you can <code>require 'sinatra'</code>. If you have a lot of dependencies, you
might want to say "require all of the gems in my <code>Gemfile</code>". To do this, put
the following code immediately following <code>require 'bundler/setup'</code>:
:code
# lang: ruby
Bundler.require(:default)
For our example Gemfile, this line is exactly equivalent to:
:code
# lang: ruby
require 'rails'
require 'rack-cache'
require 'nokogiri'
%p
For such a small <code>Gemfile</code>, we'd advise you to skip
<code>Bundler.require</code> and just require the gems by hand. For much
larger <code>Gemfile</code>s, using <code>Bundler.require</code> allows you to skip
repeating a large stack of requirements.
%h2#checking-your-code-into-version-control
Checking Your Code into Version Control
%p
After developing your application for a while, check in the application together with
the <code>Gemfile</code> and <code>Gemfile.lock</code> snapshot. Now, your repository
has a record of the exact versions of all of the gems that you used the last time you
know for sure that the application worked. Keep in mind that while your
<code>Gemfile</code> lists only three gems (with varying degrees of version strictness),
your application depends on dozens of gems, once you take into consideration all of the
implicit requirements of the gems you depend on.
%p
This is important: <strong>the <code>Gemfile.lock</code> makes your application a single
package of both your own code and the third-party code it ran the last time you know for
sure that everything worked</strong>. Specifying exact versions of the third-party code
you depend on in your <code>Gemfile</code> would not provide the same guarantee, because
gems usually declare a range of versions for their dependencies.
%p
The next time you run <code>bundle install</code> on the same machine, bundler will see
that it already has all of the dependencies you need, and skip the installation process.
%p
Do not check in the <code>.bundle</code> directory, or any of the files inside it. Those
files are specific to each particular machine, and are used to persist installation options
between runs of the <code>bundle install</code> command.
%p
If you have run <code>bundle pack</code>, the gems (although not the git gems) required
by your bundle will be downloaded into <code>vendor/cache</code>. Bundler can run without
connecting to the internet (or the RubyGems server) if all the gems you need are present
in that folder and checked in to your source control. This is an <strong>optional</strong>
step, and not recommended, due to the increase in size of your source control repository.
%h2#sharing-your-application-with-other-developers
Sharing Your Application With Other Developers
%p
When your co-developers (or you on another machine) check out your code, it will come
with the exact versions of all the third-party code your application used on the machine
that you last developed on (in the <code>Gemfile.lock</code>). When **they** run
<code>bundle install</code>, bundler will find the <code>Gemfile.lock</code> and skip
the dependency resolution step. Instead, it will install all of the same gems that you
used on the original machine.
%p
In other words, you don't have to guess which versions of the dependencies you should
install. In the example we've been using, even though <code>rack-cache</code> declares a
dependency on <code>rack >= 0.4</code>, we know for sure it works with <code>rack
1.5.2</code>. Even if the Rack team releases <code>rack 1.5.3</code>, bundler will
always install <code>1.5.2</code>, the exact version of the gem that we know works. This
relieves a large maintenance burden from application developers, because all machines
always run the exact same third-party code.
%h2#updating-a-dependency
Updating a Dependency
%p
Of course, at some point, you might want to update the version of a particular
dependency your application relies on. For instance, you might want to update
<code>rails</code> to <code>4.1.0</code> final. Importantly, just because you're
updating one dependency, it doesn't mean you want to re-resolve all of your dependencies
and use the latest version of everything. In our example, you only have three
dependencies, but even in this case, updating everything can cause complications.
%p
To illustrate, the <code>rails 4.1.0.rc2</code> gem depends on <code>actionpack
4.1.0.rc2</code> gem, which depends on <code>rack ~> 1.5.2</code> (which means <code>>=
1.5.2</code> and <code>< 1.6.0</code>). The <code>rack-cache</code> gem depends on
<code>rack >= 0.4</code>. Let's assume that the <code>rails 4.1.0</code> final gem also
depends on <code>rack ~> 1.5.2</code>, and that since the release of <code>rails
4.1.0</code>, the Rack team released <code>rack 1.5.3</code>.
%p
If we naïvely update all of our gems in order to update Rails, we'll get <code>rack
1.5.3</code>, which satisfies the requirements of both <code>rails 4.1.0</code> and
<code>rack-cache</code>. However, we didn't specifically ask to update
<code>rack-cache</code>, which may not be compatible with <code>rack 1.5.3</code> (for
whatever reason). And while an update from <code>rack 1.5.2</code> to <code>rack
1.5.3</code> probably won't break anything, similar scenarios can happen that involve
much larger jumps. (see [1] below for a larger discussion)
%p
In order to avoid this problem, when you update a gem, bundler will not update a
dependency of that gem if another gem still depends on it. In this example, since
<code>rack-cache</code> still depends on <code>rack</code>, bundler will not update the
<code>rack</code> gem. This ensures that updating <code>rails</code> doesn't
inadvertently break <code>rack-cache</code>. Since <code>rails 4.1.0</code>'s dependency
<code>actionpack 4.1.0</code> remains compatible with <code>rack 1.5.2</code>, bundler
leaves it alone, and <code>rack-cache</code> continues to work even in the face of an
incompatibility with <code>rack 1.5.3</code>.
%p
Since you originally declared a dependency on <code>rails 4.1.0.rc2</code>, if you want
to update to <code>rails 4.1.0</code>, simply update your <code>Gemfile</code> to
<code>gem 'rails', '4.1.0'</code> and run:
:code
$ bundle install
%p
As described above, the <code>bundle install</code> command always does a conservative
update, refusing to update gems (or their dependencies) that you have not explicitly
changed in the <code>Gemfile</code>. This means that if you do not modify
<code>rack-cache</code> in your <code>Gemfile</code>, bundler will treat it **and its
dependencies** (<code>rack</code>) as a single, unmodifiable unit. If <code>rails
4.1.0</code> was incompatible with <code>rack-cache</code>, bundler will report a
conflict between your snapshotted dependencies (<code>Gemfile.lock</code>) and your
updated <code>Gemfile</code>.
%p
If you update your <code>Gemfile</code>, and your system already has all of the needed
dependencies, bundler will transparently update the <code>Gemfile.lock</code> when you
boot your application. For instance, if you add <code>mysql</code> to your
<code>Gemfile</code>, and have already installed it in your system, you can boot your
application without running <code>bundle install</code>, and bundler will persist the
"last known good" configuration to the <code>Gemfile.lock</code> snapshot.
%p
This can come in handy when adding or updating gems with minimal dependencies (database
drivers, <code>wirble</code>, <code>ruby-debug</code>). It will probably fail if you
update gems with significant dependencies (<code>rails</code>), or that a lot of gems
depend on (<code>rack</code>). If a transparent update fails, your application will fail
to boot, and bundler will print out an error instructing you to run <code>bundle
install</code>.
%h2#updating-a-gem-without-modyfying-the-gemfile
Updating a Gem Without Modifying the Gemfile
%p
Sometimes, you want to update a dependency without modifying the Gemfile. For example,
you might want to update to the latest version of <code>rack-cache</code>. Because you
did not declare a specific version of <code>rack-cache</code> in the
<code>Gemfile</code>, you might want to periodically get the latest version of
<code>rack-cache</code>. To do this, you want to use the <code>bundle update</code>
command:
:code
$ bundle update rack-cache
%p
This command will update <code>rack-cache</code> and its dependencies to the latest
version allowed by the <code>Gemfile</code> (in this case, the latest version
available). It will not modify any other dependencies.
%p
It will, however, update dependencies of other gems if necessary. For instance, if the
latest version of <code>rack-cache</code> specifies a dependency on <code>rack >=
1.5.2</code>, bundler will update <code>rack</code> to <code>1.5.2</code> even though
you have not asked bundler to update <code>rack</code>. If bundler needs to update a
gem that another gem depends on, it will let you know after the update has completed.
%p
If you want to update every gem in the Gemfile to the latest possible versions, run:
:code
$ bundle update
%p
This will resolve dependencies from scratch, ignoring the <code>Gemfile.lock</code>. If
you do this, keep <code>git reset --hard</code> and your test suite in your back pocket.
Resolving all dependencies from scratch can have surprising results, especially if a
number of the third-party packages you depend on have released new versions since you
last did a full update.
%h2#summary
Summary
%h2 A Simple Bundler Workflow
%ul
%li
%p
When you first create a Rails application, it already comes with a
<code>Gemfile</code>. For another kind of application (such as Sinatra), run:
:code
$ bundle init
%p
The <code>bundle init</code> command creates a simple <code>Gemfile</code> which you
can edit.
%li
%p
Next, add any gems that your application depends on. If you care which version of a
particular gem that you need, be sure to include an appropriate version restriction:
:code
# lang: ruby
source 'https://rubygems.org'
gem 'sinatra', '~> 1.3.6'
gem 'rack-cache'
gem 'rack-bug'
%li
%p
If you don't have the gems installed in your system yet, run:
:code
$ bundle install
%li
%p
To update a gem's version requirements, first modify the Gemfile:
:code
# lang: ruby
source 'https://rubygems.org'
gem 'sinatra', '~> 1.4.5'
gem 'rack-cache'
gem 'rack-bug'
%p
and then run:
:code
$ bundle install
%li
%p
If <code>bundle install</code> reports a conflict between your <code>Gemfile</code>
and <code>Gemfile.lock</code>, run:
:code
$ bundle update sinatra
%p
This will update just the Sinatra gem, as well as any of its dependencies.
%li
%p
To update all of the gems in your <code>Gemfile</code> to the latest possible
versions, run:
:code
$ bundle update
%li
Whenever your <code>Gemfile.lock</code> changes, always check it in to version
control. It keeps a history of the exact versions of all third-party code that you
used to successfully run your application.
%li
%p
When deploying your code to a staging or production server, first run your tests (or
boot your local development server), make sure you have checked in your
<code>Gemfile.lock</code> to version control. On the remote server, run:
:code
$ bundle install --deployment
%h2#notes
Notes
%p
[1] For instance, if <code>rails 4.1.0</code> depended on <code>rack 2.0</code>, that
gem would still satisfy the requirement of <code>rack-cache</code>, which declares
<code>>= 0.4</code> as a dependency. Of course, you could argue that
<code>rack-cache</code> is silly for depending on open-ended versions, but these
situations exist (extensively) in the wild, and projects often find themselves between a
rock and a hard place when deciding what version to depend on. Constrain the dependency
too much (<code>rack =1.5.1</code>) and you make it hard to use your project in other
compatible projects. Constrain it too little (<code>rack >= 1.0</code>) and a new
release of Rack may break your code. Using dependencies like <code>rack ~> 1.5.2</code>
and versioning code in a SemVer compliant way mostly solves this problem, but it assumes
universal compliance. Since RubyGems has over 100,000 packages, this assumption simply
doesn't hold in practice.