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.27
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   assert_lib
127        assert_lib(%args);
128
129       This behaves exactly the same as find_lib, except that instead of
130       returning empty list of failure it throws an exception.
131
132   check_lib_or_exit
133        check_lib_or_exit(%args);
134
135       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
139   find_lib_or_exit
140       [version 0.05]
141
142        my(@libs) = find_lib_or_exit(%args);
143
144       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
147   find_lib_or_die
148       [version 0.06]
149
150        my(@libs) = find_lib_or_die(%args);
151
152       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
155   check_lib
156        my $bool = check_lib(%args);
157
158       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
161   which
162       [version 0.17]
163
164        my $path = where($name);
165
166       Return the path to the first library that matches the given name.
167
168       Not exported by default.
169
170   where
171       [version 0.17]
172
173        my @paths = where($name);
174
175       Return the paths to all the libraries that match the given name.
176
177       Not exported by default.
178
179   has_symbols
180       [version 0.17]
181
182        my $bool = has_symbols($path, @symbol_names);
183
184       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
188       Not exported by default.
189
190   system_path
191       [version 0.20]
192
193        my $path = FFI::CheckLib::system_path;
194
195       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
201       This function is not exportable, even on request.
202

FAQ

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
209           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
214           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
222           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
227           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
235       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
239       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

SEE ALSO

251       FFI::Platypus
252           Call library functions dynamically without a compiler.
253
254       Dist::Zilla::Plugin::FFI::CheckLib
255           Dist::Zilla plugin for this module.
256

AUTHOR

258       Author: Graham Ollis <plicease@cpan.org>
259
260       Contributors:
261
262       Bakkiaraj Murugesan (bakkiaraj)
263
264       Dan Book (grinnz, DBOOK)
265
266       Ilya Pavlov (Ilya, ILUX)
267
268       Shawn Laffan (SLAFFAN)
269
270       Petr Pisar (ppisar)
271
273       This software is copyright (c) 2014-2018 by Graham Ollis.
274
275       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.
277
278
279
280perl v5.32.1                      2021-01-27                  FFI::CheckLib(3)
Impressum