Using bundler and rvm to build a rubygem

flyerhzm Posted by flyerhzm on January 15, 2011

Introduction

Bundler and RVM are two of the most important tools for me to develop ruby/rails projects, especially make it easier to build a rubygem. Here I will describe how I use them to build the rails_best_practices gem.

RVM

RVM is a command line tool which allows you to easily install, manage and work with multiple ruby environments from interpreters to sets of gems. I recommend you to install rvm before you starting to develop ruby/rails projects. Check it here: http://rvm.beginrescueend.com/.

Bundler

Bundler is a tool that manages gem dependencies for your ruby application. It is recommended to install bundler in rvm global gemset because the gems in global gemset can be also used in other gemset.

rvm gemset use global
gem install bundler

Check more info about bundler here: http://gembundler.com/

Generate rubygem skeleton

After installing rvm and bundler, we can start to build a rubygem. Bundler provides a way to generate a skeleton for creating a rubygem.

bundle gem GEM_NAME

change the GEM_NAME to your rubygem name, such as rails_best_practices, the following is the skeleton generated

create  rails_best_practices/Gemfile
create  rails_best_practices/Rakefile
create  rails_best_practices/.gitignore
create  rails_best_practices/rails_best_practices.gemspec
create  rails_best_practices/lib/rails_best_practices.rb
create  rails_best_practices/lib/rails_best_practices/version.rb

Let's go through these files one by one.

1. rails_best_practices.gemspec, it's the rubygem specification file, you can define the author, summary, description of this rubygem, add the dependencies and development dependencies, and define the files and executables which should be packaged into .gem. The following is the source code of rails_best_practices.gemspec.

# -*- encoding: utf-8 -*-
require File.expand_path("../lib/rails_best_practices/version", __FILE__)
Gem::Specification.new do |s|
  s.name        = "rails_best_practices"
  s.version     = RailsBestPractices::VERSION
  s.platform    = Gem::Platform::RUBY
  s.authors     = ["Richard Huang"]
  s.email       = ["flyerhzm@gmail.com"]
  s.homepage    = "http://rails-bestpractices.com"
  s.summary     = "a code metric tool for rails codes."
  s.description = "a code metric tool for rails codes, written in Ruby."

  s.required_rubygems_version = ">= 1.3.6"

  s.add_dependency("ruby_parser", "~> 2.0.4")
  s.add_dependency("ruby-progressbar", "~> 0.0.9")
  s.add_dependency("colored", "~> 1.2")
  s.add_dependency("erubis", "~> 2.6.6")
  s.add_dependency("haml", "~> 3.0.18")
  s.add_dependency("i18n")
  s.add_dependency("activesupport")

  s.add_development_dependency("rspec", "~> 2.0.1")
  s.add_development_dependency("watchr", "~> 0.6")
  s.add_development_dependency("bundler", ">= 1.0.0")

  s.files         = `git ls-files`.split("\n")
  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
  s.require_paths = ["lib"]
end

2. Gemfile, it's a format for describing gem dependencies for ruby programs used by Bundler. In common you don't need to change it, the following is the generated Gemfile.

source "http://rubygems.org"
gemspec

As you seen, it uses gemspec which tells Bundler the gem dependencies are defined in .gemspec file.

3. lib/rails_best_practices.rb, it is the main file where you write or require your logic codes.

4. lib/rails_best_practices/version.rb, it defines the version of the rubygem.

5. Rakefile, define the rake tasks to build, install and release your rubygem.

Gemset for your rubygem

RVM's gemset provides you a isolated rubygems environment, you can install the gems without gem version conflicts.

First you should create a gemset for your rubygem, what I always do is creating a .rvmrc file under the root directory of rubygem, here is the example of rails_best_practices gem.

rvm_gemset_create_on_use_flag=1
rvm gemset use rails_best_practices

It means whenever you enter the directory of rails_best_practices gem, rvm will create or use the gemset.

'rails_best_practices'. Let's make the gemset take effect, just leave and re-enter the rubygem directory.

$ cd ..
$ cd rails_best_practices
Now using gemset 'rails_best_practices'

As you seen, when you re-enter the rails_best_practices, rvm tells you the gemset 'rails_best_practices' take effects. Next we should use bundler to install the gem dependencies.

$ bundle install

Bundler will install all the dependent gems in the 'rails_best_practices' gemset.

Release your rubygem

For now, we have generated the skeleton of our rubygem and installed dependent gems. Next we can write any logic codes for your rubygems, test, and release them. I will introduce about test in the next blog post, here I will show you how to release your codes.

Suppose we have completed the rubygem or added a new feature, we want to release it. It's really easy, what you should do is changing the version number in lib/rails_best_practices/version.rb, from 0.0.1 to 0.1.0, then run rake task

rake release

After that, it will add a tag "0.1.0" to your git repository, build rails_best_practices.gem, and push the gem to rubygems.org. Then everybody can install your new rubygem.

That's all, with the help of rvm and bundler, writing a rubygem is as easy as possible. And you will see more benefits of rvm and bundler in my next blog post about testing a rubygem.

comments powered by Disqus