280 lines
10 KiB
Plaintext
280 lines
10 KiB
Plaintext
|
Gemfile(5) -- 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 "http://rubygems.org"
|
||
|
|
source "http://gems.github.com"
|
||
|
|
|
||
|
|
Each of these _source_s `MUST` be a valid Rubygems repository.
|
||
|
|
|
||
|
|
## 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 its main file, which should be used when autorequiring
|
||
|
|
(`Bundler.require`).
|
||
|
|
|
||
|
|
gem "sqlite3-ruby", :require => "sqlite3"
|
||
|
|
|
||
|
|
This defaults to the name of the gem itself. For instance, 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
|
||
|
|
* `mri`:
|
||
|
|
Same as _ruby_, but not Rubinius
|
||
|
|
* `mri_18`:
|
||
|
|
_mri_ `AND` version 1.8
|
||
|
|
* `mri_19`:
|
||
|
|
_mri_ `AND` version 1.9
|
||
|
|
* `jruby`:
|
||
|
|
JRuby
|
||
|
|
* `mswin`:
|
||
|
|
Windows
|
||
|
|
* `mingw`:
|
||
|
|
Windows 'mingw32' platform (aka RubyInstaller)
|
||
|
|
* `mingw_18`:
|
||
|
|
_mingw_ `AND` version 1.8
|
||
|
|
* `mingw_19`:
|
||
|
|
_mingw_ `AND` version 1.9
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### 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-ruby"
|
||
|
|
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`, in the order in which they were
|
||
|
|
declared in the `Gemfile`.
|