Creating and Publishing Gems, and Rake

pocket/
├── .github/workflows/main.yml   CI: bundle exec rake on a Ruby matrix
├── .gitignore                   /.bundle/, /pkg/, /coverage/, /doc/, /tmp/ ...
├── .rubocop.yml                 TargetRubyVersion and double-quoted strings
├── CHANGELOG.md                 "## [Unreleased]" and "## [0.1.0]"
├── Gemfile                      source, "gemspec", irb, rake, minitest, rubocop
├── LICENSE.txt
├── README.md
├── Rakefile                     bundler/gem_tasks, test and rubocop tasks
├── bin/console                  IRB with the gem loaded
├── bin/setup                    bundle install and other setup
├── exe/pocket                   the executable (with --exe)
├── lib/pocket.rb                the entry point: module Pocket, class Error
├── lib/pocket/version.rb        VERSION = "0.1.0"
├── pocket.gemspec
├── sig/pocket.rbs               RBS signatures
└── test/                        test_helper.rb and test_pocket.rb

# frozen_string_literal: true

require "bundler/gem_tasks"
require "minitest/test_task"

Minitest::TestTask.create

require "rubocop/rake_task"

RuboCop::RakeTask.new

task default: %i[test rubocop]

# frozen_string_literal: true

Gem::Specification.new do |spec|
  spec.name = "files-glob"
  spec.version = "0.1.0"
  spec.authors = ["Example Author"]
  spec.summary = "An explicit allowlist of globs."
  spec.required_ruby_version = ">= 4.0"
  spec.metadata["rubygems_mfa_required"] = "true"

  # Predictable and independent of git, but a new kind of top-level file
  # has to be added to the list by hand.
  spec.files = Dir["lib/**/*.rb", "exe/*", "README.md", "LICENSE.txt"]
end

# frozen_string_literal: true

Gem::Specification.new do |spec|
  spec.name = "files-git"
  spec.version = "0.1.0"
  spec.authors = ["Example Author"]
  spec.summary = "Whatever git tracks, minus development files."
  spec.required_ruby_version = ">= 4.0"
  spec.metadata["rubygems_mfa_required"] = "true"

  # The bundle gem template: files that are not added to git are not packaged.
  gemspec = File.basename(__FILE__)
  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
    ls.readlines("\x0", chomp: true).reject do |f|
      (f == gemspec) || f.start_with?(*%w[bin/ test/ .github/ .rubocop.yml])
    end
  end
end

$ ruby -e 'puts Gem::Specification.load("pocket.gemspec").files'
CHANGELOG.md
LICENSE.txt
README.md
Rakefile
exe/pocket
lib/pocket.rb
lib/pocket/version.rb
sig/pocket.rbs
$ git add lib/pocket/extra.rb
$ ruby -e 'puts Gem::Specification.load("pocket.gemspec").files.grep(/extra/)'
lib/pocket/extra.rb

# frozen_string_literal: true

require_relative "lib/shelf/version"

Gem::Specification.new do |spec|
  spec.name = "shelf-sqlite"
  spec.version = Shelf::VERSION
  spec.authors = ["Example Author"]
  spec.summary = "SQLite store for the shelf catalogue."
  spec.homepage = "https://example.com/shelf-sqlite"
  spec.license = "MIT"
  spec.required_ruby_version = ">= 4.0"
  spec.metadata["rubygems_mfa_required"] = "true"
  spec.files = Dir["lib/**/*.rb"]

  # The gem this one extends: a lower bound only.
  spec.add_dependency "shelf", ">= 0.1"
  # A native gem that provides the database driver.
  spec.add_dependency "sqlite3", ">= 2.0"
  # csv became a bundled gem in Ruby 3.4 and must now be declared.
  spec.add_dependency "csv"
end

# frozen_string_literal: true

spec = Gem::Specification.load("shelf-sqlite.gemspec")
spec.dependencies.each do |dep|
  puts format("%<name>-9s %<req>-7s %<type>s", name: dep.name, req: dep.requirement, type: dep.type)
end

shelf     >= 0.1  runtime
sqlite3   >= 2.0  runtime
csv       >= 0    runtime

WARNING:  See https://guides.rubygems.org/specification-reference/ for help
ERROR:  While executing gem ... (Gem::InvalidSpecificationException)
    "FIXME" or "TODO" is not a summary

Invalid gemspec in [dep.gemspec]: Illformed requirement ["*"]
ERROR:  Error loading gemspec. Aborting.

