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.24
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   assert_lib
119        assert_lib(%args);
120
121       This behaves exactly the same as find_lib, except that instead of
122       returning empty list of failure it throws an exception.
123
124   check_lib_or_exit
125        check_lib_or_exit(%args);
126
127       This behaves exactly the same as assert_lib, except that instead of
128       dying, it warns (with exactly the same error message) and exists.  This
129       is intended for use in "Makefile.PL" or "Build.PL"
130
131   find_lib_or_exit
132       [version 0.05]
133
134        my(@libs) = find_lib_or_exit(%args);
135
136       This behaves exactly the same as find_lib, except that if the library
137       is not found, it will call exit with an appropriate diagnostic.
138
139   find_lib_or_die
140       [version 0.06]
141
142        my(@libs) = find_lib_or_die(%args);
143
144       This behaves exactly the same as find_lib, except that if the library
145       is not found, it will die with an appropriate diagnostic.
146
147   check_lib
148        my $bool = check_lib(%args);
149
150       This behaves exactly the same as find_lib, except that it returns true
151       (1) on finding the appropriate libraries or false (0) otherwise.
152
153   which
154       [version 0.17]
155
156        my $path = where($name);
157
158       Return the path to the first library that matches the given name.
159
160       Not exported by default.
161
162   where
163       [version 0.17]
164
165        my @paths = where($name);
166
167       Return the paths to all the libraries that match the given name.
168
169       Not exported by default.
170
171   has_symbols
172       [version 0.17]
173
174        my $bool = has_symbols($path, @symbol_names);
175
176       Returns true if all of the symbols can be found in the dynamic library
177       located at the given path.  Can be useful in conjunction with "verify"
178       with "find_lib" above.
179
180       Not exported by default.
181
182   system_path
183       [version 0.20]
184
185        my $path = FFI::CheckLib::system_path;
186
187       Returns the system path as a list reference.  On some systems, this is
188       "PATH" on others it might be "LD_LIBRARY_PATH" on still others it could
189       be something completely different.  So although you may add items to
190       this list, you should probably do some careful consideration before you
191       do so.
192
193       This function is not exportable, even on request.
194

AUTHOR

203       Author: Graham Ollis <plicease@cpan.org>
204
205       Contributors:
206
207       Bakkiaraj Murugesan (bakkiaraj)
208
209       Dan Book (grinnz, DBOOK)
210
211       Ilya Pavlov (Ilya, ILUX)
212
213       Shawn Laffan (SLAFFAN)
214

COPYRIGHT AND LICENSE

216       This software is copyright (c) 2014-2018 by Graham Ollis.
217
218       This is free software; you can redistribute it and/or modify it under
219       the same terms as the Perl 5 programming language system itself.
220
221
222
223perl v5.28.1                      2019-04-29                  FFI::CheckLib(3)