Gemspec (Ruby Gem Specification) File Format

Overview

The Gemspec format is used to define Ruby gem specifications, containing metadata and configuration information about Ruby gems (packages). These files describe gem properties including name, version, dependencies, files to include, and other essential information needed for gem building, installation, and distribution through RubyGems.

Technical Details

File Characteristics

• Extension: .gemspec
• MIME Type: text/x-ruby
• Category: Config
• Format Type: Ruby DSL (Domain Specific Language)

Purpose and Function

• Gem Metadata: Name, version, author, description
• Dependency Management: Runtime and development dependencies
• File Specification: Which files to include in the gem
• Build Configuration: Compilation and installation instructions

Basic Structure

Simple Gemspec Example

# my_gem.gemspec
Gem::Specification.new do |spec|
  spec.name          = "my_gem"
  spec.version       = "1.0.0"
  spec.authors       = ["John Doe"]
  spec.email         = ["[email protected]"]
  
  spec.summary       = "A brief summary of my gem"
  spec.description   = "A longer description of what my gem does and why you might want to use it."
  spec.homepage      = "https://github.com/johndoe/my_gem"
  spec.license       = "MIT"
  
  spec.required_ruby_version = ">= 2.7.0"
  
  spec.metadata["homepage_uri"] = spec.homepage
  spec.metadata["source_code_uri"] = "https://github.com/johndoe/my_gem"
  spec.metadata["changelog_uri"] = "https://github.com/johndoe/my_gem/blob/main/CHANGELOG.md"
  
  # Specify which files should be added to the gem when it is released
  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
  end
  
  spec.bindir        = "exe"
  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
  spec.require_paths = ["lib"]
  
  # Runtime dependencies
  spec.add_dependency "activesupport", "~> 7.0"
  spec.add_dependency "thor", "~> 1.0"
  
  # Development dependencies
  spec.add_development_dependency "bundler", "~> 2.0"
  spec.add_development_dependency "rake", "~> 13.0"
  spec.add_development_dependency "rspec", "~> 3.0"
  spec.add_development_dependency "rubocop", "~> 1.0"
end

Advanced Gemspec Configuration

# advanced_gem.gemspec
require_relative "lib/advanced_gem/version"

Gem::Specification.new do |spec|
  spec.name          = "advanced_gem"
  spec.version       = AdvancedGem::VERSION
  spec.authors       = ["Alice Smith", "Bob Johnson"]
  spec.email         = ["[email protected]", "[email protected]"]
  
  spec.summary       = "An advanced Ruby gem with complex features"
  spec.description   = <<~DESC
    This gem provides advanced functionality for Ruby applications,
    including data processing, API integrations, and utility methods.
    It supports multiple Ruby versions and includes comprehensive
    testing and documentation.
  DESC
  
  spec.homepage      = "https://advanced-gem.example.com"
  spec.license       = "Apache-2.0"
  
  spec.required_ruby_version = ">= 2.7.0"
  spec.required_rubygems_version = ">= 3.0.0"
  
  # Metadata for RubyGems.org
  spec.metadata = {
    "bug_tracker_uri"   => "https://github.com/example/advanced_gem/issues",
    "changelog_uri"     => "https://github.com/example/advanced_gem/blob/main/CHANGELOG.md",
    "documentation_uri" => "https://rubydoc.info/gems/advanced_gem",
    "homepage_uri"      => spec.homepage,
    "source_code_uri"   => "https://github.com/example/advanced_gem",
    "wiki_uri"          => "https://github.com/example/advanced_gem/wiki",
    "funding_uri"       => "https://github.com/sponsors/example",
    "rubygems_mfa_required" => "true"
  }
  
  # File specifications
  spec.files = Dir[
    "lib/**/*.rb",
    "bin/*",
    "*.md",
    "LICENSE*",
    "CHANGELOG*",
    "Gemfile",
    "Rakefile",
    "*.gemspec"
  ]
  
  spec.bindir        = "bin"
  spec.executables   = ["advanced_gem"]
  spec.require_paths = ["lib"]
  
  # Platform-specific configurations
  if RUBY_PLATFORM =~ /java/
    spec.platform = "java"
    spec.add_dependency "jdbc-sqlite3"
  else
    spec.add_dependency "sqlite3", "~> 1.4"
  end
  
  # Runtime dependencies with specific version constraints
  spec.add_dependency "activesupport", ">= 6.0", "< 8.0"
  spec.add_dependency "faraday", "~> 2.0"
  spec.add_dependency "dry-validation", "~> 1.8"
  spec.add_dependency "zeitwerk", "~> 2.6"
  
  # Development dependencies organized by purpose
  spec.add_development_dependency "bundler", "~> 2.0"
  spec.add_development_dependency "rake", "~> 13.0"
  
  # Testing
  spec.add_development_dependency "rspec", "~> 3.11"
  spec.add_development_dependency "rspec-rails", "~> 5.1"
  spec.add_development_dependency "factory_bot", "~> 6.2"
  spec.add_development_dependency "webmock", "~> 3.18"
  spec.add_development_dependency "vcr", "~> 6.1"
  
  # Code quality
  spec.add_development_dependency "rubocop", "~> 1.36"
  spec.add_development_dependency "rubocop-performance", "~> 1.15"
  spec.add_development_dependency "rubocop-rspec", "~> 2.13"
  
  # Documentation
  spec.add_development_dependency "yard", "~> 0.9"
  spec.add_development_dependency "redcarpet", "~> 3.5"
  
  # Coverage
  spec.add_development_dependency "simplecov", "~> 0.21"
  
  # Extensions and native code
  spec.extensions = ["ext/advanced_gem/extconf.rb"] if Dir.exist?("ext")
  
  # Post-install message
  spec.post_install_message = <<~MSG
    Thank you for installing advanced_gem!
    
    Visit https://advanced-gem.example.com for documentation.
    Report issues at https://github.com/example/advanced_gem/issues
  MSG
