traveling-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad2eee4e23f9daaad4c1aeb441f57b85abbbfe1562323028e04e17881a3fb6bd
+  data.tar.gz: b1bf5034edee04138c17f0baa72d394218259d83ce8acdc9bf9b79b81f8cb898
+SHA512:
+  metadata.gz: c30cd182e8717d7e896ce2924f7e6d3cda1f1dea73973695559be1d25e7881af8a4471642bebabaff660393c2e377fbaa454f9ab462750c787d166cc685555ed
+  data.tar.gz: 7941f806e53aef207c3e6bce3d98abf083430579281ea52f3c13d01e6212afd83e2e76cbeb2aa59fbdabf4a4a5b63e34d83476d1768597d0e1fd049313a5abeb

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2014-2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# truby
+
+**truby** packages Ruby apps with [Traveling Ruby](../README.md), a portable Ruby, so people can run them on Linux, macOS and Windows without installing Ruby. It ships in the `traveling-ruby` gem.
+
+```console
+$ gem install traveling-ruby
+$ truby package
+Packaging hello 1.0.0 with Ruby 3.4.12 (Traveling Ruby 3.4.12-1)
+  ✓ linux-x86_64    12 gems, 2 native  pkg/hello-1.0.0-linux-x86_64.tar.gz    14.1 MB
+  ✓ linux-arm64     12 gems, 2 native  pkg/hello-1.0.0-linux-arm64.tar.gz     13.8 MB
+  ✓ macos-x86_64    12 gems, 2 native  pkg/hello-1.0.0-macos-x86_64.tar.gz    14.6 MB
+  ✓ macos-arm64     12 gems, 2 native  pkg/hello-1.0.0-macos-arm64.tar.gz     14.4 MB
+  ✓ windows-x86_64  12 gems, 2 native  pkg/hello-1.0.0-windows-x86_64.tar.gz  20.2 MB
+
+Done in 9.8s. Launcher: hello
+```
+
+Each package holds a launcher per program, the app, and a Ruby with the app's locked gems installed:
+
+```
+hello-1.0.0-linux-x86_64/
+  hello              launcher (hello.bat on Windows)
+  lib/app/           the app
+  lib/ruby/          Ruby and the app's gems
+  lib/bundle/config  Bundler settings for the app
+```
+
+Nothing is compiled. Gems are installed from their `ruby` platform `.gem` files, and native gems get the extensions Traveling Ruby built for the release, so you can package for every platform from any machine. `traveling-ruby` also works as the command's name.
+
+## Get started
+
+```sh
+bundle lock --add-platform ruby   # lock gems truby can install for every target
+truby init                        # write truby.yml
+truby check                       # see that every gem works on every target
+truby package
+```
+
+`truby check` builds nothing. It shows each launcher and each native gem, and says what to do about a gem with no extension built for a target:
+
+```
+Gems
+  ✓ 65 locked for the ruby platform
+  ✓ json-3.1.0        built for all targets
+  ✗ prism-2.1.0       no extension built for all targets
+      → 3.4.12-1 builds prism 1.9.0: pin it with gem "prism", "1.9.0"
+
+Not ready to package.
+```
+
+`truby package` stops on the same problem, since a gem without its extension fails when the app loads it. Pin a version the release builds, or pass `--allow-missing-extensions` to package without it.
+
+## truby.yml
+
+The app's packaging settings live in `truby.yml` (or `.truby.yml`), and command line options win over it:
+
+```yaml
+name: pact
+version: 2.5.0
+ruby: 3.4.12
+targets: [linux-x86_64, linux-arm64, macos-arm64, windows-x86_64]
+bin:
+  pact-broker: pact-broker.rb   # a script in the app
+  pact-mock-service:            # bin/, exe/, pact-mock-service.rb, or a gem's executable
+ruby_opts: [-EUTF-8]
+keep: [pact_broker/public]      # gem files that pruning would remove
+```
+
+| Setting | Option | Default |
+| --- | --- | --- |
+| `name` | `--name` | the app directory's name |
+| `version` | `--app-version` | none; when set it goes in package names |
+| `bin` | `--bin NAME[=SCRIPT]` | `bin/NAME` or `exe/NAME` |
+| `targets` | `--targets` | `linux-x86_64, linux-arm64, macos-x86_64, macos-arm64, windows-x86_64` (`truby targets` lists them all) |
+| `ruby` | `--ruby` | the latest release's Ruby |
+| `revision` | `--revision` | the newest release of that Ruby |
+| `runtime` | `--full` | `slim`; `full` adds Ruby's headers and static libraries |
+| `without` | `--without` | `development, test` |
+| `ruby_opts` | `--ruby-opt` | none; passed to `ruby` by each launcher |
+| `keep` | `--keep` | none; a gem, or a path in one, that pruning keeps |
+| `prune` | `--[no-]prune` | on: removes gems' tests, docs and extension sources |
+| `archive` | `--[no-]archive` | on: a `.tar.gz` per package, and `SHA256SUMS` |
+| `allow_missing_extensions` | `--allow-missing-extensions` | off |
+| `source` | `--source` | `https://github.com/trubygems/traveling-ruby`, or a directory of release assets |
+| `out` | `--out` | `pkg` |
+
+A `bin` entry with no script runs the first of `bin/NAME`, `exe/NAME`, `NAME.rb` and `NAME` in the app, or else the `NAME` executable of a locked gem, so an app can ship `rackup` or `puma` without a script of its own.
+
+Downloads are verified against each release's `SHA256SUMS` and the lockfile's `CHECKSUMS`, and cached in `~/.cache/traveling-ruby`. Pass `-v` to list each gem as it is installed.
+
+## Package a gem
+
+`truby gem` packages a gem from rubygems.org with a launcher for each of its executables:
+
+```console
+$ truby gem rubocop --targets macos-arm64,linux-x86_64
+$ ./pkg/rubocop-1.92.2-macos-arm64/rubocop --version
+1.92.2
+```
+
+Give a version as `rubocop:1.92.2`, and pick executables with `--bin`.
+
+## Rake task
+
+```ruby
+# Rakefile
+require "traveling_ruby/rake_task"
+
+TravelingRuby::RakeTask.new do |t|
+  t.app_version = "1.0.0"
+end
+```
+
+`rake package` builds every target, `rake package:linux-arm64` builds one and `rake package:check` checks the app. The task reads `truby.yml`, and settings given to it win over the file.
+
+## How a launcher runs the app
+
+A launcher runs `lib/ruby/bin/ruby -rbundler/setup` with the program's script, with `BUNDLE_GEMFILE` pointing at the app's Gemfile and any `BUNDLE_PATH` from the user's environment cleared. It follows symlinks, to itself or to a directory above it, so you can link it onto the `PATH`.
+
+The packaged lockfile locks only the `ruby` platform, with the checksums of the gems installed, so Bundler finds exactly what is in the package.
+
+Gems from git sources are not supported yet. Gems from path sources must be inside the app, and ship with it.
+
+## YJIT
+
+`ruby_opts: [--yjit]` turns YJIT on in the launchers. Linux and macOS runtimes are built with YJIT from 3.4.12-1 and 4.0.9-1. Windows runtimes are not yet, so there Ruby prints `warning: Ruby was built without YJIT support` and runs without it.
+
+## Development
+
+```sh
+cd packager
+bundle install
+bundle exec rake test
+bundle exec rake test:end_to_end   # package the fixture apps with a real release and run them
+```
+
+The end-to-end tests package real-world apps too: [the Pact CLI](test/fixtures/pact-cli), as pact-standalone ships it, and [a Pact Broker](test/fixtures/pact_broker) on SQLite or PostgreSQL under Puma, which the test publishes a pact to.
+
+## Releasing
+
+The gem is published by the [Packager workflow](../.github/workflows/packager.yml) with trusted publishing, so no rubygems.org API key is stored. Bump `TravelingRuby::VERSION`, merge, then tag the merge:
+
+```sh
+git tag gem-v0.1.0
+git push origin gem-v0.1.0
+```
+
+The workflow tests the gem, checks the tag matches its version, and pushes it from the `rubygems` environment. It also publishes a `gem-v0.1.0` GitHub release with the gem, its SHA-256 and a build provenance attestation. The release is never marked latest, since `cli.sh` installs the latest release as a Ruby runtime.

