diff options
Diffstat (limited to 'rationale.html')
| -rw-r--r-- | rationale.html | 454 |
1 files changed, 0 insertions, 454 deletions
diff --git a/rationale.html b/rationale.html deleted file mode 100644 index e756507877..0000000000 --- a/rationale.html +++ /dev/null @@ -1,454 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <title>Bundler: The best way to manage a Ruby application's gems</title> - <meta content='text/html; charset=UTF-8' http-equiv='Content-Type'> - <meta content='276VSYOko8B8vIu1i8i5qbj7_ql5PXo0dU69XQy-SL' name='globalsign-domain-verification'> - <link href='/images/favicon.png' rel='shortcut icon' type='image/png'> - <link href="/stylesheets/application.css" media="screen" rel="stylesheet" type="text/css" /> - </head> - <body> - <div id='body'> - <div id='header'> - <a class="image" href="/"><img width="725" alt="The best way to manage your application's dependencies" src="/images/gembundler.png" /></a> - </div> - <div id='container'> - <div id='contents'> - <div id='intro'> - If you just want to know our recommended workflow, and don't care about the rationale, feel - free to jump to the summary below. - </div> - <br> - <div id='standalone'> - <h2 id='bundlers-purpose-and-rationale'> - Bundler's Purpose and Rationale - </h2> - <p> - First, you declare these dependencies in a file at the root of your application, called - <code>Gemfile</code>. It looks something like this: - </p> - <pre class="highlight ruby"><span class="n">source</span> <span class="s1">'https://rubygems.org'</span>

<span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="s1">'3.0.0.rc'</span>
<span class="n">gem</span> <span class="s1">'rack-cache'</span>
<span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="s1">'~> 1.4.2'</span>
</pre> - <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>http://rubygems.org</code>. You can declare - multiple Rubygems sources, and bundler will look for gems in the order you declared the - sources. - </p> - <p> - Next, you declare a few dependencies: - </p> - <ul> - <li>on version <code>3.0.0.rc</code> of <code>rails</code></li> - <li>on any version of <code>rack-cache</code></li> - <li>on a version of <code>nokogiri</code> that is <code>>= 1.4.2</code> but <code>< 1.5.0</code></li> - </ul> - <p> - After declaring your first set of dependencies, you tell bundler to go get them: - </p> - <pre class="highlight plaintext">$ bundle install # <code>bundle</code> is a shortcut for <code>bundle install</code>
</pre> - <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. - </p> - <pre class="highlight plaintext">$ bundle install
Fetching gem metadata from https://rubygems.org/
Resolving dependencies...
Using rake (0.8.7)
Using abstract (1.0.0)
Installing activesupport (3.0.0.rc)
Using builder (2.1.2)
Using i18n (0.4.1)
Installing activemodel (3.0.0.rc)
Using erubis (2.6.6)
Using rack (1.2.1)
Installing rack-mount (0.6.9)
Using rack-test (0.5.4)
Using tzinfo (0.3.22)
Installing actionpack (3.0.0.rc)
Using mime-types (1.16)
Using polyglot (0.3.1)
Using treetop (1.4.8)
Using mail (2.2.5)
Installing actionmailer (3.0.0.rc)
Using arel (0.4.0)
Installing activerecord (3.0.0.rc)
Installing activeresource (3.0.0.rc)
Using bundler (1.0.0.rc.3)
Installing nokogiri (1.4.3.1) with native extensions
Installing rack-cache (0.5.2)
Installing thor (0.14.0)
Installing railties (3.0.0.rc)
Installing rails (3.0.0.rc)
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
</pre> - <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>. - </p> - <h2 id='setting-up-your-application-to-use-bundler'> - Setting Up Your Application to Use Bundler - </h2> - <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 3 app, your default application - already has the code necessary to invoke bundler. If it is a Rails 2.3 app, please see - <a href="./rails23.html">Setting up Bundler in Rails 2.3</a>. - </p> - <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: - </p> - <pre class="highlight ruby"><span class="nb">require</span> <span class="s1">'rubygems'</span>
<span class="nb">require</span> <span class="s1">'bundler/setup'</span>
</pre> - <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> - <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>: - </p> - <pre class="highlight ruby"><span class="no">Bundler</span><span class="p">.</span><span class="nf">require</span><span class="p">(</span><span class="ss">:default</span><span class="p">)</span>
</pre> - For our example Gemfile, this line is exactly equivalent to: - <pre class="highlight ruby"><span class="nb">require</span> <span class="s1">'rails'</span>
<span class="nb">require</span> <span class="s1">'rack-cache'</span>
<span class="nb">require</span> <span class="s1">'nokogiri'</span>
</pre> - <p> - Astute readers will notice that the correct way to require the <code>rack-cache</code> - gem is <code>require 'rack/cache'</code>, not <code>require 'rack-cache'</code>. To tell - bundler to use <code>require 'rack/cache'</code>, update your Gemfile: - </p> - <pre class="highlight ruby"><span class="n">source</span> <span class="s1">'http://rubygems.org'</span>

