Precompiled Ruby bakes the build machine's PKG_CONFIG into rbconfig.rb, breaking native gems that use mkmf's pkg_config eg. ruby-magic

[jaredlt]

Summary

Precompiled rubies from jdx/ruby ship an rbconfig.rb whose PKG_CONFIG entry points at the
bootstrap pkgconf inside the GitHub Actions build tree:

$ ruby -rrbconfig -e 'p RbConfig::CONFIG["PKG_CONFIG"], RbConfig::MAKEFILE_CONFIG["PKG_CONFIG"]'
"/Users/runner/work/ruby/ruby/.build/4.0.5-macos-yjit/tools/bin/pkgconf"
"/Users/runner/work/ruby/ruby/.build/4.0.5-macos-yjit/tools/bin/pkgconf"

That path does not exist on an end-user machine. Any gem whose extconf.rb calls mkmf's pkg_config therefore fails to configure with a misleading failure message (even when pkg-config is installed and on PATH).

Environment

• Ruby 4.0.5 (arm64-darwin23), installed by mise with ruby.compile = false
• macOS 15 (Apple Silicon)
• pkgconf 2.x installed via Homebrew at /opt/homebrew/bin/pkg-config

Reproduction

$ which pkg-config
/opt/homebrew/bin/pkg-config

$ gem install ruby-magic -v 0.6.0
...
checking for pkg-config for .../ports/arm64-apple-darwin23/libmagic/5.44/lib/pkgconfig/libmagic.pc... not found
extconf.rb:322:in '<main>': Please install the `pkg-config` utility! (RuntimeError)

Note that pkg-config is installed, and it handles the .pc file without complaint:

$ pkg-config --exists .../libmagic/5.44/lib/pkgconfig/libmagic.pc; echo $?
0

ruby-magic's error text is its own (it turns a nil return from pkg_config into "please install
pkg-config"), so the wording is confusing.

Root cause

jdx/ruby configures Ruby with PKG_CONFIG set to a bootstrap pkgconf living inside the CI build tree, and configure bakes that absolute path into the shipped rbconfig.rb. Its patch_rbconfig step rewrites the other build-machine leakage (compiler names, -I/-L flags, PKG_CONFIG_PATH) but never touches PKG_CONFIG, so every downloaded Ruby points at a directory that only ever existed on a GitHub Actions runner. mkmf reads that value ahead of both ENV["PKG_CONFIG"] and pkg-config on PATH, and because the broken value is non-empty it short-circuits those fallbacks rather than deferring to them, so pkg_config returns nil for every package and gems like ruby-magic die claiming pkg-config isn't installed.

Too much detail

libexec/package.rb injects the bootstrap pkgconf into the environment when Ruby is configured:

def build_env(extra = {})
  {
    "PATH" => [File.join(@tools_prefix, "bin"), ENV["PATH"]].compact.join(File::PATH_SEPARATOR),
    "PKG_CONFIG" => pkgconf,
    "MAKEFLAGS" => "-j#{jobs}"
  }.merge(extra.reject { |_key, value| value.to_s.empty? })
end

Ruby's configure records that absolute path into rbconfig.rb. Neither patch_rbconfig nor
rbconfig_portability_patch rewrites it afterwards. Both already do exactly this kind of
sanitization for other keys — patch_rbconfig scrubs -I/-L/-B/-Wl,-rpath-link= flags
containing @build_root and normalizes CC/CXX/AR/NM/RANLIB, and the portability patch
rewrites CC/CPP/CXX/LDSHARED across both CONFIG and MAKEFILE_CONFIG, and prepends the
portable pkgconfig dir to PKG_CONFIG_PATH (added in #7457). PKG_CONFIG itself was
simply missed.

It's fatal rather than degraded because mkmf.rb (Ruby 4.0.5, line 1968):

if pkgconfig = with_config("#{pkg}-config") and find_executable0(pkgconfig)
elsif ($PKGCONFIG ||=
       (pkgconfig = with_config("pkg-config") {config_string("PKG_CONFIG") || ENV["PKG_CONFIG"] || "pkg-config"}) &&
       find_executable0(pkgconfig) && pkgconfig) and
     xsystem([*envs, $PKGCONFIG, "--exists", pkg])

config_string("PKG_CONFIG") returns the stale path first. Because the || chain sits inside
the assignment, a non-empty-but-broken value short-circuits it: find_executable0 then fails, the
whole expression evaluates to nil, and neither ENV["PKG_CONFIG"] nor the "pkg-config" PATH
default is ever consulted. pkg_config returns nil for every package.

Note this also makes the ENV["PKG_CONFIG"] escape hatch unreachable. Users cannot work around it
by exporting PKG_CONFIG.

Also worth knowing: mkmf's CONFIG is RbConfig::MAKEFILE_CONFIG (mkmf.rb:78), not
RbConfig::CONFIG, so a fix must patch both hashes. They currently both carry the bad value.

Suggested fix

In patch_rbconfig (and/or rbconfig_portability_patch), blank the entry in both hashes so mkmf's
own fallback chain takes over:

[CONFIG, MAKEFILE_CONFIG].each do |config|
  config["PKG_CONFIG"] = ""
end

config_string treats an empty string as absent (s = config[key] and !s.empty? and ...), so this
restores both the ENV["PKG_CONFIG"] override and the "pkg-config"-on-PATH default. Verified
locally:

$ ruby -rmkmf -e 'RbConfig::MAKEFILE_CONFIG["PKG_CONFIG"] = ""
                  p(config_string("PKG_CONFIG") || ENV["PKG_CONFIG"] || "pkg-config")'
"pkg-config"

Hard-coding "pkg-config" instead would also fix the build, but keeps the ENV override shadowed.
Shipping a pkgconf binary inside the Ruby prefix and pointing at it relatively would work too,
though none is shipped today.

Workaround for anyone hitting this now

$ bundle config set --local build.ruby-magic "--with-pkg-config=$(which pkg-config)"

--with-pkg-config is read by with_config before config_string, so it wins.

[jdx]

Thanks for the exceptionally detailed report. This was exactly the root cause.

The fix landed in jdx/ruby#55: the portability patch now removes PKG_CONFIG from both RbConfig::CONFIG and RbConfig::MAKEFILE_CONFIG, allowing mkmf to honor ENV["PKG_CONFIG"] or find pkg-config on PATH.

I rebuilt the current supported patch releases from the fixed commit:

• Ruby 3.2.11-6
• Ruby 3.3.11-5
• Ruby 3.4.10-2
• Ruby 4.0.5-3

The floating release tags now point at those fixed builds. I also tested the published macOS 4.0.5 artifact through mise with ruby.compile = false: both PKG_CONFIG keys were absent, ruby-magic 0.6.0 built successfully using Homebrew pkg-config, and its native extension loaded correctly.

Anyone with an already-installed affected Ruby will need to uninstall and reinstall that version to pick up the rebuilt artifact.

Historical patch releases have not been rebuilt yet.

This comment was generated by an AI coding assistant.