data/exe/traveling-ruby

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require_relative "../lib/traveling_ruby"
+require "traveling_ruby/cli"
+
+exit TravelingRuby::CLI.new.run(ARGV)

data/exe/truby

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require_relative "../lib/traveling_ruby"
+require "traveling_ruby/cli"
+
+exit TravelingRuby::CLI.new.run(ARGV)

data/lib/traveling_ruby/bundle.rb

@@ -0,0 +1,171 @@
+require "bundler"
+
+module TravelingRuby
+  # An app's Gemfile and lockfile: which locked gems a target needs, and the
+  # lockfile to ship, which locks the ruby platform variant of every gem so it
+  # matches what the package installs.
+  class Bundle
+    GEMFILES = %w[Gemfile gems.rb].freeze
+
+    LockedGem = Struct.new(:name, :version, :remotes, :checksum, keyword_init: true) do
+      def full_name
+        "#{name}-#{version}"
+      end
+    end
+
+    attr_reader :gemfile, :lockfile
+
+    def self.find(app_dir, **options)
+      gemfile = GEMFILES.map { |file| File.join(app_dir, file) }.find { |path| File.file?(path) }
+      gemfile && new(gemfile, **options)
+    end
+
+    def initialize(gemfile, without: %w[development test])
+      @gemfile = File.expand_path(gemfile)
+      @lockfile = @gemfile.end_with?(".rb") ? @gemfile.sub(/\.rb\z/, ".locked") : "#{@gemfile}.lock"
+      raise Error, "#{@lockfile} not found; run bundle lock first" unless File.file?(@lockfile)
+      @without = without.map(&:to_sym)
+      @lock_text = File.read(@lockfile)
+      @lock = Bundler::LockfileParser.new(@lock_text)
+      @dependencies = evaluate_gemfile
+    end
+
+    def app_dir
+      File.dirname(@gemfile)
+    end
+
+    # The locked gems to install for target, outside the groups left out.
+    # Gems from path sources inside the app ship with it and are not included.
+    def gems(target)
+      by_name = @lock.specs.group_by(&:name)
+      queue = @dependencies
+        .select { |dep| (dep.groups - @without).any? && platform?(dep.platforms, target) }
+        .map(&:name)
+      selected = {}
+      while (name = queue.shift)
+        next if selected.key?(name)
+        variants = by_name[name] or next # bundler itself is not locked as a spec
+        spec = variants.find { |s| s.platform.to_s == "ruby" } or raise Error,
+          "#{name} is locked only for #{variants.map { |s| s.platform.to_s }.uniq.join(", ")}; " \
+          "add the ruby platform with: bundle lock --add-platform ruby"
+        selected[name] = spec
+        queue.concat(spec.dependencies.map(&:name))
+      end
+      selected.values.filter_map { |spec| locked_gem(spec) }.sort_by(&:name)
+    end
+
+    # The lockfile with only ruby platform specs, the given gem checksums and
+    # bundler_version as the Bundler it was bundled with
+    def packaged_lockfile(checksums:, bundler_version:)
+      out = []
+      section = nil
+      seen = {}
+      skipping = false
+      @lock_text.each_line do |line|
+        if line.match?(/\A\S/)
+          section = line.strip
+          out << line
+          out << "  ruby\n" if section == "PLATFORMS"
+          next
+        end
+
+        case section
+        when "PLATFORMS"
+          out << line if line.strip.empty?
+        when "BUNDLED WITH"
+          out << (bundler_version ? line.sub(/\S+/, bundler_version) : line)
+        when "CHECKSUMS"
+          name, version = parse_spec_line(line)
+          next out << line unless name
+          key = "#{name}-#{version}"
+          next if seen.key?([section, key])
+          seen[[section, key]] = true
+          if (sha256 = checksums[key])
+            out << "  #{name} (#{version}) sha256=#{sha256}\n"
+          elsif line.include?("(#{version})")
+            out << line
+          else
+            out << "  #{name} (#{version})\n"
+          end
+        when "GEM", "PATH", "GIT"
+          if line.start_with?("    ") && !line.start_with?("      ")
+            name, version = parse_spec_line(line)
+            skipping = seen.key?([section, name, version])
+            next if skipping
+            seen[[section, name, version]] = true
+            out << "    #{name} (#{version})\n"
+          elsif line.start_with?("      ")
+            out << line unless skipping
+          else
+            skipping = false
+            out << line
+          end
+        else
+          out << line
+        end
+      end
+      out.join
+    end
+
+    private
+
+    def evaluate_gemfile
+      previous = ENV["BUNDLE_GEMFILE"]
+      ENV["BUNDLE_GEMFILE"] = @gemfile
+      Dir.chdir(app_dir) { Bundler::Dsl.new.tap { |dsl| dsl.eval_gemfile(@gemfile) }.dependencies }
+    ensure
+      ENV["BUNDLE_GEMFILE"] = previous
+    end
+
+    # Whether a dependency limited to platforms (Bundler's names, such as :ruby,
+    # :mri, :windows) is used on target
+    def platform?(platforms, target)
+      return true if platforms.empty?
+      platforms.any? do |platform|
+        case platform.to_s
+        when /\A(mri|ruby)(_\d+)?\z/ then platform.to_s.start_with?("mri") || !TravelingRuby.windows?(target)
+        when /\A(windows|mswin|mswin64|mingw|x64_mingw)(_\d+)?\z/ then TravelingRuby.windows?(target)
+        else false
+        end
+      end
+    end
+
+    def locked_gem(spec)
+      case (source = spec.source)
+      when Bundler::Source::Git
+        raise Error, "#{spec.name} comes from git (#{source}); git gems are not supported yet"
+      when Bundler::Source::Path
+        path = File.expand_path(source.path.to_s, app_dir)
+        return nil if path == app_dir || path.start_with?("#{app_dir}/")
+        raise Error, "#{spec.name} comes from #{path}, outside the app; path gems must be inside the app"
+      when Bundler::Source::Rubygems
+        version = spec.version.to_s
+        LockedGem.new(
+          name: spec.name,
+          version: version,
+          remotes: source.remotes.map(&:to_s),
+          checksum: locked_checksums["#{spec.name}-#{version}"]
+        )
+      else
+        raise Error, "#{spec.name} comes from an unsupported source (#{source})"
+      end
+    end
+
+    # sha256 checksums of ruby platform gems, from the lockfile's CHECKSUMS
+    def locked_checksums
+      @locked_checksums ||= begin
+        body = @lock_text[/^CHECKSUMS\n((?: .*\n)*)/, 1].to_s
+        body.each_line.filter_map do |line|
+          match = line.match(/\A\s+(\S+) \(([^)-]+)\) .*sha256=(\h{64})/) or next
+          ["#{match[1]}-#{match[2]}", match[3]]
+        end.to_h
+      end
+    end
+
+    # [name, version] from "  name (version[-platform])", or nil
+    def parse_spec_line(line)
+      match = line.match(/\A\s+(\S+) \(([^)]+)\)/) or return nil
+      [match[1], match[2].split("-", 2).first]
+    end
+  end
+end

