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 ofuse_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 therequires
dynamic dependencies and checked again atbuild
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 torequires
.
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 printingConsider 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>