rubycc 1.0.0

data/lib/rubycc/objfile/relocatable_writer.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+module Rubycc
+  module ObjFile
+    # Writes a *general* ELF64 relocatable object (ET_REL) for Linux x86_64:
+    # arbitrary named sections, an arbitrary symbol table, and full SHT_RELA
+    # relocation tables carrying any relocation type and addend.
+    #
+    # It is the counterpart the linker's `ld -r` core needs and deliberately
+    # NOT the compiler's ELFWriter. That writer serves a single translation
+    # unit through a fixed menu — .text/.rodata/.data/.bss and three baked-in
+    # relocation kinds — because a compiler always emits the same shape. A
+    # merged object is open-ended: it may hold any section the inputs carried
+    # (.comment, .note.*, .eh_frame, ...), section symbols pointing at merged
+    # sections, and relocations of any numeric type against any symbol with any
+    # addend. Rather than contort the compiler's writer, this one accepts those
+    # pieces directly and lays them out.
+    #
+    # The API is build-then-emit: #add_section, #add_symbol and #add_relocation
+    # return opaque handles (the value structs below) that later calls reference
+    # by identity, so the caller never computes on-disk indices itself. #to_binary
+    # fixes the section order (NULL, the content sections in insertion order, one
+    # .rela.<name> per relocated target, then .symtab/.strtab/.shstrtab), resolves
+    # every cross-reference (symbol st_shndx, rela sh_link/sh_info, r_info's symbol
+    # index) against that order, and concatenates the image.
+    #
+    # Two invariants the caller relies on: symbols are emitted with every
+    # STB_LOCAL before the first non-local (a stable partition of insertion
+    # order, so relocation handles stay valid) and sh_info of .symtab lands on
+    # the first global; output is fully deterministic (N4) — identical build
+    # calls yield byte-identical bytes, with no timestamps embedded.
+    class RelocatableWriter
+      ELFCLASS64  = 2
+      ELFDATA2LSB = 1
+      EV_CURRENT  = 1
+      ET_REL      = 1
+      EM_X86_64   = 62
+      EM_AARCH64  = 183
+
+      SHN_UNDEF = 0
+      SHN_ABS   = 0xFFF1
+
+      SHT_SYMTAB = 2
+      SHT_STRTAB = 3
+      SHT_RELA   = 4
+      SHT_NOBITS = 8
+
+      SHF_INFO_LINK = 0x40
+
+      # Symbolic bind/type/visibility accepted from the caller, mapped to their
+      # st_info / st_other encodings. A caller may also pass the raw integer,
+      # which passes through unchanged.
+      BINDINGS     = { local: 0, global: 1, weak: 2 }.freeze
+      TYPES        = { notype: 0, object: 1, func: 2, section: 3, file: 4, tls: 6, ifunc: 10 }.freeze
+      VISIBILITIES = { default: 0, internal: 1, hidden: 2, protected: 3 }.freeze
+
+      SYM_ENTSIZE  = 24
+      RELA_ENTSIZE = 24
+      SHDR_ENTSIZE = 64
+      EHDR_SIZE    = 64
+
+      # A section to emit. `data` holds the file bytes for a non-NOBITS section;
+      # a NOBITS section (.bss) carries `size` instead and occupies no file
+      # space. `index` is filled in during layout.
+      Section = Struct.new(
+        :name, :type, :flags, :addralign, :entsize, :data, :size, :index,
+        keyword_init: true
+      )
+
+      # A symbol to emit. `section` (a Section handle) names the section that
+      # defines it, in which case st_shndx is that section's index; otherwise
+      # `shndx` carries a reserved value (SHN_UNDEF / SHN_ABS). `index` is filled
+      # in during layout.
+      Symbol = Struct.new(
+        :name, :bind, :type, :visibility, :section, :shndx, :value, :size, :index,
+        keyword_init: true
+      )
+
+      # A relocation to emit into the .rela table of `target`. `symbol` is a
+      # Symbol handle; `type` is the numeric x86_64 relocation type.
+      Relocation = Struct.new(:target, :offset, :symbol, :type, :addend, keyword_init: true)
+
+      # `machine` is the ELF e_machine value stamped into the output header. It
+      # defaults to x86_64 so an existing caller is unaffected; the partial-link
+      # merge passes the inputs' own machine through so a merged aarch64 object
+      # keeps its EM_AARCH64 identity (the final linker reads it back to pick the
+      # target's relocation and crt logic).
+      def initialize(machine: EM_X86_64)
+        @machine = machine
+        @sections = []
+        # The reserved null symbol is index 0 by the ELF ABI; expose it so a
+        # caller can re-point a "no symbol" relocation at it.
+        @null_symbol = Symbol.new(name: nil, bind: 0, type: 0, visibility: 0,
+                                  section: nil, shndx: SHN_UNDEF, value: 0, size: 0)
+        @symbols = [@null_symbol]
+        @relocations = []
+      end
+
+      attr_reader :null_symbol
+
+      # Registers a content section. `type`/`flags`/`entsize` are raw ELF values;
+      # `data` (bytes) or, for a NOBITS section, `size` gives its extent. Returns
+      # the Section handle to reference from symbols and relocations.
+      def add_section(name:, type:, flags:, addralign:, entsize: 0, data: nil, size: nil)
+        section = Section.new(name: name, type: type, flags: flags,
+                              addralign: [addralign, 1].max, entsize: entsize,
+                              data: data&.b, size: size)
+        @sections << section
+        section
+      end
+
+      # Registers a symbol. `bind`/`type`/`visibility` may be the symbolic forms
+      # (:local, :func, :hidden, ...) or raw integers. Returns the Symbol handle.
+      def add_symbol(name:, bind:, type:, visibility: :default, section: nil, shndx: SHN_UNDEF, value: 0, size: 0)
+        symbol = Symbol.new(
+          name: name, bind: BINDINGS.fetch(bind, bind), type: TYPES.fetch(type, type),
+          visibility: VISIBILITIES.fetch(visibility, visibility),
+          section: section, shndx: shndx, value: value, size: size
+        )
+        @symbols << symbol
+        symbol
+      end
+
+      # Records a relocation to emit into `target`'s .rela table.
+      def add_relocation(target:, offset:, symbol:, type:, addend:)
+        @relocations << Relocation.new(target: target, offset: offset, symbol: symbol,
+                                       type: type, addend: addend)
+        self
+      end
+
+      # Assembles and returns the object as an ASCII-8BIT String.
+      def to_binary
+        order_symbols
+        layout = build_layout
+        assemble(layout)
+      end
+
+      def write(path)
+        File.binwrite(path, to_binary)
+      end
+
+      private
+
+      # Stable-partitions the symbol table so every STB_LOCAL precedes the first
+      # non-local, as the ABI requires, without disturbing relative order within
+      # each class. The null symbol (bind 0 = local) naturally stays first.
+      def order_symbols
+        locals, globals = @symbols.partition { |sym| sym.bind == BINDINGS[:local] }
+        @symbols = locals + globals
+        @first_global = locals.size
+        @symbols.each_with_index { |sym, i| sym.index = i }
+      end
+
+      # The relocations aimed at `section`, in insertion order — matched by
+      # object identity, since a Section struct hashes by value and its :index
+      # field is mutated during layout (a value-keyed lookup would then miss).
+      def relocations_for(section)
+        @relocations.select { |reloc| reloc.target.equal?(section) }
+      end
+
+      # A section descriptor used only during layout, carrying the payload bytes
+      # and the resolved sh_link/sh_info as concrete indices.
+      LaidOut = Struct.new(:name, :type, :flags, :addr, :size, :link, :info,
+                           :addralign, :entsize, :data, :offset, keyword_init: true)
+
+      # Fixes the on-disk section order and assigns every section its index, then
+      # builds the symbol/relocation/string payloads against those indices.
+      def build_layout
+        # Section order: NULL, the content sections, one .rela per relocated
+        # target, then the symbol and string tables. Indices are assigned as this
+        # list is built so the cross-references below resolve to concrete values.
+        sections = [null_layout]
+        index = 1
+        @sections.each do |sec|
+          sec.index = index
+          index += 1
+        end
+        rela_targets = @sections.select { |sec| relocations_for(sec).any? }
+        symtab_index = index + rela_targets.size
+        strtab_index = symtab_index + 1
+        shstrtab_index = strtab_index + 1
+
+        strtab, sym_name_offsets = build_strtab
+        symtab = build_symtab(sym_name_offsets)
+
+        @sections.each { |sec| sections << content_layout(sec) }
+        rela_targets.each do |target|
+          sections << rela_layout(target, relocations_for(target), symtab_index)
+        end
+        sections << symtab_layout(symtab, strtab_index)
+        sections << strtab_layout(strtab)
+        sections << shstrtab_layout
+
+        { sections: sections, shstrtab_index: shstrtab_index }
+      end
+
+      def null_layout
+        LaidOut.new(name: nil, type: 0, flags: 0, addr: 0, size: 0, link: 0, info: 0,
+                    addralign: 0, entsize: 0, data: "".b)
+      end
+
+      # A NOBITS section reports its in-memory size but carries no file bytes; any
+      # other section carries its data (nil data means the layout pass skips it).
+      def content_layout(sec)
+        nobits = sec.type == SHT_NOBITS
+        LaidOut.new(
+          name: sec.name, type: sec.type, flags: sec.flags, addr: 0,
+          size: nobits ? (sec.size || 0) : (sec.data ? sec.data.bytesize : 0),
+          link: 0, info: 0, addralign: sec.addralign, entsize: sec.entsize,
+          data: nobits ? nil : (sec.data || "".b)
+        )
+      end
+
+      def rela_layout(target, relocs, symtab_index)
+        LaidOut.new(
+          name: ".rela#{target.name}", type: SHT_RELA, flags: SHF_INFO_LINK, addr: 0,
+          size: relocs.size * RELA_ENTSIZE, link: symtab_index, info: target.index,
+          addralign: 8, entsize: RELA_ENTSIZE, data: build_rela(relocs)
+        )
+      end
+
+      def symtab_layout(symtab, strtab_index)
+        LaidOut.new(
+          name: ".symtab", type: SHT_SYMTAB, flags: 0, addr: 0, size: symtab.bytesize,
+          link: strtab_index, info: @first_global, addralign: 8, entsize: SYM_ENTSIZE,
+          data: symtab
+        )
+      end
+
+      def strtab_layout(strtab)
+        LaidOut.new(name: ".strtab", type: SHT_STRTAB, flags: 0, addr: 0,
+                    size: strtab.bytesize, link: 0, info: 0, addralign: 1, entsize: 0,
+                    data: strtab)
+      end
+
+      def shstrtab_layout
+        # Filled with real bytes in #assemble, once every section name is known.
+        LaidOut.new(name: ".shstrtab", type: SHT_STRTAB, flags: 0, addr: 0, size: 0,
+                    link: 0, info: 0, addralign: 1, entsize: 0, data: nil)
+      end
+
+      # Builds .strtab (symbol names). Returns [bytes, name -> offset]. Names are
+      # de-duplicated so two symbols with the same string share one entry.
+      def build_strtab
+        buf = +"\0".b
+        offsets = {}
+        @symbols.each do |sym|
+          name = sym.name
+          next if name.nil? || name.empty? || offsets.key?(name)
+
+          offsets[name] = buf.bytesize
+          buf << name.b << "\0".b
+        end
+        [buf, offsets]
+      end
+
+      def build_symtab(sym_name_offsets)
+        buf = +"".b
+        @symbols.each do |sym|
+          shndx = sym.section ? sym.section.index : sym.shndx
+          name_off = sym.name && !sym.name.empty? ? sym_name_offsets.fetch(sym.name) : 0
+          buf << sym_entry(name: name_off, info: (sym.bind << 4) | sym.type,
+                           other: sym.visibility, shndx: shndx, value: sym.value, size: sym.size)
+        end
+        buf
+      end
+
+      # Builds one .rela payload: 24 bytes per entry (r_offset, r_info, r_addend).
+      # r_info packs the symbol's resolved table index with the numeric type.
+      def build_rela(relocs)
+        buf = +"".b
+        relocs.each do |reloc|
+          r_info = (reloc.symbol.index << 32) | (reloc.type & 0xFFFFFFFF)
+          buf << [reloc.offset].pack("Q<") << [r_info].pack("Q<") << [reloc.addend].pack("q<")
+        end
+        buf
+      end
+
+      # Computes file offsets, fills in .shstrtab, and concatenates the header,
+      # section payloads and section header table.
+      def assemble(layout)
+        sections = layout[:sections]
+        shstrtab, name_offsets = build_shstrtab(sections)
+        sections[layout[:shstrtab_index]].data = shstrtab
+        sections[layout[:shstrtab_index]].size = shstrtab.bytesize
+
+        offset = EHDR_SIZE
+        sections.each do |sec|
+          # A NOBITS section keeps an aligned sh_offset for tooling but does not
+          # advance the file cursor; a NULL section (nil-ish) is skipped likewise.
+          if sec.type == SHT_NOBITS
+            offset = align(offset, [sec.addralign, 1].max)
+            sec.offset = offset
+            next
+          end
+          next if sec.data.nil?
+
+          offset = align(offset, [sec.addralign, 1].max)
+          sec.offset = offset
+          offset += sec.data.bytesize
+        end
+        shoff = align(offset, 8)
+
+        out = +"".b
+        out << build_ehdr(shoff, sections.size, layout[:shstrtab_index])
+        sections.each do |sec|
+          next if sec.data.nil? || sec.type == SHT_NOBITS
+
+          pad_to(out, sec.offset)
+          out << sec.data
+        end
+        pad_to(out, shoff)
+        sections.each { |sec| out << build_shdr(sec, name_offsets) }
+        out
+      end
+
+      def build_shstrtab(sections)
+        buf = +"\0".b
+        offsets = {}
+        sections.each do |sec|
+          name = sec.name
+          next if name.nil? || offsets.key?(name)
+
+          offsets[name] = buf.bytesize
+          buf << name.b << "\0".b
+        end
+        [buf, offsets]
+      end
+
+      def build_ehdr(shoff, shnum, shstrndx)
+        e_ident = [0x7F, 0x45, 0x4C, 0x46, ELFCLASS64, ELFDATA2LSB, EV_CURRENT,
+                   0, 0, 0, 0, 0, 0, 0, 0, 0].pack("C16")
+        e_ident +
+          [ET_REL].pack("S<") +
+          [@machine].pack("S<") +
+          [EV_CURRENT].pack("L<") +
+          [0].pack("Q<") +            # e_entry
+          [0].pack("Q<") +            # e_phoff
+          [shoff].pack("Q<") +        # e_shoff
+          [0].pack("L<") +            # e_flags
+          [EHDR_SIZE].pack("S<") +    # e_ehsize
+          [0].pack("S<") +            # e_phentsize
+          [0].pack("S<") +            # e_phnum
+          [SHDR_ENTSIZE].pack("S<") + # e_shentsize
+          [shnum].pack("S<") +        # e_shnum
+          [shstrndx].pack("S<")       # e_shstrndx
+      end
+
+      def build_shdr(sec, name_offsets)
+        [sec.name ? name_offsets[sec.name] : 0].pack("L<") +
+          [sec.type].pack("L<") +
+          [sec.flags].pack("Q<") +
+          [sec.addr].pack("Q<") +
+          [sec.offset || 0].pack("Q<") +
+          [sec.size].pack("Q<") +
+          [sec.link].pack("L<") +
+          [sec.info].pack("L<") +
+          [sec.addralign].pack("Q<") +
+          [sec.entsize].pack("Q<")
+      end
+
+      def sym_entry(name:, info:, other:, shndx:, value:, size:)
+        [name].pack("L<") + [info].pack("C") + [other].pack("C") +
+          [shndx].pack("S<") + [value].pack("Q<") + [size].pack("Q<")
+      end
+
+      def align(value, alignment)
+        (value + alignment - 1) / alignment * alignment
+      end
+
+      def pad_to(buffer, target_offset)
+        buffer << ("\0" * (target_offset - buffer.bytesize)).b if buffer.bytesize < target_offset
+      end
+    end
+  end
+end

