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