One Hat Cyber Team

Edit File: Devel::CheckLib.3pm

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Devel::CheckLib 3"
.TH Devel::CheckLib 3 "2022-05-04" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::CheckLib \- check that a library is available
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Devel::CheckLib is a perl module that checks whether a particular C
library and its headers are available.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Devel::CheckLib;
\&
\&    check_lib_or_exit( lib => \*(Aqjpeg\*(Aq, header => \*(Aqjpeglib.h\*(Aq );
\&    check_lib_or_exit( lib => [ \*(Aqiconv\*(Aq, \*(Aqjpeg\*(Aq ] );
\&  
\&    # or prompt for path to library and then do this:
\&    check_lib_or_exit( lib => \*(Aqjpeg\*(Aq, libpath => $additional_path );
.Ve
.SH "USING IT IN Makefile.PL or Build.PL"
.IX Header "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 \s-1PAUSE\s0 and search.cpan.org index the distro.  Instead, use
the use-devel-checklib script.
.SH "HOW IT WORKS"
.IX Header "HOW IT WORKS"
You pass named parameters to a function, describing to it how to build
and link to the libraries.
.PP
It works by trying to compile some code \- which defaults to this:
.PP
.Vb 1
\&    int main(int argc, char *argv[]) { return 0; }
.Ve
.PP
and linking it to the specified libraries.  If something pops out the end
which looks executable, it gets executed, and if \fBmain()\fR 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.
.PP
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 \fBmain()\fR thus:
.PP
.Vb 7
\&    check_lib_or_exit(
\&        function => \*(Aqfoo();if(libversion() > 5) return 0; else return 1;\*(Aq
\&        incpath  => ...
\&        libpath  => ...
\&        lib      => ...
\&        header   => ...
\&    );
.Ve
.PP
In that case, it will fail to build if either \fBfoo()\fR or \fBlibversion()\fR don't
exist, and \fBmain()\fR will return the wrong value if \fBlibversion()\fR's return
value isn't what you want.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
All of these take the same named parameters and are exported by default.
To avoid exporting them, \f(CW\*(C`use Devel::CheckLib ()\*(C'\fR.
.SS "assert_lib"
.IX Subsection "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.  \fBNote\fR: dying in a Makefile.PL or Build.PL may provoke
a '\s-1FAIL\s0' report from \s-1CPAN\s0 Testers' automated smoke testers.  Use 
\&\f(CW\*(C`check_lib_or_exit\*(C'\fR instead.
.PP
The named parameters are:
.IP "lib" 4
.IX Item "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
\&\f(CW\*(C`\-l\*(C'\fR arguments or as \f(CW\*(C`.lib\*(C'\fR file names.  (E.g. \f(CW\*(C`\-ljpeg\*(C'\fR or \f(CW\*(C`jpeg.lib\*(C'\fR)
.IP "libpath" 4
.IX Item "libpath"
a string or an array of strings
representing additional paths to search for libraries.
.IP "\s-1LIBS\s0" 4
.IX Item "LIBS"
a \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR\-style space-separated list of
libraries (each preceded by '\-l') and directories (preceded by '\-L').
.Sp
This can also be supplied on the command-line.
.IP "debug" 4
.IX Item "debug"
If true \- emit information during processing that can be used for
debugging.
.PP
And libraries are no use without header files, so ...
.IP "header" 4
.IX Item "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.
.IP "incpath" 4
.IX Item "incpath"
a string or an array of strings
representing additional paths to search for headers.
.IP "\s-1INC\s0" 4
.IX Item "INC"
a \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR\-style space-separated list of
incpaths, each preceded by '\-I'.
.Sp
This can also be supplied on the command-line.
.IP "ccflags" 4
.IX Item "ccflags"
Extra flags to pass to the compiler.
.IP "ldflags" 4
.IX Item "ldflags"
Extra flags to pass to the linker.
.IP "analyze_binary" 4
.IX Item "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.
.Sp
It is possible to use this callback, for instance, to inspect the
binary for further dependencies.
.IP "not_execute" 4
.IX Item "not_execute"
Do not try to execute generated binary. Only check that compilation has not failed.
.SS "check_lib_or_exit"
.IX Subsection "check_lib_or_exit"
This behaves exactly the same as \f(CW\*(C`assert_lib()\*(C'\fR 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.
.PP
If any library or header is missing, it exits with an exit value of 0 to avoid
causing a \s-1CPAN\s0 Testers '\s-1FAIL\s0' report.  \s-1CPAN\s0 Testers should ignore this
result \*(-- which is what you want if an external library dependency is not
available.
.SS "check_lib"
.IX Subsection "check_lib"
This behaves exactly the same as \f(CW\*(C`assert_lib()\*(C'\fR except that it is silent,
returning false instead of dieing, or true otherwise.
.SH "PLATFORMS SUPPORTED"
.IX Header "PLATFORMS SUPPORTED"
You must have a C compiler installed.  We check for \f(CW$Config{cc}\fR,
both literally as it is in Config.pm and also in the \f(CW$PATH\fR.
.PP
It has been tested with varying degrees of rigorousness on:
.IP "gcc (on Linux, *BSD, Mac \s-1OS X,\s0 Solaris, Cygwin)" 4
.IX Item "gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin)"
.PD 0
.IP "Sun's compiler tools on Solaris" 4
.IX Item "Sun's compiler tools on Solaris"
.IP "\s-1IBM\s0's tools on \s-1AIX\s0" 4
.IX Item "IBM's tools on AIX"
.IP "\s-1SGI\s0's tools on Irix 6.5" 4
.IX Item "SGI's tools on Irix 6.5"
.IP "Microsoft's tools on Windows" 4
.IX Item "Microsoft's tools on Windows"
.IP "MinGW on Windows (with Strawberry Perl)" 4
.IX Item "MinGW on Windows (with Strawberry Perl)"
.IP "Borland's tools on Windows" 4
.IX Item "Borland's tools on Windows"
.IP "\s-1QNX\s0" 4
.IX Item "QNX"
.PD
.SH "WARNINGS, BUGS and FEEDBACK"
.IX Header "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.
.PP
Feedback is most welcome, including constructive criticism.
Bug reports should be made using <http://rt.cpan.org/> or by email.
.PP
When submitting a bug report, please include the output from running:
.PP
.Vb 2
\&    perl \-V
\&    perl \-MDevel::CheckLib \-e0
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::CheckOS
.PP
Probe::Perl
.SH "AUTHORS"
.IX Header "AUTHORS"
David Cantrell <david@cantrell.org.uk>
.PP
David Golden <dagolden@cpan.org>
.PP
Yasuhiro Matsumoto <mattn@cpan.org>
.PP
Thanks to the cpan-testers-discuss mailing list for prompting us to write it
in the first place;
.PP
to Chris Williams for help with Borland support;
.PP
to Tony Cook for help with Microsoft compiler command-line options
.SH "COPYRIGHT and LICENCE"
.IX Header "COPYRIGHT and LICENCE"
Copyright 2007 David Cantrell. Portions copyright 2007 David Golden.
.PP
This module is free-as-in-speech software, and may be used, distributed,
and modified under the same conditions as perl itself.
.SH "CONSPIRACY"
.IX Header "CONSPIRACY"
This module is also free-as-in-mason software.