PPKG-CONFIG(1p)

📦
version 0.26026 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💅 PPKG-CONFIG 💅

okay bestie, you've landed on the 1p manual page and honestly? iconic. grab a boba, we're getting into it. 🧋✨

🌸 NAME 🌸

PkgConfig — a Pure-Perl, Core-Only replacement for pkg-config. no cap, it literally just does the thing without dragging glib along for the ride. 💖

🦋 SYNOPSIS 🦋

✨ As a replacement for pkg-config

$ ppkg-config --libs --cflags --static gio-2.0

#outputs (lines artificially broken up for readability):
# -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
# -pthread -lgio-2.0 -lz -lresolv -lgobject-2.0
# -lgmodule-2.0 -ldl -lgthread-2.0 -pthread -lrt -lglib-2.0

so pkg-config.pl can be used as an alias for ppkg-config on platforms that support it. it can also be installed as pkg-config, but like… don't, bestie, not recommended if your system already has a native pkg-config. 🙈

now compare that to the O.G.:

$ pkg-config --libs --cflags --static gio-2.0

#outputs ( "" ):
# -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
# -pthread -lgio-2.0 -lz -lresolv -lgobject-2.0 -lgmodule-2.0
# -ldl -lgthread-2.0 -lrt -lglib-2.0

🌈 From another Perl module

use PkgConfig;

my $o = PkgConfig->find('gio');
if($o->errmsg) {
    #handle error
} else {
    my $prefix = $o->get_var('prefix');
    my @cflags = $o->get_cflags;
    my @ldflags = $o->get_ldflags;
}

👑 DESCRIPTION 👑

PkgConfig provides a pure-perl, core-only replacement for the pkg-config utility. periodt.

important vibe check though: this is not a description of what pkg-config is even for. it's a description of the differences between the C version and the Perl one. so if you came here looking for "what does pkg-config do," wrong page bestie, but you're still welcome. 💜

so while pkg-config is a compiled binary linked with glib, the pure-perl version has no such requirement, and will run wherever Perl ( >= 5.6 ) does. slay.

the main supported options are the common ones you'd actually use: --libs, --cflags, --static, --exists and --modversion. the greatest hits, fr fr. 🔥

🎀 SCRIPT OPTIONS 🎀

USAGE

<packagename1 pkgname2..> [ --options ]

ARGUMENTS

by default, a library name must be supplied — unless one of --version or --real-version is specified. so like, either give it a package or give it a version flag, it's not gonna guess. 😭