data/lib/traveling_ruby/cli.rb

@@ -0,0 +1,210 @@
+require "optparse"
+require "bundler"
+require "open3"
+require "tmpdir"
+
+module TravelingRuby
+  # truby (also installed as traveling-ruby): the command line
+  class CLI
+    PROGRAM = "truby".freeze
+
+    # Raised once --help has printed a command's help
+    class HelpShown < StandardError; end
+
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @ui = UI.new(err)
+    end
+
+    def run(argv)
+      argv = argv.dup
+      case (command = argv.shift)
+      when "package" then package(argv)
+      when "check" then check(argv)
+      when "gem" then package_gem(argv)
+      when "init" then init(argv)
+      when "targets" then @out.puts(TARGETS) || 0
+      when "version", "--version" then @out.puts("#{PROGRAM} #{VERSION}") || 0
+      when nil, "help", "--help", "-h" then @out.puts(usage) || 0
+      else
+        @err.puts "#{PROGRAM}: unknown command #{command.inspect}\n\n#{usage}"
+        1
+      end
+    rescue HelpShown
+      0
+    rescue Error, OptionParser::ParseError => e
+      @err.puts "#{@ui.paint("#{PROGRAM}:", :red, :bold)} #{e.message}"
+      1
+    rescue Interrupt
+      @err.puts
+      130
+    end
+
+    private
+
+    def usage
+      <<~USAGE
+        #{PROGRAM} packages Ruby apps with Traveling Ruby, a portable Ruby, so they run
+        on Linux, macOS and Windows without Ruby installed.
+
+        Usage: #{PROGRAM} <command> [options]
+
+        Commands:
+          package [APP_DIR]    Package an app for each target
+          check [APP_DIR]      Check an app is ready to package, without building it
+          gem NAME[:VERSION]   Package a gem's executables, such as rubocop
+          init [APP_DIR]       Write a truby.yml with the app's settings
+          targets              List the targets
+          version              Show the version
+
+        Settings come from truby.yml in the app, and options win over it.
+        Run #{PROGRAM} <command> --help for a command's options.
+      USAGE
+    end
+
+    def package(argv)
+      options = {}
+      args = parser(options, "package [options] [APP_DIR]",
+                    "Packages the app in APP_DIR (default .) for each target, with its Gemfile.lock's gems.").parse(argv)
+      app_dir = app_dir(args)
+      print_paths(packager(app_dir, options).run)
+      0
+    end
+
+    def check(argv)
+      options = {}
+      args = parser(options, "check [options] [APP_DIR]",
+                    "Checks the app in APP_DIR (default .) is ready to package: its launchers resolve, its gems " \
+                    "are locked for the ruby platform and every native gem has an extension built for each target.")
+        .parse(argv)
+      packager(app_dir(args), options).check ? 0 : 1
+    end
+
+    def package_gem(argv)
+      options = {}
+      args = parser(options, "gem [options] NAME[:VERSION]",
+                    "Packages a gem from rubygems.org with a launcher for each of its executables " \
+                    "(or the ones given with --bin), into ./pkg.", app: false).parse(argv)
+      raise OptionParser::InvalidArgument, "give one gem, as in #{PROGRAM} gem rubocop:1.70.0" unless args.size == 1
+      gem_name, version = args.first.split(/[:@]/, 2)
+
+      Dir.mktmpdir("truby-gem-") do |dir|
+        File.write(File.join(dir, "Gemfile"), <<~RUBY)
+          source "https://rubygems.org"
+          gem #{gem_name.inspect}#{", #{version.inspect}" if version}
+        RUBY
+        @ui.say @ui.paint("  Resolving #{gem_name}#{" #{version}" if version}", :dim)
+        output, status = Bundler.with_unbundled_env do
+          Open3.capture2e("bundle", "lock", "--add-platform", "ruby", chdir: dir)
+        end
+        raise Error, "could not resolve #{args.first}:\n#{output}" unless status.success?
+        locked = Bundler::LockfileParser.new(File.read(File.join(dir, "Gemfile.lock"))).specs
+          .find { |spec| spec.name == gem_name }
+        options[:out] = File.expand_path(options[:out] || "pkg")
+        options[:name] ||= gem_name
+        packager = Packager.new(app_dir: dir, app_version: locked.version.to_s, gem_bins: gem_name, ui: @ui, **options)
+        print_paths(packager.run)
+      end
+      0
+    end
+
+    def init(argv)
+      force = false
+      args = OptionParser.new do |o|
+        o.banner = "Usage: #{PROGRAM} init [options] [APP_DIR]"
+        o.separator ""
+        o.separator "Writes APP_DIR/truby.yml (default ./truby.yml) with the app's name and programs."
+        o.separator ""
+        o.on("-f", "--force", "Overwrite an existing truby.yml") { force = true }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          raise HelpShown
+        end
+      end.parse(argv)
+      app_dir = File.expand_path(app_dir(args))
+      path = File.join(app_dir, "truby.yml")
+      existing = Config.find(app_dir)
+      raise Error, "#{existing} already exists; pass --force to overwrite it" if existing && !force
+
+      name = File.basename(app_dir)
+      bins = (Dir.glob("{bin,exe}/*", base: app_dir) - %w[bin/setup bin/console bin/bundle bin/rake bin/rails])
+        .select { |file| File.file?(File.join(app_dir, file)) }
+        .sort
+      version_file = File.join(app_dir, "VERSION")
+      lines = ["# Packaging settings for #{PROGRAM} (gem install traveling-ruby)", "name: #{name}"]
+      lines << "version: #{File.read(version_file).strip}" if File.file?(version_file)
+      lines << "targets: [#{DEFAULT_TARGETS.join(", ")}]"
+      if bins.empty?
+        lines << "# bin:            # a launcher per program: name: script in the app"
+        lines << "#   #{name}: #{name}.rb"
+      else
+        lines << "bin:"
+        bins.each { |file| lines << "  #{File.basename(file)}: #{file}" }
+      end
+      lines << "# ruby: 3.4.12          # default: the latest release's Ruby"
+      lines << "# ruby_opts: [-EUTF-8]"
+      lines << "# keep: [some_gem/docs]   # gem files that pruning would remove"
+      File.write(path, lines.join("\n") + "\n")
+      @ui.done "wrote #{path}"
+      @ui.hint "next: #{PROGRAM} check, then #{PROGRAM} package"
+      0
+    end
+
+    # Package paths for scripts, when stdout is piped; a terminal already has
+    # them in the report
+    def print_paths(paths)
+      paths.each { |path| @out.puts path } unless @out.respond_to?(:tty?) && @out.tty?
+    end
+
+    def app_dir(args)
+      raise OptionParser::InvalidArgument, "one app directory at most" if args.size > 1
+      args.first || "."
+    end
+
+    # The app's truby.yml, with the command line's options over it
+    def packager(app_dir, options)
+      settings = Config.load(app_dir).merge(options)
+      Packager.new(app_dir: app_dir, ui: @ui, **settings)
+    end
+
+    def parser(options, banner, description, app: true)
+      OptionParser.new do |o|
+        o.banner = "Usage: #{PROGRAM} #{banner}"
+        o.separator ""
+        o.separator description
+        o.separator ""
+        if app
+          o.on("--name NAME", "Package name (default: the app directory's name)") { |v| options[:name] = v }
+          o.on("--app-version VERSION", "Version to put in package names") { |v| options[:app_version] = v }
+        end
+        o.on("--bin NAME[=SCRIPT]", "A launcher: NAME runs SCRIPT in the app, or else bin/NAME, exe/NAME,",
+             "NAME.rb or a gem's NAME executable (repeatable; default: bin/NAME or exe/NAME)") do |v|
+          name, script = Config.parse_bin(v)
+          (options[:bins] ||= {})[name] = script
+        end
+        o.on("--targets LIST", Array, "Comma-separated targets (default: #{DEFAULT_TARGETS.join(",")})") { |v| options[:targets] = v }
+        o.on("--ruby VERSION", "Ruby version (default: the latest release's)") { |v| options[:ruby] = v }
+        o.on("--revision N", "Release revision (default: the newest for the Ruby version)") { |v| options[:revision] = v }
+        o.on("--full", "Use the full runtime, with Ruby's headers and static libraries") { options[:runtime] = "full" }
+        o.on("--out DIR", "Output directory (default: pkg)") { |v| options[:out] = v }
+        o.on("--without GROUPS", Array, "Gem groups to leave out (default: development,test)") { |v| options[:without] = v }
+        o.on("--ruby-opt OPT", "Option for ruby in the launchers, e.g. -EUTF-8 (repeatable)") { |v| (options[:ruby_opts] ||= []) << v }
+        o.on("--keep GEM[/PATH]", "Keep a gem's files that pruning would remove (repeatable)") { |v| (options[:keep] ||= []) << v }
+        o.on("--allow-missing-extensions", "Package native gems with no extension built, rather than fail") do
+          options[:allow_missing_extensions] = true
+        end
+        o.on("--[no-]prune", "Remove gems' tests, docs and extension sources (default: on)") { |v| options[:prune] = v }
+        o.on("--[no-]archive", "Make a .tar.gz of each package and SHA256SUMS (default: on)") { |v| options[:archive] = v }
+        o.on("--source URL_OR_DIR", "GitHub repository or directory of releases (default: #{Release::DEFAULT_SOURCE})") { |v| options[:source] = v }
+        o.on("--cache DIR", "Download cache (default: #{Fetcher.default_cache_dir})") { |v| options[:cache_dir] = v }
+        o.on("--entry PATH", "Same as --bin NAME=PATH, for the package's name") { |v| options[:entry] = v } if app
+        o.on("-v", "--verbose", "List each gem as it is installed") { @ui = UI.new(@err, verbose: true) }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts o
+          raise HelpShown
+        end
+      end
+    end
+  end
+end

data/lib/traveling_ruby/config.rb

@@ -0,0 +1,84 @@
+require "yaml"
+
+module TravelingRuby
+  # An app's packaging settings, from truby.yml (or .truby.yml) at its root:
+  #
+  #   name: pact
+  #   version: 2.5.0
+  #   ruby: 3.4.12
+  #   targets: [linux-x86_64, linux-arm64, macos-arm64, windows-x86_64]
+  #   bin:
+  #     pact-broker: pact-broker.rb      # a script in the app
+  #     rackup:                          # the app's bin/rackup, or a gem's rackup
+  #   ruby_opts: [-EUTF-8]
+  #   keep: [pact_broker/public]         # gem files that pruning would remove
+  #
+  # Settings given on the command line or to the Rake task win over the file.
+  module Config
+    FILES = %w[truby.yml .truby.yml].freeze
+
+    # Setting in the file => Packager option
+    KEYS = {
+      "name" => :name,
+      "version" => :app_version,
+      "entry" => :entry,
+      "bin" => :bins,
+      "bins" => :bins,
+      "targets" => :targets,
+      "ruby" => :ruby,
+      "revision" => :revision,
+      "runtime" => :runtime,
+      "source" => :source,
+      "out" => :out,
+      "without" => :without,
+      "ruby_opts" => :ruby_opts,
+      "keep" => :keep,
+      "prune" => :prune,
+      "archive" => :archive,
+      "allow_missing_extensions" => :allow_missing_extensions
+    }.freeze
+
+    module_function
+
+    def find(app_dir)
+      FILES.map { |file| File.join(app_dir, file) }.find { |path| File.file?(path) }
+    end
+
+    # Packager options from the app's config file; {} when it has none
+    def load(app_dir)
+      path = find(app_dir) or return {}
+      data = YAML.safe_load_file(path) || {}
+      raise Error, "#{path} must hold a mapping of settings" unless data.is_a?(Hash)
+      data.each_with_object({}) do |(key, value), options|
+        option = KEYS[key.to_s] or raise Error, "#{File.basename(path)}: unknown setting #{key.inspect} (known: #{KEYS.keys.uniq.join(", ")})"
+        options[option] = normalize(option, value)
+      end
+    end
+
+    def normalize(option, value)
+      case option
+      when :bins then bins(value)
+      when :targets, :without, :ruby_opts, :keep then value.is_a?(String) ? value.split(/[\s,]+/) : Array(value).map(&:to_s)
+      when :prune, :archive, :allow_missing_extensions then value == true
+      else value&.to_s
+      end
+    end
+
+    # bin: as a mapping of launcher => script, or a list of launcher names
+    def bins(value)
+      case value
+      when Hash then value.to_h { |name, script| [name.to_s, script&.to_s] }
+      when Array then value.to_h { |name| [name.to_s, nil] }
+      when String then {value => nil}
+      else raise Error, "bin: must be a mapping of launcher names to scripts"
+      end
+    end
+
+    # NAME or NAME=SCRIPT, as --bin takes
+    def parse_bin(arg)
+      name, script = arg.split("=", 2)
+      raise Error, "--bin needs a name, as in --bin NAME or --bin NAME=SCRIPT" if name.to_s.empty?
+      [name, script.to_s.empty? ? nil : script]
+    end
+  end
+end