NAME

       "Module::Build::Using::PkgConfig" - extend "Module::Build" to more easily use platform
       libraries provided by pkg-config

SYNOPSIS

       In Build.PL:

          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 and no "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>