File Coverage

blib/lib/PkgConfig/LibPkgConf.pm

Criterion	Covered	Total	%
statement	28	28	100.0
branch	2	2	100.0
condition			n/a
subroutine	10	10	100.0
pod	6	6	100.0
total	46	46	100.0

package PkgConfig::LibPkgConf;

use strict;
use warnings;
use base qw( Exporter );

our $VERSION = '0.10';
our @EXPORT = qw(
  pkgconf_cflags
  pkgconf_libs
  pkgconf_exists
  pkgconf_version
  pkgconf_cflags_static
  pkgconf_libs_static
);

=head1 NAME

PkgConfig::LibPkgConf - Interface to .pc file interface via libpkgconf

=head1 SYNOPSIS

 use PkgConfig::LibPkgConf;

 if(pkgconf_exists('libarchive'))
 {
   my $version = pkgconf_version('libarchive');
   my $cflags  = pkgconf_cflags('libarchive');
   my $libs    = pkgconf_libs('libarchive');
 }

=head1 DESCRIPTION

Many libraries in compiled languages such as C or C++ provide C<.pc>
files to specify the flags required for compiling and linking against
those libraries.  Traditionally, the command line program C
is used to query these files.  This module provides a Perl level API
using C to these files.

This module provides a simplified interface for getting the existence,
version, cflags and library flags needed for compiling against a package,
using the default compiled in configuration of C.  For a more
powerful, but complicated interface see L.
In addition, L provides some useful utility
functions that are also provided by C.

=head1 FUNCTIONS

=head2 pkgconf_exists

 my $bool = pkgconf_exists $package_name;

Returns true if the package is available.

Exported by default.

=cut

sub pkgconf_exists
{
  my $pkg = eval { _pkg($_[0]) };
  return defined $pkg;
}

=head2 pkgconf_version

 my $version = pkgconf_version $package_name;

Returns the version of the package, if it exists.  Will throw an exception
if not found.

Exported by default.

=cut

sub pkgconf_version
{
  my $pkg = _pkg($_[0]);
  $pkg->version;
}

=head2 pkgconf_cflags

 my $cflags = pkgconf_cflags $package_name;

Returns the compiler flags for the package, if it exists.  Will throw an
exception if not found.

Exported by default.

=cut

sub pkgconf_cflags
{
  my $pkg = _pkg($_[0]);
  $pkg->cflags;
}

=head2 pkgconf_cflags_static

 my $cflags = pkgconf_cflags_static $package_name;

Returns the static compiler flags for the package, if it exists.  Will throw
an exception if not found.

=cut

sub pkgconf_cflags_static
{
  my $pkg = _pkg($_[0]);
  $pkg->cflags_static;
}

=head2 pkgconf_libs

 my $libs = pkgconf_libs $package_name;

Returns the linker library flags for the package, if it exists.  Will throw
an exception if not found.

Exported by default.

=cut

sub pkgconf_libs
{
  my $pkg = _pkg($_[0]);
  $pkg->libs;
}

=head2 pkgconf_libs_static

 my $libs = pkgconf_libs_static $package_name;

Returns the static linker library flags for the package, if it exists.  Will
throw an exception if not found.

=cut

sub pkgconf_libs_static
{
  my $pkg = _pkg($_[0]);
  $DB::single = 1;
  $pkg->libs_static;
}

sub _pkg
{
  my($name) = @_;
  require PkgConfig::LibPkgConf::Client;
  my $pkg = PkgConfig::LibPkgConf::Client->new->find($name);
  die "package $name not found" unless $pkg;
  $pkg;
}

1;

=head1 SUPPORT

IRC #native on irc.perl.org

Project GitHub tracker:

L

If you want to contribute, please open a pull request on GitHub:

L

=head1 SEE ALSO

The best entry point to the low level C interface can be found
via L.

Alternatives include:

=over 4

=item L

Pure Perl implementation of C which can be used from the
command line, or as an API from Perl.  Does not require pkg-config in
your path, so is a safe dependency for CPAN modules.

=item L

Wrapper for the C command line interface.  This module will
fail to install if C cannot be found in the C, so it
is not safe to use a dependency if you want your CPAN module to work on
platforms where C is not installed.

=item L

Provides tools for building non-Perl libraries and making them
dependencies for your CPAN modules, even on platforms where the non-Perl
libraries aren't already installed.  Includes hooks for probing
C C<.pc> files using either C or L.

=back

=head1 ACKNOWLEDGMENTS

Thanks to the C developers for their efforts:

L

=head1 AUTHOR

Graham Ollis

Contributors:

A. Wilcox (awilfox)

Petr Pisar (ppisar)

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2016 Graham Ollis.

This is free software; you may redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut