class Gem::Package

使用 Gem::Package 的示例

根据 Gem::Specification 构建 .gem 文件。.gem 文件是一个 tarball，其中包含 data.tar.gz、metadata.gz、checksums.yaml.gz 和可能的签名。

require 'rubygems'
require 'rubygems/package'

spec = Gem::Specification.new do |s|
  s.summary = "Ruby based make-like utility."
  s.name = 'rake'
  s.version = PKG_VERSION
  s.requirements << 'none'
  s.files = PKG_FILES
  s.description = <<-EOF
Rake is a Make-like program implemented in Ruby. Tasks
and dependencies are specified in standard Ruby syntax.
  EOF
end

Gem::Package.build spec

读取 .gem 文件。

require 'rubygems'
require 'rubygems/package'

the_gem = Gem::Package.new(path_to_dot_gem)
the_gem.contents # get the files in the gem
the_gem.extract_files destination_directory # extract the gem into a directory
the_gem.spec # get the spec out of the gem
the_gem.verify # check the gem is OK (contains valid gem specification, contains a not corrupt contents archive)

files 是 .gem tar 文件中的文件，而不是 gem 中的 Ruby 文件。extract_files 和 contents 会自动调用 verify。

属性

checksums [R]

包内容的校验和

data_mode [RW]

其他文件的权限

dir_mode [RW]

目录的权限

files [R]

此包中的文件。这并非 gem 的内容，只是顶层容器中的文件。

gem [R]

对正在打包的 gem 的引用。

prog_mode [RW]

程序文件的权限

security_policy [RW]

用于验证此包内容的安全性策略。

spec [W]

设置用于构建此包的 Gem::Specification。

公共类方法

build (spec, skip_validation = false, strict_validation = false, file_name = nil)

源代码

# File lib/rubygems/package.rb, line 131
def self.build(spec, skip_validation = false, strict_validation = false, file_name = nil)
  gem_file = file_name || spec.file_name

  package = new gem_file
  package.spec = spec
  package.build skip_validation, strict_validation

  gem_file
end

new (gem, security_policy = nil)

源代码

# File lib/rubygems/package.rb, line 148
def self.new(gem, security_policy = nil)
  gem = if gem.is_a?(Gem::Package::Source)
    gem
  elsif gem.respond_to? :read
    Gem::Package::IOSource.new gem
  else
    Gem::Package::FileSource.new gem
  end

  return super unless self == Gem::Package
  return super unless gem.present?

  return super unless gem.start
  return super unless gem.start.include? "MD5SUM ="

  Gem::Package::Old.new gem
end

为 gem 处的文件创建一个新的 Gem::Package。 gem 也可以作为 IO 对象提供。

如果 gem 是旧格式的现有文件，则将返回 Gem::Package::Old。

调用父类方法 BasicObject::new

raw_spec (path, security_policy = nil)

源代码

# File lib/rubygems/package.rb, line 171
def self.raw_spec(path, security_policy = nil)
  format = new(path, security_policy)
  spec = format.spec

  metadata = nil

  File.open path, Gem.binary_mode do |io|
    tar = Gem::Package::TarReader.new io
    tar.each_entry do |entry|
      case entry.full_name
      when "metadata" then
        metadata = entry.read
      when "metadata.gz" then
        metadata = Gem::Util.gunzip entry.read
      end
    end
  end

  [spec, metadata]
end

从 path 处的 .gem 文件中提取 Gem::Specification 和原始元数据。

公共实例方法

add_checksums (tar)

源代码

# File lib/rubygems/package.rb, line 221
def add_checksums(tar)
  Gem.load_yaml

  checksums_by_algorithm = Hash.new {|h, algorithm| h[algorithm] = {} }

  @checksums.each do |name, digests|
    digests.each do |algorithm, digest|
      checksums_by_algorithm[algorithm][name] = digest.hexdigest
    end
  end

  tar.add_file_signed "checksums.yaml.gz", 0o444, @signer do |io|
    gzip_to io do |gz_io|
      Psych.dump checksums_by_algorithm, gz_io
    end
  end
