Kenhuang Academy
  • English

      • Ruby Gems and Bundler Package Management

      In the Ruby ecosystem, Gems are the standard format for code packages, and Bundler is the tool for managing project dependencies. Mastering these two tools is crucial for Ruby development.

      📋 Chapter Contents

      • What are Ruby Gems
      • Installing and Using Gems
      • Creating Your Own Gem
      • Bundler Dependency Management
      • Gemfile and Gemfile.lock
      • Best Practices and Common Issues

      💎 What are Ruby Gems

      Gems are Ruby's package management system, similar to package managers in other languages:

      • pip for Python
      • npm for Node.js
      • Composer for PHP

      Basic Gem Concepts

      # A Gem is a package containing:
# - Ruby code
# - Documentation
# - gemspec file (containing metadata)

      🔧 RubyGems Basic Operations

      Viewing Gem Information

      # View installed gems
gem list

# View specific gem information
gem info rails

# Search for gems
gem search json

# View detailed gem information
gem specification rails

      Installing and Uninstalling Gems

      # Install latest version
gem install rails

# Install specific version
gem install rails -v 6.1.0

# Install pre-release version
gem install rails --pre

# Install from local file
gem install my_gem-1.0.0.gem

# Uninstall gem
gem uninstall rails

# Uninstall specific version
gem uninstall rails -v 6.1.0

      Updating Gems

      # Update all gems
gem update

# Update specific gem
gem update rails

# Update RubyGems system itself
gem update --system

      📦 Using Gems

      Using Gems in Code

      # Load gems using require
require 'json'
require 'httparty'
require 'nokogiri'

# Example: Using HTTParty to send HTTP request
response = HTTParty.get('https://api.github.com/users/octocat')
puts response.body

# Example: Using JSON to parse data
data = JSON.parse(response.body)
puts data['name']

# Example: Using Nokogiri to parse HTML
html = "<html><body><h1>Hello World</h1></body></html>"
doc = Nokogiri::HTML(html)
puts doc.css('h1').text

      Version Constraints

      # Specify version constraints in gemspec or Gemfile
gem 'rails', '~> 6.1.0'    # >= 6.1.0, < 6.2.0
gem 'nokogiri', '>= 1.10'  # >= 1.10
gem 'json', '= 2.3.0'      # Exact version

      🏗️ Creating Your Own Gem

      Generating Gem Skeleton

      # Use bundle gem command to create new gem
bundle gem my_awesome_gem

# Or use gem command
gem generate my_awesome_gem

      Gem Directory Structure

      my_awesome_gem/
├── lib/
│   ├── my_awesome_gem/
│   │   └── version.rb
│   └── my_awesome_gem.rb
├── test/
│   └── test_my_awesome_gem.rb
├── bin/
│   └── my_awesome_gem
├── Gemfile
├── Rakefile
├── README.md
├── LICENSE.txt
└── my_awesome_gem.gemspec

      Writing Gem Code

      # lib/my_awesome_gem.rb
require_relative 'my_awesome_gem/version'

module MyAwesomeGem
  class Error < StandardError; end

  class Calculator
    def self.add(a, b)
      a + b
    end

    def self.multiply(a, b)
      a * b
    end
  end

  def self.greet(name)
    "Hello, #{name}! Welcome to My Awesome Gem!"
  end
end
      # lib/my_awesome_gem/version.rb
module MyAwesomeGem
  VERSION = "0.1.0"
end

      Writing gemspec File

      # my_awesome_gem.gemspec
require_relative 'lib/my_awesome_gem/version'

Gem::Specification.new do |spec|
  spec.name          = "my_awesome_gem"
  spec.version       = MyAwesomeGem::VERSION
  spec.authors       = ["Your Name"]
  spec.email         = ["your.email@example.com"]

  spec.summary       = "An awesome Ruby gem example"
  spec.description   = "This gem demonstrates how to create and publish Ruby gems"
  spec.homepage      = "https://github.com/yourusername/my_awesome_gem"
  spec.license       = "MIT"

  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")

  spec.metadata["homepage_uri"] = spec.homepage
  spec.metadata["source_code_uri"] = spec.homepage
  spec.metadata["changelog_uri"] = "#{spec.homepage}/CHANGELOG.md"

  # Specify files to include
  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 "json", "~> 2.0"

  # Development dependencies
  spec.add_development_dependency "bundler", "~> 2.0"
  spec.add_development_dependency "rake", "~> 13.0"
  spec.add_development_dependency "minitest", "~> 5.0"
