PNG/inc/Devel/CheckLib.pm

   1 # $Id: CheckLib.pm,v 1.25 2008/10/27 12:16:23 drhyde Exp $
   2
   3 package #
   4 Devel::CheckLib;
   5
   6 use strict;
   7 use vars qw($VERSION @ISA @EXPORT);
   8 $VERSION = '0.699_002';
   9 use Config;
  10
  11 use File::Spec;
  12 use File::Temp;
  13
  14 require Exporter;
  15 @ISA = qw(Exporter);
  16 @EXPORT = qw(assert_lib check_lib_or_exit check_lib);
  17
  18 # localising prevents the warningness leaking out of this module
  19 local $^W = 1;    # use warnings is a 5.6-ism
  20
  21 _findcc(); # bomb out early if there's no compiler
  22
  23 =head1 NAME
  24
  25 Devel::CheckLib - check that a library is available
  26
  27 =head1 DESCRIPTION
  28
  29 Devel::CheckLib is a perl module that checks whether a particular C
  30 library and its headers are available.
  31
  32 =head1 SYNOPSIS
  33
  34     use Devel::CheckLib;
  35
  36     check_lib_or_exit( lib => 'jpeg', header => 'jpeglib.h' );
  37     check_lib_or_exit( lib => [ 'iconv', 'jpeg' ] );
  38
  39     # or prompt for path to library and then do this:
  40     check_lib_or_exit( lib => 'jpeg', libpath => $additional_path );
  41
  42 =head1 USING IT IN Makefile.PL or Build.PL
  43
  44 If you want to use this from Makefile.PL or Build.PL, do
  45 not simply copy the module into your distribution as this may cause
  46 problems when PAUSE and search.cpan.org index the distro.  Instead, use
  47 the use-devel-checklib script.
  48
  49 =head1 HOW IT WORKS
  50
  51 You pass named parameters to a function, describing to it how to build
  52 and link to the libraries.
  53
  54 It works by trying to compile some code - which defaults to this:
  55
  56     int main(void) { return 0; }
  57
  58 and linking it to the specified libraries.  If something pops out the end
  59 which looks executable, it gets executed, and if main() returns 0 we know
  60 that it worked.  That tiny program is
  61 built once for each library that you specify, and (without linking) once
  62 for each header file.
  63
  64 If you want to check for the presence of particular functions in a
  65 library, or even that those functions return particular results, then
  66 you can pass your own function body for main() thus:
  67
  68     check_lib_or_exit(
  69         function => 'foo();if(libversion() > 5) return 0; else return 1;'
  70         incpath  => ...
  71         libpath  => ...
  72         lib      => ...
  73         header   => ...
  74     );
  75
  76 In that case, it will fail to build if either foo() or libversion() don't
  77 exist, and main() will return the wrong value if libversion()'s return
  78 value isn't what you want.
  79
  80 =head1 FUNCTIONS
  81
  82 All of these take the same named parameters and are exported by default.
  83 To avoid exporting them, C<use Devel::CheckLib ()>.
  84
  85 =head2 assert_lib
  86
  87 This takes several named parameters, all of which are optional, and dies
  88 with an error message if any of the libraries listed can
  89 not be found.  B<Note>: dying in a Makefile.PL or Build.PL may provoke
  90 a 'FAIL' report from CPAN Testers' automated smoke testers.  Use
  91 C<check_lib_or_exit> instead.
  92
  93 The named parameters are:
  94
  95 =over
  96
  97 =item lib
  98
  99 Must be either a string with the name of a single
 100 library or a reference to an array of strings of library names.  Depending
 101 on the compiler found, library names will be fed to the compiler either as
 102 C<-l> arguments or as C<.lib> file names.  (E.g. C<-ljpeg> or C<jpeg.lib>)
 103
 104 =item libpath
 105
 106 a string or an array of strings
 107 representing additional paths to search for libraries.
 108
 109 =item LIBS
 110
 111 a C<ExtUtils::MakeMaker>-style space-seperated list of
 112 libraries (each preceded by '-l') and directories (preceded by '-L').
 113
 114 This can also be supplied on the command-line.
 115
 116 =back
 117
 118 And libraries are no use without header files, so ...
 119
 120 =over
 121
 122 =item header
 123
 124 Must be either a string with the name of a single
 125 header file or a reference to an array of strings of header file names.
 126
 127 =item incpath
 128
 129 a string or an array of strings
 130 representing additional paths to search for headers.
 131
 132 =item INC
 133
 134 a C<ExtUtils::MakeMaker>-style space-seperated list of
 135 incpaths, each preceded by '-I'.
 136
 137 This can also be supplied on the command-line.
 138
 139 =back
 140
 141 If you need to perform know more than "does it link?" you can provide
 142 code to be compiled and run:
 143
 144 =over
 145
 146 =item function
 147
 148 the body of the <main()> function.  If not provided C<return 0;> is
 149 used.
 150
 151 =item prologue
 152
 153 code to insert between the C<#include> of the headers and the
 154 definition of main.
 155
 156 =back
 157
 158 =head2 check_lib_or_exit
 159
 160 This behaves exactly the same as C<assert_lib()> except that instead of
 161 dieing, it warns (with exactly the same error message) and exits.
 162 This is intended for use in Makefile.PL / Build.PL
 163 when you might want to prompt the user for various paths and
 164 things before checking that what they've told you is sane.
 165
 166 If any library or header is missing, it exits with an exit value of 0 to avoid
 167 causing a CPAN Testers 'FAIL' report.  CPAN Testers should ignore this
 168 result -- which is what you want if an external library dependency is not
 169 available.
 170
 171 =head2 check_lib
 172
 173 This behaves exactly the same as C<assert_lib()> except that it is silent,
 174 returning false instead of dieing, or true otherwise.
 175
 176 =cut
 177
 178 sub check_lib_or_exit {
 179     eval 'assert_lib(@_)';
 180     if($@) {
 181         warn $@;
 182         exit;
 183     }
 184 }
 185
 186 sub check_lib {
 187     eval 'assert_lib(@_)';
 188     return $@ ? 0 : 1;
 189 }
 190
 191 sub assert_lib {
 192     my %args = @_;
 193     my (@libs, @libpaths, @headers, @incpaths);
 194
 195     # FIXME: these four just SCREAM "refactor" at me
 196     @libs = (ref($args{lib}) ? @{$args{lib}} : $args{lib})
 197         if $args{lib};
 198     @libpaths = (ref($args{libpath}) ? @{$args{libpath}} : $args{libpath})
 199         if $args{libpath};
 200     @headers = (ref($args{header}) ? @{$args{header}} : $args{header})
 201         if $args{header};
 202     @incpaths = (ref($args{incpath}) ? @{$args{incpath}} : $args{incpath})
 203         if $args{incpath};
 204
 205     # each entry is an arrayref containing:
 206     # 0: arrayref of library search paths
 207     # 1: arrayref of library names
 208     my @link_cfgs = map [ \@libpaths, [ $_ ] ], @libs;
 209
 210     # work-a-like for Makefile.PL's LIBS and INC arguments
 211     # if given as command-line argument, append to %args
 212     for my $arg (@ARGV) {
 213         for my $mm_attr_key qw(LIBS INC) {
 214             if (my ($mm_attr_value) = $arg =~ /\A $mm_attr_key = (.*)/x) {
 215             # it is tempting to put some \s* into the expression, but the
 216             # MM command-line parser only accepts LIBS etc. followed by =,
 217             # so we should not be any more lenient with whitespace than that
 218                 $args{$mm_attr_key} .= " $mm_attr_value";
 219             }
 220         }
 221     }
 222     # using special form of split to trim whitespace
 223     if(defined($args{LIBS})) {
 224         if (ref $args{LIBS}) {
 225             foreach my $arg (@{$args{LIBS}}) {
 226                 my @sep = split ' ', $arg;
 227                 my @libs = map { /^-l(.+)$/ ? $1 : () } @sep;
 228                 my @paths = map { /^-L(.+)$/ ? $1 : () } @sep;
 229                 push @link_cfgs, [ \@paths, \@libs ];
 230             }
 231         }
 232         else {
 233             my @libs;
 234             my @paths;
 235             foreach my $arg (split(' ', $args{LIBS})) {
 236                 die("LIBS argument badly-formed: $arg\n") unless($arg =~ /^-l/i);
 237                 push @{$arg =~ /^-l/ ? \@libs : \@paths}, substr($arg, 2);
 238             }
 239             push @link_cfgs, map [ \@paths, [ $_ ] ], @libs;
 240         }
 241     }
 242     if(defined($args{INC})) {
 243         foreach my $arg (split(' ', $args{INC})) {
 244             die("INC argument badly-formed: $arg\n") unless($arg =~ /^-I/);
 245             push @incpaths, substr($arg, 2);
 246         }
 247     }
 248
 249     my @cc = _findcc();
 250     my @missing;
 251     my @wrongresult;
 252
 253     # first figure out which headers we can't find ...
 254     my @use_headers;
 255     for my $header (@headers) {
 256         push @use_headers, $header;
 257         my($ch, $cfile) = File::Temp::tempfile(
 258             'assertlibXXXXXXXX', SUFFIX => '.c'
 259         );
 260         print $ch qq{#include <$_>\n} for @use_headers;
 261         print $ch qq{int main(void) { return 0; }\n};
 262         close($ch);
 263         my $exefile = File::Temp::mktemp( 'assertlibXXXXXXXX' ) . $Config{_exe};
 264         my @sys_cmd;
 265         # FIXME: re-factor - almost identical code later when linking
 266         if ( $Config{cc} eq 'cl' ) {                 # Microsoft compiler
 267             require Win32;
 268             @sys_cmd = (
 269                 @cc,
 270                 $cfile,
 271                 "/Fe$exefile",
 272                 (map { '/I'.Win32::GetShortPathName($_) } @incpaths)
 273             );
 274         } elsif($Config{cc} =~ /bcc32(\.exe)?/) {    # Borland
 275             @sys_cmd = (
 276                 @cc,
 277                 (map { "-I$_" } @incpaths),
 278                 "-o$exefile",
 279                 $cfile
 280             );
 281         } else { # Unix-ish: gcc, Sun, AIX (gcc, cc), ...
 282             @sys_cmd = (
 283                 @cc,
 284                 $cfile,
 285                 (map { "-I$_" } @incpaths),
 286                 "-o", "$exefile"
 287             );
 288         }
 289         warn "# @sys_cmd\n" if $args{debug};
 290         my $rv = $args{debug} ? system(@sys_cmd) : _quiet_system(@sys_cmd);
 291         push @missing, $header if $rv != 0 || ! -x $exefile;
 292         _cleanup_exe($exefile);
 293         unlink $cfile;
 294     }
 295
 296     # now do each library in turn with headers
 297     my($ch, $cfile) = File::Temp::tempfile(
 298         'assertlibXXXXXXXX', SUFFIX => '.c'
 299     );
 300     print $ch qq{#include <$_>\n} foreach (@headers);
 301     print $ch "\n$args{prologue}\n" if $args{prologue};
 302     print $ch "int main(void) { ".($args{function} || 'return 0;')." }\n";
 303     close($ch);
 304     for my $link_cfg ( @link_cfgs ) {
 305         my ($paths, $libs) = @$link_cfg;
 306         my $exefile = File::Temp::mktemp( 'assertlibXXXXXXXX' ) . $Config{_exe};
 307         my @sys_cmd;
 308         if ( $Config{cc} eq 'cl' ) {                 # Microsoft compiler
 309             require Win32;
 310             my @libpath = map {
 311                 q{/libpath:} . Win32::GetShortPathName($_)
 312             } @libpaths;
 313             # this is horribly sensitive to the order of arguments
 314             @sys_cmd = (
 315                 @cc,
 316                 $cfile,
 317                 ( map { "$_.lib" } @$libs ),
 318                 "/Fe$exefile",
 319                 (map { '/I'.Win32::GetShortPathName($_) } @incpaths),
 320                 "/link",
 321                 (map {'/libpath:'.Win32::GetShortPathName($_)} @$paths),
 322             );
 323         } elsif($Config{cc} eq 'CC/DECC') {          # VMS
 324         } elsif($Config{cc} =~ /bcc32(\.exe)?/) {    # Borland
 325             @sys_cmd = (
 326                 @cc,
 327                 "-o$exefile",
 328                 (map { "-l$_" } @$libs ),
 329                 (map { "-I$_" } @incpaths),
 330                 (map { "-L$_" } @$paths),
 331                 $cfile);
 332         } else {                                     # Unix-ish
 333                                                      # gcc, Sun, AIX (gcc, cc)
 334             @sys_cmd = (
 335                 @cc,
 336                 $cfile,
 337                 "-o", "$exefile",
 338                 (map { "-l$_" } @$libs ),
 339                 (map { "-I$_" } @incpaths),
 340                 (map { "-L$_" } @$paths)
 341             );
 342         }
 343         warn "# @sys_cmd\n" if $args{debug};
 344         my $rv = $args{debug} ? system(@sys_cmd) : _quiet_system(@sys_cmd);
 345         push @missing, @$libs if $rv != 0 || ! -x $exefile;
 346         push @wrongresult, @$libs if $rv == 0 && -x $exefile && system(File::Spec->rel2abs($exefile)) != 0;
 347         _cleanup_exe($exefile);
 348     }
 349     unlink $cfile;
 350
 351     my $miss_string = join( q{, }, map { qq{'$_'} } @missing );
 352     die("Can't link/include $miss_string\n") if @missing;
 353     my $wrong_string = join( q{, }, map { qq{'$_'} } @wrongresult);
 354     die("wrong result: $wrong_string\n") if @wrongresult;
 355 }
 356
 357 sub _cleanup_exe {
 358     my ($exefile) = @_;
 359     my $ofile = $exefile;
 360     $ofile =~ s/$Config{_exe}$/$Config{_o}/;
 361     unlink $exefile if -f $exefile;
 362     unlink $ofile if -f $ofile;
 363     unlink "$exefile\.manifest" if -f "$exefile\.manifest";
 364     return
 365 }
 366
 367 sub _findcc {
 368     my @paths = split(/$Config{path_sep}/, $ENV{PATH});
 369     my @cc = split(/\s+/, $Config{cc});
 370     return @cc if -x $cc[0];
 371     foreach my $path (@paths) {
 372         my $compiler = File::Spec->catfile($path, $cc[0]) . $Config{_exe};
 373         return ($compiler, @cc[1 .. $#cc]) if -x $compiler;
 374     }
 375     die("Couldn't find your C compiler\n");
 376 }
 377
 378 # code substantially borrowed from IPC::Run3
 379 sub _quiet_system {
 380     my (@cmd) = @_;
 381
 382     # save handles
 383     local *STDOUT_SAVE;
 384     local *STDERR_SAVE;
 385     open STDOUT_SAVE, ">&STDOUT" or die "CheckLib: $! saving STDOUT";
 386     open STDERR_SAVE, ">&STDERR" or die "CheckLib: $! saving STDERR";
 387
 388     # redirect to nowhere
 389     local *DEV_NULL;
 390     open DEV_NULL, ">" . File::Spec->devnull
 391         or die "CheckLib: $! opening handle to null device";
 392     open STDOUT, ">&" . fileno DEV_NULL
 393         or die "CheckLib: $! redirecting STDOUT to null handle";
 394     open STDERR, ">&" . fileno DEV_NULL
 395         or die "CheckLib: $! redirecting STDERR to null handle";
 396
 397     # run system command
 398     my $rv = system(@cmd);
 399
 400     # restore handles
 401     open STDOUT, ">&" . fileno STDOUT_SAVE
 402         or die "CheckLib: $! restoring STDOUT handle";
 403     open STDERR, ">&" . fileno STDERR_SAVE
 404         or die "CheckLib: $! restoring STDERR handle";
 405
 406     return $rv;
 407 }
 408
 409 =head1 PLATFORMS SUPPORTED
 410
 411 You must have a C compiler installed.  We check for C<$Config{cc}>,
 412 both literally as it is in Config.pm and also in the $PATH.
 413
 414 It has been tested with varying degrees on rigourousness on:
 415
 416 =over
 417
 418 =item gcc (on Linux, *BSD, Mac OS X, Solaris, Cygwin)
 419
 420 =item Sun's compiler tools on Solaris
 421
 422 =item IBM's tools on AIX
 423
 424 =item SGI's tools on Irix 6.5
 425
 426 =item Microsoft's tools on Windows
 427
 428 =item MinGW on Windows (with Strawberry Perl)
 429
 430 =item Borland's tools on Windows
 431
 432 =item QNX
 433
 434 =back
 435
 436 =head1 WARNINGS, BUGS and FEEDBACK
 437
 438 This is a very early release intended primarily for feedback from
 439 people who have discussed it.  The interface may change and it has
 440 not been adequately tested.
 441
 442 Feedback is most welcome, including constructive criticism.
 443 Bug reports should be made using L<http://rt.cpan.org/> or by email.
 444
 445 When submitting a bug report, please include the output from running:
 446
 447     perl -V
 448     perl -MDevel::CheckLib -e0
 449
 450 =head1 SEE ALSO
 451
 452 L<Devel::CheckOS>
 453
 454 L<Probe::Perl>
 455
 456 =head1 AUTHORS
 457
 458 David Cantrell E<lt>david@cantrell.org.ukE<gt>
 459
 460 David Golden E<lt>dagolden@cpan.orgE<gt>
 461
 462 Thanks to the cpan-testers-discuss mailing list for prompting us to write it
 463 in the first place;
 464
 465 to Chris Williams for help with Borland support.
 466
 467 =head1 COPYRIGHT and LICENCE
 468
 469 Copyright 2007 David Cantrell. Portions copyright 2007 David Golden.
 470
 471 This module is free-as-in-speech software, and may be used, distributed,
 472 and modified under the same conditions as perl itself.
 473
 474 =head1 CONSPIRACY
 475
 476 This module is also free-as-in-mason software.
 477
 478 =cut
 479
 480 1;