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