end

      Building and Publishing Gems

      # Build gem
gem build my_awesome_gem.gemspec

# Local install for testing
gem install ./my_awesome_gem-0.1.0.gem

# Publish to RubyGems.org (requires account)
gem push my_awesome_gem-0.1.0.gem

      📋 Bundler Dependency Management

      What is Bundler

      Bundler is Ruby's dependency management tool, ensuring projects use the correct versions of gems.

      Installing Bundler

      gem install bundler

      Creating Gemfile

      # Gemfile
source 'https://rubygems.org'

ruby '3.0.0'

# Production environment dependencies
gem 'rails', '~> 6.1.0'
gem 'pg', '~> 1.1'
gem 'puma', '~> 5.0'
gem 'sass-rails', '>= 6'
gem 'webpacker', '~> 5.0'
gem 'turbo-rails'
gem 'stimulus-rails'
gem 'jbuilder', '~> 2.7'
gem 'bootsnap', '>= 1.4.4', require: false

# Development and test environments
group :development, :test do
  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
  gem 'rspec-rails'
  gem 'factory_bot_rails'
end

# Development only
group :development do
  gem 'web-console', '>= 4.1.0'
  gem 'listen', '~> 3.3'
  gem 'spring'
end

# Test only
group :test do
  gem 'capybara', '>= 3.26'
  gem 'selenium-webdriver'
  gem 'webdrivers'
end

      Bundler Basic Commands

      # Initialize Gemfile
bundle init

# Install dependencies
bundle install

# Update dependencies
bundle update

# Update specific gem
bundle update rails

# Check dependencies
bundle check

# Show dependency tree
bundle viz

# Execute command (using bundle environment)
bundle exec rails server
bundle exec rake test
bundle exec rspec

      Gemfile.lock File

      # Gemfile.lock records exact version information
GEM
  remote: https://rubygems.org/
  specs:
    actioncable (6.1.4)
      actionpack (= 6.1.4)
      activesupport (= 6.1.4)
      nio4r (~> 2.0)
      websocket-driver (>= 0.6.1)
    # ... more dependency information

PLATFORMS
  ruby

DEPENDENCIES
  rails (~> 6.1.0)
  pg (~> 1.1)
  # ... more dependencies

RUBY VERSION
   ruby 3.0.0p0

BUNDLED WITH
   2.2.3

      🎯 Practical Application Examples

      Creating CLI Tool Gem

      # lib/my_cli_tool.rb
require 'optparse'
require 'json'

module MyCliTool
  class CLI
    def self.start(args)
      options = {}

      OptionParser.new do |opts|
        opts.banner = "Usage: my_cli_tool [options]"

        opts.on("-f", "--file FILE", "Specify input file") do |file|
          options[:file] = file
        end

        opts.on("-o", "--output FILE", "Specify output file") do |file|
          options[:output] = file
        end

        opts.on("-v", "--verbose", "Verbose output") do
          options[:verbose] = true
        end

        opts.on("-h", "--help", "Show help") do
          puts opts
          exit
        end
     .parse!(args)

      new(options).run
    end

    def initialize(options)
      @options = options
    end

    def run
      puts "Processing file: #{@options[:file]}" if @options[:verbose]

      if @options[:file] && File.exist?(@options[:file])
        process_file(@options[:file])
      else
        puts "Error: File does not exist or not specified"
        exit 1
      end
    end

    private

    def process_file(file)
      data = JSON.parse(File.read(file))
      result = transform_data(data)

      if @options[:output]
        File.write(@options[:output], JSON.pretty_generate(result))
        puts "Result saved to: #{@options[:output]}"
      else
        puts JSON.pretty_generate(result)
      end
    end

    def transform_data(data)
      # Data transformation logic
      data.transform_keys(&:upcase)
    end
  end
end
      # bin/my_cli_tool
#!/usr/bin/env ruby

require_relative '../lib/my_cli_tool'