<span class="n">gem</span> <span class="s1">'rails'</span><span class="p">,</span> <span class="s1">'3.0.0.rc'</span>
<span class="n">gem</span> <span class="s1">'rack-cache'</span><span class="p">,</span> <span class="ss">:require</span> <span class="o">=></span> <span class="s1">'rack/cache'</span>
<span class="n">gem</span> <span class="s1">'nokogiri'</span><span class="p">,</span> <span class="s1">'~> 1.4.2'</span>
</pre> - <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 (especially given the - need to put in a <code>:require</code> directive in the <code>Gemfile</code>). For much - larger <code>Gemfile</code>s, using <code>Bundler.require</code> allows you to skip - repeating a large stack of requirements. - </p> - <h2 id='checking-your-code-into-version-control'> - Checking Your Code into Version Control - </h2> - <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> - <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> - <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> - <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> - <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. - </p> - <h2 id='sharing-your-application-with-other-developers'> - Sharing Your Application With Other Developers - </h2> - <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> - <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.2.1</code>. Even if the Rack team releases <code>rack 1.2.2</code>, bundler will - always install <code>1.2.1</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. - </p> - <h2 id='updating-a-dependency'> - Updating a Dependency - </h2> - <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>3.0.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> - <p> - To illustrate, the <code>rails 3.0.0.rc</code> gem depends on <code>actionpack - 3.0.0.rc</code> gem, which depends on <code>rack ~> 1.2.1</code> (which means <code>>= - 1.2.1</code> and <code>< 1.3.0</code>). The <code>rack-cache</code> gem depends on - <code>rack >= 0.4</code>. Let's assume that the <code>rails 3.0.0</code> final gem also - depends on <code>rack ~> 1.2.1</code>, and that since the release of <code>rails - 3.0.0</code>, the Rack team released <code>rack 1.2.2</code>. - </p> - <p> - If we naïvely update all of our gems in order to update Rails, we'll get <code>rack - 1.2.2</code>, which satisfies the requirements of both <code>rails 3.0.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.2.2</code> (for - whatever reason). And while an update from <code>rack 1.2.1</code> to <code>rack - 1.2.2</code> probably won't break anything, similar scenarios can happen that involve - much larger jumps. (see [1] below for a larger discussion) - </p> - <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 3.0.0</code>'s dependency - <code>actionpack 3.0.0</code> remains compatible with <code>rack 1.2.1</code>, bundler - leaves it alone, and <code>rack-cache</code> continues to work even in the face of an - incompatibility with <code>rack 1.2.2</code>. - </p> - <p> - Since you originally declared a dependency on <code>rails 3.0.0.rc</code>, if you want - to update to <code>rails 3.0.0</code>, simply update your <code>Gemfile</code> to - <code>gem 'rails', '3.0.0'</code> and run: - </p> - <pre class="highlight plaintext">$ bundle install
</pre> - <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 - 3.0.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> - <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> - <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>. - </p> - <h2 id='updating-a-gem-without-modyfying-the-gemfile'> - Updating a Gem Without Modifying the Gemfile - </h2> - <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: - </p> - <pre class="highlight plaintext">$ bundle update rack-cache
</pre> - <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> - <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.2.2</code>, bundler will update <code>rack</code> to <code>1.2.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> - <p> - If you want to update every gem in the Gemfile to the latest possible versions, run: - </p> - <pre class="highlight plaintext">$ bundle update
</pre> - <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. - </p> - <h2 id='summary'> - Summary - </h2> - <h2>A Simple Bundler Workflow</h2> - <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: - </p> - <pre class="highlight plaintext">$ bundle init
</pre> - <p> - The <code>bundle init</code> command creates a simple <code>Gemfile</code> which you - can edit. - </p> - </li> - <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: - </p> - <pre class="highlight ruby"><span class="n">source</span> <span class="s1">'http://rubygems.org'</span>

<span class="n">gem</span> <span class="s1">'sinatra'</span><span class="p">,</span> <span class="s1">'~> 0.9.0'</span>
<span class="n">gem</span> <span class="s1">'rack-cache'</span>
<span class="n">gem</span> <span class="s1">'rack-bug'</span>
</pre> - </li> - <li> - <p> - If you don't have the gems installed in your system yet, run: - </p> - <pre class="highlight plaintext">$ bundle install
</pre> - </li> - <li> - <p> - To update a gem's version requirements, first modify the Gemfile: - </p> - <pre class="highlight ruby"><span class="n">source</span> <span class="s1">'http://rubygems.org'</span>