WARNING:  licenses is empty, but is recommended. Use an license identifier from
https://spdx.org/licenses or 'Nonstandard' for a nonstandard license,
or set it to nil if you don't want to specify a license.
WARNING:  no homepage specified
WARNING:  make sure you specify the oldest ruby version constraint (like ">= 3.0") that you want your gem to support by setting the `required_ruby_version` gemspec attribute
WARNING:  See https://guides.rubygems.org/specification-reference/ for help
  Successfully built RubyGem
  Name: bare
  Version: 0.0.1
  File: bare-0.0.1.gem

# frozen_string_literal: true

versions = %w[2.0.0 1.0.0 1.0.1 1.0.0.rc1 1.0.0.beta2 1.1.0.beta 1.0.0.alpha 1.0.0.beta10 1.0.0.beta9]
puts versions.map { |v| Gem::Version.new(v) }.sort.join(" < ")

v = Gem::Version.new("1.2.3")
p v.segments
p v.bump
p v.release
p Gem::Version.new("1.0.0.rc1").prerelease?
p Gem::Version.new("1.0") == Gem::Version.new("1.0.0")
p Gem::Version.new("1.0.0-rc1").to_s
p Gem::Version.new("1.4.2").approximate_recommendation

begin
  Gem::Version.new("1.0.0+001")
rescue ArgumentError => e
  puts "#{e.class}: #{e.message}"
end

req = Gem::Requirement.new("~> 2.2")
puts req
p req.satisfied_by?(Gem::Version.new("2.9.1"))
p req.satisfied_by?(Gem::Version.new("3.0.0"))
p Gem::Requirement.new(">= 2.2", "< 4.0").satisfied_by?(Gem::Version.new("3.5"))
p Gem::Requirement.new("~> 2").satisfied_by?(Gem::Version.new("2.9"))
p Gem::Requirement.new("~> 2.2.0").satisfied_by?(Gem::Version.new("2.3.0"))

begin
  Gem::Requirement.new("*")
rescue Gem::Requirement::BadRequirementError => e
  puts "#{e.class}: #{e.message}"
end

1.0.0.alpha < 1.0.0.beta2 < 1.0.0.beta9 < 1.0.0.beta10 < 1.0.0.rc1 < 1.0.0 < 1.0.1 < 1.1.0.beta < 2.0.0
[1, 2, 3]
#<Gem::Version "1.3">
#<Gem::Version "1.2.3">
true
true
"1.0.0.pre.rc1"
"~> 1.4"
ArgumentError: Malformed version number string 1.0.0+001
~> 2.2
true
false
true
true
false
Gem::Requirement::BadRequirementError: Illformed requirement ["*"]

tar -tf shelf-0.1.0.gem
tar -xOf shelf-0.1.0.gem data.tar.gz | tar -tzf -
gem spec shelf-0.1.0.gem files
gem unpack shelf-0.1.0.gem --target tmp/unpacked

metadata.gz
data.tar.gz
checksums.yaml.gz
---
CHANGELOG.md
LICENSE.txt
README.md
exe/shelf
lib/shelf.rb
lib/shelf/author.rb
lib/shelf/book.rb
lib/shelf/catalog.rb
lib/shelf/isbn.rb
lib/shelf/loan.rb
lib/shelf/refinements/title_case.rb
lib/shelf/store/memory.rb
lib/shelf/version.rb
sig/shelf.rbs

gem push shelf-0.1.0.gem            # not run: uploads the archive and registers the version
gem push shelf-0.1.0.gem --otp 123456
gem push shelf-0.1.0.gem --key ci-push-key
gem push shelf-0.1.0.gem --host https://gems.example.com
gem push shelf-0.1.0.gem --attestation shelf-0.1.0.sigstore.json

Usage: gem push GEM [options]

  Options:
    -k, --key KEYNAME                Use the given API key
        --otp CODE                   Digit code for multifactor authentication
        --host HOST                  Push to another gemcutter-compatible host
        --attestation FILE           Push with sigstore attestations

rake release[remote]
    Create tag v0.1.0 and build and push shelf-0.1.0.gem to rubygems.org
    To prevent publishing in RubyGems use `gem_push=no rake release`

name: Release

on:
  push:
    tags:
      - "v*"

permissions:
  contents: read

jobs:
  push:
    name: Push gem to RubyGems.org
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: "4.0"
          bundler-cache: true
      - name: Run the tests before releasing
        run: bundle exec rake
      - uses: rubygems/release-gem@v1

$ cd data
$ rake -T
(in /path/to/project)
rake books:count  # Count the title files
rake books:list   # List the title files
$ rake -N -T
rake aborted!
No Rakefile found (looking for: rakefile, Rakefile, rakefile.rb, Rakefile.rb)