end

将 gem 中每个条目的校验和添加到 checksums.yaml.gz。

build (skip_validation = false, strict_validation = false)

源代码

# File lib/rubygems/package.rb, line 292
  def build(skip_validation = false, strict_validation = false)
    raise ArgumentError, "skip_validation = true and strict_validation = true are incompatible" if skip_validation && strict_validation

    Gem.load_yaml

    @spec.validate true, strict_validation unless skip_validation

    setup_signer(
      signer_options: {
        expiration_length_days: Gem.configuration.cert_expiration_length_days,
      }
    )

    @gem.with_write_io do |gem_io|
      Gem::Package::TarWriter.new gem_io do |gem|
        add_metadata gem
        add_contents gem
        add_checksums gem
      end
    end

    say <<-EOM
  Successfully built RubyGem
  Name: #{@spec.name}
  Version: #{@spec.version}
  File: #{File.basename @gem.path}
EOM
  ensure
    @signer = nil
  end

基于 spec= 设置的规范构建此包

contents ()

源代码

# File lib/rubygems/package.rb, line 326
def contents
  return @contents if @contents

  verify unless @spec

  @contents = []

  @gem.with_read_io do |io|
    gem_tar = Gem::Package::TarReader.new io

    gem_tar.each do |entry|
      next unless entry.full_name == "data.tar.gz"

      open_tar_gz entry do |pkg_tar|
        pkg_tar.each do |contents_entry|
          @contents << contents_entry.full_name
        end
      end

      return @contents
    end
  end
rescue Zlib::GzipFile::Error, EOFError, Gem::Package::TarInvalidError => e
  raise Gem::Package::FormatError.new e.message, @gem
end

此 gem 中包含的文件名列表

copy_to (path)

源代码

# File lib/rubygems/package.rb, line 214
def copy_to(path)
  FileUtils.cp @gem.path, path unless File.exist? path
end

将此包复制到 path（如果可能）

extract_files (destination_dir, pattern = "*")

源代码

# File lib/rubygems/package.rb, line 385
def extract_files(destination_dir, pattern = "*")
  verify unless @spec

  FileUtils.mkdir_p destination_dir, mode: dir_mode && 0o755

  @gem.with_read_io do |io|
    reader = Gem::Package::TarReader.new io

    reader.each do |entry|
      next unless entry.full_name == "data.tar.gz"

      extract_tar_gz entry, destination_dir, pattern

      break # ignore further entries
    end
  end
rescue Zlib::GzipFile::Error, EOFError, Gem::Package::TarInvalidError => e
  raise Gem::Package::FormatError.new e.message, @gem
end

将此包中的文件解压到 destination_dir

如果指定了 pattern，则仅会解压与该 glob 匹配的条目。

gzip_to (io) { |gz_io| ... }

源代码

# File lib/rubygems/package.rb, line 490
def gzip_to(io) # :yields: gz_io
  gz_io = Zlib::GzipWriter.new io, Zlib::BEST_COMPRESSION
  gz_io.mtime = @build_time

  yield gz_io
ensure
  gz_io.close
end

将写入到 gz_io 的内容压缩到 io 中。

limit_read (io, name, limit)

源代码

# File lib/rubygems/package.rb, line 727
def limit_read(io, name, limit)
  bytes = io.read(limit + 1)
  raise Gem::Package::FormatError, "#{name} is too big (over #{limit} bytes)" if bytes.size > limit
  bytes
end

normalize_path (pathname)

源代码

# File lib/rubygems/package.rb, line 517
def normalize_path(pathname)
  if Gem.win_platform?
    pathname.downcase
  else
    pathname
  end
end

read_checksums (gem)

源代码

# File lib/rubygems/package.rb, line 554
def read_checksums(gem)
  Gem.load_yaml

  @checksums = gem.seek "checksums.yaml.gz" do |entry|
    Zlib::GzipReader.wrap entry do |gz_io|
      Gem::SafeYAML.safe_load limit_read(gz_io, "checksums.yaml.gz", 10 * 1024 * 1024)
    end
  end