data/lib/rubycc/pkgconf/cli.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Rubycc
+  module Pkgconf
+    PROG = "rubycc-pkgconf"
+
+    # The exact option vocabulary mkmf's mkmf.rb#pkg_config can invoke
+    # $PKGCONFIG with (tallied against this environment's mkmf.rb — see the
+    # Step 59 report): `--exists` to probe availability, and, as `--#{option}`
+    # for each entry of pkg_config's own *options argument or of its built-in
+    # default path, `--modversion`/`--cflags`/`--cflags-only-I`/
+    # `--cflags-only-other`/`--libs`/`--libs-only-l`. No other pkg-config
+    # option (--static, --print-requires, ...) is in scope.
+    KNOWN_OPTIONS = %w[exists modversion cflags cflags-only-I cflags-only-other libs libs-only-l].freeze
+
+    # Runs the shim for +argv+ and returns the process exit status: 0 on
+    # success, 1 if a named module (or one of its Requires) cannot be found,
+    # the .pc text is malformed, or an unknown option/no module was given —
+    # the same pass/fail contract mkmf's xsystem(... "--exists" ...) and
+    # get[...] calls rely on.
+    def self.run(argv, stdout: $stdout, stderr: $stderr, resolver: Resolver.new, filter: SystemPathFilter.new)
+      Cli.new(argv, stdout: stdout, stderr: stderr, resolver: resolver, filter: filter).run
+    end
+
+    # Parses argv into requested options + module names and renders exactly
+    # the options given, in the order given, onto one line — mirroring how
+    # mkmf's pkg_config() invokes $PKGCONFIG with all of a single call's
+    # `--#{option}` flags at once and reads back one combined line of output.
+    class Cli
+      def initialize(argv, stdout:, stderr:, resolver:, filter:)
+        @argv = argv
+        @out = stdout
+        @err = stderr
+        @resolver = resolver
+        @filter = filter
+        @options = []
+        @modules = []
+      end
+
+      def run
+        parse_argv
+        return 1 if @options.empty?
+
+        if @modules.empty?
+          @err.puts "#{PROG}: no package name specified"
+          return 1
+        end
+
+        if @options.include?("exists")
+          @modules.all? { |name| @resolver.exists?(name) } ? 0 : 1
+        else
+          render
+        end
+      rescue PkgconfError => e
+        @err.puts "#{PROG}: #{e.message}"
+        1
+      end
+
+      private
+
+      def parse_argv
+        @argv.each do |arg|
+          if arg.start_with?("--")
+            option = arg[2..]
+            unless KNOWN_OPTIONS.include?(option)
+              @err.puts "#{PROG}: unknown option '#{arg}'"
+              @options.clear
+              return
+            end
+            @options << option
+          else
+            @modules << arg
+          end
+        end
+      end
+
+      def render
+        parts = @options.map { |option| render_option(option) }
+        @out.puts parts.reject(&:empty?).join(" ")
+        0
+      end
+
+      def render_option(option)
+        case option
+        when "modversion"        then @modules.map { |name| @resolver.load(name).version.to_s }.join(" ")
+        when "cflags"             then all_cflags.join(" ")
+        when "cflags-only-I"      then all_cflags.select { |t| t.start_with?("-I") }.join(" ")
+        when "cflags-only-other"  then all_cflags.reject { |t| t.start_with?("-I") }.join(" ")
+        when "libs"                then all_libs.join(" ")
+        when "libs-only-l"         then all_libs.select { |t| t.start_with?("-l") }.join(" ")
+        end
+      end
+
+      # Multiple module arguments are concatenated in the order given — the
+      # "複数モジュール" case mkmf's pkg_config() call shape allows for.
+      #
+      # The system-path filter is applied here, once, rather than inside
+      # Resolver or per rendered option: Resolver's token lists are what the
+      # Requires chain says (the parser-level tests assert exactly that), while
+      # every option that renders those tokens — --cflags, --cflags-only-I,
+      # --cflags-only-other, --libs, --libs-only-l — has to agree on which of
+      # them are suppressed. --cflags-only-other and --libs-only-l are
+      # unaffected in practice, since they keep only tokens the filter never
+      # touches.
+      def all_cflags
+        dedupe_search_paths(@filter.cflags(@modules.flat_map { |name| @resolver.cflags_tokens(name) }), "-I")
+      end
+
+      def all_libs
+        dedupe_search_paths(@filter.libs(@modules.flat_map { |name| @resolver.libs_tokens(name) }), "-L")
+      end
+
+      # Collapse a repeated search-path token to its first occurrence, the way
+      # the real pkg-config does. A directory named twice searches the same
+      # directory twice, so dropping the later copy cannot change what is found,
+      # while keeping the first preserves the order the .pc files asked for.
+      #
+      # This is not hypothetical tidying: zlib.pc writes
+      # `Libs: -L${libdir} -L${sharedlibdir} -lz` and on this environment both
+      # variables expand to the same directory, so the shim emitted that -L
+      # twice where the real tool emitted it once. It went unnoticed because the
+      # system-path filter happened to remove both copies on Debian; measured on
+      # Alpine, where that directory is not a system directory and neither copy
+      # is removed (docs/development/STEPS.md Step 199).
+      #
+      # Only search paths are collapsed. `-l` is deliberately left alone: a
+      # repeated library can matter to a static link's resolution order, and no
+      # measurement here covers it.
+      def dedupe_search_paths(tokens, flag)
+        seen = {}
+        tokens.reject do |token|
+          next false unless token.start_with?(flag) && token.length > flag.length
+
+          seen.key?(token).tap { seen[token] = true }
+        end
+      end
+    end
+  end
+end

