[This is the first part of a series of posts about writing a Ruby gem. The introductory post about this tutorial contains links to each part of the tutorial. Next post: Adding some code.]

The first thing to do when creating a new gem is to create a file called gemspec that contains information about the gem. The gemspec file will have the name of your gem, ie. my gemspec will be called yourgemname.gemspec.

(Once again, I'd recommend naming your gem something other than "sudoku" since that name is already taken and you'll not be able to share your awesome gem on rubygems.org. For the rest of the post, I'll use the name sudoku for the gem, and you will have to replace it as required.)

Create a directory for your sudoku solver gem and add a gemspec file. In your gemspec file, add the following code, replacing the values for name, authors, email and homepage:

Gem::Specification.new do |s|
 s.name        = "sudoku"
 s.version     = '0.0.0'
 s.authors     = ["Nithin Bekal"]
 s.email       = ["me@nithinbekal.com"]

 s.summary     = "Sudoku solver in Ruby"
 s.description = "Solves Sudoku puzzles. D'uh!"
 s.homepage    = "http://github.com/nithinbekal/sudoku"
end

Now that you've written the gemspec, build the gem using the "gem build" command:

$ gem build sudoku.gemspec
 Successfully built RubyGem
 Name: sudoku
 Version: 0.0.0
 File: sudoku-0.0.0.gem

This command will package your gem project into a gem file that can be used to install the gem. This file will have the structure gem_name-version.gem (with the gem name and version coming from the gemspec). Our sudoku gem is at version 0.0.0, so the gem file will have the name sudoku-0.0.0.gem. You can use this file to install the gem for your ruby installation with "gem install sudoku-0.0.0.gem".

$ gem install sudoku-0.0.0.gem
Successfully installed sudoku-0.0.0
1 gem installed
Installing ri documentation for sudoku-0.0.0...
Installing RDoc documentation for sudoku-0.0.0...

You can check that the gem is available by doing:

$ gem list | grep sudoku
sudoku (0.0.0)

If you check the gem installation folder for the gem and you’ll see that there are no files in it. To find the location where the gem will be installed, do “gem env” on the terminal:

$ gem env
RubyGems Environment:
 - RUBYGEMS VERSION: 1.8.5
 - RUBY VERSION: 1.9.2 (2011-02-18 patchlevel 180) [i686-linux]
 - INSTALLATION DIRECTORY: /home/username/.rvm/gems/ruby-1.9.2-p180
 - RUBY EXECUTABLE: /home/username/.rvm/rubies/ruby-1.9.2-p180/bin/ruby
 - EXECUTABLE DIRECTORY: /home/username/.rvm/gems/ruby-1.9.2-p180/bin
 - RUBYGEMS PLATFORMS:
    - ruby
    - x86-linux
 - GEM PATHS:
    - /home/username/.rvm/gems/ruby-1.9.2-p180
    - /home/username/.rvm/gems/ruby-1.9.2-p180@global
 - GEM CONFIGURATION:
    - :update_sources => true
    - :verbose => true
    - :benchmark => false
    - :backtrace => false
    - :bulk_threshold => 1000
 - REMOTE SOURCES:
    - http://rubygems.org/

Go to the path shown as INSTALLATION DIRECTORY, and within that navigate to gems directory. Here, you will find your new sudoku gem in the directory sudoku-0.0.1. This directory will be empty now because we haven't yet written any code for our awesome sudoku solver.

Now that we have created a gemspec, used it to build our (empty) gem and even installed it, you can sit back for a few minutes and bask in the glory of your awesome new gem. (Let's ignore the fact for now that it does absolutely nothing. After all, eventually our gem will be able to solve any sudoku you throw at it.)

In the next post, we'll look at the next few steps in writing our gem - adding a lib directory that contains all the logic and some source files for our gem.

[Subscribe to this blog to find out when the next part of this tutorial is published, or keep an eye on the first post in this series where I'll post the links to all published posts.]