/ 
Devel-CheckLib-0.2
River stage three • 88 direct dependents • 417 total dependents
/ Devel::CheckLib

NAME

Devel::CheckLib - check that a library is available

DESCRIPTION

Devel::CheckLib is a perl module that checks whether a particular C library is available, and dies if it is not.

SYNOPSIS

  # in a Makefile.PL or Build.PL
  use lib qw(inc);
  use Devel::CheckLib;

  check_lib_or_exit( lib => 'jpeg' );
  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 );

HOW IT WORKS

You pass named parameters to a function describing how to build and link to the library. Currently the only parameter supported is 'lib', which can be a string or an arrayref of several libraries. In the future, expect us to add something for checking that header files are available as well.

It works by trying to compile this:

int main(void) { return 0; }

and linking it to the specified libraries. If something pops out the end which looks executable, then the module simply returns. If not, it dies.

FUNCTIONS

All of these take the same named parameters and are exported by default. To avoid exporting them, use Devel::CheckLib ().

assert_lib

Takes parameters lib and libpath. The value of 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)

Likewise, libpath must either be a string or an array of strings representing additional paths to search for libraries.

This will die 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.

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 a library isn't found, 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.

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.

Probably contains unsupportable assumptions about how to invoke the compilers and stuff.

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.

I welcome feedback about my code, including constructive criticism. Bug reports should be made using http://rt.cpan.org/ or by email.

If you are feeling particularly generous you can encourage me in my open source endeavours by buying me something from my wishlist: http://www.cantrell.org.uk/david/wishlist/

SEE ALSO

Devel::CheckOS

AUTHORS

David Cantrell <david@cantrell.org.uk>

David Golden <dagolden@cpan.org>

Thanks to the cpan-testers-discuss mailing list for prompting me to write it in the first place.

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.