<span class="n">gem</span> <span class="s1">'sinatra'</span><span class="p">,</span> <span class="s1">'~> 1.0.0'</span>
<span class="n">gem</span> <span class="s1">'rack-cache'</span>
<span class="n">gem</span> <span class="s1">'rack-bug'</span>
</pre> - <p> - and then run: - </p> - <pre class="highlight plaintext">$ bundle install
</pre> - </li> - <li> - <p> - If <code>bundle install</code> reports a conflict between your <code>Gemfile</code> - and <code>Gemfile.lock</code>, run: - </p> - <pre class="highlight plaintext">$ bundle update sinatra
</pre> - <p> - This will update just the Sinatra gem, as well as any of its dependencies - </p> - </li> - <li> - <p> - To update all of the gems in your <code>Gemfile</code> to the latest possible - versions, run: - </p> - <pre class="highlight plaintext">$ bundle update
</pre> - </li> - <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> - <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: - </p> - <pre class="highlight plaintext">$ bundle install --deployment
</pre> - </li> - </ul> - <h2 id='notes'> - Notes - </h2> - <p> - [1] For instance, if <code>rails 3.0.0</code> depended on <code>rack 2.0</code>, that - gem would still satisfy the requirement of <code>rack-cache</code>, which declares - <code>>= 1.0</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.2.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.2.1</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. - </p> - </div> - </div> - <div id='sidebar'> - <h2>Would you like to</h2> - <ul> - <li><a href="/#getting-started">Get started</a></li> - <li><a href="/issues.html">Report a bug</a></li> - <li><a href="/v1.6/whats_new.html">See what's new</a></li> - <li><a href="/v1.6/man/bundle.1.html">Read documentation</a></li> - <li><a href="/#get-involved">Discuss and Contribute</a></li> - <li><a href="/v1.6/faq.html">View FAQs</a></li> - </ul> - <div class='shirts'> - <div class='content'> - <p> - Bundler is developed entirely by a team of volunteers. - <a href="http://www.gittip.com/bundler">Support their work</a> - and help make Bundler better for everyone. - </p> - <p> - <script data-gittip-username='bundler' src='//gttp.co/v1.js'></script> - <br> - <br> - </p> - </div> - </div> - <h2>Bundler Commands</h2> - <ul> - <li><a href="/v1.6/bundle_install.html">bundle install</a></li> - <li><a href="/v1.6/bundle_update.html">bundle update</a></li> - <div class='buttons'> - <a href="/v1.6/commands.html">View all commands</a> - </div> - </ul> - <h2>Help With</h2> - <ul> - <li><a href="/v1.6/gemfile.html">Gemfiles</a></li> - <li><a href="/v1.6/groups.html">Groups</a></li> - <li><a href="/v1.6/git.html">Gems from git</a></li> - <li><a href="/v1.6/bundler_setup.html">Bundler.setup</a></li> - <li><a href="/v1.6/deploying.html">Deploying</a></li> - <li><a href="/v1.6/bundler_sharing.html">Sharing</a></li> - <li><a href="/v1.6/updating_gems.html">Updating Gems</a></li> - <li><a href="/compatibility.html">Compatible versions</a></li> - </ul> - <h2>Use Bundler with</h2> - <ul> - <li><a href="/v1.6/rails3.html">Rails 3</a></li> - <li><a href="/v1.6/rails23.html">Rails 2.3</a></li> - <li><a href="/v1.6/sinatra.html">Sinatra</a></li> - <li><a href="/v1.6/rubygems.html">Rubygems</a></li> - <li><a href="/v1.6/rubymotion.html">RubyMotion</a></li> - </ul> - <div class='shirts'> - <div class='content'> - <a class="image" onclick="ga('send', 'devswag');" href="http://www.devswag.com/collections/bundler"><img src="/images/bundler-shirt.png" /> - </a> - - <p> - <a onclick="ga('send', 'devswag');" href="http://www.devswag.com/collections/bundler">Buy Bundler Shirts & Stickers!</a> - </p> - </div> - </div> - </div> - </div> - </div> - <div id='footer'> - <img src="/images/emocow.png" /> - <img src="/images/panda.jpg" /> - <div class='spacer'></div> - <div id='credits'> - <p> - Many thanks to Bundler's <a href="/contributors.html">contributors</a> - and <a href="/sponsors.html">sponsors</a> - </p> - </div> - <div class='spacer'></div> - <img src="/images/bundler-small.png" /> - </div> - <a href='http://github.com/bundler/bundler/' id='github'> - <img alt='Fork me on GitHub' src='http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png'> - </a> - <div id='prod-versions'> - Docs: - <a href="/v0.9/">v0.9</a> - <a href="/v1.0/">v1.0</a> - <a href="/v1.1/">v1.1</a> - <a href="/v1.2/">v1.2</a> - <a href="/v1.3/">v1.3</a> - <a href="/v1.5/index.html">v1.5</a> - <a class="current" href="/">v1.6</a> - </div> - <script> - (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ - (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), - m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) - })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); - ga('create', 'UA-39559982-1', 'bundler.io'); - ga('send', 'pageview'); - </script> - </body> -</html> |