README
1NAME
2
3 Module::Build::Using::PkgConfig - extend Module::Build to more easily
4 use platform libraries provided by pkg-config
5
6SYNOPSIS
7
8 In Build.PL:
9
10 use Module::Build::Using::PkgConfig;
11
12 my $build = Module::Build::Using::PkgConfig->new(
13 module_name => "Module::Here",
14 ... # other arguments as per Module::Build
15 );
16
17 # A platform library provided by pkg-config
18 $build->use_pkgconfig( "libfoo" );
19
20 # We need at least a given version
21 $build->use_pkgconfig( "libbar",
22 atleast_version => "0.5",
23 );
24
25 # A platform librariy that's also wrapped as an Alien module
26 $build->use_pkgconfig( "libsplot",
27 atleast_version => "1.0",
28 alien => "Alien::libsplot",
29 alien_version => "0.05", # Alien::libsplot 0.05 provides libsplot v1.0
30 );
31
32 $build->create_build_script;
33
34DESCRIPTION
35
36 This subclass of Module::Build provides some handy methods to assist
37 the Build.PL script of XS-based module distributions that make use of
38 platform libraries managed by pkg-config.
39
40 As well as supporting libraries installed on a platform-wide basis and
41 thus visible to pkg-config itself, this subclass also assists with
42 Alien::-based wrappers of these system libraries, allowing them to be
43 dynamically installed at build time if the platform does not provide
44 them.
45
46 RPATH generation
47
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 same
51 logic performed by libtool when it would link a C program or library,
52 as we don't get to use its code when linking dynamic libraries for
53 Perl.
54
55PROPERTIES
56
57 no_late_aliens => BOOL
58
59 If true, applies the no_late_alien option to every use of
60 use_pkgconfig that specifies an Alien module.
61
62METHODS
63
64 use_pkgconfig
65
66 $build->use_pkgconfig( $modname, ... )
67
68 Requires the given pkg-config module of the given version, and extends
69 the compiler and linker arguments sufficient to build from it.
70
71 Takes the following named options:
72
73 atleast_version => $modver
74
75 If given, the pkg-config module is required to be at least the given
76 version. If unspecified, then any version is considered sufficient.
77
78 alien => $alien
79
80 If given and the pkg-config module does not exist, try to use the
81 given Alien:: module to provide it instead.
82
83 If this module is not yet available and the no_late_alien option is
84 not true, the Alien module is added to the requires dynamic
85 dependencies and checked again at build action time.
86
87 no_late_alien => BOOL
88
89 If true, suppresses the dynamic requires feature of Alien modules
90 described above.
91
92 alien_version => $version
93
94 If the Alien:: module is not available, gives the module version of
95 it that will be required to provide the pkg-config module of the
96 required version. This gets added to requires.
97
98 If neither the pkg-config module and no Alien:: module was requested
99 (or none was found and no_late_alien was set), this method dies with an
100 OS unsupported message, which is usually what is required for a
101 Build.PL script.
102
103 try_pkconfig
104
105 $ok = $build->try_pkconfig( $modname, ... )
106
107 Boolean-returning version of "use_pkgconfig". If successful, returns
108 true. If it fails it returns false rather than dying, allowing the
109 Build.PL script to take alternative action.
110
111 pkgconfig_atleast_version
112
113 $ok = $build->pkgconfig_atleast_version( $modname, $modver )
114
115 Returns true if the pkg-config module name exists and has at least the
116 given version.
117
118 add_cflags_libs_from_pkgconfig
119
120 $build->add_cflags_libs_from_pkgconfig( $modname )
121
122 Extend the extra_compiler_flags and extra_linker_flags arguments from
123 the --cflags and --libs from the given pkg-config module name.
124
125 alien_atleast_version
126
127 $ok = $build->alien_atleast_version( $alien, $modver )
128
129 Returns true if the given Alien:: module provides a pkg-config module
130 version at least the given version.
131
132 add_cflags_libs_from_alien
133
134 $build->add_cflags_libs_from_alien( $alien )
135
136 Extend the extra_compiler_flags and extra_linker_flags arguments from
137 the --cflags and --libs from the given Alien:: module name.
138
139 use_late_alien
140
141 $ok = $build->use_late_alien( $alien, ... )
142
143 Adds an Alien module directly to the requires hash, and makes a note to
144 use its cflags and libraries later at build time.
145
146 Normally this method would not be necessary as it is automatically
147 called from use_pkgconfig if required, but one use-case may be to
148 provide a final last-ditch attempt after trying some other possible
149 attempts, after an earlier call to use_pkgconfig with no_late_alien
150 set.
151
152 push_extra_compiler_flags
153
154 $build->push_extra_compiler_flags( @flags )
155
156 Appends more values onto the extra_compiler_flags.
157
158 push_extra_linker_flags
159
160 $build->push_extra_linker_flags( @flags )
161
162 Appends more values onto the extra_linker_flags.
163
164TODO
165
166 * Consider a quiet option to suppress verbose printing
167
168 * Consider defining a constructor argument, perhaps
169 build_requires_pkgconfig, to neaten the common case of simple
170 requirements.
171
172 * Consider further stealing the various helper methods from
173 ExtUtils::CChecker and possibly splitting this class into a lower
174 "C-using XS modules" and higher-level pkg-config+Alien layer.
175
176AUTHOR
177
178 Paul Evans <leonerd@leonerd.org.uk>
179
180