FFI::CheckLib(3pm)

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.25
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

AUTHOR

211       Author: Graham Ollis <plicease@cpan.org>
212
213       Contributors:
214
215       Bakkiaraj Murugesan (bakkiaraj)
216
217       Dan Book (grinnz, DBOOK)
218
219       Ilya Pavlov (Ilya, ILUX)
220
221       Shawn Laffan (SLAFFAN)
222
223       Petr Pisar (ppisar)
224

COPYRIGHT AND LICENSE

226       This software is copyright (c) 2014-2018 by Graham Ollis.
227
228       This is free software; you can redistribute it and/or modify it under
229       the same terms as the Perl 5 programming language system itself.
230
231
232
233perl v5.30.0                      2019-07-26                  FFI::CheckLib(3)