Ruby Academy · Lesson

Gem Structure

Files and gemspec.

Gem Structure is a free Ruby Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Ruby Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is a Gem?

A gem is a packaged Ruby library or application that can be installed, versioned, and shared through RubyGems. Almost every Ruby tool you use is a gem.

A gem bundles code, metadata, and dependencies.
The metadata lives in a gemspec file.
Tools like bundler and gem manage gems.

Generating a Skeleton

The fastest start is bundle gem mygem. It scaffolds the standard directory layout, a gemspec, a test folder, a README, and a license. You then fill in the code.

The Standard Layout

A typical gem named mygem looks like this:

lib/mygem.rb the entry file.
lib/mygem/ additional source files.
lib/mygem/version.rb the version constant.
mygem.gemspec the metadata.
test/ or spec/ the tests.
README.md and a license file.

The Entry File

lib/mygem.rb is loaded when someone does require 'mygem'. It usually requires the version file and the rest of the library, and defines the top-level module.

module Mygem
  def self.greet(name)
    "Hello, " + name
  end
end

puts Mygem.greet("world")

The Version File

Keeping the version in its own file lets both the gemspec and the code read it. Convention is a VERSION constant inside the gem's module.

module Mygem
  VERSION = "0.1.0"
end

puts "Current version: " + Mygem::VERSION

What Is a Gemspec?

The gemspec is a Ruby file describing the gem: its name, version, author, summary, files, and dependencies. RubyGems reads it to build and publish the package.

It is normal Ruby, so you can compute values, but keep it simple and declarative.

A Minimal Gemspec

The core fields are name, version, authors, summary, and files. Here is the shape, written as plain Ruby you could place in mygem.gemspec.

require "ostruct"

spec = OpenStruct.new
spec.name = "mygem"
spec.version = "0.1.0"
spec.authors = ["Your Name"]
spec.summary = "A tiny example gem"

puts spec.name + " " + spec.version

Listing Files

The gemspec must declare which files ship in the gem. Many gemspecs ask git for the tracked files so nothing is forgotten:

spec.files = Dir['lib/**/*.rb'] + ['README.md']

Only listed files are packaged, so a forgotten file means a broken install.

Declaring Dependencies

Two kinds of dependencies go in the gemspec:

add_dependency for runtime needs users must install.
add_development_dependency for tools used only while developing, like test frameworks.

Use version constraints such as '~> 1.2' to stay compatible.

Required Ruby Version

Set spec.required_ruby_version so users on too-old a Ruby get a clear error instead of a confusing crash. Also fill homepage, license, and metadata for a polished gem.

required = ">= 3.0.0"
current = RUBY_VERSION
puts "Requires Ruby " + required
puts "Running Ruby " + current

Building the Gem

Once the gemspec is ready, gem build mygem.gemspec produces a .gem file. You can install it locally with gem install ./mygem-0.1.0.gem to test before publishing.

Quick Check

Test your understanding of gem structure.

Recap: Gem Structure

You learned how a gem is organized:

bundle gem scaffolds the layout.
lib/mygem.rb is the entry point.
The version lives in its own file.
The gemspec holds metadata, files, and dependencies.
gem build packages it.

Next we organize the actual code inside the gem.

Frequently asked questions

Is the “Gem Structure” lesson free?

Yes — the full text of “Gem Structure” is free to read here on the web, and the Ruby Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Ruby Academy course, upgrade to CoddyKit PRO.

What will I learn in “Gem Structure”?

Files and gemspec. You practise Ruby Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Ruby Academy?

No prior experience is required. Ruby Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Gem Structure” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Ruby Academy lesson?

Yes. Every Ruby Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Ruby Academy