1Module::Build::Using::PUksgeCronCfoingt(r3i)buted Perl DMoocduumleen:t:aBtuiiolnd::Using::PkgConfig(3)
2
6 "Module::Build::Using::PkgConfig" - extend "Module::Build" to more
7 easily use platform libraries provided by pkg-config
8
10 In Build.PL:
11 use Module::Build::Using::PkgConfig;
13 my $build = Module::Build::Using::PkgConfig->new(
15 module_name => "Module::Here",
16 ... # other arguments as per Module::Build
17 );
18 # A platform library provided by pkg-config
20 $build->use_pkgconfig( "libfoo" );
21 # We need at least a given version
23 $build->use_pkgconfig( "libbar",
24 atleast_version => "0.5",
25 );
26 # 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 $build->create_build_script;
35
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 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 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
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
61 use_pkgconfig
62 $build->use_pkgconfig( $modname, ... )
63 Requires the given pkg-config module of the given version, and extends
65 the compiler and linker arguments sufficient to build from it.
66 Takes the following named options:
68 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 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 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 no_late_alien => BOOL
83 If true, suppresses the dynamic "requires" feature of Alien modules
84 described above.
85 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 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 try_pkconfig
97 $ok = $build->try_pkconfig( $modname, ... )
98 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 pkgconfig_atleast_version
104 $ok = $build->pkgconfig_atleast_version( $modname, $modver )
105 Returns true if the pkg-config module name exists and has at least the
107 given version.
108 add_cflags_libs_from_pkgconfig
110 $build->add_cflags_libs_from_pkgconfig( $modname )
111 Extend the "extra_compiler_flags" and "extra_linker_flags" arguments
113 from the "--cflags" and "--libs" from the given pkg-config module name.
114 alien_atleast_version
116 $ok = $build->alien_atleast_version( $alien, $modver )
117 Returns true if the given "Alien::" module provides a pkg-config module
119 version at least the given version.
120 add_cflags_libs_from_alien
122 $build->add_cflags_libs_from_alien( $alien )
123 Extend the "extra_compiler_flags" and "extra_linker_flags" arguments
125 from the "--cflags" and "--libs" from the given "Alien::" module name.
126 use_late_alien
128 $ok = $build->use_late_alien( $alien, ... )
129 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 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 push_extra_compiler_flags
140 $build->push_extra_compiler_flags( @flags )
141 Appends more values onto the "extra_compiler_flags".
143 push_extra_linker_flags
145 $build->push_extra_linker_flags( @flags )
146 Appends more values onto the "extra_linker_flags".
148
150 • Consider a "quiet" option to suppress verbose printing
151 • Consider defining a constructor argument, perhaps
153 "build_requires_pkgconfig", to neaten the common case of simple
154 requirements.
155 • 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
161 Paul Evans <leonerd@leonerd.org.uk>
162perl v5.34.0 2021-07-22Module::Build::Using::PkgConfig(3)