Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Module::Build::Using::UseroContributed Perl Module::Build::Using::PkgConfig(3)

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
       o   Consider a "quiet" option to	suppress verbose printing

       o   Consider defining a constructor argument, perhaps
	   "build_requires_pkgconfig", to neaten the common case of simple
	   requirements.

       o   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>

perl v5.32.1			  2021-08-26Module::Build::Using::PkgConfig(3)

NAME | SYNOPSIS | DESCRIPTION | PROPERTIES | METHODS | TODO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Module::Build::Using::PkgConfig&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help