1FFI::CheckLib(3)      User Contributed Perl Documentation     FFI::CheckLib(3)
2
3
4

NAME

6       FFI::CheckLib - Check that a library is available for FFI
7

VERSION

9       version 0.31
10

SYNOPSIS

12        use FFI::CheckLib;
13
14        check_lib_or_exit( lib => 'jpeg', symbol => 'jinit_memory_mgr' );
15        check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] );
16
17        # 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

DESCRIPTION

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

FUNCTIONS

36       All of these take the same named parameters and are exported by
37       default.
38
39   find_lib
40        my(@libs) = find_lib(%args);
41
42       This will return a list of dynamic libraries, or empty list if none
43       were found.
44
45       [version 0.05]
46
47       If called in scalar context it will return the first library found.
48
49       Arguments are key value pairs with these keys:
50
51       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
56           [version 0.11]
57
58           As a special case, if "*" is specified then any libs found will
59           match.
60
61       libpath
62           A string or array of additional paths to search for libraries.
63
64       systempath
65           [version 0.11]
66
67           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
71       symbol
72           A string or a list of symbol names that must be found.
73
74       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
82            use FFI::CheckLib;
83            use FFI::Platypus;
84
85            my($lib) = find_lib(
86              lib => 'foo',
87              verify => sub {
88                my($name, $libpath) = @_;
89
90                my $ffi = FFI::Platypus->new;
91                $ffi->lib($libpath);
92
93                my $f = $ffi->function('foo_version', [] => 'int');
94
95                return $f->call() >= 500; # we accept version 500 or better
96              },
97            );
98
99       recursive
100           [version 0.11]
101
102           Recursively search for libraries in any non-system paths (those
103           provided via "libpath" above).
104
105       try_linker_script
106           [version 0.24]
107
108           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
115           An example is libyaml on Red Hat based Linux distributions.  On
116           Debian these are handled with symlinks and no trickery is required.
117
118       alien
119           [version 0.25]
120
121           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
126           [version 0.28]
127
128           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
135           [version 0.30] [breaking change]
136
137           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
145   assert_lib
146        assert_lib(%args);
147
148       This behaves exactly the same as find_lib, except that instead of
149       returning empty list of failure it throws an exception.
150
151   check_lib_or_exit
152        check_lib_or_exit(%args);
153
154       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
158   find_lib_or_exit
159       [version 0.05]
160
161        my(@libs) = find_lib_or_exit(%args);
162
163       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
166   find_lib_or_die
167       [version 0.06]
168
169        my(@libs) = find_lib_or_die(%args);
170
171       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
174   check_lib
175        my $bool = check_lib(%args);
176
177       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
180   which
181       [version 0.17]
182
183        my $path = which($name);
184
185       Return the path to the first library that matches the given name.
186
187       Not exported by default.
188
189   where
190       [version 0.17]
191
192        my @paths = where($name);
193
194       Return the paths to all the libraries that match the given name.
195
196       Not exported by default.
197
198   has_symbols
199       [version 0.17]
200
201        my $bool = has_symbols($path, @symbol_names);
202
203       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
207       Not exported by default.
208
209   system_path
210       [version 0.20]
211
212        my $path = FFI::CheckLib::system_path;
213
214       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
220       This function is not exportable, even on request.
221

ENVIRONMENT

223       FFI::CheckLib responds to these environment variables:
224
225       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
231           This behaviour can be overridden using the environment variable
232           "FFI_CHECKLIB_PACKAGE".
233
234           Allowed values are:
235
236           - "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
240           A comma separated list is also valid:
241
242            export FFI_CHECKLIB_PACKAGE=macports,homebrew
243
244           Order matters. So in this example, MacPorts' lib path appears
245           before Homebrew's path.
246
247       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
254       PATH
255           On Windows the "PATH" environment variable will be used as a search
256           path for libraries.
257
258       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

FAQ

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
269           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
274           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
282           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
287           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
295       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
299       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

SEE ALSO

311       FFI::Platypus
312           Call library functions dynamically without a compiler.
313
314       Dist::Zilla::Plugin::FFI::CheckLib
315           Dist::Zilla plugin for this module.
316

AUTHOR

318       Author: Graham Ollis <plicease@cpan.org>
319
320       Contributors:
321
322       Bakkiaraj Murugesan (bakkiaraj)
323
324       Dan Book (grinnz, DBOOK)
325
326       Ilya Pavlov (Ilya, ILUX)
327
328       Shawn Laffan (SLAFFAN)
329
330       Petr Písař (ppisar)
331
332       Michael R. Davis (MRDVT)
333
334       Shawn Laffan (SLAFFAN)
335
336       Carlos D. Álvaro (cdalvaro)
337
339       This software is copyright (c) 2014-2022 by Graham Ollis.
340
341       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.
343
344
345
346perl v5.38.0                      2023-07-20                  FFI::CheckLib(3)
Impressum