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>