the output should normally be suitable for passing to your favorite compiler. yes, your favorite. we don't judge here. 💅

  • --libs — (also) print linker flags. Dependencies are traversed in order, and top-level dependencies will show up earlier in the command line than bottom-level dependencies. so the order is giving organized, we love to see it.
  • --libs-only-L — prints just the -L/-R part of --libs. it defines the library search path but without the libraries to link with. it's giving "here's the neighborhood, not the house." 🏘️
  • --libs-only-l — prints the -l part of --libs. (that's lowercase l, don't get it twisted with the one above. 👀)
  • --libs-only-other — prints the part of --libs not covered by --libs-only-L and --libs-only-l, such as --pthread. the leftovers, but make it useful.
  • --list-all — list all known packages. a whole catalog, bestie. 📚
  • --cflags — (also) print compiler and C preprocessor flags.
  • --cflags-only-I — prints the -I part of --cflags. include paths only, no extras.
  • --cflags-only-other — prints the parts of --cflags not covered by --cflags-only-I. the "everything else" bucket. 🪣
  • --modversion — print the version of a given package. just the number, ma'am.
  • --static — use extra dependencies and libraries if you're linking against a static version of the requested library. static linking era, we're committed. 🔒
  • --exists — return success (0) if the package exists in the search path. the quiet "does this even exist" check.
  • --with-path=PATH — prepend PATH to the list of search paths containing .pc files. and yes, this option can be specified multiple times with different paths, and they'll all be added. stacking paths like it's a fit check. ✨
  • --env-only — using this option, only paths specified in PKG_CONFIG_PATH are recognized, and any hard-coded defaults are ignored. strict mode, basically.
  • --guess-paths — invoke gcc and ld to determine default linker and include paths. default paths will then be excluded from explicit -L and -I flags. it's giving detective energy. 🔍
  • --define-variable=VARIABLE=VALUE — define a variable, overriding any such variable definition in the .pc file, and allowing your value to interpolate with subsequent uses. you're the author now. ✍️
  • --variable=VARIABLE — this returns the value of a variable defined in a package's .pc file. just ask, it'll tell you. 🫶
  • --print-variables — print all defined variables found in the .pc files. the whole variable roster, no secrets.
  • --version — the target version of pkg-config emulated by this script. (emulated, bestie. we're doing an impression.)
  • --real-version — the actual version of this script. the real one, no filter. 💯
  • --debug — print debugging information. for when you need the lore. 🔎
  • --silence-errors — turn off errors. this is the default for non-libs/cflag/modversion arguments. shhh. 🤫
  • --print-errors — print errors to STDERR, and takes precedence over --silence-errors. so if both are on, this one wins. periodt.
  • --short-errors — ignored, but recognized for compatibility. it's there, it's just not doing anything. an icon that simply exists. 💀
  • --errors-to-stdout — print errors to STDOUT, and takes precedence over --print-errors. the final boss of error destinations. 👑

🌱 ENVIRONMENT 🌱

the PKG_CONFIG_PATH and PKG_CONFIG_LIBDIR variables are honored and used as a colon-delimited (semicolon-delimited on Windows) list of directories that contain .pc files.

other environment variables recognized by both pkg-config and PkgConfig include:

  • PKG_CONFIG_ALLOW_SYSTEM_CFLAGS
  • PKG_CONFIG_ALLOW_SYSTEM_LIBS

if Win32API::Registry is installed, on Windows (but not Cygwin) PkgConfig will also consult these registry keys. the names are ignored, but the values are paths containing .pc files.

  • HKEY_CURRENT_USER\Software\pkgconfig\PKG_CONFIG_PATH
  • HKEY_LOCAL_MACHINE\Software\pkgconfig\PKG_CONFIG_PATH
⚠️ registry support should be considered somewhat experimental, subject to change in the future — though not without good reason. the rationale for this caveat is that this feature is documented in several places, but the author has yet to find a working version that actually implements this feature. so like… it's real in the docs, bestie. 🫠

🧚 MODULE OPTIONS 🧚

✨ PkgConfig->find

my $result = PkgConfig->find($library, %options);

find a library and return a result object. $library can be either a single name of a library, or a reference to an array of library names. flexible, we love her. 💅

the options are in the form of hash keys and values, and the following are recognized:

  • search_path, search_path_override — prepend search paths in addition to the paths specified in $ENV{PKG_CONFIG_PATH}. the value is an array reference. the _override variant ignores defaults (like PKG_CONFIG_PATH).
  • file_path — specifies the full path of the .pc file that you wish to load. it does not need to be in the search path (although any dependencies will need to be). useful if you already know the full path of the exact .pc file that you want. no searching required, you already found it. 🎯
  • exclude_cflags, exclude_ldflags, exclude_cflags_override, exclude_ldflags_override — some .pc files specify default compiler and linker search paths, e.g. -I/usr/include -L/usr/lib. specifying them on the command line can be problematic because it drastically changes the search order. 😭 the above options will either append or replace the options which are excluded and filtered. the default excluded linker and compiler options can be obtained via @PkgConfig::DEFAULT_EXCLUDE_LFLAGS and @PkgConfig::DEFAULT_EXCLUDE_CFLAGS, respectively.
  • static — also specify static libraries.
  • no_recurse — do not recurse dependencies. this is useful for just doing version checks. low effort, high reward. ✨
  • VARS — define a hashref of variables to override any variable definitions within the .pc files. this is equivalent to the --define-variable command-line option.

a PkgConfig object is returned and may be queried about the results:

  • $o->errmsg — an error message, if any. this is a string and indicates an error. if it's here, something went sideways. 😬
  • $o->pkg_exists — boolean value, true if the package exists. just a yes/no vibe.
  • $o->pkg_version — the version of the package.
  • $o->get_cflags, $o->get_ldflags — returns compiler and linker flags, respectively.
    • in list context, these methods return a list with each argument split on unescaped spaces.
    • in list context returns a list of compiler and linker flags, respectively.
    • in scalar context returns a string of compiler and linker flags with spaces and quotes escaped correctly.
  • $o->get_var($name) — get the variable with the given name.

🌟 PkgConfig->Guess

this is a class method, and will replace the hard-coded default linker and include paths with those discovered by invoking ld(1) and cpp(1).

currently this only works with GCC-supplied ld and GNU ld. so if that's not your setup… yeah. 🙈

🛠️ INSTALL 🛠️

the Makefile.PL that comes with PkgConfig can take one or more --script options to change the name of the script (or scripts) that are installed. pick your fighter. 🥊

  • --script ppkg-config — this is the default and works on all platforms. the safe, universal choice. 🌍
  • --script pkg-config.pl — this is installed by default on all platforms except for Windows, where the .pl may confuse the shell and cause the script to be opened in a text editor. (imagine trying to run something and it just opens Notepad. 😭)
  • --script pkg-config — this is the default name of the real pkg-config, and so you have to specifically enable it if you want it. opt-in only, bestie.
  • --script none — don't install any scripts. minimalism. 🍃

example, install all script names:

% perl Makefile.PL --script ppkg-config --script pkg-config.pl --script pkg-config

example, don't install any scripts:

% perl Makefile.PL --script none

you can also set the environment variable PERL_PKG_CONFIG_SCRIPTS to the desired --script value (separating each script name with a comma ,) to ensure that upgrades of PkgConfig do the same. set it once, and future-you says thank you. 💖

🌸 CAVEATS 🌸

on Strawberry Perl, ppkg-config acts like Strawberry is the system. so basically:

  • the .pc files that are bundled with Strawberry are searched by default.
  • the Strawberry include and lib directories are used to compute the exclusion lists.

as of Strawberry 5.20.0.1, PkgConfig is bundled with Strawberry and pkg-config is installed by default (in addition to ppkg-config — though the ppkg-config alias is NOT bundled with Strawberry itself). read that twice, bestie, it matters. 👀

for details on how to patch the .pc files bundled with older Strawberries, see the README.win32 that comes with this Distribution.

💀 BUGS 💀

the order of the flags is not exactly matching that of pkg-config. from the author's own observation, it seems this module does a better job, but they might be wrong. humble queen behavior honestly. 👑

unlike pkg-config, the script's --exists function will return nonzero if a package or any of its dependencies are missing. this differs from the behavior of pkg-config, which will just check for the definition of the package itself (without dependencies). so yeah, --exists here is doing extra work. overachiever energy. 💅

✨ SEE ALSO ✨

okay bestie, here's the whole squad of other implementations and friends 💖 go look at them if you're nosy (respectfully):

👑 AUTHOR 👑

the credits, because we give credit around here:

  • Original Author: M. Nunberg
  • Current maintainer: Graham Ollis <plicease@cpan.org>

Other contributors include, and we are obsessed with every single one of them:

  • Vladimir Timofeev (vovkasm)
  • kmx
  • Sanel Zukan
  • Breno G. de Oliveira (garu)
  • Gregor Herrmann
  • Ilya Pavlov (ILUX, Ilya33)
  • Shawn Laffan (SLAFFAN, shawnlaffan)
  • Ari Jolma (AJOLMA)

no cap, that's a stacked roster 🌸🫶

Copyright (C) 2012 M. Nunberg

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, go off, remix it, share it, whatever — just keep it under those same terms, periodt 💜

and that's the whole page bestie!! you read all of it, main character behavior fr fr 😭💖

this lil edition is from perl v5.40.1, dated 2025-04-17, and it's the PPKG-CONFIG(1p) manual — mwah, go forth and pkg-config responsibly 💅✨🌈

📦 where this page comes from