Provided by: bundler_1.3.5-2ubuntu1_all bug

NAME

       Gemfile - A format for describing gem dependencies for Ruby programs

SYNOPSIS

       A Gemfile describes the gem dependencies required to execute associated Ruby code.

       Place  the  Gemfile  in  the  root  of  the  directory containing the associated code. For
       instance, in a Rails application, place the Gemfile in the same directory as the Rakefile.

SYNTAX

       A Gemfile is evaluated as Ruby code, in a  context  which  makes  available  a  number  of
       methods used to describe the gem requirements.

SOURCES (#source)

       At  the  top  of the Gemfile, add one line for each Rubygems source that might contain the
       gems listed in the Gemfile.

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

       Each of these _source_s MUST be a valid Rubygems repository. Sources are checked for  gems
       following the heuristics described in SOURCE PRIORITY.

RUBY (#ruby)

       If  your application requires a specific Ruby version or engine, specify your requirements
       using the ruby method, with the following arguments. All parameters  are  OPTIONAL  unless
       otherwise specified.

   VERSION (required)
       The  version  of  Ruby  that  your  application  requires. If your application requires an
       alternate Ruby engine, such as JRuby or Rubinius, this should be the Ruby version that the
       engine is compatible with.

           ruby "1.9.3"

   ENGINE (:engine)
       Each  application  may specify a Ruby engine. If an engine is specified, an engine version
       must also be specified.

   ENGINE VERSION (:engine_version)
       Each application may specify a Ruby engine version. If an engine version is specified,  an
       engine  must  also be specified. If the engine is "ruby" the engine version specified must
       match the Ruby version.

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

GEMS (#gem)

       Specify gem  requirements  using  the  gem  method,  with  the  following  arguments.  All
       parameters are OPTIONAL unless otherwise specified.

   NAME (required)
       For each gem requirement, list a single gem line.

           gem "nokogiri"

   VERSION
       Each gem MAY have one or more version specifiers.

           gem "nokogiri", ">= 1.4.2"
           gem "RedCloth", ">= 4.1.0", "< 4.2.0"

   REQUIRE AS (:require)
       Each gem MAY specify files that should be used when autorequiring via Bundler.require. You
       may pass an  array  with  multiple  files,  or  false  to  prevent  any  file  from  being
       autorequired.

           gem "redis", :require => ["redis/connection/hiredis", "redis"]
           gem "webmock", :require => false

       The argument defaults to the name of the gem. For example, these are identical:

           gem "nokogiri"
           gem "nokogiri", :require => "nokogiri"

   GROUPS (:group or :groups)
       Each  gem  MAY  specify  membership  in  one or more groups. Any gem that does not specify
       membership in any group is placed in the default group.

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

       The Bundler runtime allows its two main methods,  Bundler.setup  and  Bundler.require,  to
       limit their impact to particular groups.

           # setup adds gems to Ruby´s load path
           Bundler.setup                    # defaults to all groups
           require "bundler/setup"          # same as Bundler.setup
           Bundler.setup(:default)          # only set up the _default_ group
           Bundler.setup(:test)             # only set up the _test_ group (but `not` _default_)
           Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others

           # require requires all of the gems in the specified groups
           Bundler.require                  # defaults to just the _default_ group
           Bundler.require(:default)        # identical
           Bundler.require(:default, :test) # requires the _default_ and _test_ groups
           Bundler.require(:test)           # requires just the _test_ group

       The  Bundler  CLI  allows you to specify a list of groups whose gems bundle install should
       not install with the --without option. To specify multiple groups  to  ignore,  specify  a
       list of groups separated by spaces.

           bundle install --without test
           bundle install --without development test

       After  running  bundle install --without test, bundler will remember that you excluded the
       test group in the last installation. The next time you run  bundle  install,  without  any
       --without option, bundler will recall it.

       Also,  calling  Bundler.setup  with no parameters, or calling require "bundler/setup" will
       setup all groups except for the ones you excluded via --without (since they are  obviously
       not available).

       Note  that on bundle install, bundler downloads and evaluates all gems, in order to create
       a single canonical list of all of the required gems and  their  dependencies.  This  means
       that  you  cannot  list  different versions of the same gems in different groups. For more
       details, see Understanding Bundler http://gembundler.com/rationale.html.

   PLATFORMS (:platforms)
       If a gem should only be used in a particular platform or set of platforms, you can specify
       them.  Platforms  are  essentially identical to groups, except that you do not need to use
       the --without install-time flag to exclude groups of gems for other platforms.

       There are a number of Gemfile platforms:

       ruby   C Ruby (MRI) or Rubinius, but NOT Windows

       ruby_18
              ruby AND version 1.8

       ruby_19
              ruby AND version 1.9

       ruby_20
              ruby AND version 2.0

       mri    Same as ruby, but not Rubinius

       mri_18 mri AND version 1.8

       mri_19 mri AND version 1.9

       mri_20 mri AND version 2.0

       rbx    Same as ruby, but only Rubinius (not MRI)

       jruby  JRuby

       mswin  Windows

       mingw  Windows ´mingw32´ platform (aka RubyInstaller)

       mingw_18
              mingw AND version 1.8

       mingw_19
              mingw AND version 1.9

       mingw_20
              mingw AND version 2.0

       As with groups, you can specify one or more platforms:

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

       All operations involving groups (bundle install,  Bundler.setup,  Bundler.require)  behave
       exactly  the  same  as  if  any  groups  not matching the current platform were explicitly
       excluded.

   GIT (:git)
       If necessary, you can specify that a gem is located at a particular  git  repository.  The
       repository     can    be    public    (http://github.com/rails/rails.git)    or    private
       (git@github.com:rails/rails.git). If the repository is private, the user that you  use  to
       run bundle install MUST have the appropriate keys available in their $HOME/.ssh.

       Git repositories are specified using the :git parameter. The group, platforms, and require
       options are available and behave exactly the same as they would for a normal gem.

           gem "rails", :git => "git://github.com/rails/rails.git"

       A git repository SHOULD have at least one file, at the root of  the  directory  containing
       the gem, with the extension .gemspec. This file MUST contain a valid gem specification, as
       expected by the gem build command. It MUST NOT have any dependencies, other  than  on  the
       files in the git repository itself and any built-in functionality of Ruby or Rubygems.

       If  a  git repository does not have a .gemspec, bundler will attempt to create one, but it
       will not contain any dependencies, executables, or C extension  compilation  instructions.
       As a result, it may fail to properly integrate into your application.

       If  a  git  repository  does  have  a  .gemspec  for the gem you attached it to, a version
       specifier, if provided, means that the git  repository  is  only  valid  if  the  .gemspec
       specifies a version matching the version specifier. If not, bundler will print a warning.

           gem "rails", "2.3.8", :git => "git://github.com/rails/rails.git"
           # bundle install will fail, because the .gemspec in the rails
           # repository´s master branch specifies version 3.0.0

       If  a  git  repository  does not have a .gemspec for the gem you attached it to, a version
       specifier MUST be provided. Bundler will use  this  version  in  the  simple  .gemspec  it
       creates.

       Git repositories support a number of additional options.

       branch, tag, and ref
              You  MUST  only  specify  at  most  one of these options. The default is :branch =>
              "master"

       submodules
              Specify :submodules => true to cause bundler to expand any submodules  included  in
              the git repository

       If a git repository contains multiple .gemspecs, each .gemspec represents a gem located at
       the same place in the file system as the .gemspec.

           |~rails                   [git root]
           | |-rails.gemspec         [rails gem located here]
           |~actionpack
           | |-actionpack.gemspec    [actionpack gem located here]
           |~activesupport
           | |-activesupport.gemspec [activesupport gem located here]
           |...

       To install a gem located in a git repository, bundler changes to the directory  containing
       the  gemspec,  runs  gem  build  name.gemspec and then installs the resulting gem. The gem
       build command, which comes standard with Rubygems, evaluates the .gemspec in  the  context
       of the directory in which it is located.

   GITHUB (:github)
       If  the  git repository you want to use is hosted on GitHub and is public, you can use the
       :github shorthand to specify just the github username and  repository  name  (without  the
       trailing  ".git"),  separated by a slash. If both the username and repository name are the
       same, you can omit one.

           gem "rails", :github => "rails/rails"
           gem "rails", :github => "rails"

       Are both equivalent to

           gem "rails", :git => "git://github.com/rails/rails.git"

   PATH (:path)
       You can specify that a gem is located  in  a  particular  location  on  the  file  system.
       Relative paths are resolved relative to the directory containing the Gemfile.

       Similar  to the semantics of the :git option, the :path option requires that the directory
       in question either contains a .gemspec for the  gem,  or  that  you  specify  an  explicit
       version that bundler should use.

       Unlike :git, bundler does not compile C extensions for gems specified as paths.

           gem "rails", :path => "vendor/rails"

BLOCK FORM OF GIT, PATH, GROUP and PLATFORMS

       The :git, :path, :group, and :platforms options may be applied to a group of gems by using
       block form.

           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

       In the case of the git block form, the :ref, :branch, :tag, and :submodules options may be
       passed to the git method, and all gems in the block will inherit those options.

GEMSPEC (#gemspec)

       If  you  wish  to  use  Bundler  to  help install dependencies for a gem while it is being
       developed, use the gemspec method to pull in the dependencies listed in the .gemspec file.

       The gemspec method adds any runtime dependencies as gem requirements in the default group.
       It  also  adds  development  dependencies  as  gem  requirements in the development group.
       Finally, it adds a gem requirement on your project (:path =>  ´.´).  In  conjunction  with
       Bundler.setup,  this allows you to require project files in your test code as you would if
       the project were installed as a gem; you need not manipulate the  load  path  manually  or
       require project files via relative paths.

       The  gemspec  method supports optional :path, :name, and :development_group options, which
       control where bundler looks for the .gemspec, what named .gemspec it uses  (if  more  than
       one is present), and which group development dependencies are included in.

SOURCE PRIORITY

       When  attempting  to locate a gem to satisfy a gem requirement, bundler uses the following
       priority order:

       1.  The source explicitly attached to the gem (using :path or :git)

       2.  For implicit gems  (dependencies  of  explicit  gems),  any  git  or  path  repository
           otherwise  declared.  This  results in bundler prioritizing the ActiveSupport gem from
           the Rails git repository over ones from rubygems.org

       3.  The sources specified via source, searching each source  in  your  Gemfile  from  last
           added to first added.

                                            April 2013                                 GEMFILE(5)