Think of a .gemspec file like a detailed shipping manifest for a physical product. If you were shipping a DIY furniture kit, you wouldn't just throw a pile of wood in a box and hope for the best. You'd include a document that says: "This is the 'Nordic Coffee Table', version 2.0, created by Hans. To build this, you need a Phillips-head screwdriver and a hammer, and inside this box, you'll find four legs, one tabletop, and twelve screws."

In Ruby, the gemspec is that manifest. It tells RubyGems exactly what your library is, who is responsible for it, and—most importantly—what other pieces of software must be installed on the user's system for your code to actually run. Without it, your code is just a folder of scripts; with it, your code becomes a distributable package.

Defining Your Gem's Identity

When you first open a gemspec, you're looking at a Gem::Specification.new block. This is where you set the "metadata." I've seen a lot of beginners treat these fields as optional, but they aren't. If you're planning to publish this to RubyGems.org, the name and version are the primary keys the entire ecosystem uses to track your work.

Gem::Specification.new do |spec|
  spec.name          = "string_sorter"
  spec.version       = "0.1.0"
  spec.authors       = ["Your Name"]
  spec.email         = ["you@example.com"]
  spec.summary       = "A utility for alphabetically sorting complex strings."
  spec.description   = "This gem provides advanced sorting algorithms for strings that contain mixed numeric and alphabetic characters."
  spec.homepage      = "https://github.com/username/string_sorter"
  spec.license       = "MIT"
end

Notice the difference between summary and description. The summary is the "elevator pitch"—one short sentence. The description is the deeper dive. If you make them the same, it looks sloppy to anyone browsing your gem.

Managing Your Dependencies

This is where the "ingredients list" from our analogy comes in. You'll encounter two types of dependencies: runtime and development. This distinction is critical. If you mess this up, you'll either force your users to install a bunch of testing tools they don't need, or your gem will crash because it's missing a core library.

Runtime dependencies are things your code cannot function without. If your gem uses httparty to make API calls, httparty is a runtime dependency.

spec.add_dependency "httparty", "~> 0.21.0"

Development dependencies, on the other hand, are tools you need while you're writing the code, but the end-user doesn't need. I always put rspec or rubocop here. Your user doesn't need to run your tests to use your library, so don't bloat their system with your testing suite.

spec.add_development_dependency "rspec", "~> 3.12"

Telling Ruby What to Pack

One of the most frustrating "gotchas" I've run into is the spec.files array. If you don't tell the gemspec which files to include, RubyGems might just package everything in your folder—including your .gitignore, your README, and even your local environment secrets.

The standard professional approach is to use a Git command to dynamically list all tracked files. This ensures that only the code you've actually committed to version control gets shipped.

spec.files = `git ls-files -z`.split("\x0").reject do |f| 
  f.match(%r{^(test|spec|bin)/}) 
end

In the example above, I'm telling Ruby to grab everything Git knows about, but then I'm explicitly rejecting the test and spec folders. Why? Because your users don't need your test files sitting in their gems directory; they just need the lib folder.

📋 Practical Task

Configure the "ClimateQuery" Gemspec

You are building a gem called climate_query that fetches weather data from a remote API. You have the code written, but the climate_query.gemspec file is currently empty.

Complete the gemspec file with the following requirements:

• Identity: Set the name to "climate_query" and the version to "1.0.0".
• Authorship: Add yourself as the author and use "dev@climatequery.io" as the email.
• Runtime Dependency: The gem requires the "rest-client" gem (any version) to make HTTP requests.
• Development Dependency: You use "rake" to automate your build tasks during development.
• Files: Use the git ls-files method to populate spec.files, ensuring that the spec/ directory is excluded from the final package.

Write the full Gem::Specification.new block that implements these configurations.