end

从 tar 文件 gem 中读取和加载 checksums.yaml.gz

setup_signer (signer_options: {})

源代码

# File lib/rubygems/package.rb, line 568
def setup_signer(signer_options: {})
  passphrase = ENV["GEM_PRIVATE_KEY_PASSPHRASE"]
  if @spec.signing_key
    @signer =
      Gem::Security::Signer.new(
        @spec.signing_key,
        @spec.cert_chain,
        passphrase,
        signer_options
      )

    @spec.signing_key = nil
    @spec.cert_chain = @signer.cert_chain.map(&:to_s)
  else
    @signer = Gem::Security::Signer.new nil, nil, passphrase
    @spec.cert_chain = @signer.cert_chain.map(&:to_pem) if
      @signer.cert_chain
  end
end

准备 gem 进行签名和校验和生成。如果不存在签名证书和密钥，则仅设置校验和生成。

spec ()

源代码

# File lib/rubygems/package.rb, line 595
def spec
  verify unless @spec

  @spec
end

此 gem 的规范。

如果这是已构建 gem 的包，则会从 gem 中加载规范并返回。如果这是正在构建的 gem 的包，则会返回提供的规范。

verify ()

源代码

# File lib/rubygems/package.rb, line 611
def verify
  @files     = []
  @spec      = nil

  @gem.with_read_io do |io|
    Gem::Package::TarReader.new io do |reader|
      read_checksums reader

      verify_files reader
    end
  end

  verify_checksums @digests, @checksums

  @security_policy&.verify_signatures @spec, @digests, @signatures

  true
rescue Gem::Security::Exception
  @spec = nil
  @files = []
  raise
rescue Errno::ENOENT => e
  raise Gem::Package::FormatError.new e.message
rescue Zlib::GzipFile::Error, EOFError, Gem::Package::TarInvalidError => e
  raise Gem::Package::FormatError.new e.message, @gem
end

验证此 gem

包含有效的 gem 规范
包含内容存档
内容存档未损坏

验证后，可以从 spec 中获取 gem 中的 gem 规范

verify_entry (entry)

源代码

# File lib/rubygems/package.rb, line 660
def verify_entry(entry)
  file_name = entry.full_name
  @files << file_name

  case file_name
  when /\.sig$/ then
    @signatures[$`] = limit_read(entry, file_name, 1024 * 1024) if @security_policy
    return
  else
    digest entry
  end

  case file_name
  when "metadata", "metadata.gz" then
    load_spec entry
  when "data.tar.gz" then
    verify_gz entry
  end
rescue StandardError
  warn "Exception while verifying #{@gem.path}"
  raise
end

验证 .gem 文件中的 entry。

verify_files (gem)

源代码

# File lib/rubygems/package.rb, line 686
def verify_files(gem)
  gem.each do |entry|
    verify_entry entry
  end

  unless @spec
    raise Gem::Package::FormatError.new "package metadata is missing", @gem
  end

  unless @files.include? "data.tar.gz"
    raise Gem::Package::FormatError.new \
      "package content (data.tar.gz) is missing", @gem
  end

  if (duplicates = @files.group_by {|f| f }.select {|_k,v| v.size > 1 }.map(&:first)) && duplicates.any?
    raise Gem::Security::Exception, "duplicate files in the package: (#{duplicates.map(&:inspect).join(", ")})"
  end
end

验证 gem 的文件

受保护的实例方法

initialize (gem, security_policy)

源代码

# File lib/rubygems/package.rb, line 195
def initialize(gem, security_policy) # :notnew:
  require "zlib"

  @gem = gem

  @build_time      = Gem.source_date_epoch
  @checksums       = {}
  @contents        = nil
  @digests         = Hash.new {|h, algorithm| h[algorithm] = {} }
  @files           = nil
  @security_policy = security_policy
  @signatures      = {}
  @signer          = nil
  @spec            = nil
end

创建一个新的包，该包将读取或写入文件 gem。