Before we start, the
.gemspec itself only appears once. Here it is, as generated by
bundle init and hand-tweaked for relevance:
lib = File.expand_path("../lib", __FILE__) $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) require "your_gem/version" Gem::Specification.new do |s| s.name = "your-gem" s.version = YourGem::VERSION s.authors = ["Your Name"] s.email = ["email@example.com"] s.homepage = "https://github.com/you/should-use-github" s.summary = "Describe this gem like you're talking to me." s.description = "Describe this gem like you're talking to your mom." s.require_paths = ["lib"] s.files = `git ls-files`.split("n") s.test_files = `git ls-files -- spec/*`.split("n") s.add_dependency "hashie", "~> 2.0" s.add_development_dependency "rspec", "~> 2.12" end
But what does all this mean? Moreover, how do all these crazy bits fit together?
The most important component of any gemspec is the list of files that it includes when building the gem. After all, a
.gem file is just a tarball with a metadata header written in Ruby. Here’s how we make that happen:
s.files = ['file/one', 'file/two'] s.test_files = ['spec/one', 'spec/two']
Let’s exploit part of
git to give us the list of files. Don’t use
git on your project? Start using
git. Problem solved! Here’s what it gives us:
$ git ls-files .gitignore .rvmrc Gemfile LICENSE README.md your-gem.gemspec lib/your_gem.rb lib/your_gem/version.rb spec/lib/your_gem.rb spec/spec_helper.rb
We can make this output into a Ruby array of strings quite simply:
Now, gems are laid out in a conventional way. That means a
lib directory, a
spec directory and some predictable files. That means nobody has to guess where your files are, which is fantastic!
Now let’s say you want to exclude your .rvmrc and .gitignore, because those files aren’t really all that important:
`git ls-files`.split("n") - %w(.rvmrc .gitignore)
Gemfile.lock from git, even though it might exist in your directory. This is conventional.
Your gem’s classes are called YourGem, while they live in files named
your_gem. As a matter of taste, I believe gems should be named
your-gem. There’s an argument to be made that gem names should match their requires (i.e., the gem should be named
The first component here is the version number for your gem. In this example, the
your_gem/version.rb looks like this:
module YourGem VERSION = "0.1.0" end
This is a Semantic Versioning string, and it’s the Simplest Thing that Could Possibly Work for a version.
This is the fun part. I’m of the opinion that dependencies should be as loose as possible until they’re not, but that throwing them away by doing
>= 0 is the wrong approach.
For example, the above file will pull in RSpec as a dependency, but require any version that matches a pattern like
2.y.z, as long as
y is above 12. Note that
z is allowed to be anything, which allows patch versions to be included.
Of course, this means that everyone in the community has to play along and not break their gem on a minor version bump. Also, the community now includes you!
So now you’ve got a conventional gem with loosely-required dependencies. How do you know if these change? Well, if you’re on github, you can use Gemnasium to watch for new dependency versions and see if anything’s broken!
- Rubygems Patterns
- Semantic Versioning
- Clarifying the Roles of the gem spec and Gemfile
- The Pessimistic Gem Version Operator
About the Author