DevOps Zone is brought to you in partnership with:

Daniel Doubrovkine (aka dB.) is one of the tallest engineers at Art.sy. He founded and exited a successful Swiss start-up in the 90s, worked for Microsoft Corp. in Redmond, specializing in security and authentication, dabbled in large scale social networking and ran a big team that developed an expensive Enterprise product in NYC. After turning open-source cheerleader a few years ago in the worlds of C++, Java and .NET, he converted himself to Ruby and has been slowly unlearning everything he learned in the last 15 years of software practice. Daniel has posted 46 posts at DZone. You can read more from them at their website. View Full User Profile

Your First Ruby Gem

05.18.2013
| 3553 views |
  • submit to reddit

I live-coded a new gem called Ruby::Enum at NYC.rb on Tuesday. This library adds enum-like functionality to Ruby.

 

Here’s my checklist for creating a new gem.

 

Check the Name

 

Ruby gems are registered with Rubygems and managed in your projects using Bundler. Search for the new gem name on Rubygems to make sure it's not taken.

 

Create a Folder

 

I organize all my code in source and since I often fork code from others to contribute, create a subfolder with the Github username, including mine.

 
  1. $ mkdir ~/source/ruby-enum/dblock
  2. $ cd ~/source/ruby-enum/dblock
 

 

Initialize a Git Repository

 
  1. $ git init
  2. Initialized empty Git repository in /home/dblock/source/ruby-enum/dblock/.git/
 

 

Create a Github Repo

 

Create a new repository on Github.

 

image

 

Add it as a remote.

 
  1. $ git remote add origin git@github.com:dblock/ruby-enum.git
 

 

Create a Readme

 

Documentation is written in Markdown. Create and commit a README.md.

 
  1. $ git commit -m "Added README."
  2. [master acc5880] Added README.
  3. 1 file changed, 4 insertions(+)
  4. create mode 100644 README.md
 

Push the README to Github.

 
  1. $ git push origin master
  2. Counting objects: 6, done.
  3. Compressing objects: 100% (5/5), done.
  4. Writing objects: 100% (6/6), 963 bytes, done.
  5. Total 6 (delta 0), reused 0 (delta 0)
  6. To git@github.com:dblock/ruby-enum.git
  7. * [new branch]      master -> master
 

 

Add a License

 

Every project needs a license. I use the MIT license because it’s short and nobody has time to read licenses. Add a copyright notice to the README, don't forget future contributors.

 
  1. Copyright (c) 2013, Daniel Doubrovkine and Contributors. All Rights Reserved.
  2. This project is licenced under the [MIT License](LICENSE.md).
 

 

Gemfile

 

A Gemfile is something that comes with Bundler and declares gem dependencies.

 

Install Bundler.

 
  1. $ gem install bundler
  2. Fetching: bundler-1.3.5.gem (100%)
  3. Successfully installed bundler-1.3.5
  4. 1 gem installed
  5. Installing ri documentation for bundler-1.3.5...
  6. Installing RDoc documentation for bundler-1.3.5...
 

Create a Gemfile. For now it just says where to get other gems from.

 
  1. source "http://rubygems.org"
 

Run bundle install.

 
  1. $ bundle install
  2. Resolving dependencies...
  3. Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
 

 

.gitignore

 

The generated Gemfile.lock should not be included, create a .gitignore.

 
  1. Gemfile.lock
 

 

Enum Library

 

Create lib/ruby-enum.rb and lib/ruby-enum/version.rb.

 

 

  1. require 'ruby-enum/version'
 

 

  1. module Ruby::Enum
  2.  VERSION = '0.1.0'
  3. end
 

 

Tests

 

You. Must. Test.

 

Add RSpec to Gemfile.

 
  1. gem "rspec"
 

Tests need some setup, specifically to load the code in lib. Create spec/spec_helper.rb.

 
  1. $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
  2. require 'rubygems'
  3. require 'rspec'
  4. require 'ruby-enum'
 

Create a test in spec/ruby-enum/version.rb.

 
  1. require 'spec_helper'
  2. describe Ruby::Enum do
  3.  it "has a version" do
  4.    Ruby::Enum::VERSION.should_not be_nil
  5.  end
  6. end
 

