lib/Autom4te/General.pm

   1 # autoconf -- create `configure' using m4 macros
   2 # Copyright (C) 2001-2004, 2006-2007, 2009-2011 Free Software
   3 # Foundation, Inc.
   4
   5 # This program is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation, either version 3 of the License, or
   8 # (at your option) any later version.
   9
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 package Autom4te::General;
  19
  20 =head1 NAME
  21
  22 Autom4te::General - general support functions for Autoconf and Automake
  23
  24 =head1 SYNOPSIS
  25
  26   use Autom4te::General
  27
  28 =head1 DESCRIPTION
  29
  30 This perl module provides various general purpose support functions
  31 used in several executables of the Autoconf and Automake packages.
  32
  33 =cut
  34
  35 use 5.005_03;
  36 use Exporter;
  37 use Autom4te::ChannelDefs;
  38 use Autom4te::Channels;
  39 use File::Basename;
  40 use File::Path ();
  41 use File::stat;
  42 use IO::File;
  43 use Carp;
  44 use strict;
  45
  46 use vars qw (@ISA @EXPORT);
  47
  48 @ISA = qw (Exporter);
  49
  50 # Variables we define and export.
  51 my @export_vars =
  52   qw ($debug $force $help $me $tmp $verbose $version);
  53
  54 # Functions we define and export.
  55 my @export_subs =
  56   qw (&debug
  57       &getopt &shell_quote &mktmpdir
  58       &uniq);
  59
  60 # Functions we forward (coming from modules we use).
  61 my @export_forward_subs =
  62   qw (&basename &dirname &fileparse);
  63
  64 @EXPORT = (@export_vars, @export_subs, @export_forward_subs);
  65
  66
  67 # Variable we share with the main package.  Be sure to have a single
  68 # copy of them: using `my' together with multiple inclusion of this
  69 # package would introduce several copies.
  70
  71 =head2 Global Variables
  72
  73 =over 4
  74
  75 =item C<$debug>
  76
  77 Set this variable to 1 if debug messages should be enabled.  Debug
  78 messages are meant for developpers only, or when tracking down an
  79 incorrect execution.
  80
  81 =cut
  82
  83 use vars qw ($debug);
  84 $debug = 0;
  85
  86 =item C<$force>
  87
  88 Set this variable to 1 to recreate all the files, or to consider all
  89 the output files are obsolete.
  90
  91 =cut
  92
  93 use vars qw ($force);
  94 $force = undef;
  95
  96 =item C<$help>
  97
  98 Set to the help message associated with the option C<--help>.
  99
 100 =cut
 101
 102 use vars qw ($help);
 103 $help = undef;
 104
 105 =item C<$me>
 106
 107 The name of this application, for diagnostic messages.
 108
 109 =cut
 110
 111 use vars qw ($me);
 112 $me = basename ($0);
 113
 114 =item C<$tmp>
 115
 116 The name of the temporary directory created by C<mktmpdir>.  Left
 117 C<undef> otherwise.
 118
 119 =cut
 120
 121 # Our tmp dir.
 122 use vars qw ($tmp);
 123 $tmp = undef;
 124
 125 =item C<$verbose>
 126
 127 Enable verbosity messages.  These messages are meant for ordinary
 128 users, and typically make explicit the steps being performed.
 129
 130 =cut
 131
 132 use vars qw ($verbose);
 133 $verbose = 0;
 134
 135 =item C<$version>
 136
 137 Set to the version message associated to the option C<--version>.
 138
 139 =cut
 140
 141 use vars qw ($version);
 142 $version = undef;
 143
 144 =back
 145
 146 =cut
 147
 148
 149
 150 ## ----- ##
 151 ## END.  ##
 152 ## ----- ##
 153
 154 =head2 Functions
 155
 156 =over 4
 157
 158 =item C<END>
 159
 160 Filter Perl's exit codes, delete any temporary directory (unless
 161 C<$debug>), and exit nonzero whenever closing C<STDOUT> fails.
 162
 163 =cut
 164
 165 # END
 166 # ---
 167 sub END
 168 {
 169   # $? contains the exit status we will return.
 170   # It was set using one of the following ways:
 171   #
 172   #  1) normal termination
 173   #     this sets $? = 0
 174   #  2) calling `exit (n)'
 175   #     this sets $? = n
 176   #  3) calling die or friends (croak, confess...):
 177   #     a) when $! is non-0
 178   #        this set $? = $!
 179   #     b) when $! is 0 but $? is not
 180   #        this sets $? = ($? >> 8)   (i.e., the exit code of the
 181   #        last program executed)
 182   #     c) when both $! and $? are 0
 183   #        this sets $? = 255
 184   #
 185   # Cases 1), 2), and 3b) are fine, but we prefer $? = 1 for 3a) and 3c).
 186   my $status = $?;
 187   $status = 1 if ($! && $! == $?) || $? == 255;
 188   # (Note that we cannot safely distinguish calls to `exit (n)'
 189   # from calls to die when `$! = n'.  It's not big deal because
 190   # we only call `exit (0)' or `exit (1)'.)
 191
 192   if (!$debug && defined $tmp && -d $tmp)
 193     {
 194       local $SIG{__WARN__} = sub { $status = 1; warn $_[0] };
 195       File::Path::rmtree $tmp;
 196     }
 197
 198   # This is required if the code might send any output to stdout
 199   # E.g., even --version or --help.  So it's best to do it unconditionally.
 200   if (! close STDOUT)
 201     {
 202       print STDERR "$me: closing standard output: $!\n";
 203       $? = 1;
 204       return;
 205     }
 206
 207   $? = $status;
 208 }
 209
 210
 211 ## ----------- ##
 212 ## Functions.  ##
 213 ## ----------- ##
 214
 215
 216 =item C<debug (@message)>
 217
 218 If the debug mode is enabled (C<$debug> and C<$verbose>), report the
 219 C<@message> on C<STDERR>, signed with the name of the program.
 220
 221 =cut
 222
 223 # &debug(@MESSAGE)
 224 # ----------------
 225 # Messages displayed only if $DEBUG and $VERBOSE.
 226 sub debug (@)
 227 {
 228   print STDERR "$me: ", @_, "\n"
 229     if $verbose && $debug;
 230 }
 231
 232
 233 =item C<getopt (%option)>
 234
 235 Wrapper around C<Getopt::Long>.  In addition to the user C<option>s,
 236 support C<-h>/C<--help>, C<-V>/C<--version>, C<-v>/C<--verbose>,
 237 C<-d>/C<--debug>, C<-f>/C<--force>.  Conform to the GNU Coding
 238 Standards for error messages.  Try to work around a weird behavior
 239 from C<Getopt::Long> to preserve C<-> as an C<@ARGV> instead of
 240 rejecting it as a broken option.
 241
 242 =cut
 243
 244 # getopt (%OPTION)
 245 # ----------------
 246 # Handle the %OPTION, plus all the common options.
 247 # Work around Getopt bugs wrt `-'.
 248 sub getopt (%)
 249 {
 250   my (%option) = @_;
 251   use Getopt::Long;
 252
 253   # F*k.  Getopt seems bogus and dies when given `-' with `bundling'.
 254   # If fixed some day, use this: '' => sub { push @ARGV, "-" }
 255   my $stdin = grep /^-$/, @ARGV;
 256   @ARGV = grep !/^-$/, @ARGV;
 257   %option = ("h|help"     => sub { print $help; exit 0 },
 258              "V|version"  => sub { print $version; exit 0 },
 259
 260              "v|verbose"  => sub { ++$verbose },
 261              "d|debug"    => sub { ++$debug },
 262              'f|force'    => \$force,
 263
 264              # User options last, so that they have precedence.
 265              %option);
 266   Getopt::Long::Configure ("bundling", "pass_through");
 267   GetOptions (%option)
 268     or exit 1;
 269
 270   foreach (grep { /^-./ } @ARGV)
 271     {
 272       print STDERR "$0: unrecognized option `$_'\n";
 273       print STDERR "Try `$0 --help' for more information.\n";
 274       exit (1);
 275     }
 276
 277   push @ARGV, '-'
 278     if $stdin;
 279
 280   setup_channel 'note', silent => !$verbose;
 281   setup_channel 'verb', silent => !$verbose;
 282 }
 283
 284
 285 =item C<shell_quote ($file_name)>
 286
 287 Quote C<$file_name> for the shell.
 288
 289 =cut
 290
 291 # $FILE_NAME
 292 # shell_quote ($FILE_NAME)
 293 # ------------------------
 294 # If the string $S is a well-behaved file name, simply return it.
 295 # If it contains white space, quotes, etc., quote it, and return
 296 # the new string.
 297 sub shell_quote($)
 298 {
 299   my ($s) = @_;
 300   if ($s =~ m![^\w+/.,-]!)
 301     {
 302       # Convert each single quote to '\''
 303       $s =~ s/\'/\'\\\'\'/g;
 304       # Then single quote the string.
 305       $s = "'$s'";
 306     }
 307   return $s;
 308 }
 309
 310 =item C<mktmpdir ($signature)>
 311
 312 Create a temporary directory which name is based on C<$signature>.
 313 Store its name in C<$tmp>.  C<END> is in charge of removing it, unless
 314 C<$debug>.
 315
 316 =cut
 317
 318 # mktmpdir ($SIGNATURE)
 319 # ---------------------
 320 sub mktmpdir ($)
 321 {
 322   my ($signature) = @_;
 323   my $TMPDIR = $ENV{'TMPDIR'} || '/tmp';
 324   my $quoted_tmpdir = shell_quote ($TMPDIR);
 325
 326   # If mktemp supports dirs, use it.
 327   $tmp = `(umask 077 &&
 328            mktemp -d $quoted_tmpdir/"${signature}XXXXXX") 2>/dev/null`;
 329   chomp $tmp;
 330
 331   if (!$tmp || ! -d $tmp)
 332     {
 333       $tmp = "$TMPDIR/$signature" . int (rand 10000) . ".$$";
 334       mkdir $tmp, 0700
 335         or croak "$me: cannot create $tmp: $!\n";
 336     }
 337
 338   print STDERR "$me:$$: working in $tmp\n"
 339     if $debug;
 340 }
 341
 342
 343 =item C<uniq (@list)>
 344
 345 Return C<@list> with no duplicates, keeping only the first
 346 occurrences.
 347
 348 =cut
 349
 350 # @RES
 351 # uniq (@LIST)
 352 # ------------
 353 sub uniq (@)
 354 {
 355   my @res = ();
 356   my %seen = ();
 357   foreach my $item (@_)
 358     {
 359       if (! exists $seen{$item})
 360         {
 361           $seen{$item} = 1;
 362           push (@res, $item);
 363         }
 364     }
 365   return wantarray ? @res : "@res";
 366 }
 367
 368
 369 =item C<handle_exec_errors ($command)>
 370
 371 Display an error message for C<$command>, based on the content of
 372 C<$?> and C<$!>.
 373
 374 =cut
 375
 376
 377 # handle_exec_errors ($COMMAND)
 378 # -----------------------------
 379 sub handle_exec_errors ($)
 380 {
 381   my ($command) = @_;
 382
 383   $command = (split (' ', $command))[0];
 384   if ($!)
 385     {
 386       error "failed to run $command: $!";
 387     }
 388   else
 389     {
 390       use POSIX qw (WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG);
 391
 392       if (WIFEXITED ($?))
 393         {
 394           my $status = WEXITSTATUS ($?);
 395           # WIFEXITED and WEXITSTATUS can alter $!, reset it so that
 396           # error() actually propagates the command's exit status, not $!.
 397           $! = 0;
 398           error "$command failed with exit status: $status";
 399         }
 400       elsif (WIFSIGNALED ($?))
 401         {
 402           my $signal = WTERMSIG ($?);
 403           # In this case we prefer to exit with status 1.
 404           $! = 1;
 405           error "$command terminated by signal: $signal";
 406         }
 407       else
 408         {
 409           error "$command exited abnormally";
 410         }
 411     }
 412 }
 413
 414 =back
 415
 416 =head1 SEE ALSO
 417
 418 L<Autom4te::XFile>
 419
 420 =head1 HISTORY
 421
 422 Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt> and Akim
 423 Demaille E<lt>F<akim@freefriends.org>E<gt>.
 424
 425 =cut
 426
 427
 428
 429 1; # for require
 430
 431 ### Setup "GNU" style for perl-mode and cperl-mode.
 432 ## Local Variables:
 433 ## perl-indent-level: 2
 434 ## perl-continued-statement-offset: 2
 435 ## perl-continued-brace-offset: 0
 436 ## perl-brace-offset: 0
 437 ## perl-brace-imaginary-offset: 0
 438 ## perl-label-offset: -2
 439 ## cperl-indent-level: 2
 440 ## cperl-brace-offset: 0
 441 ## cperl-continued-brace-offset: 0
 442 ## cperl-label-offset: -2
 443 ## cperl-extra-newline-before-brace: t
 444 ## cperl-merge-trailing-else: nil
 445 ## cperl-continued-statement-offset: 2
 446 ## End: