Hi All! today we are going to learn how to create a gem from scratch!
STEP1: Choose a name for your gem and create an empty repository for the gem in GitHub.
Your Gem name must be unique so run a quick search in Github or Rubygems.org to check if the name has already been taken or use the following command:
$ gem list -r your_gem_name
*** REMOTE GEMS ***
If the gem name exists it would be returned as an output after you type the above command.
In this example, I have chosen my gem name to be ‘word_play’. You can find this in GitHub
STEP2: Inside your rails console, create the following folders and files for the gem you wish to create and follow the naming conventions, the below images shows the required files/folders to be created for the gem ‘word_play’ :
Do not create the folders ‘doc’ and ‘word_play-0.0.1.gem’ file yet as I will explain more more about it later !
STEP3: The ‘lib’ folder and its contents
The source code of the gem would go into a ruby file which has the same name as the gem itself and is found under the ‘lib’ folder by convention.
There is a another folder under the ‘lib’ folder, also with the same name as the gem and has a ruby file named ‘version.rb’ under it. It contains the version number of the gem embedded into it by the following ruby code:
VERSION = “0.0.1”
Every time we make any change in the gem, we should increment the gem’s version number before pushing it into rubygems.org or GitHub. The version number of gem is of the form A.B.C , where A, B, C are non-negative integers. Remember the following rules while giving a version to the gem.
- Increment A in A.B.C for a backward incompatible changes to your public API, which is a major change.
- Increment B in A.B.C if new backward compatible functionality is introduced to the public API or if any public API functionality is deprecated, a minor change.
- Increment C in A.B.C for backward compatible bug fixes, a patch level change.
STEP4 The Gemspec file
The gemspec file consists of information about the gem. It contains details about the gem author, summary of its function, dependent gems, gem file path etc. It would be worthwhile to click the below image and learn more from the comments.
STEP5 Build and Install your gem
$ gem build word_play.gemspec
WARNING: no homepage specified
Successfully built RubyGem
$ gem install word_play-0.0.1.gem
Successfully installed word_play-0.0.1
1 gem installed
STEP6 Testing your gem
Testing your gem is very important. Your test cases should be under the ‘test’ folder or ‘spec’ folder as in my case. I have used rspec gem to test my code although one can use any gem for testing.
STEP7 Push your gem into GitHub or Rubygems.org
To push your gem into Rubygems.org, create an account in the website and in your rails console use the below command:
$ gem push word_play-0.0.1.gem
Enter your RubyGems.org credentials.
Don’t have an account yet? Create one at http://rubygems.org/sign_up
Pushing gem to https://rubygems.org…
Pushing gem to https://rubygems.org…
Successfully registered gem: word_play (0.0.1)
Use the following commands to push your gem into GitHub:
touch README.md #(It is good to have a Readme file to explain how to use your gem)
git add README.md
git commit -m “first commit”
git remote add origin firstname.lastname@example.org:Anu4ruby/your_gem.git
git push -u origin master
STEP 8: To Use your Gem, go to the ruby terminal and type the following commands.
The 2 words are anagram of each other
The word is a palindrome
STEP9 Delete your gem if you want!
first install the gemcutter gem and then use ‘gem yank’ command as below to remove your gem from rubygems.org:
$ gem install gemcutter
$ gem yank your_gem -v x.y.z (# you gem version number in x.y.z )
to remove your gem from GitHub, simply delete the gem repository.
That’s all for now. We now know how to create a basic gem and publish it. There are more features that can be added to a gem namely executable files, extensions and requiring more files into your gemfile. We will see about each of these in Part 2 of this blog.