Add .rspec to pretty-print test output.

 
  1. --format documentation
  2. --color
 

 

Gem Declaration

 

A ruby-enum.gemspec is a gem declaration.

 
  1. $:.push File.expand_path("../lib", __FILE__)
  2. require "ruby-enum/version"
  3. Gem::Specification.new do |s|
  4.  s.name = "ruby-enum"
  5.  s.version = Ruby::Enum::VERSION
  6.  s.authors = [ "Daniel Doubrovkine" ]
  7.  s.email = "dblock@dblock.org"
  8.  s.platform = Gem::Platform::RUBY
  9.  s.required_rubygems_version = '>= 1.3.6'
  10.  s.files = `git ls-files`.split("\n")
  11.  s.require_paths = [ "lib" ]
  12.  s.homepage = "http://github.com/dblock/ruby-enum"
  13.  s.licenses = [ "MIT" ]
  14.  s.summary = "Enum-like Behavior for Ruby"
  15. end
 

The declaration can be loaded in Gemfile, so that we can list dependencies in one place.

 
  1. source "http://rubygems.org"
  2. gemspec
 

When running under Bundler, the Gemfile will automatically be loaded, which will automatically load the gem specification.

 
  1. $ bundle exec irb
  2. 1.9.3-p362 :001 > require 'ruby-enum'
  3. => true
  4. 1.9.3-p362 :002 > Ruby::Enum::VERSION
  5. => "0.1.0"
 

 

Rakefile

 

Bundler comes with a number of Rake tasks to release a gem. Add Rake to Gemfile.

 
  1. gem "rake"
 

Create a Rakefile.

 

 

  1. require 'rubygems'
  2. require 'bundler/gem_tasks'
  3. Bundler.setup(:default, :development)
 

 

  1. $ rake -T
  2. rake build    # Build ruby-enum-0.1.0.gem into the pkg directory.
  3. rake install  # Build and install ruby-enum-0.1.0.gem into system gems.
  4. rake release  # Create tag v0.1.0 and build and push ruby-enum-0.1.0.gem to Rubygems
 

 

  1. $ rake build
  2. ruby-enum 0.1.0 built to pkg/ruby-enum-0.1.0.gem.
 

Add pkg to .gitignore.

 

 

Default Rakefile to Running Tests

 
  1. require 'rspec/core'
  2. require 'rspec/core/rake_task'
  3. RSpec::Core::RakeTask.new(:spec) do |spec|
  4.  spec.pattern = FileList['spec/**/*_spec.rb']
  5. end
  6. task :default => :spec
 

 

Travis-CI

 

Add .travis.yml, register the project on travis-ci.org and add a badge.

 

 

  1. rvm:
  2.  - 1.8.7
  3.  - 1.9.3
  4.  - 2.0.0
  5.  - jruby-19mode
  6.  - rbx-19mode
 

 

  1. [![Build Status](https://travis-ci.org/dblock/ruby-enum.png)](https://travis-ci.org/dblock/ruby-enum)
 

image

 

 

Enum Library Code

 

Include ruby-enum/enum. See enum.rb and enum_spec.rb for the implementation.

 

 

Changelog

 

Create a CHANGELOG to list current and future updates.

 
  1. ### 0.1.0 (5/14/2013)
  2. * Initial public release - [@dblock](https://github.com/dblock).
 

 

Contributing

 

Add a contributing section to README.

 
  1. * Fork the project.
  2. * Make your feature addition or bug fix with tests.
  3. * Update CHANGELOG.
  4. * Send a pull request. Bonus points for topic branches.
 

 

Release the Gem

 
  1. $ rake release
 

 

Prepare for Next Release

 

Bump the version, add a Next Release section to CHANGELOG.md.

 
  1. ### Next Release (TBD)
  2. * Your Contribution Here
 

 

Source Code

 

All source code for the above can be found at https://github.com/dblock/ruby-enum.

Published at DZone with permission of its author, Daniel Doubrovkine. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)