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

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 on rigourousness 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.