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.29
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 assert_lib
136 assert_lib(%args);
137 This behaves exactly the same as find_lib, except that instead of
139 returning empty list of failure it throws an exception.
140 check_lib_or_exit
142 check_lib_or_exit(%args);
143 This behaves exactly the same as assert_lib, except that instead of
145 dying, it warns (with exactly the same error message) and exists. This
146 is intended for use in "Makefile.PL" or "Build.PL"
147 find_lib_or_exit
149 [version 0.05]
150 my(@libs) = find_lib_or_exit(%args);
152 This behaves exactly the same as find_lib, except that if the library
154 is not found, it will call exit with an appropriate diagnostic.
155 find_lib_or_die
157 [version 0.06]
158 my(@libs) = find_lib_or_die(%args);
160 This behaves exactly the same as find_lib, except that if the library
162 is not found, it will die with an appropriate diagnostic.
163 check_lib
165 my $bool = check_lib(%args);
166 This behaves exactly the same as find_lib, except that it returns true
168 (1) on finding the appropriate libraries or false (0) otherwise.
169 which
171 [version 0.17]
172 my $path = which($name);
174 Return the path to the first library that matches the given name.
176 Not exported by default.
178 where
180 [version 0.17]
181 my @paths = where($name);
183 Return the paths to all the libraries that match the given name.
185 Not exported by default.
187 has_symbols
189 [version 0.17]
190 my $bool = has_symbols($path, @symbol_names);
192 Returns true if all of the symbols can be found in the dynamic library
194 located at the given path. Can be useful in conjunction with "verify"
195 with "find_lib" above.
196 Not exported by default.
198 system_path
200 [version 0.20]
201 my $path = FFI::CheckLib::system_path;
203 Returns the system path as a list reference. On some systems, this is
205 "PATH" on others it might be "LD_LIBRARY_PATH" on still others it could
206 be something completely different. So although you may add items to
207 this list, you should probably do some careful consideration before you
208 do so.
209 This function is not exportable, even on request.
211
213 Why not just use "dlopen"?
214 Calling "dlopen" on a library name and then "dlclose" immediately
215 can tell you if you have the exact name of a library available on a
216 system. It does have a number of drawbacks as well.
217 No absolute or relative path
219 It only tells you that the library is somewhere on the system,
220 not having the absolute or relative path makes it harder to
221 generate useful diagnostics.
222 POSIX only
224 This doesn't work on non-POSIX systems like Microsoft Windows.
225 If you are using a POSIX emulation layer on Windows that
226 provides "dlopen", like Cygwin, there are a number of gotchas
227 there as well. Having a layer written in Perl handles this
228 means that developers on Unix can develop FFI that will more
229 likely work on these platforms without special casing them.
230 inconsistent implementations
232 Even on POSIX systems you have inconsistent implementations.
233 OpenBSD for example don't usually include symlinks for ".so"
234 files meaning you need to know the exact ".so" version.
235 non-system directories
237 By default "dlopen" only works for libraries in the system
238 paths. Most platforms have a way of configuring the search for
239 different non-system paths, but none of them are portable, and
240 are usually discouraged anyway. Alien and friends need to do
241 searches for dynamic libraries in non-system directories for
242 "share" installs.
243 My 64-bit Perl is misconfigured and has 32-bit libraries in its search
245 path. Is that a bug in FFI::CheckLib?
246 Nope.
247 The way FFI::CheckLib is implemented it won't work on AIX, HP-UX,
249 OpenVMS or Plan 9.
250 I know for a fact that it doesn't work on AIX as currently
251 implemented because I used to develop on AIX in the early 2000s,
252 and I am aware of some of the technical challenges. There are
253 probably other systems that it won't work on. I would love to add
254 support for these platforms. Realistically these platforms have a
255 tiny market share, and absent patches from users or the companies
256 that own these operating systems (patches welcome), or hardware /
257 CPU time donations, these platforms are unsupportable anyway.
258
260 FFI::Platypus
261 Call library functions dynamically without a compiler.
262 Dist::Zilla::Plugin::FFI::CheckLib
264 Dist::Zilla plugin for this module.
265
267 Author: Graham Ollis <plicease@cpan.org>
268 Contributors:
270 Bakkiaraj Murugesan (bakkiaraj)
272 Dan Book (grinnz, DBOOK)
274 Ilya Pavlov (Ilya, ILUX)
276 Shawn Laffan (SLAFFAN)
278 Petr Písař (ppisar)
280 Michael R. Davis (MRDVT)
282 Shawn Laffan (SLAFFAN)
284
286 This software is copyright (c) 2014-2018 by Graham Ollis.
287 This is free software; you can redistribute it and/or modify it under
289 the same terms as the Perl 5 programming language system itself.
290perl v5.36.0 2022-12-07 FFI::CheckLib(3)