Module...gConfig(3pm)

💖 NAME 💖

Bestie, welcome to the User Contributed Perl Documentation page for Module::Build::Using::PkgConfig (3pm). Its whole NAME-section flex is this: extend Module::Build to more easily use platform libraries provided by pkg-config. Periodt. 💅

🦋 SYNOPSIS 🦋

In Build.PL, the setup is giving exactly this energy:

          use Module::Build::Using::PkgConfig;

          my $build = Module::Build::Using::PkgConfig->new(
             module_name => "Module::Here",
             ... # other arguments as per Module::Build
          );

          # A platform library provided by pkg-config
          $build->use_pkgconfig( "libfoo" );

          # We need at least a given version
          $build->use_pkgconfig( "libbar",
             atleast_version => "0.5",
          );

          # A platform librariy that's also wrapped as an Alien module
          $build->use_pkgconfig( "libsplot",
             atleast_version => "1.0",
             alien           => "Alien::libsplot",
             alien_version   => "0.05", # Alien::libsplot 0.05 provides libsplot v1.0
          );

          $build->create_build_script;

🌸 DESCRIPTION 🌸

This subclass of Module::Build provides some handy methods to assist the Build.PL script of XS-based module distributions that make use of platform libraries managed by pkg-config.

As well as supporting libraries installed on a platform-wide basis and thus visible to pkg-config itself, this subclass also assists with Alien::-based wrappers of these system libraries, allowing them to be dynamically installed at build time if the platform does not provide them.

🛠️ RPATH generation 🛠️

This module also provides some helper code to generate the required RPATH arguments needed to link against the libraries found by inspecting the extra_linker_flags. This attempts to duplicate the same logic performed by libtool when it would link a C program or library, as we don't get to use its code when linking dynamic libraries for Perl.

🎀 PROPERTIES 🎀

• no_late_aliens => BOOL — If true, applies the no_late_alien option to every use of use_pkgconfig that specifies an Alien module.

✨ METHODS ✨

💅 use_pkgconfig

$build->use_pkgconfig( $modname, ... )

Requires the given pkg-config module of the given version, and extends the compiler and linker arguments sufficient to build from it.

Takes the following named options:

• atleast_version => $modver — If given, the pkg-config module is required to be at least the given version. If unspecified, then any version is considered sufficient.
• alien => $alien — If given and the pkg-config module does not exist, try to use the given Alien:: module to provide it instead.

If this module is not yet available and the no_late_alien option is not true, the Alien module is added to the requires dynamic dependencies and checked again at build action time.

• no_late_alien => BOOL — If true, suppresses the dynamic requires feature of Alien modules described above.
• alien_version => $version — If the Alien:: module is not available, gives the module version of it that will be required to provide the pkg-config module of the required version. This gets added to requires.

If neither the pkg-config module nor an Alien:: module was requested — or none was found and no_late_alien was set — this method dies with an OS unsupported message, which is usually what is required for a Build.PL script.

🦋 try_pkconfig

$ok = $build->try_pkconfig( $modname, ... )

Boolean-returning version of use_pkgconfig. If successful, returns true. If it fails it returns false rather than dying, allowing the Build.PL script to take alternative action.

🔍 pkgconfig_atleast_version

$ok = $build->pkgconfig_atleast_version( $modname, $modver )

Returns true if the pkg-config module name exists and has at least the given version.

🧚 add_cflags_libs_from_pkgconfig

$build->add_cflags_libs_from_pkgconfig( $modname )

Extend the extra_compiler_flags and extra_linker_flags arguments from the --cflags and --libs from the given pkg-config module name.

🧁 alien_atleast_version

$ok = $build->alien_atleast_version( $alien, $modver )

Returns true if the given Alien:: module provides a pkg-config module version at least the given version.

🍓 add_cflags_libs_from_alien

$build->add_cflags_libs_from_alien( $alien )

Extend the extra_compiler_flags and extra_linker_flags arguments from the --cflags and --libs from the given Alien:: module name.

🌈 use_late_alien

$ok = $build->use_late_alien( $alien, ... )

Adds an Alien module directly to the requires hash, and makes a note to use its cflags and libraries later at build time.

Normally this method would not be necessary as it is automatically called from use_pkgconfig if required, but one use-case may be to provide a final last-ditch attempt after trying some other possible attempts, after an earlier call to use_pkgconfig with no_late_alien set.

💜 push_extra_compiler_flags

$build->push_extra_compiler_flags( @flags )

Appends more values onto the extra_compiler_flags.

💎 push_extra_linker_flags

$build->push_extra_linker_flags( @flags )

Appends more values onto the extra_linker_flags.

🌟 TODO 🌟

• Consider a quiet option to suppress verbose printing
• Consider defining a constructor argument, perhaps build_requires_pkgconfig, to neaten the common case of simple requirements.
• Consider further stealing the various helper methods from ExtUtils::CChecker and possibly splitting this class into a lower C-using XS modules and higher-level pkg-config+Alien layer.

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

💖 Cute sign-off time: this page is from perl v5.42.0, dated 2020-11-23, and it's the Module...gConfig(3pm) page. Stay slaying, bestie! 💖