Permalink
Fetching contributors…
Cannot retrieve contributors at this time
159 lines (144 sloc) 7.03 KB
.container.guide
%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', class: 'btn btn-primary'
%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' do
# Gems here
end
.notes
Global source lines are a security risk and should not be used as they can lead to gems being installed from unintended sources.
.bullet
.description
Some gem sources require a username and password. Use
<code>bundle config</code> to set the username and password for any
sources that need it. The command must be run once on each computer that
will install the Gemfile, but this keeps the credentials from being stored
in plain text in version control.
:code
$ bundle config https://gems.example.com/ user:password
.description
For some sources, like a company Gemfury account, it may be easier to
simply include the credentials in the Gemfile as part of the source URL.
:code
# lang: ruby
source "https://user:password@gems.example.com"
.description
Credentials in the source URL will take precedence over credentials set
using <code>config</code>.
.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', '5.0.0'
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>.
<code>~> 0</code> is identical to <code>>= 0.0</code> and <code>< 1.0</code>.
= link_to 'RubyGems version specifiers', 'http://guides.rubygems.org/patterns/#pessimistic-version-constraint', class: 'btn btn-primary'
.bullet
.description
If a gem's main file is different than the gem name, specify how to require it.
:code
# lang: ruby
gem 'rack-cache', :require => 'rack/cache'
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', './guides/groups.html', class: 'btn btn-primary'
.bullet
.description
If some of your gems need to be fetched from a private gem server, this default source can be overridden for those gems.
For a gem server that contains a single gem, it is easiest to use the <code>:source</code> option on that gem.
:code
# lang: ruby
gem 'my_gem', '1.0', :source => 'https://gems.example.com'
.description
If several gems come from the same server, you can use a <code>source</code> block to group them together.
:code
# lang: ruby
source 'https://gems.example.com' do
gem 'my_gem', '1.0'
gem 'another_gem', '1.2.1'
end
.description
Credentials for gem servers can be specified either in the URL or using
<code>bundle config</code>, as described above.
.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', './guides/git.html', class: 'btn btn-primary'
.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 gem's files.
:code
# lang: ruby
gem 'extracted_library', :path => './vendor/extracted_library'
.bullet
.description
If you would like to use multiple local gems directly from the filesystem, you can set a global `path` option to the path containing the gem's files. This will automatically load gemspec files from subdirectories.
:code
# lang: ruby
path 'components' do
gem 'admin_ui'
gem 'public_ui'
end
.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', './guides/groups.html', class: 'btn btn-primary'
.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', class: 'btn btn-primary'