end

Version Management

Semantic Versioning

# lib/my_gem/version.rb
module MyGem
  VERSION = "1.2.3"
  
  # Alternative with build metadata
  # VERSION = "1.2.3-beta.1"
  # VERSION = "1.2.3+build.20240101"
end

# In gemspec
require_relative "lib/my_gem/version"

Gem::Specification.new do |spec|
  spec.version = MyGem::VERSION
  # ... rest of specification
end

Dynamic Version from Git

# Dynamic versioning based on git tags
def git_version
  if Dir.exist?('.git')
    `git describe --tags --always`.chomp
  else
    "0.0.0"
  end
end

Gem::Specification.new do |spec|
  spec.version = git_version
  # ... rest of specification
end

Dependency Management

Version Constraints

Gem::Specification.new do |spec|
  # Exact version
  spec.add_dependency "exact_gem", "1.0.0"
  
  # Pessimistic version constraint (recommended)
  spec.add_dependency "rails", "~> 7.0.0"  # >= 7.0.0, < 7.1.0
  spec.add_dependency "sidekiq", "~> 6.5"  # >= 6.5.0, < 7.0.0
  
  # Range constraints
  spec.add_dependency "nokogiri", ">= 1.10", "< 2.0"
  
  # Multiple constraints
  spec.add_dependency "activesupport", ">= 6.0", "!= 7.0.0", "< 8.0"
  
  # Platform-specific dependencies
  spec.add_dependency "wdm", "~> 0.1" if Gem.win_platform?
  
  # Conditional dependencies
  if RUBY_VERSION >= "3.0"
    spec.add_dependency "modern_gem", "~> 2.0"
  else
    spec.add_dependency "legacy_gem", "~> 1.0"
  end
end

Development Dependencies

Gem::Specification.new do |spec|
  # Testing framework
  spec.add_development_dependency "rspec", "~> 3.11"
  spec.add_development_dependency "minitest", "~> 5.16"
  
  # Mocking and stubbing
  spec.add_development_dependency "webmock", "~> 3.18"
  spec.add_development_dependency "vcr", "~> 6.1"
  
  # Code coverage
  spec.add_development_dependency "simplecov", "~> 0.21"
  spec.add_development_dependency "codecov", "~> 0.6"
  
  # Code quality
  spec.add_development_dependency "rubocop", "~> 1.36"
  spec.add_development_dependency "reek", "~> 6.1"
  spec.add_development_dependency "flay", "~> 2.13"
  
  # Performance testing
  spec.add_development_dependency "benchmark-ips", "~> 2.10"
  spec.add_development_dependency "memory_profiler", "~> 1.0"
  
  # Documentation
  spec.add_development_dependency "yard", "~> 0.9"
  spec.add_development_dependency "kramdown", "~> 2.4"
end

File and Executable Configuration

File Inclusion Patterns

