Debian Codegraph @

README

raw
1 NAME
2
3 FFI::CheckLib - Check that a library is available for FFI
4
5 VERSION
6
7 version 0.31
8
9 SYNOPSIS
10
11 use FFI::CheckLib;
12
13 check_lib_or_exit( lib => 'jpeg', symbol => 'jinit_memory_mgr' );
14 check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] );
15
16 # or prompt for path to library and then:
17 print "where to find jpeg library: ";
18 my $path = <STDIN>;
19 check_lib_or_exit( lib => 'jpeg', libpath => $path );
20
21 DESCRIPTION
22
23 This module checks whether a particular dynamic library is available
24 for FFI to use. It is modeled heavily on Devel::CheckLib, but will find
25 dynamic libraries even when development packages are not installed. It
26 also provides a find_lib function that will return the full path to the
27 found dynamic library, which can be feed directly into FFI::Platypus or
28 another FFI system.
29
30 Although intended mainly for FFI modules via FFI::Platypus and similar,
31 this module does not actually use any FFI to do its detection and
32 probing. This module does not have any non-core runtime dependencies.
33 The test suite does depend on Test2::Suite.
34
35 FUNCTIONS
36
37 All of these take the same named parameters and are exported by
38 default.
39
40 find_lib
41
42 my(@libs) = find_lib(%args);
43
44 This will return a list of dynamic libraries, or empty list if none
45 were found.
46
47 [version 0.05]
48
49 If called in scalar context it will return the first library found.
50
51 Arguments are key value pairs with these keys:
52
53 lib
54
55 Must be either a string with the name of a single library or a
56 reference to an array of strings of library names. Depending on your
57 platform, CheckLib will prepend lib or append .dll or .so when
58 searching.
59
60 [version 0.11]
61
62 As a special case, if * is specified then any libs found will match.
63
64 libpath
65
66 A string or array of additional paths to search for libraries.
67
68 systempath
69
70 [version 0.11]
71
72 A string or array of system paths to search for instead of letting
73 FFI::CheckLib determine the system path. You can set this to [] in
74 order to not search any system paths.
75
76 symbol
77
78 A string or a list of symbol names that must be found.
79
80 verify
81
82 A code reference used to verify a library really is the one that you
83 want. It should take two arguments, which is the name of the library
84 and the full path to the library pathname. It should return true if
85 it is acceptable, and false otherwise. You can use this in
86 conjunction with FFI::Platypus to determine if it is going to meet
87 your needs. Example:
88
89 use FFI::CheckLib;
90 use FFI::Platypus;
91
92 my($lib) = find_lib(
93 lib => 'foo',
94 verify => sub {
95 my($name, $libpath) = @_;
96
97 my $ffi = FFI::Platypus->new;
98 $ffi->lib($libpath);
99
100 my $f = $ffi->function('foo_version', [] => 'int');
101
102 return $f->call() >= 500; # we accept version 500 or better
103 },
104 );
105
106 recursive
107
108 [version 0.11]
109
110 Recursively search for libraries in any non-system paths (those
111 provided via libpath above).
112
113 try_linker_script
114
115 [version 0.24]
116
117 Some vendors provide .so files that are linker scripts that point to
118 the real binary shared library. These linker scripts can be used by
119 gcc or clang, but are not directly usable by FFI::Platypus and
120 friends. On select platforms, this options will use the linker
121 command (ld) to attempt to resolve the real .so for non-binary files.
122 Since there is extra overhead this is off by default.
123
124 An example is libyaml on Red Hat based Linux distributions. On Debian
125 these are handled with symlinks and no trickery is required.
126
127 alien
128
129 [version 0.25]
130
131 If no libraries can be found, try the given aliens instead. The Alien
132 classes specified must provide the Alien::Base interface for dynamic
133 libraries, which is to say they should provide a method called
134 dynamic_libs that returns a list of dynamic libraries.
135
136 [version 0.28]
137
138 In 0.28 and later, if the Alien is not installed then it will be
139 ignored and this module will search in system or specified
140 directories only. This module will still throw an exception, if the
141 Alien doesn't look like a module name or if it does not provide a
142 dynamic_libs method (which is implemented by all Alien::Base
143 subclasses).
144
145 [version 0.30] [breaking change]
146
147 Starting with version 0.30, libraries provided by Aliens is preferred
148 over the system libraries. The original thinking was that you want to
149 prefer the system libraries because they are more likely to get
150 patched with regular system updates. Unfortunately, the reason a
151 module needs to install an Alien is likely because the system library
152 is not new enough, so we now prefer the Aliens instead.
153
154 assert_lib
155
156 assert_lib(%args);
157
158 This behaves exactly the same as find_lib, except that instead of
159 returning empty list of failure it throws an exception.
160
161 check_lib_or_exit
162
163 check_lib_or_exit(%args);
164
165 This behaves exactly the same as assert_lib, except that instead of
166 dying, it warns (with exactly the same error message) and exists. This
167 is intended for use in Makefile.PL or Build.PL
168
169 find_lib_or_exit
170
171 [version 0.05]
172
173 my(@libs) = find_lib_or_exit(%args);
174
175 This behaves exactly the same as find_lib, except that if the library
176 is not found, it will call exit with an appropriate diagnostic.
177
178 find_lib_or_die
179
180 [version 0.06]
181
182 my(@libs) = find_lib_or_die(%args);
183
184 This behaves exactly the same as find_lib, except that if the library
185 is not found, it will die with an appropriate diagnostic.
186
187 check_lib
188
189 my $bool = check_lib(%args);
190
191 This behaves exactly the same as find_lib, except that it returns true
192 (1) on finding the appropriate libraries or false (0) otherwise.
193
194 which
195
196 [version 0.17]
197
198 my $path = which($name);
199
200 Return the path to the first library that matches the given name.
201
202 Not exported by default.
203
204 where
205
206 [version 0.17]
207
208 my @paths = where($name);
209
210 Return the paths to all the libraries that match the given name.
211
212 Not exported by default.
213
214 has_symbols
215
216 [version 0.17]
217
218 my $bool = has_symbols($path, @symbol_names);
219
220 Returns true if all of the symbols can be found in the dynamic library
221 located at the given path. Can be useful in conjunction with verify
222 with find_lib above.
223
224 Not exported by default.
225
226 system_path
227
228 [version 0.20]
229
230 my $path = FFI::CheckLib::system_path;
231
232 Returns the system path as a list reference. On some systems, this is
233 PATH on others it might be LD_LIBRARY_PATH on still others it could be
234 something completely different. So although you may add items to this
235 list, you should probably do some careful consideration before you do
236 so.
237
238 This function is not exportable, even on request.
239
240 ENVIRONMENT
241
242 FFI::CheckLib responds to these environment variables:
243
244 FFI_CHECKLIB_PACKAGE
245
246 On macOS platforms with Homebrew <http://brew.sh> and/or MacPorts
247 <https://www.macports.org> installed, their corresponding lib paths
248 will be automatically appended to $system_path. In case of having
249 both managers installed, Homebrew will appear before.
250
251 This behaviour can be overridden using the environment variable
252 FFI_CHECKLIB_PACKAGE.
253
254 Allowed values are:
255
256 - none: Won't use either Homebrew's path nor MacPorts - homebrew:
257 Will append $(brew --prefix)/lib to the system paths - macports: Will
258 append port's default lib path
259
260 A comma separated list is also valid:
261
262 export FFI_CHECKLIB_PACKAGE=macports,homebrew
263
264 Order matters. So in this example, MacPorts' lib path appears before
265 Homebrew's path.
266
267 FFI_CHECKLIB_PATH
268
269 List of directories that will be considered by FFI::CheckLib as
270 additional "system directories". They will be searched before other
271 system directories but after libpath. The variable is colon separated
272 on Unix and semicolon separated on Windows. If you use this variable,
273 FFI_CHECKLIB_PACKAGE will be ignored.
274
275 PATH
276
277 On Windows the PATH environment variable will be used as a search
278 path for libraries.
279
280 On some operating systems LD_LIBRARY_PATH, DYLD_LIBRARY_PATH,
281 DYLD_FALLBACK_LIBRARY_PATH or others may be used as part of the search
282 for dynamic libraries and may be used (indirectly) by FFI::CheckLib as
283 well.
284
285 FAQ
286
287 Why not just use dlopen?
288
289 Calling dlopen on a library name and then dlclose immediately can
290 tell you if you have the exact name of a library available on a
291 system. It does have a number of drawbacks as well.
292
293 No absolute or relative path
294
295 It only tells you that the library is somewhere on the system, not
296 having the absolute or relative path makes it harder to generate
297 useful diagnostics.
298
299 POSIX only
300
301 This doesn't work on non-POSIX systems like Microsoft Windows. If
302 you are using a POSIX emulation layer on Windows that provides
303 dlopen, like Cygwin, there are a number of gotchas there as well.
304 Having a layer written in Perl handles this means that developers
305 on Unix can develop FFI that will more likely work on these
306 platforms without special casing them.
307
308 inconsistent implementations
309
310 Even on POSIX systems you have inconsistent implementations.
311 OpenBSD for example don't usually include symlinks for .so files
312 meaning you need to know the exact .so version.
313
314 non-system directories
315
316 By default dlopen only works for libraries in the system paths.
317 Most platforms have a way of configuring the search for different
318 non-system paths, but none of them are portable, and are usually
319 discouraged anyway. Alien and friends need to do searches for
320 dynamic libraries in non-system directories for share installs.
321
322 My 64-bit Perl is misconfigured and has 32-bit libraries in its search
323 path. Is that a bug in FFI::CheckLib?
324
325 Nope.
326
327 The way FFI::CheckLib is implemented it won't work on AIX, HP-UX,
328 OpenVMS or Plan 9.
329
330 I know for a fact that it doesn't work on AIX as currently
331 implemented because I used to develop on AIX in the early 2000s, and
332 I am aware of some of the technical challenges. There are probably
333 other systems that it won't work on. I would love to add support for
334 these platforms. Realistically these platforms have a tiny market
335 share, and absent patches from users or the companies that own these
336 operating systems (patches welcome), or hardware / CPU time
337 donations, these platforms are unsupportable anyway.
338
339 SEE ALSO
340
341 FFI::Platypus
342
343 Call library functions dynamically without a compiler.
344
345 Dist::Zilla::Plugin::FFI::CheckLib
346
347 Dist::Zilla plugin for this module.
348
349 AUTHOR
350
351 Author: Graham Ollis <[email protected]>
352
353 Contributors:
354
355 Bakkiaraj Murugesan (bakkiaraj)
356
357 Dan Book (grinnz, DBOOK)
358
359 Ilya Pavlov (Ilya, ILUX)
360
361 Shawn Laffan (SLAFFAN)
362
363 Petr Písař (ppisar)
364
365 Michael R. Davis (MRDVT)
366
367 Shawn Laffan (SLAFFAN)
368
369 Carlos D. Álvaro (cdalvaro)
370
371 COPYRIGHT AND LICENSE
372
373 This software is copyright (c) 2014-2022 by Graham Ollis.
374
375 This is free software; you can redistribute it and/or modify it under
376 the same terms as the Perl 5 programming language system itself.
377