Devel::CheckLib(3) User Contributed Perl Documentation Devel::CheckLib(3)
NAME
Devel::CheckLib - check that a library is available
DESCRIPTION
Devel::CheckLib is a perl module that checks whether a particular C
library and its headers are available.
SYNOPSIS
use Devel::CheckLib;
check_lib_or_exit( lib => 'jpeg', header => 'jpeglib.h' );
check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] );
# or prompt for path to library and then do this:
check_lib_or_exit( lib => 'jpeg', libpath => $additional_path );
USING IT IN Makefile.PL or Build.PL
If you want to use this from Makefile.PL or Build.PL, do not simply
copy the module into your distribution as this may cause problems when
PAUSE and search.cpan.org index the distro. Instead, use the use-
devel-checklib script.
HOW IT WORKS
You pass named parameters to a function, describing to it how to build
and link to the libraries.
It works by trying to compile some code - which defaults to this:
int main(int argc, char *argv[]) { return 0; }
and linking it to the specified libraries. If something pops out the
end which looks executable, it gets executed, and if main() returns 0
we know that it worked. That tiny program is built once for each
library that you specify, and (without linking) once for each header
file.
If you want to check for the presence of particular functions in a
library, or even that those functions return particular results, then
you can pass your own function body for main() thus:
check_lib_or_exit(
function => 'foo();if(libversion() > 5) return 0; else return 1;'
incpath => ...
libpath => ...
lib => ...
header => ...
);
In that case, it will fail to build if either foo() or libversion()
don't exist, and main() will return the wrong value if libversion()'s
return value isn't what you want.
FUNCTIONS
All of these take the same named parameters and are exported by
default. To avoid exporting them, "use Devel::CheckLib ()".
assert_lib
This takes several named parameters, all of which are optional, and
dies with an error message if any of the libraries listed can not be
found. Note: dying in a Makefile.PL or Build.PL may provoke a 'FAIL'
report from CPAN Testers' automated smoke testers. Use
"check_lib_or_exit" instead.
The named parameters are:
lib Must be either a string with the name of a single library or a
reference to an array of strings of library names. Depending on
the compiler found, library names will be fed to the compiler
either as "-l" arguments or as ".lib" file names. (E.g. "-ljpeg"
or "jpeg.lib")
libpath
a string or an array of strings representing additional paths to
search for libraries.
LIBS
a "ExtUtils::MakeMaker"-style space-separated list of libraries
(each preceded by '-l') and directories (preceded by '-L').
This can also be supplied on the command-line.
debug
If true - emit information during processing that can be used for
debugging.
And libraries are no use without header files, so ...
header
Must be either a string with the name of a single header file or a
reference to an array of strings of header file names.
incpath
a string or an array of strings representing additional paths to
search for headers.
INC a "ExtUtils::MakeMaker"-style space-separated list of incpaths,
each preceded by '-I'.
This can also be supplied on the command-line.
ccflags
Extra flags to pass to the compiler.
ldflags
Extra flags to pass to the linker.
analyze_binary
a callback function that will be invoked in order to perform custom
analysis of the generated binary. The callback arguments are the
library name and the path to the binary just compiled.
It is possible to use this callback, for instance, to inspect the
binary for further dependencies.
not_execute
Do not try to execute generated binary. Only check that compilation
has not failed.
check_lib_or_exit
This behaves exactly the same as assert_lib() except that instead of
dieing, it warns (with exactly the same error message) and exits. This
is intended for use in Makefile.PL / Build.PL when you might want to
prompt the user for various paths and things before checking that what
they've told you is sane.
If any library or header is missing, it exits with an exit value of 0
to avoid causing a CPAN Testers 'FAIL' report. CPAN Testers should
ignore this result -- which is what you want if an external library
dependency is not available.
check_lib
This behaves exactly the same as assert_lib() except that it is silent,
returning false instead of dieing, or true otherwise.
PLATFORMS SUPPORTED
You must have a C compiler installed. We check for $Config{cc}, both
literally as it is in Config.pm and also in the $PATH.
It has been tested with varying degrees of rigorousness on:
gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin)
Sun's compiler tools on Solaris
IBM's tools on AIX
SGI's tools on Irix 6.5
Microsoft's tools on Windows
MinGW on Windows (with Strawberry Perl)
Borland's tools on Windows
QNX
WARNINGS, BUGS and FEEDBACK
This is a very early release intended primarily for feedback from
people who have discussed it. The interface may change and it has not
been adequately tested.
Feedback is most welcome, including constructive criticism. Bug
reports should be made using or by email.
When submitting a bug report, please include the output from running:
perl -V
perl -MDevel::CheckLib -e0
SEE ALSO
Devel::CheckOS
Probe::Perl
AUTHORS
David Cantrell
David Golden
Yasuhiro Matsumoto
Thanks to the cpan-testers-discuss mailing list for prompting us to
write it in the first place;
to Chris Williams for help with Borland support;
to Tony Cook for help with Microsoft compiler command-line options
COPYRIGHT and LICENCE
Copyright 2007 David Cantrell. Portions copyright 2007 David Golden.
This module is free-as-in-speech software, and may be used,
distributed, and modified under the same conditions as perl itself.
CONSPIRACY
This module is also free-as-in-mason software.
perl v5.38.0 2023-07-25 Devel::CheckLib(3)