MyCliTool::CLI.start(ARGV)

      Web Application Gem Dependency Management

      # Gemfile for a web application
source 'https://rubygems.org'
git_source(:github) { |repo| "https://github.com/#{repo}.git" }

ruby '3.0.0'

# Core gems
gem 'rails', '~> 6.1.0'
gem 'sprockets-rails', '>= 2.0.0'
gem 'pg', '~> 1.1'
gem 'puma', '~> 5.0'
gem 'importmap-rails', '>= 0.3.4'
gem 'turbo-rails', '>= 0.7.11'
gem 'stimulus-rails', '>= 0.4.0'
gem 'jbuilder', '~> 2.7'
gem 'redis', '~> 4.0'
gem 'bootsnap', '>= 1.4.4', require: false
gem 'sassc-rails', '>= 2.1.0'
gem 'image_processing', '~> 1.2'

# Authentication & Authorization
gem 'devise'
gem 'cancancan'

# Background Jobs
gem 'sidekiq'
gem 'sidekiq-web'

# API
gem 'grape'
gem 'grape-entity'

# Utilities
gem 'kaminari'
gem 'friendly_id'
gem 'carrierwave'
gem 'mini_magick'

group :development, :test do
  gem 'debug', '>= 1.0.0', platforms: %i[mri mingw x64_mingw]
  gem 'rspec-rails'
  gem 'factory_bot_rails'
  gem 'faker'
  gem 'shoulda-matchers'
end

group :development do
  gem 'web-console', '>= 4.1.0'
  gem 'listen', '~> 3.3'
  gem 'spring'
  gem 'letter_opener'
  gem 'annotate'
  gem 'bullet'
end

group :test do
  gem 'capybara', '>= 3.26'
  gem 'selenium-webdriver'
  gem 'webdrivers'
  gem 'database_cleaner-active_record'
  gem 'simplecov', require: false
end

group :production do
  gem 'lograge'
  gem 'newrelic_rpm'
end

      ⚠️ Common Problems and Solutions

      Version Conflicts

      # View dependency conflicts
bundle install --verbose

# Force update gems with conflicts
bundle update --conservative gem_name

# View why a gem is needed
bundle viz --format=png --requirements

      Permission Issues

      # User-level installation (recommended)
gem install --user-install gem_name

# Or use rbenv/rvm to manage Ruby versions
rbenv install 3.0.0
rbenv global 3.0.0

      Network Issues

      # Use domestic mirror source
gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

# Specify mirror in Gemfile
source 'https://gems.ruby-china.com'

      Cleaning Old Versions

      # Clean up old versions of gems
gem cleanup

# Clean up old versions of specific gem
gem cleanup rails

      🔒 Security Best Practices

      Checking for Security Vulnerabilities

      # Install bundler-audit
gem install bundler-audit

# Update vulnerability database
bundle audit update

# Check project dependencies for security vulnerabilities
bundle audit check

      Locking Dependency Versions

      # Use exact versions in production
gem 'rails', '6.1.4'  # Instead of '~> 6.1.0'

# Or use Gemfile.lock to ensure consistency
bundle install --deployment

      📊 Performance Optimization

      Parallel Installation

      # Install gems in parallel (faster installation)
bundle install --jobs 4

      Local Caching

      # Cache gems to vendor/cache
bundle package

# Install from cache
bundle install --local

      Reducing Dependencies

      # Only load gems in needed environments
group :development do
  gem 'byebug'
end

# Use require: false for lazy loading
gem 'whenever', require: false

      🎓 Best Practices Summary

      1. Version Management:

        • Use semantic versioning
        • Specify reasonable version constraints in Gemfile
        • Commit Gemfile.lock to version control

      2. Dependency Management:

        • Regularly update dependencies
        • Check for security vulnerabilities
        • Avoid unnecessary dependencies

      3. Development Workflow:

        • Use bundle exec to run commands
        • Test in different environments
        • Document dependency requirements

      4. Gem Development:

        • Follow Ruby community conventions
        • Write tests and documentation
        • Use semantic versioning

      By mastering Gems and Bundler, you will be better equipped to manage Ruby project dependencies, create reusable code packages, and participate in the Ruby ecosystem. These skills are essential for any Ruby developer.