Comprehensive Guide to Resolving "pkg-config script could not be found" Error on macOS

Problem Background and Error Analysis

When compiling and installing software on macOS systems, developers frequently encounter a common configuration error: configure: error: The pkg-config script could not be found or is too old. This error typically occurs when running ./configure scripts, indicating that the system cannot locate the pkg-config tool or the existing version is outdated.

pkg-config is a widely used tool in Unix-like systems designed to query compilation and linking parameters for installed libraries. When build toolchains require specific library support, pkg-config provides correct header file paths and linking library information. In macOS environments, where the system-provided toolchain may be incomplete, developers often need to manually install these fundamental development tools.

Source Code Compilation Installation Method

Based on practical experience, installation via source code compilation proves to be the most reliable solution. This approach ensures obtaining the latest version while maintaining full compatibility with the current system environment.

First, download the pkg-config source package. Use the curl command to fetch it from the official repository:

curl https://pkgconfig.freedesktop.org/releases/pkg-config-0.29.tar.gz -o pkgconfig.tgz

After downloading, extract the source package and navigate to the extraction directory:

tar -zxf pkgconfig.tgz && cd pkg-config-0.29

Proceed with the configuration and compilation installation process:

./configure && make install

This installation process places pkg-config in the system's standard path, typically /usr/local/bin. Once completed, the system should automatically recognize the tool.

Environment Variable Configuration Principles

If issues persist after installation, checking the PATH environment variable configuration may be necessary. The PATH environment variable determines which directories the system searches for executable files.

In macOS, temporarily add a path using the following command:

export PATH=$PATH:/usr/local/bin

To make this configuration permanent, add the above command to the shell configuration file, such as ~/.bash_profile or ~/.zshrc (depending on the shell being used).

An alternative solution involves setting the PKG_CONFIG environment variable to directly specify the full path to pkg-config:

export PKG_CONFIG=/usr/local/bin/pkg-config

Alternative Installation Methods Comparison

Besides source code compilation installation, consider using package managers for installation. Homebrew stands as the most popular package manager on macOS:

brew install pkg-config

Homebrew automatically handles dependency resolution and path configuration, simplifying the installation process. This method suits developers seeking quick problem resolution.

For other Linux distributions, installation commands differ: Ubuntu/Debian systems use apt-get install -y pkg-config, Redhat/Yum systems use yum install -y pkgconfig, and Archlinux systems use pacman -S pkgconf.

Verification and Troubleshooting

After installation, verify that pkg-config functions correctly. Run the following command to check version information:

pkg-config --version

If the command returns a version number, installation succeeded. Additionally, test pkg-config's ability to query specific libraries:

pkg-config --cflags --libs glib-2.0

If encountering permission issues, using sudo during installation may be necessary. For source code compilation installation, ensure the system has essential development tools installed, such as Xcode Command Line Tools.

Advanced Configuration Options

In specific scenarios, configuring pkg-config's search paths might be required. pkg-config defaults to searching for .pc files in directories like /usr/lib/pkgconfig and /usr/share/pkgconfig. Add custom search paths by setting the PKG_CONFIG_PATH environment variable:

export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/custom/path/pkgconfig

For particular compilation scenarios, directly setting relevant environment variables to bypass pkg-config remains possible, as mentioned in the error message with variables like XMEDCON_GLIB_CFLAGS and XMEDCON_GLIB_LIBS. While feasible, this approach lacks flexibility and isn't recommended as a long-term solution.

Summary and Best Practices

Resolving pkg-config-related issues requires a systematic approach. Developers should: first attempt installation via package managers, resorting to source code compilation if necessary; ensure correct PATH environment variable configuration; understand pkg-config working principles and configuration options. Maintaining good development environment management habits effectively prevents similar issues and enhances development efficiency.