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.29
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   assert_lib
136        assert_lib(%args);
137
138       This behaves exactly the same as find_lib, except that instead of
139       returning empty list of failure it throws an exception.
140
141   check_lib_or_exit
142        check_lib_or_exit(%args);
143
144       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
148   find_lib_or_exit
149       [version 0.05]
150
151        my(@libs) = find_lib_or_exit(%args);
152
153       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
156   find_lib_or_die
157       [version 0.06]
158
159        my(@libs) = find_lib_or_die(%args);
160
161       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
164   check_lib
165        my $bool = check_lib(%args);
166
167       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
170   which
171       [version 0.17]
172
173        my $path = which($name);
174
175       Return the path to the first library that matches the given name.
176
177       Not exported by default.
178
179   where
180       [version 0.17]
181
182        my @paths = where($name);
183
184       Return the paths to all the libraries that match the given name.
185
186       Not exported by default.
187
188   has_symbols
189       [version 0.17]
190
191        my $bool = has_symbols($path, @symbol_names);
192
193       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
197       Not exported by default.
198
199   system_path
200       [version 0.20]
201
202        my $path = FFI::CheckLib::system_path;
203
204       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
210       This function is not exportable, even on request.
211

FAQ

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
218           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
223           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
231           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
236           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
244       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
248       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

SEE ALSO

260       FFI::Platypus
261           Call library functions dynamically without a compiler.
262
263       Dist::Zilla::Plugin::FFI::CheckLib
264           Dist::Zilla plugin for this module.
265

AUTHOR

267       Author: Graham Ollis <plicease@cpan.org>
268
269       Contributors:
270
271       Bakkiaraj Murugesan (bakkiaraj)
272
273       Dan Book (grinnz, DBOOK)
274
275       Ilya Pavlov (Ilya, ILUX)
276
277       Shawn Laffan (SLAFFAN)
278
279       Petr Písař (ppisar)
280
281       Michael R. Davis (MRDVT)
282
283       Shawn Laffan (SLAFFAN)
284
286       This software is copyright (c) 2014-2018 by Graham Ollis.
287
288       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.
290
291
292
293perl v5.36.0                      2022-12-07                  FFI::CheckLib(3)
Impressum