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(void) { 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.
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.
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 <
http://rt.cpan.org/> 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@cantrell.org.uk>
David Golden <dagolden@cpan.org>
Yasuhiro Matsumoto <mattn@cpan.org>
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.