data/lib/rubycc/pkgconf/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rubycc
+  # The base error is normally provided by lib/rubycc.rb. Like rmake (M3 B1),
+  # Pkgconf is loadable on its own (its only caller so far is the
+  # exe/rubycc-pkgconf CLI, not the Rubycc aggregate), so define a stand-in only
+  # when the full library has not been required yet.
+  Error = Class.new(StandardError) unless defined?(Error)
+
+  module Pkgconf
+    # Base for every error this shim raises: a malformed .pc file, a module
+    # that cannot be found on the search path, or a construct outside the
+    # subset mkmf's pkg_config() actually calls for (R11/ROADMAP §6 B4).
+    class PkgconfError < Rubycc::Error; end
+
+    # The .pc text used a construct the parser does not accept: an
+    # unrecognized line, or a `${var}` reference to a variable that was never
+    # assigned (in this file, at the point the reference appears — pkg-config
+    # itself requires forward-references to be avoided the same way).
+    class ParseError < PkgconfError
+      def initialize(message, path:, line_number:)
+        super("#{path || '<pc>'}:#{line_number}: #{message}")
+      end
+    end
+
+    # No `<name>.pc` was found on the search path (PKG_CONFIG_PATH, then the
+    # default directories) — the same condition mkmf's `pkg-config --exists`
+    # probe reports as "not found".
+    class NotFoundError < PkgconfError; end
+
+    # A `Requires`/`Requires.private` entry carried a version comparison
+    # (`zlib >= 1.2`-style). mkmf's own `pkg_config(pkg, *options)` never
+    # passes a version constraint — the `pkg` argument is always a bare module
+    # name — so comparing versions is out of scope here (see the Step 59
+    # report for the mkmf.rb tally this is based on); a constraint inside a
+    # `Requires` field is diagnosed instead of silently ignored or guessed at.
+    class UnsupportedError < PkgconfError; end
+  end
+end

