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

NAME

6       Devel::CheckLib - check that a library is available
7

DESCRIPTION

9       Devel::CheckLib is a perl module that checks whether a particular C
10       library and its headers are available.
11

SYNOPSIS

13           use Devel::CheckLib;
14
15           check_lib_or_exit( lib => 'jpeg', header => 'jpeglib.h' );
16           check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] );
17
18           # or prompt for path to library and then do this:
19           check_lib_or_exit( lib => 'jpeg', libpath => $additional_path );
20

USING IT IN Makefile.PL or Build.PL

22       If you want to use this from Makefile.PL or Build.PL, do not simply
23       copy the module into your distribution as this may cause problems when
24       PAUSE and search.cpan.org index the distro.  Instead, use the use-
25       devel-checklib script.
26

HOW IT WORKS

28       You pass named parameters to a function, describing to it how to build
29       and link to the libraries.
30
31       It works by trying to compile some code - which defaults to this:
32
33           int main(int argc, char *argv[]) { return 0; }
34
35       and linking it to the specified libraries.  If something pops out the
36       end which looks executable, it gets executed, and if main() returns 0
37       we know that it worked.  That tiny program is built once for each
38       library that you specify, and (without linking) once for each header
39       file.
40
41       If you want to check for the presence of particular functions in a
42       library, or even that those functions return particular results, then
43       you can pass your own function body for main() thus:
44
45           check_lib_or_exit(
46               function => 'foo();if(libversion() > 5) return 0; else return 1;'
47               incpath  => ...
48               libpath  => ...
49               lib      => ...
50               header   => ...
51           );
52
53       In that case, it will fail to build if either foo() or libversion()
54       don't exist, and main() will return the wrong value if libversion()'s
55       return value isn't what you want.
56

FUNCTIONS

58       All of these take the same named parameters and are exported by
59       default.  To avoid exporting them, "use Devel::CheckLib ()".
60
61   assert_lib
62       This takes several named parameters, all of which are optional, and
63       dies with an error message if any of the libraries listed can not be
64       found.  Note: dying in a Makefile.PL or Build.PL may provoke a 'FAIL'
65       report from CPAN Testers' automated smoke testers.  Use
66       "check_lib_or_exit" instead.
67
68       The named parameters are:
69
70       lib Must be either a string with the name of a single library or a
71           reference to an array of strings of library names.  Depending on
72           the compiler found, library names will be fed to the compiler
73           either as "-l" arguments or as ".lib" file names.  (E.g. "-ljpeg"
74           or "jpeg.lib")
75
76       libpath
77           a string or an array of strings representing additional paths to
78           search for libraries.
79
80       LIBS
81           a "ExtUtils::MakeMaker"-style space-separated list of libraries
82           (each preceded by '-l') and directories (preceded by '-L').
83
84           This can also be supplied on the command-line.
85
86       debug
87           If true - emit information during processing that can be used for
88           debugging.
89
90       And libraries are no use without header files, so ...
91
92       header
93           Must be either a string with the name of a single header file or a
94           reference to an array of strings of header file names.
95
96       incpath
97           a string or an array of strings representing additional paths to
98           search for headers.
99
100       INC a "ExtUtils::MakeMaker"-style space-separated list of incpaths,
101           each preceded by '-I'.
102
103           This can also be supplied on the command-line.
104
105       ccflags
106           Extra flags to pass to the compiler.
107
108       ldflags
109           Extra flags to pass to the linker.
110
111       analyze_binary
112           a callback function that will be invoked in order to perform custom
113           analysis of the generated binary. The callback arguments are the
114           library name and the path to the binary just compiled.
115
116           It is possible to use this callback, for instance, to inspect the
117           binary for further dependencies.
118
119       not_execute
120           Do not try to execute generated binary. Only check that compilation
121           has not failed.
122
123   check_lib_or_exit
124       This behaves exactly the same as assert_lib() except that instead of
125       dieing, it warns (with exactly the same error message) and exits.  This
126       is intended for use in Makefile.PL / Build.PL when you might want to
127       prompt the user for various paths and things before checking that what
128       they've told you is sane.
129
130       If any library or header is missing, it exits with an exit value of 0
131       to avoid causing a CPAN Testers 'FAIL' report.  CPAN Testers should
132       ignore this result -- which is what you want if an external library
133       dependency is not available.
134
135   check_lib
136       This behaves exactly the same as assert_lib() except that it is silent,
137       returning false instead of dieing, or true otherwise.
138

PLATFORMS SUPPORTED

140       You must have a C compiler installed.  We check for $Config{cc}, both
141       literally as it is in Config.pm and also in the $PATH.
142
143       It has been tested with varying degrees of rigorousness on:
144
145       gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin)
146       Sun's compiler tools on Solaris
147       IBM's tools on AIX
148       SGI's tools on Irix 6.5
149       Microsoft's tools on Windows
150       MinGW on Windows (with Strawberry Perl)
151       Borland's tools on Windows
152       QNX
153

WARNINGS, BUGS and FEEDBACK

155       This is a very early release intended primarily for feedback from
156       people who have discussed it.  The interface may change and it has not
157       been adequately tested.
158
159       Feedback is most welcome, including constructive criticism.  Bug
160       reports should be made using <http://rt.cpan.org/> or by email.
161
162       When submitting a bug report, please include the output from running:
163
164           perl -V
165           perl -MDevel::CheckLib -e0
166

SEE ALSO

168       Devel::CheckOS
169
170       Probe::Perl
171

AUTHORS

173       David Cantrell <david@cantrell.org.uk>
174
175       David Golden <dagolden@cpan.org>
176
177       Yasuhiro Matsumoto <mattn@cpan.org>
178
179       Thanks to the cpan-testers-discuss mailing list for prompting us to
180       write it in the first place;
181
182       to Chris Williams for help with Borland support;
183
184       to Tony Cook for help with Microsoft compiler command-line options
185
187       Copyright 2007 David Cantrell. Portions copyright 2007 David Golden.
188
189       This module is free-as-in-speech software, and may be used,
190       distributed, and modified under the same conditions as perl itself.
191

CONSPIRACY

193       This module is also free-as-in-mason software.
194
195
196
197perl v5.38.0                      2023-07-20                Devel::CheckLib(3)
Impressum