How-to: Develop a RubyGem Using Bundler
I am by no means a Ruby expert. This is my humble attempt of sharing what I have learned and serves as a note to future me. It should be helpful to whoever is new to Ruby and would like to have a jump start on developing a Ruby gem.
Ruby is a powerful programming language which gains popularity with the rise of many active open source projects and communities built around it. Before thinking build some library from scratch, there might already be a free open source library which you can easily leverage. Therefore saving tons of development time.
gem is a Ruby library packaged in a standard format. You can easily download and install gems to help your development through RubyGems, which will be discussed later in the article. In a nutshell, RubyGems works a lot like
rvm stands for Ruby enVironment Manager.
rvm allows you to switch to a specific Ruby version and a specific set of gems for different projects. It is highly recommended that you install
rvm to manage different versions of Ruby and gemsets for your projects.
To install Ruby 1.9.3, do.
1 2 3
rvm list to verify your Ruby installation. Use
rvm list known to see a list of available Ruby versions that rvm is capable of installing.
Notice the last command
rvm rubygems lastest will install latest version of
rubygems, which is a Ruby library packaging and distribution manager.
As mentioned above, with RubyGems, installing libraries published by others is made very easy.
Substitute [gem_name] in above command to install the actual gem you want.
Note: A gem may depend on other gems. Therefore installing one gem may result in installing multiple other gems.
Tip: You can specify which version of the gem you want to install by
gem install [gem_name] -v ‘1.0.0’,
gem install [gem_name] -v ‘>=1.0.0’, or
gem install [gem_name] -v ‘~>1.0.0’
Important: If you are using
rvmlike many people recommended, DO NOT use
sudowhen installing gems. You may come across many tutorials telling you to do things like
sudo gem install devise. DON’T do that. Because
sudowill mess up your
rvm. See more details on why not using
sudohere if you are interested.
Install git, do.
Building your first gem using Bundler
Bundler is a great gem which can do a lot of things. Scaffolding a new gem is one of its many features.
I will be using colorfulMD as an example gem for this walk through. ColorfulMD colorfies your markdown text by adding
<font color=”a_color”></color> tag to certain text defined in a
There is a very good guide here. I will be explaining things that might not be too obvious. At least not so obvious to me.
To install Bundler, do.
To create a new gem, do.
This should create a new folder called
colorfulMD. Some skeleton files and directories will be created under
If you have Git installed,
bundle gem colorfulMDalso initializes a Git repository in
./colorfulMDso you can start committing right away.
Tip: You can add
.gitignorefile if your text editor creates tmp file ending with
~. This will prevent unnecessary files get pushed into your repo.
Tip: If you are using IDEs like
RubyMine. You may also want to add
Tip: Usually you can define all your gem dependencies in your
[gem_name].gemspecfile by default and defines dependencies there.
Tip: It is a good practice that you put a
.rvmrclike this one in
cdback in, you should see that
rvmwill initialize a independent Ruby environment for this project. This means when working in
colorfulMDfolder, you are using different Ruby version or gemsets than the global ones.
I didn’t find BDD particularly intriguing. But as for this walk through, we shall start writing our test cases even before any actual coding following BDD discipline.
colorfulMD.gemspec file and add the following. (example here)
add_development_dependency means those gems will only be installed for development use.)
cucumber gem and
aruba gem are great testing tools help us generate test code following BDD discipline. (here is a pretty good introductive tutorial for
bundle install is a command that goes through gemspec file, figure out the dependency and installs gems needed.
bundle install to install dependencies.
features and create directory structure and files like shown here.
/support: Ruby files in
supportfolder will be executed before
cucumberruns any actual tests, therefore it is good to put code that sets up environment here.
/step_definitions: Actual test code for a feature will be in this folder.
cli.feature: Write your feature in this file. You can name it differently.
I put down the following into my
1 2 3 4 5 6 7 8 9 10 11 12
It doesn’t seem to really matter what you put right after
Scenario:. The main thing you want to define here is what follows
Then keywords. It is relatively comprehensive.
Given defines what argument(s) your method is taking. (you don’t need
given if you are not going to do anything fancy with the arguments) I specified values of the three arguments with
When keyword. Note how close the test case is to natural language. That is supposed to be the beauty of BDD. Given the arguments specified after
When, I put down the expected output after
Then keyword. Triple quotes was used for escaping the quotes in the expected output.
After all that, run
bundle exec cucumber features/. Copy paste the output after
You can implement step definitions for undefined steps with these snippets:
/step_definitions/colorfy_steps.rb. (you should copy paste something close to the below)
1 2 3 4 5 6 7 8 9 10 11
Now add some actual testing code to
colorfy_steps.rb like shown here.
spec.add_dependency "thor" to your
gemspec file. And run
At project root, do
touch lib/colorfulMD/cli.rb and
touch lib/colorfulMD/colorfulMD.rb. Paste the following to
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8
At this point, if you run
bundle exec cucumber features, you should see you have passed all cucumber test! Systems all green!
And now we just need to make a cli executable.
At project root, do
mkdir bin. Do
touch bin/colorfulMD and
sudo chmod +x bin/colorfulMD.
bin/colorfulMD will be your CLI executable for your gem. Paste the following code to
1 2 3 4 5
Run your executable by
bundle exec bin/colorfulMD colorfy red apple apple. You can modify the code to have colorfy method output string by replacing
text.gsub(given_string, "<font color=\"" + given_color + "\">" + given_string + "</font>" ) with
puts text.gsub(given_string, "<font color=\"" + given_color + "\">" + given_string + "</font>" ) in
This concludes the tutorial.