Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
246 lines (236 sloc) 19.5 KB
<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Managing Rails Versions and Gems &#183; RailsApps</title>
<link href="" rel="publisher" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-5109366-14']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a href="" class="brand">RailsApps Project</a>
<ul class="pull-right nav">
<li><a href="" class="twitter">Blog</a></li>
<li><a href="" class="twitter">Twitter</a></li>
<li><a href="" class="google">Google +</a></li>
<li><a href="" class="github">GitHub Repository</a></li>
<div class="container">
<div class="content wikistyle gollum textile">
<h1>Managing Rails Versions and Gems</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 1 February 2012</em></p>
<p>Learn tips and tricks for managing Rails and Ruby gems. Relieve your headaches when versions collide.</p>
<p>This is a guide for developers using the example apps from the <a href="">Rails Apps</a> repository. Others may find it helpful as well.</p>
<p>Before you install one of the <a href="">Rails example apps</a>, there are a few things you should know about managing the pieces of the Rails platform. Often, everything “just works,” but when it doesn’t, here’s what you need to review. Read on if you’d like to know how all the moving parts work together.</p>
<h2>Install Rails 3.2</h2>
<p>See <a href="">Installing Rails 3.2</a> for detailed instructions and advice and see an <a href="">Example Rails 3.2 Gemfile</a>.</p>
<p>The Ruby on Rails platform is a living ecosystem: a community of developers, their projects, and complex dependencies among their projects. At times (often before and after the release of a major new version of Rails) the ecosystem enters a state of disequilibrium and important pieces no longer work together easily. These times of disequilibrium are valuable for the ecosystem because, as a whole, developers innovate and Rails improves during these times.</p>
<p>For you as a developer, it may feel like a trainwreck. You productivity will stall as you try to sort out what is broken and how to fix it. But you’ll find help here.</p>
<h4>Example Apps</h4>
<p>The example apps from the <a href="">Rails Apps</a> repository help you keep current with changing Rails and gem versions.</p>
<p>Each example provides a set of useful, popular Rails gems integrated into a working application. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Many developers use the apps, report problems as they arise, and propose solutions as GitHub issues.</p>
<p>These examples provide a working <strong>Rails app</strong> with a <strong>detailed tutorial</strong> plus an <strong>application template</strong> that can be used to create a <strong>starter app</strong>.</p>
<th>Author </th>
<th>Example App </th>
<th>Tutorial </th>
<th>App Template </th>
<th>Comments </th>
<td> Daniel Kehoe </td>
<td> <a href="">Devise, RSpec, Cucumber</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> Uses ActiveRecord and SQLite </td>
<td> Daniel Kehoe </td>
<td> <a href="">Twitter Bootstrap, Devise, CanCan</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> Devise for authentication, CanCan for authorization, Twitter Bootstrap for <span class="caps">CSS</span> </td>
<td> Daniel Kehoe </td>
<td> <a href="">Startup Prelaunch Signup</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> For a startup prelaunch signup site </td>
<td> Daniel Kehoe </td>
<td> <a href="">Devise, Mongoid</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> Combines Devise with MongoDB </td>
<td> Daniel Kehoe </td>
<td> <a href="">OmniAuth, Mongoid</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> OmniAuth for authentication with a MongoDB datastore </td>
<td> Daniel Kehoe </td>
<td> <a href="">Subdomains, Devise, Mongoid</a> </td>
<td> <a href="">Tutorial</a> </td>
<td> <a href="">App Template</a> </td>
<td> Basecamp-style subdomains with Devise and MongoDB </td>
<p>Ruby is the programming language used for Rails projects.</p>
<p>What version of Ruby is installed on your machine? Check with:</p>
<p><code>$ ruby -v</code></p>
<p>For the example apps it should be version 1.9.3.</p>
<p>You can check for the current <a href="">recommended version of Ruby</a>.</p>
<p>Ruby 1.9.3 patch level 0 was current when this was written.</p>
<p>See instructions for <a href="">Installing Rails 3.2</a> to install a newer version of Ruby if necessary.</p>
<p>RubyGems is a package management framework for Ruby. A gem is a packaged Ruby application or library. You can <a href="">read more about gems</a> if you wish. Gems come from a wonderful pool of open source love but can be a headache to track and integrate.</p>
<p>The RubyGems package management system comes as part of a standard Ruby language installation.</p>
<p>What version of the RubyGems system is installed on your machine? Check with:</p>
<p><code>$ gem -v</code></p>
<p>For the example apps it should be version 1.8.17 or newer.</p>
<p>The RubyGems package management system is part of a standard Ruby language installation. It can be updated by installing the rubygems-update gem.</p>
<p>You can check for the current <a href="">rubygems-update gem</a>.</p>
<p>Use <code>gem update --system</code> to upgrade the RubyGems system.</p>
<p>As of release 1.8.0 (4 May 2011), the RubyGems system gem began a series of rapid updates (with <a href="">controversy</a> and a promised <a href="">resolution</a>). The example apps all work with version 1.8.15 but if you install a gem and find it doesn’t work, roll back to an older version of RubyGems:</p>
<p><code>gem update --system 1.7.2</code></p>
<p>or even:</p>
<p><code>gem update --system 1.3.7</code></p>
<p>Rails itself is a gem, which means it can be installed and updated like any other gem.</p>
<p>What version of Rails is installed on your machine? Check with:</p>
<p><code>$ rails -v</code></p>
<p>You can check for the newest released <a href="">Rails version</a>.</p>
<p>For the example apps it should be version 3.2.</p>
<p>See instructions for <a href="">Installing Rails 3.2</a> to install or update Rails. I recommend that you create a new gemset using <a href="">rvm</a> before installing a new version of Rails (rather than using <code>gem update rails</code>). With rvm, you can switch gemsets to run your application under an earlier version of Rails.</p>
<p><a href="">Rake</a> is a software task management or “build” tool used extensively by Rails and many gems.</p>
<p>What version of rake is installed on your machine? Check with:</p>
<p><code>$ rake --version</code></p>
<p>You can check for the newest released <a href="">rake gem</a>.</p>
<p>For apps built with Rails 3.2, use rake or newer.</p>
<p>If you are using an older version of Rake, you should update Rake to 0.9.2 or newer immediately after creating a new gemset and before installing Rails 3.2.</p>
<p>Here’s how to update Rake:</p>
$ gem update rake
$ rake --version
<p>If you see this error message when installing one of the <a href="">Rails Apps examples</a>, you should create a new gemset, update Rake, and create a fresh install of Rails 3.2:</p>
The template ... could not be loaded.
Error: You have already activated rake 0.8.7, but your Gemfile requires rake 0.9.x.
Consider using bundle exec.
<p>See an explanation by David Chelimsky in his blog post <a href="">Rake 0.9 and Gem Version Constraints</a> about collisions among versions of Rake and gems.</p>
<h2>Bundler and the Gemfile</h2>
<p>The <a href="">Ruby Bundler</a> manages an application’s gems. Bundler works by reading a <strong>Gemfile</strong> in an application’s root directory, downloading and unpacking specified versions of each required gem, resolving any dependencies among gems, and creating a <strong>Gemfile.lock</strong> file to force use of the specified gem versions.</p>
<p>Each of the example apps is provided with a gemfile that specifies a known working set of required gems.</p>
<p>After creating an example app, run <code>bundle install</code> to install all the necessary gems.</p>
<p>If you add a new gem to the gemfile, run <code>bundle install</code> again.</p>
<p>If you want to force an upgrade to all the gems that have newer versions, run <code>bundle update</code>. When you update a gem, bundler will not update a dependency of that gem if another gem still depends on it.</p>
<h4>Gem Version Constraint</h4>
<p>You will specify the gems you need in your application’s Gemfile. If you don’t specify a version, your application will use the newest gem version installed on your machine.</p>
<p>If you run <code>bundle update</code>, each gem will be updated to the newest available. You may benefit from the features (or the bug fixes) of the newest version. Or you may discover integration issues with other gems which cause failures. To avoid surprises and manage gem updates cautiously, you can specify gem versions in your Gemfile (<a href="">described in the RubyGems manual</a>).</p>
<h4>Optimistic Version Constraint</h4>
<p>In the gemfiles for the example apps, you’ll often see “optimistic version constraint” specified with the <code>&gt;=</code> operator like this:</p>
<p><code>gem 'devise', '&gt;= 1.3.4'</code></p>
<p>This means, “use any version of the Devise gem that is newer than version 1.3.4.” It will force an upgrade of the Devise gem to version 1.3.4 the first time you run <code>bundle update</code> and check and install newer versions each subsequent time you run <code>bundle update</code>. That’s a good scheme for keeping your gems up-to-date unless there is a known issue with a gem.</p>
<h4>Pessimistic Version Constraint</h4>
<p>In the some gemfiles you may see “pessimistic version constraint” like this:</p>
<p><code>gem 'library', '~&gt; 2.2'</code></p>
<p>which is shorthand for</p>
<p><code>gem 'library', '&gt;= 2.2.0', '&lt; 3.0'</code></p>
<p>which means use any gem version newer than 2.2.0 but don’t install 3.0 or anything newer.</p>
<p>We seldom specify pessimistic version constraint for gems in the example apps unless a gem developer recommends it.</p>
<p>See recommendations about using pessimistic version constraint in a blog post by Dan Croak titled <a href="">Twiddle Wakka</a> (yes, the <code>~&gt;</code> operator is variously known as the “twiddle wakka,” “tildemator,” or “spermy operator.”)</p>
<h4>Absolute Version Constraint</h4>
<p>In the example apps, we use “absolute version constraint” to specify a known working version of a gem if we’ve seen reported problems with newer versions. Absolute version constraint looks like this:</p>
<p><code>gem 'library', '2.2'</code></p>
<h2>Using rvm to Manage Multiple Versions of Rails</h2>
<p>I recommend installing rvm, the <a href="">Ruby Version Manager</a>. It’s essential if you must use multiple versions of Rails. And rvm makes it easy to switch sets of gems if you suspect a problem with incompatibilities among gems.</p>
<h4>Install <span class="caps">RVM</span>
<p>The rvm website explains <a href="">how to install rvm</a>.</p>
<h4>Create a Gemset for a Project</h4>
<p>See instructions for <a href="">Installing Rails 3.2</a> to install Rails and create a new gemset using rvm.</p>
<h4>Using the .rvmrc file for Project-Specific Gemsets</h4>
<p>After you’ve created an rvm gemset that you’ll use for a project, you can create an <strong>.rvmrc</strong> file in the application’s root directory. <span class="caps">RVM</span> recgonizes an <strong>.rvmrc</strong> file in a directory and loads the gemset specified inside.</p>
<p>Here’s how to create an <strong>.rvmrc</strong> file if you’re using a gemset named “ruby-1.9.3-p0@rails32”:</p>
$ echo "rvm ruby-1.9.3-p0@rails32" &gt; .rvmrc
<p>Using an <strong>.rvmrc</strong> file means you’ll automatically be using the correct Rails and gem version when you run your application on your local machine. This works best if you create an rvm gemset specifically for your application.</p>
<h2>Using Pik to Manage Multiple Versions of Rails on Windows</h2>
<p>For Windows users juggling different versions of Ruby, <a href="">pik</a> is a tool similar to <span class="caps">RVM</span>. The pik set of commands for managing multiple rubies is similar to that of <span class="caps">RVM</span>.</p>
<h4>Install Pik</h4>
<p>The readme section on the <a href="">repository home page</a> gives the requirements for running pik, the most notable of which is that it requires Mat’s Ruby Interpreter version 1.8.7-p330. Make sure to install this version as your “default” Ruby version, which can be done most easily using <a href="">RubyInstaller</a>. In addition to Mat’s Ruby Interpreter, RubyInstaller also includes <a href="">DevKit</a> and other useful tools for Ruby programmers using Windows.</p>
<p>Pik can be installed with Windows Installer or by simply typing: </p><pre>C:\gem install pik</pre> once RubyInstaller 1.8.7-p330 has been installed and configured.
</div><!-- class="content" -->
<div class="comments">
<div class="content wikistyle gollum">
<h2>Comments and Issues</h2>
<p>Is this helpful? Please add a comment below. Your encouragement fuels the project.</p>
<p>Did you find an error? Or couldn't get something to work? For the example apps and tutorials, please create a GitHub issue in the repository for the example app. Creating a GitHub issue is the best way to make sure a problem is investigated and fixed.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
<noscript>Please enable JavaScript to view the <a href="">comments powered by Disqus.</a></noscript>
<a href="" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
<div class="footer row">
<div class="span4">
<p><a href="">Daniel Kehoe</a> initiated the <a href="">RailsApps Project</a>. Thanks to all the users and contributors.</p>
<div class="span4">
<p>Corrections? Additions? You can edit this page <a href="">on the wiki</a>.</p>
<div class="span4">
<h3>Last edit</h3>
<p>by <b>Daniel Kehoe</b>, 2012-07-20 23:08:42</p>
Something went wrong with that request. Please try again.