Bundler : A gem to bundle gems
Bundler is a tool that manages gem dependencies for your ruby application. It takes a gem manifest file and is able to fetch, download, and install the gems and all child dependencies specified in this manifest. It can manage any update to the gem manifest file and update the bundled gems accordingly. It also lets you run any ruby code in context of the bundled gem environment.
Bundler has no dependencies. Just clone the git repository and install the gem with the following rake task:
Bundler requires a gem manifest file to be created. By default, this should be a file named 'Gemfile' located in the root directory of your application. After the manifest has been created, in your shell, cd into your application's directory and run 'gem_bundler'. This will start the bundling process.
This is where you specify all of your application's dependencies. By default this should be in a file named Gemfile located in your application's root directory. The following is an example of a potential Gemfile. For more information, please refer to Bundler::ManifestBuilder.
# Specify a dependency on rails. When the bundler downloads gems, # it will download rails as well as all of rails' dependencies (such as # activerecord, actionpack, etc...) # # At least one dependency must be specified gem "rails" # Specify a dependency on rack v.1.0.0. The version is optional. If present, # it can be specified the same way as with rubygems' #gem method. gem "rack", "1.0.0" # Specify a dependency rspec, but only activate that gem in the "testing" # environment (read more about environments later). :except is also a valid # option to specify environment restrictions. gem "rspec", :only => :testing # Add http://gems.github.com as a source that the bundler will use # to find gems listed in the manifest. By default, # http://gems.rubyforge.org is already added to the list. # # This is an optional setting. source "http://gems.github.com" # Specify where the bundled gems should be stashed. This directory will # be a gem repository where all gems are downloaded to and installed to. # # This is an optional setting. # The default is: vendor/gems bundle_path "my/bundled/gems" # Specify where gem executables should be copied to. # # This is an optional setting. # The default is: bin bin_path "my/executables" # Specify that rubygems should be completely disabled. This means that it # will be impossible to require it and that available gems will be # limited exclusively to gems that have been bundled. # # The default is to not require rubygems automatically (bundled gems are # available without rubygems), but rubygems can still be required and it # behaves normally. disable_rubygems
Once a manifest file has been created, the only thing that needs to be done is to run the “gem_bundler” command anywhere in your application. The script will load the manifest file, resole all the dependencies, download all needed gems, and install them into the specified directory.
Every time an update is made to the manifest file, run “gem_bundler” again to get the changes installed.
Running your application
The easiest way to run your application is to start it with an executable copied to the specified bin directory (by default, simply bin). For example, if the application in question is a rack app, start it with bin/rackup. This will automatically set the gem environment correctly.
Another way to run arbitrary ruby code in context of the bundled gems is to run it with the gem_bundler command. For example:
gem_bundler ruby my_ruby_script.rb
Yet another way is to manually require the environment file first. This is located in [bundle_path]/environments/[environment_name].rb. The default environment file is default.rb. For example:
ruby -r vendor/gems/environments/default.rb my_ruby_script.rb
More to come…
Please report all bugs on the github issue tracker for the project located at:
* There are certain complex, but valid dependency combinations that cause Bundler to freeze up. * Running ruby code with 'gem_bundler ruby my_ruby_script.rb' will require the entire Bundler source code which also requires rubygems.