1Module::Build::Using::PUksgeCronCfoingt(r3i)buted Perl DMoocduumleen:t:aBtuiiolnd::Using::PkgConfig(3)
2
3
4

NAME

6       "Module::Build::Using::PkgConfig" - extend "Module::Build" to more
7       easily use platform libraries provided by pkg-config
8

SYNOPSIS

10       In Build.PL:
11
12          use Module::Build::Using::PkgConfig;
13
14          my $build = Module::Build::Using::PkgConfig->new(
15             module_name => "Module::Here",
16             ... # other arguments as per Module::Build
17          );
18
19          # A platform library provided by pkg-config
20          $build->use_pkgconfig( "libfoo" );
21
22          # We need at least a given version
23          $build->use_pkgconfig( "libbar",
24             atleast_version => "0.5",
25          );
26
27          # A platform librariy that's also wrapped as an Alien module
28          $build->use_pkgconfig( "libsplot",
29             atleast_version => "1.0",
30             alien           => "Alien::libsplot",
31             alien_version   => "0.05", # Alien::libsplot 0.05 provides libsplot v1.0
32          );
33
34          $build->create_build_script;
35

DESCRIPTION

37       This subclass of Module::Build provides some handy methods to assist
38       the Build.PL script of XS-based module distributions that make use of
39       platform libraries managed by pkg-config.
40
41       As well as supporting libraries installed on a platform-wide basis and
42       thus visible to pkg-config itself, this subclass also assists with
43       "Alien::"-based wrappers of these system libraries, allowing them to be
44       dynamically installed at build time if the platform does not provide
45       them.
46
47   RPATH generation
48       This module also provides some helper code to generate the required
49       "RPATH" arguments needed to link against the libraries found by
50       inspecting the "extra_linker_flags". This attempts to duplicate the
51       same logic performed by libtool when it would link a C program or
52       library, as we don't get to use its code when linking dynamic libraries
53       for Perl.
54

PROPERTIES

56       no_late_aliens => BOOL
57           If true, applies the "no_late_alien" option to every use of
58           "use_pkgconfig" that specifies an Alien module.
59

METHODS

61   use_pkgconfig
62          $build->use_pkgconfig( $modname, ... )
63
64       Requires the given pkg-config module of the given version, and extends
65       the compiler and linker arguments sufficient to build from it.
66
67       Takes the following named options:
68
69       atleast_version => $modver
70           If given, the pkg-config module is required to be at least the
71           given version. If unspecified, then any version is considered
72           sufficient.
73
74       alien => $alien
75           If given and the pkg-config module does not exist, try to use the
76           given "Alien::" module to provide it instead.
77
78           If this module is not yet available and the "no_late_alien" option
79           is not true, the Alien module is added to the "requires" dynamic
80           dependencies and checked again at "build" action time.
81
82       no_late_alien => BOOL
83           If true, suppresses the dynamic "requires" feature of Alien modules
84           described above.
85
86       alien_version => $version
87           If the "Alien::" module is not available, gives the module version
88           of it that will be required to provide the pkg-config module of the
89           required version.  This gets added to "requires".
90
91       If neither the pkg-config module and no "Alien::" module was requested
92       (or none was found and "no_late_alien" was set), this method dies with
93       an "OS unsupported" message, which is usually what is required for a
94       Build.PL script.
95
96   try_pkconfig
97          $ok = $build->try_pkconfig( $modname, ... )
98
99       Boolean-returning version of "use_pkgconfig". If successful, returns
100       true.  If it fails it returns false rather than dying, allowing the
101       Build.PL script to take alternative action.
102
103   pkgconfig_atleast_version
104          $ok = $build->pkgconfig_atleast_version( $modname, $modver )
105
106       Returns true if the pkg-config module name exists and has at least the
107       given version.
108
109   add_cflags_libs_from_pkgconfig
110          $build->add_cflags_libs_from_pkgconfig( $modname )
111
112       Extend the "extra_compiler_flags" and "extra_linker_flags" arguments
113       from the "--cflags" and "--libs" from the given pkg-config module name.
114
115   alien_atleast_version
116          $ok = $build->alien_atleast_version( $alien, $modver )
117
118       Returns true if the given "Alien::" module provides a pkg-config module
119       version at least the given version.
120
121   add_cflags_libs_from_alien
122          $build->add_cflags_libs_from_alien( $alien )
123
124       Extend the "extra_compiler_flags" and "extra_linker_flags" arguments
125       from the "--cflags" and "--libs" from the given "Alien::" module name.
126
127   use_late_alien
128          $ok = $build->use_late_alien( $alien, ... )
129
130       Adds an Alien module directly to the "requires" hash, and makes a note
131       to use its cflags and libraries later at build time.
132
133       Normally this method would not be necessary as it is automatically
134       called from use_pkgconfig if required, but one use-case may be to
135       provide a final last-ditch attempt after trying some other possible
136       attempts, after an earlier call to "use_pkgconfig" with "no_late_alien"
137       set.
138
139   push_extra_compiler_flags
140          $build->push_extra_compiler_flags( @flags )
141
142       Appends more values onto the "extra_compiler_flags".
143
144   push_extra_linker_flags
145          $build->push_extra_linker_flags( @flags )
146
147       Appends more values onto the "extra_linker_flags".
148

TODO

150       •   Consider a "quiet" option to suppress verbose printing
151
152       •   Consider defining a constructor argument, perhaps
153           "build_requires_pkgconfig", to neaten the common case of simple
154           requirements.
155
156       •   Consider further stealing the various helper methods from
157           ExtUtils::CChecker and possibly splitting this class into a lower
158           "C-using XS modules" and higher-level pkg-config+Alien layer.
159

AUTHOR

161       Paul Evans <leonerd@leonerd.org.uk>
162
163
164
165perl v5.34.0                      2021-07-22Module::Build::Using::PkgConfig(3)
Impressum