Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 152 lines (112 sloc) 5.289 kb
f4e7a03 Update the README
Carl Lerche authored
1 ## Bundler : A gem to bundle gems
2
3 Github: http://github.com/wycats/bundler
4 Mailing list: http://groups.google.com/group/ruby-bundler
5 IRC: #carlhuda on freenode
6
7 ## Intro
8
9 Bundler is a tool that manages gem dependencies for your ruby application. It
10 takes a gem manifest file and is able to fetch, download, and install the gems
11 and all child dependencies specified in this manifest. It can manage any update
12 to the gem manifest file and update the bundle's gems accordingly. It also lets
13 you run any ruby code in context of the bundle's gem environment.
14
15 ## Installation
16
17 Bundler has no dependencies besides Ruby and RubyGems. Just clone the git
18 repository and install the gem with the following rake task:
19
20 rake install
21
22 You can also install the gem with
23
24 gem install bundler --prerelease
25
26 ## Usage
27
28 The first thing to do is create a gem manifest file named `Gemfile` at the
29 root directory of your application. This can quickly be done by running
30 `bundle init` in the directory that you wish the Gemfile to be created in.
31
32 ### Gemfile
33
34 This is where you specify all of your application's dependencies. The
35 following is an example. For more information, refer to
36 Bundler::Dsl.
37
38 # Add :gemcutter as a source that Bundler will use
39 # to find gems listed in the manifest. At least one source
40 # should be listed. URLs maybe also be used, such as
41 # http://gems.github.com.
42 #
43 source :gemcutter
44
45 # Specify a dependency on rails. When bundler downloads gems,
46 # it will download rails as well as all of rails' dependencies
47 # (such as activerecord, actionpack, etc...)
48 #
49 # At least one dependency must be specified
50 #
51 gem "rails"
52
53 # Specify a dependency on rack v.1.0.0. The version is optional.
54 # If present, it can be specified the same way as with rubygems'
55 # #gem method.
56 #
57 gem "rack", "1.0.0"
58
59 ### Installing gems
60
61 Once the manifest file has been created, the next step is to install all
62 the gems needed to satisfy the Gemfile's dependencies. The `bundle install`
63 command will do this.
64
65 This command will load the Gemfile, resolve all the dependencies, download
66 all gems that are missing, and install them to the system's RubyGems
67 repository. Every time an update is made to the Gemfile, run `bundle install`
68 again to get the new gems installed.
69
70 ### Locking dependencies
71
72 By default, bundler will only ensure that the activated gems satisfy the
73 Gemfile's dependencies. If you install a newer version of a gem and it
74 satisfies the dependencies, it will be used instead of the older one.
75
76 The command `bundle lock` will lock the bundle to the current set of
77 resolved gems. This ensures that, until the lock file is removed, that
78 bundle install and Bundle.setup will always activate the same gems.
79
80 ### Running the application
81
82 Bundler must be required and setup before anything else is required. This
83 is because it will configure all the load paths and manage rubygems for your.
84 To do this, include the following at the beginning of your code.
85
86 begin
87 # Require the preresolved locked set of gems.
d4e033e Rename vendor/environment.rb to .bundle/environment.rb
Carlhuda authored
88 require File.expand_path('../.bundle/environment', __FILE__)
f4e7a03 Update the README
Carl Lerche authored
89 rescue LoadError
90 # Fallback on doing the resolve at runtime.
91 require "rubygems"
92 require "bundler"
93 Bundler.setup
94 end
95
96 # Your application requires come here
97
98 The `bundle exec` command provides a way to run arbitrary ruby code in
99 context of the bundle. For example:
100
101 bundle exec ruby my_ruby_script.rb
102
103 To enter a shell that will run all gem executables (such as rake, rails,
104 etc... ) use `bundle exec bash` (replacing bash for whatever your favorite
105 shell is).
106
107 ### Packing the bundle's gems
108
109 When sharing or deploying an application, it might be useful to include
110 everything necessary to install gem dependencies. `bundle pack` will
111 copy .gem files for all of the bundle's dependencies into vendor/cache.
112 This way, bundle install can always work no matter what the state of the
113 remote sources.
114
115 ## Gem resolution
116
117 One of the most important things that the bundler does is do a
118 dependency resolution on the full list of gems that you specify, all
119 at once. This differs from the one-at-a-time dependency resolution that
120 Rubygems does, which can result in the following problem:
121
122 # On my system:
123 # activesupport 3.0.pre
124 # activesupport 2.3.4
125 # activemerchant 1.4.2
126 # rails 2.3.4
127 #
128 # activemerchant 1.4.2 depends on activesupport >= 2.3.2
129
130 gem "activemerchant", "1.4.2"
131 # results in activating activemerchant, as well as
132 # activesupport 3.0.pre, since it is >= 2.3.2
133
134 gem "rails", "2.3.4"
135 # results in:
136 # can't activate activesupport (= 2.3.4, runtime)
137 # for ["rails-2.3.4"], already activated
138 # activesupport-3.0.pre for ["activemerchant-1.4.2"]
139
140 This is because activemerchant has a broader dependency, which results
141 in the activation of a version of activesupport that does not satisfy
142 a more narrow dependency.
143
144 Bundler solves this problem by evaluating all dependencies at once,
145 so it can detect that all gems *together* require activesupport "2.3.4".
146
147 ## Reporting bugs
148
149 Please report all bugs on the github issue tracker for the project located
150 at:
151
152 http://github.com/wycats/bundler/issues/
Something went wrong with that request. Please try again.