data/lib/rubycc/pkgconf/model.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Rubycc
+  module Pkgconf
+    # One parsed .pc file: the handful of fields mkmf's pkg_config() and its
+    # own Requires chain ever touch. `cflags`/`libs`/`libs_private` are the
+    # field text after `${var}` expansion, still a raw (unsplit) string —
+    # Resolver is the one that shellsplits it into tokens, since only Resolver
+    # knows whether a field is being consumed for --cflags or --libs.
+    class Package
+      attr_reader :name, :description, :version, :requires, :requires_private,
+                  :cflags, :libs, :libs_private, :path
+
+      def initialize(name:, description:, version:, requires:, requires_private:,
+                     cflags:, libs:, libs_private:, path:)
+        @name = name
+        @description = description
+        @version = version
+        @requires = requires
+        @requires_private = requires_private
+        @cflags = cflags
+        @libs = libs
+        @libs_private = libs_private
+        @path = path
+      end
+    end
+  end
+end

data/lib/rubycc/pkgconf/parser.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Rubycc
+  module Pkgconf
+    # Parses one .pc file's text into a Package. The grammar covered is
+    # exactly what the real .pc files this environment ships (zlib.pc,
+    # libffi.pc, openssl.pc's Requires chain — see test/fixtures/pkgconfig)
+    # and mkmf's own pkg_config() call shape actually use: `#`-comments and
+    # blank lines, `name=value` variable assignments, `${name}` expansion
+    # inside both variable and field values, and the seven fields
+    # Name/Description/Version/Requires/Requires.private/Libs/Libs.private/
+    # Cflags. Any other field line (URL:, Conflicts:, ...) is accepted and
+    # ignored — mkmf's pkg_config() never reads them — rather than rejected,
+    # so a real-world .pc with extra fields still parses.
+    class Parser
+      VARIABLE_LINE = /\A([A-Za-z_][A-Za-z0-9_.]*)=(.*)\z/
+      FIELD_LINE = /\A([A-Za-z][A-Za-z0-9.]*)\s*:\s*(.*)\z/
+      VARIABLE_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_.]*)\}/
+
+      # A single `Requires`/`Requires.private` entry with a version
+      # comparison attached, spaced (`zlib >= 1.2`) or not (`zlib>=1.2`).
+      REQUIRES_OPERATOR = /\A(<=|>=|==|!=|<|>|=)\z/
+
+      KNOWN_FIELDS = %w[Name Description Version Requires Requires.private Libs Libs.private Cflags].freeze
+
+      def self.parse(text, path: nil)
+        new(text, path: path).parse
+      end
+
+      def initialize(text, path: nil)
+        @text = text
+        @path = path
+        @variables = {}
+        @fields = {}
+      end
+
+      def parse
+        @text.each_line.with_index(1) do |raw_line, line_number|
+          parse_line(raw_line.chomp, line_number)
+        end
+        build_package
+      end
+
+      private
+
+      def parse_line(line, line_number)
+        return if line.strip.empty?
+        return if line.lstrip.start_with?("#")
+
+        if (m = VARIABLE_LINE.match(line))
+          @variables[m[1]] = expand(m[2].strip, line_number)
+        elsif (m = FIELD_LINE.match(line))
+          @fields[m[1]] = expand(m[2].strip, line_number) if KNOWN_FIELDS.include?(m[1])
+        else
+          raise ParseError.new("unrecognized line: #{line.inspect}", path: @path, line_number: line_number)
+        end
+      end
+
+      # Variables are expanded at the point they are assigned, against
+      # whatever variables are already known — the same order the real
+      # fixtures rely on (prefix, then exec_prefix=${prefix}, then
+      # libdir=${exec_prefix}/lib, ...). Fields are expanded the same way,
+      # against the full variable table (fields conventionally follow all
+      # variable assignments in a .pc file).
+      def expand(value, line_number)
+        value.gsub(VARIABLE_REFERENCE) do
+          name = Regexp.last_match(1)
+          @variables.fetch(name) do
+            raise ParseError.new("undefined variable '#{name}'", path: @path, line_number: line_number)
+          end
+        end
+      end
+
+      def build_package
+        Package.new(
+          name: @fields["Name"],
+          description: @fields["Description"],
+          version: @fields["Version"],
+          requires: parse_requires(@fields["Requires"]),
+          requires_private: parse_requires(@fields["Requires.private"]),
+          cflags: @fields["Cflags"] || "",
+          libs: @fields["Libs"] || "",
+          libs_private: @fields["Libs.private"] || "",
+          path: @path
+        )
+      end
+
+      # A bare module-name list ("libssl libcrypto" or "libssl, libcrypto").
+      # A version comparison attached to an entry is diagnosed rather than
+      # evaluated: mkmf's pkg_config(pkg, *options) always passes `pkg` as a
+      # bare module name (see the Step 59 report), so this shim only needs to
+      # resolve Requires by name.
+      def parse_requires(value)
+        return [] if value.nil? || value.strip.empty?
+
+        spaced = value.gsub(/(<=|>=|==|!=|<|>|=)/) { " #{Regexp.last_match(1)} " }
+        tokens = spaced.split(/[,\s]+/).reject(&:empty?)
+        tokens.each do |token|
+          next unless REQUIRES_OPERATOR.match?(token)
+
+          raise UnsupportedError,
+                "version-constrained Requires (#{value.inspect}) is unsupported: mkmf's pkg_config() " \
+                "never passes a version constraint, so only bare module names in Requires are handled"
+        end
+        tokens
+      end
+    end
+  end
+end