Gem::Specification.new do |spec|
  # Include all files tracked by git
  spec.files = `git ls-files -z`.split("\x0")
  
  # Exclude test files and sensitive data
  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
    `git ls-files -z`.split("\x0").reject do |f|
      f.match(%r{^(test|spec|features)/}) ||
      f.match(%r{^\.}) ||
      f.match(%r{^(bin|exe)/}) ||
      f.match(%r{\.(gem|log|tmp)$})
    end
  end
  
  # Explicit file patterns
  spec.files = Dir[
    "lib/**/*.rb",
    "config/**/*.yml",
    "app/**/*.rb",
    "*.md",
    "LICENSE*",
    "Gemfile",
    "Rakefile"
  ]
  
  # Test files (separate from main files)
  spec.test_files = Dir["spec/**/*_spec.rb", "test/**/*_test.rb"]
  
  # Extra files for development
  spec.extra_rdoc_files = ["README.md", "CHANGELOG.md", "LICENSE"]
end

Executable Configuration

Gem::Specification.new do |spec|
  # Single executable
  spec.bindir = "bin"
  spec.executables = ["my_gem"]
  
  # Multiple executables
  spec.executables = Dir["bin/*"].map { |f| File.basename(f) }
  
  # Generated from files
  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
  
  # Manual specification
  spec.executables = ["cli_tool", "helper_script", "daemon"]
end

Build and Installation

Extension Configuration

# For gems with C extensions
Gem::Specification.new do |spec|
  # C extension configuration
  spec.extensions = ["ext/my_gem/extconf.rb"]
  
  # Multiple extensions
  spec.extensions = Dir["ext/*/extconf.rb"]
  
  # Require compilation tools
  spec.requirements = ["gcc", "make"]
  
  # Platform-specific builds
  if RUBY_PLATFORM =~ /mswin|mingw/
    spec.requirements << "Windows development tools"
  end
end

Installation Hooks

Gem::Specification.new do |spec|
  # Post-install message
  spec.post_install_message = <<~MESSAGE
    Thanks for installing #{spec.name}!
    
    To get started:
      #{spec.name} init
      #{spec.name} --help
    
    Documentation: #{spec.homepage}
  MESSAGE
  
  # RubyGems version requirement
  spec.required_rubygems_version = ">= 2.0.0"
  
  # Ruby version requirement
  spec.required_ruby_version = [">= 2.7.0", "< 4.0"]
end

Security and Publishing

Security Configuration

Gem::Specification.new do |spec|
  # Require multi-factor authentication for publishing
  spec.metadata["rubygems_mfa_required"] = "true"
  
  # Allowed push host
  spec.metadata["allowed_push_host"] = "https://rubygems.org"
  
  # Signing key
  spec.signing_key = ENV["GEM_SIGNING_KEY"]
  spec.cert_chain = ["certs/gem_public_cert.pem"]
end

Publishing Workflow

# Build gem
gem build my_gem.gemspec

# Install locally for testing
gem install ./my_gem-1.0.0.gem

# Push to RubyGems.org
gem push my_gem-1.0.0.gem

# Validate gemspec
gem specification my_gem.gemspec

# Check gem contents
gem contents my_gem

Validation and Testing

Gemspec Validation

# validate_gemspec.rb
require_relative "my_gem.gemspec"

def validate_gemspec(spec)
  errors = []
  
  # Required fields
  errors << "Name is required" if spec.name.nil? || spec.name.empty?
  errors << "Version is required" if spec.version.nil?
  errors << "Authors are required" if spec.authors.empty?
  errors << "Summary is required" if spec.summary.nil? || spec.summary.empty?
  
  # Recommended fields
  warnings = []
  warnings << "Description should be longer than summary" if spec.description == spec.summary
  warnings << "Homepage URL is recommended" if spec.homepage.nil?
  warnings << "License is recommended" if spec.license.nil?
  
  # File validation
  errors << "No files specified" if spec.files.empty?
  missing_files = spec.files.reject { |f| File.exist?(f) }
  errors << "Missing files: #{missing_files.join(', ')}" unless missing_files.empty?
  
  if errors.any?
    puts "Errors:"
    errors.each { |error| puts "  - #{error}" }
  end
  
  if warnings.any?
    puts "Warnings:"
    warnings.each { |warning| puts "  - #{warning}" }
  end
  
  errors.empty?
end

Best Practices

Gemspec Organization

• Keep gemspec files clean and well-documented
• Use semantic versioning for releases
• Specify appropriate dependency constraints
• Include comprehensive metadata for discoverability

Security Considerations

• Enable MFA for gem publishing
• Validate all file inclusions
• Use signed gems for security-critical packages
• Regularly audit dependencies for vulnerabilities

Development Workflow

• Test gemspec validation in CI/CD pipelines
• Use development dependencies for tooling
• Maintain backwards compatibility when possible
• Document breaking changes in version updates

The Gemspec format provides a standardized way to define Ruby gem properties and dependencies, enabling proper package management and distribution within the Ruby ecosystem.