gemfile.html.haml

%h2 In Depth

.contents
  .bullet
    .description
      Read the manual for an in-depth discussion of all of the options available in the
      <code>Gemfile</code> and how to use them.
    = link_to 'Gemfile manual', './man/gemfile.5.html'

%h2 Gemfiles

.contents
  .bullet
    .description
      Gemfiles require at least one gem source, in the form of the URL for a RubyGems server. Generate a Gemfile with the default rubygems.org source by running <code>bundle init</code>. If you can, use <code>https</code> so your connection to the rubygems.org server will be verified with SSL.
    :code
      # lang: ruby
      source 'https://rubygems.org'

  .bullet
    .description
      Declare the gems that you need, including version numbers. Specify versions using the same
      syntax that RubyGems supports for dependencies.
    :code
      # lang: ruby
      gem 'nokogiri'
      gem 'rails', '3.0.0.beta3'
      gem 'rack',  '>=1.0'
      gem 'thin',  '~>1.1'
    .notes
      Most of the version specifiers, like <code>>= 1.0</code>, are self-explanatory.
      The specifier <code>~></code> has a special meaning, best shown by example.
      <code>~> 2.0.3</code> is identical to <code>>= 2.0.3</code> and <code>< 2.1</code>.
      <code>~> 2.1</code> is identical to <code>>= 2.1</code> and <code>< 3.0</code>.
      <code>~> 2.2.beta</code> will match prerelease versions like <code>2.2.beta.12</code>.
    = link_to 'RubyGems version specifiers', 'http://guides.rubygems.org/patterns/#pessimistic-version-constraint'

  .bullet
    .description
      If a gem's main file is different than the gem name, specify how to require it.
    :code
      # lang: ruby
      gem 'rspec', :require => 'spec'
      gem 'sqlite3'
    .description
      Specify <code>:require => false</code> to prevent bundler from requiring the gem, but still install it and maintain dependencies.
    :code
      # lang: ruby
      gem 'rspec', :require => false
      gem 'sqlite3'
    .notes
      In order to require gems in your <code>Gemfile</code>, you will need to call
      <code>Bundler.require</code> in your application.
    = link_to 'Learn More: Bundler.require', './groups.html'

  .bullet
    .description
      Git repositories are also valid gem sources, as long as the repo contains one or
      more valid gems. Specify what to check out with <code>:tag</code>,
      <code>:branch</code>, or <code>:ref</code>. The default is the <code>master</code> branch.
    :code
      # lang: ruby
      gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git', :branch => '1.4'
    .notes
      If the git repository does not contain a <code>.gemspec</code> file, bundler
      will create a simple one, without any dependencies, executables or C extensions.
      This may work for simple gems, but not work for others. If there is no .gemspec,
      you probably shouldn't use the gem from git.
    = link_to 'Learn more: Git', './git.html'

  .bullet
    .description
      If you would like to use an unpacked gem directly from the filesystem, simply set the <code>:path</code> option to the path containing the the gem's files.
    :code
      # lang: ruby
      gem 'extracted_library', :path => './vendor/extracted_library'

  .bullet
    .description
      Dependencies can be placed into groups. Groups can be ignored at install-time (using <code>--without</code>) or required all at once (using <code>Bundler.require</code>).
    :code
      # lang: ruby
      gem 'wirble', :group => :development
      gem 'debugger', :group => [:development, :test]

      group :test do
        gem 'rspec'
      end
    = link_to 'Learn more: Groups', './groups.html'

  .bullet
    .description
      You can specify the required version of Ruby in the <code>Gemfile</code> with <code>ruby</code>. If the <code>Gemfile</code> is loaded on a different Ruby version, Bundler will raise an exception with an explanation.
    :code
      # lang: ruby
      ruby '1.9.3'

  .bullet
    .description
      What this means is that this app has a dependency to a Ruby VM that is ABI compatible with 1.9.3. If the version check does not match, Bundler will raise an exception. This will ensure the running code matches. You can be more specific with the <code>:engine</code> and <code>:engine_version</code> options.
    :code
      # lang: ruby
      ruby '1.9.3', :engine => 'jruby', :engine_version => '1.6.7'
    = link_to 'Learn More: Ruby Directive', './gemfile_ruby.html'