---
name: "Module::Build::Using::PkgConfig"
section: "3pm"
platform: "linux"
package: "libmodule-build-using-pkgconfig-perl"
version: "0.03-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Module::Build::Using::PkgConfig"
---

# Module::Build::Using::PkgConfig(3pm)

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

## 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\>