# frozen_string_literal: true

desc "Say hello"
task :hello do
  puts "hello"
end

desc "Greet someone (default: world)"
task :greet, [:name] do |_task, args|
  args.with_defaults(name: "world")
  puts "hello, #{args[:name]}"
end

task :prepare do
  puts "prepare"
end

desc "Build after preparing"
task build: :prepare do
  puts "build"
end

task :undocumented do
  puts "nobody lists me"
end

namespace :db do
  desc "Create the schema"
  task :create do
    puts "db:create"
  end

  desc "Load fixtures"
  task seed: :create do
    puts "db:seed"
  end
end

task default: %i[build db:seed]

$ rake
prepare
build
db:create
db:seed
$ rake -T
rake build        # Build after preparing
rake db:create    # Create the schema
rake db:seed      # Load fixtures
rake greet[name]  # Greet someone (default: world)
rake hello        # Say hello
$ rake -AT
rake build         # Build after preparing
rake db:create     # Create the schema
rake db:seed       # Load fixtures
rake default       #
rake greet[name]   # Greet someone (default: world)
rake hello         # Say hello
rake prepare       #
rake undocumented  #
$ rake -P
rake build
    prepare
rake db:create
rake db:seed
    create
rake default
    build
    db:seed
rake greet
rake hello
rake prepare
rake undocumented
$ rake -D db
rake db:create
    Create the schema

rake db:seed
    Load fixtures

$ rake nope
rake aborted!
Don't know how to build task 'nope' (See the list of available tasks with `rake --tasks`)

(See full trace by running task with --trace)

# frozen_string_literal: true

task :announce, [:isbn] do |_t, args|
  puts "announce isbn=#{args[:isbn].inspect}"
end

desc "Lend a book to a member"
task :lend, %i[isbn member] => :announce do |_t, args|
  isbn = args.fetch(:isbn)
  member = args.fetch(:member, "anonymous")
  puts "lending #{isbn} to #{member}"
  puts "extras: #{args.extras.inspect}"
end

desc "Read a setting from the environment"
task :env do
  puts "LEVEL=#{ENV.fetch('LEVEL', 'info')}"
end

$ rake "lend[9780306406157,Ada,spare]"
announce isbn="9780306406157"
lending 9780306406157 to Ada
extras: ["spare"]
$ rake "lend[9780306406157]"
announce isbn="9780306406157"
lending 9780306406157 to anonymous
extras: []
$ rake lend
announce isbn=nil
rake aborted!
KeyError: key not found: :isbn (KeyError)
.../Rakefile:9:in 'block in <top (required)>'
Tasks: TOP => lend
(See full trace by running task with --trace)
$ rake env LEVEL=debug
LEVEL=debug
$ rake -T
rake env                # Read a setting from the environment
rake lend[isbn,member]  # Lend a book to a member

# frozen_string_literal: true

task :setup do
  puts "setup"
end

task :compile do
  puts "compile"
end

# A second definition adds an action; it does not replace the first one.
task :compile do
  puts "compile (second action)"
end

# enhance adds a prerequisite and an action to an existing task.
Rake::Task[:compile].enhance([:setup]) { puts "compile (enhanced)" }

desc "Show invoke, reenable and execute"
task :demo do
  Rake::Task[:compile].invoke
  puts "-- invoke again: nothing runs"
  Rake::Task[:compile].invoke
  puts "-- reenable, then invoke"
  Rake::Task[:compile].reenable
  Rake::Task[:compile].invoke
  puts "-- execute skips prerequisites"
  Rake::Task[:compile].execute
end

$ rake demo
setup
compile
compile (second action)
compile (enhanced)
-- invoke again: nothing runs
-- reenable, then invoke
compile
compile (second action)
compile (enhanced)
-- execute skips prerequisites
compile
compile (second action)
compile (enhanced)

# frozen_string_literal: true

require "rake/clean"

SOURCES = FileList["data/*.txt"]
UPPER = SOURCES.pathmap("build/%n.up")

CLEAN.include("build/*.up")
CLOBBER.include("build")

directory "build"

rule ".up" => [->(name) { name.pathmap("data/%n.txt") }, "build"] do |t|
  puts "convert #{t.source} -> #{t.name}"
  File.write(t.name, File.read(t.source).upcase)
end

file "build/all.txt" => UPPER do |t|
  puts "concatenate #{t.prerequisites.join(', ')}"
  File.write(t.name, t.prerequisites.map { |f| File.read(f) }.join)
end

desc "Build the combined report"
task report: "build/all.txt"

task default: :report

$ rake
mkdir -p build
convert data/a.txt -> build/a.up
convert data/b.txt -> build/b.up
concatenate build/a.up, build/b.up
$ rake
$ touch data/a.txt; rake
convert data/a.txt -> build/a.up
concatenate build/a.up, build/b.up
$ rake -B
convert data/a.txt -> build/a.up
convert data/b.txt -> build/b.up
concatenate build/a.up, build/b.up
$ rake clean
$ ls build
all.txt
$ rake clobber
$ ls
Rakefile
data
$ rake -T
rake clean    # Remove any temporary products
rake clobber  # Remove any generated files
rake report   # Build the combined report

# frozen_string_literal: true

require "rake"

files = Rake::FileList["data/*.txt"]
p files
p files.ext(".bak")
p files.pathmap("%n")
p files.pathmap("%{data,build}d/%n.up")
p "lib/shelf/book.rb".pathmap("%d | %f | %n | %x | %X")

# exclude changes the list in place; ask for a copy first.
p files.dup.exclude("data/b.txt").to_a
p files.to_a
p Rake::FileList["data/*"].exclude(/\.md\z/).to_a
files.exclude("data/b.txt")
p files.to_a

["data/a.txt", "data/b.txt"]
["data/a.bak", "data/b.bak"]
["a", "b"]
["build/a.up", "build/b.up"]
"lib/shelf | book.rb | book | .rb | lib/shelf/book"
["data/a.txt"]
["data/a.txt", "data/b.txt"]
["data/a.txt", "data/b.txt"]
["data/a.txt"]

# frozen_string_literal: true

desc "Run shell commands from a task"
task :shell do
  sh "echo", "echoed by sh"
  sh "echo quiet", verbose: false
  ruby "-e", "puts RUBY_VERSION", verbose: false
  sh "false" do |ok, status|
    puts "ok=#{ok} exit=#{status.exitstatus}"
  end
end

desc "A failing command stops the task"
task :broken do
  sh "false"
  puts "never printed"
end

$ rake shell
echo echoed by sh
echoed by sh
quiet
4.0.7
false
ok=false exit=1
$ rake broken
false
rake aborted!
Command failed with status (1): [false]
.../Rakefile:15:in 'block in <top (required)>'
Tasks: TOP => broken
(See full trace by running task with --trace)

# frozen_string_literal: true

SLOW = %i[slow_a slow_b slow_c].freeze

SLOW.each do |name|
  task name do
    sleep 0.3
  end
end

task serial: SLOW
multitask concurrent: SLOW

def elapsed
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  yield
  Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
end

desc "Compare ordinary and parallel prerequisites"
task :compare do
  %i[serial concurrent].each do |name|
    SLOW.each { |slow| Rake::Task[slow].reenable }
    seconds = elapsed { Rake::Task[name].invoke }
    puts format("%<name>-10s %<seconds>.1fs", name:, seconds:)
  end
end

$ rake compare
serial     0.9s
concurrent 0.3s

# frozen_string_literal: true

namespace :greetings do
  desc "Defined in rakelib/greetings.rake"
  task :hello do
    puts "hello from rakelib"
  end
end

$ rake -T
rake default          # Run everything
rake greetings:hello  # Defined in rakelib/greetings.rake
$ rake
hello from rakelib

# frozen_string_literal: true

import "tasks/docs.rake"

task default: "docs:build"

# frozen_string_literal: true

namespace :docs do
  desc "Build the documentation"
  task :build do
    puts "docs built"
  end
end

$ rake
docs built
$ rake -T
rake docs:build  # Build the documentation

# frozen_string_literal: true

require "rake/tasklib"

module Shelf
  # Defines `<name>:count` and `<name>:list` tasks for a set of title files.
  class TitlesTask < Rake::TaskLib
    attr_accessor :name, :pattern

    def initialize(name = :titles)
      super()
      @name = name
      @pattern = "data/*.txt"
      yield self if block_given?
      define
    end

    private

    def define
      files = Rake::FileList[pattern]

      namespace(name) do
        define_count(files)
        define_list(files)
      end
    end

    def define_count(files)
      desc "Count the title files"
      task(:count) { puts "#{files.size} title files" }
    end

    def define_list(files)
      desc "List the title files"
      task(:list) { files.each { |file| puts file } }
    end
  end
end

Shelf::TitlesTask.new(:books) do |t|
  t.pattern = "data/*.txt"
end

$ rake -T
rake books:count  # Count the title files
rake books:list   # List the title files
$ rake books:count
2 title files

$ rake --trace=stdout build
** Invoke build (first_time)
** Invoke prepare (first_time)
** Execute prepare
prepare
** Execute build
build