How Do I Create And Publish My First Ruby Gem?
What’s a Ruby Gem?
To solve various problems with Ruby, you might develop your own libraries. Also, you might want to open-source your libraries to get help from the Ruby community and have many developers working on the same.
A gem is a packaged Ruby application or library. RubyGems is the standard way to distribute Ruby applications and libraries and is available to you after you have downloaded and installed Ruby.
Let us create a simple Ruby library
Let’s first create a simple, trivial gem which I shall call
Please refer to the note on “How to Name Gems”1. Observe that at the end of the gem name, I have added
smt which are my initials. We would want to name the Ruby gem this way, so that it is unique on RubyGems.org.
Our library will extend the
String class and we shall store this in a file called
my_string_extend_smt.rb in the folder
my_string_extend_smt/lib. The lib folder will contain the Ruby code related to the library, namely:
# my_string_extend_smt.rb class String def writesize self.size end end
The library opens up the
String class and adds a method
writesize (which returns the size of the string).
For open-source applications, the gem server to use for your applications is the one provided at https://rubygems.org/. This is where users will look, and is where gem will also look by default when you issue a
gem install command. Please make sure that the name of your gem isn’t in use already. Type:
$ gem list -r my_string_extend_smt *** REMOTE GEMS ***
Observe that no gem of the name
my_string_extend_smt exists. We are safe! Now let us now turn our library into a gem, so that one can use it anywhere.
Steps for publishing our gem
1. Update to the latest RubyGem – In the folder
my_string_extend_smt open a command window and type:
$ gem update --system
2. Create an account on RubyGems.org – http://rubygems.org/sign_up and confirm your email. Later on, you’ll need to provide your login credentials the first time you push a gem to the server.
3. Create a Gem Specification – In the folder
my_string_extend_smt copy the following file
my_string_extend_smt.gemspec and edit it as per your needs:
Gem::Specification.new do |s| s.name = "my_string_extend_smt" s.version = "0.0.1" s.summary = "String Extend" s.date = "2013-02-18" s.description = "The library opens up the String class and adds a method writesize, which returns the size of the string." s.authors = ["Satish Talim"] s.email = ["email@example.com"] s.homepage = "http://rubylearning.org/" s.files = ["lib/my_string_extend_smt.rb"] end
The gemspec defines what’s in the gem, who made it, and the version of the gem. The gemspec is a chunk of Ruby code that the gem command will read and execute to understand our app, such as its name, files, and dependencies. It’s also our interface to RubyGems.org, all the information you see on a gem page comes from the gemspec.
A gemspec consists of several attributes. Some of these are required; most of them are optional. The required attributes are: name, version, summary, require_paths (default = ["lib"]) and rubygems_version (do not set this; it is set automatically when the gem is packaged).
The details of the attributes used in our gemspec, is available here.
4. Once we have our gemspec, we have to build a gem from it. In the folder
$ gem build my_string_extend_smt.gemspec Successfully built RubyGem Name: my_string_extend_smt Version: 0.0.1 File: my_string_extend_smt-0.0.1.gem
We can then install it locally to test it out:
$ gem install my_string_extend_smt-0.0.1.gem Successfully installed my_string_extend_smt-0.0.1 1 gem installed Installing ri documentation for my_string_extend_smt-0.0.1... Installing RDoc documentation for my_string_extend_smt-0.0.1...
Lets require our gem and use it:
$ irb --simple-prompt >> require 'my_string_extend_smt' => true >> puts "Hello".writesize 5 => nil >> quit
5. Now publish our gem out to RubyGems.org. In the folder
$ gem push my_string_extend_smt-0.0.1.gem Enter your RubyGems.org credentials. Don't have an account yet? Create one at http://rubygems.org/sign_up Email: firstname.lastname@example.org Password: Pushing gem to https://rubygems.org... Signed in. Pushing gem to https://rubygems.org... Successfully registered gem: my_string_extend_smt (0.0.1)
In just a few moments (usually a minute), your gem will be available for installation by anyone:
$ gem list -r my_string_extend_smt *** REMOTE GEMS *** my_string_extend_smt (0.0.1)
Here’s our Ruby gem on the RubyGems.org site
Deleting your gem at Rubygems.org
Since our gem is for demonstration purposes only, I would like to delete my gem from RubyGems.org’s index. To remove your gem please use the following reference. I removed an old gem of mine
my_string_extend of version 0.0.1 as follows:
gemcutter only once by typing:
$ gem install gemcutter
I then removed my old gem by typing:
$ gem yank my_string_extend -v 0.0.1 Yanking gem from RubyGems.org... Pushing gem to https://rubygems.org... Successfully yanked gem: my_string_extend (0.0.1)
However, the gem is still available for download for two main reasons:
- Other gems may have been pushed that depend on your gem.
- A mass deletion of important community based gems can be easily prevented.
Satish Talim is an author and founder of RubyLearning.com and RubyLearning.org where 1000s of participants have learnt Ruby programming from across the globe.