bin/autom4te.in

   1 #! @PERL@ -w
   2 # -*- perl -*-
   3 # @configure_input@
   4
   5 eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac'
   6     if 0;
   7
   8 # autom4te - Wrapper around M4 libraries.
   9 # Copyright (C) 2001-2003, 2005-2016 Free Software Foundation, Inc.
  10
  11 # This program is free software: you can redistribute it and/or modify
  12 # it under the terms of the GNU General Public License as published by
  13 # the Free Software Foundation, either version 3 of the License, or
  14 # (at your option) any later version.
  15
  16 # This program is distributed in the hope that it will be useful,
  17 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 # GNU General Public License for more details.
  20
  21 # You should have received a copy of the GNU General Public License
  22 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23
  24
  25 BEGIN
  26 {
  27   my $pkgdatadir = $ENV{'autom4te_perllibdir'} || '@pkgdatadir@';
  28   unshift @INC, $pkgdatadir;
  29
  30   # Override SHELL.  On DJGPP SHELL may not be set to a shell
  31   # that can handle redirection and quote arguments correctly,
  32   # e.g.: COMMAND.COM.  For DJGPP always use the shell that configure
  33   # has detected.
  34   $ENV{'SHELL'} = '@SHELL@' if ($^O eq 'dos');
  35 }
  36
  37 use Autom4te::C4che;
  38 use Autom4te::ChannelDefs;
  39 use Autom4te::Channels;
  40 use Autom4te::FileUtils;
  41 use Autom4te::General;
  42 use Autom4te::XFile;
  43 use File::Basename;
  44 use strict;
  45
  46 # Data directory.
  47 my $pkgdatadir = $ENV{'AC_MACRODIR'} || '@pkgdatadir@';
  48
  49 # $LANGUAGE{LANGUAGE} -- Automatic options for LANGUAGE.
  50 my %language;
  51
  52 my $output = '-';
  53
  54 # Mode of the output file except for traces.
  55 my $mode = "0666";
  56
  57 # If melt, don't use frozen files.
  58 my $melt = 0;
  59
  60 # Names of the cache directory, cache directory index, trace cache
  61 # prefix, and output cache prefix.  And the IO object for the index.
  62 my $cache;
  63 my $icache;
  64 my $tcache;
  65 my $ocache;
  66 my $icache_file;
  67
  68 my $flock_implemented = '@PERL_FLOCK@';
  69
  70 # The macros to trace mapped to their format, as specified by the
  71 # user.
  72 my %trace;
  73
  74 # The macros the user will want to trace in the future.
  75 # We need 'include' to get the included file, 'm4_pattern_forbid' and
  76 # 'm4_pattern_allow' to check the output.
  77 #
  78 # FIXME: What about 'sinclude'?
  79 my @preselect = ('include',
  80                  'm4_pattern_allow', 'm4_pattern_forbid',
  81                  '_m4_warn');
  82
  83 # M4 include path.
  84 my @include;
  85
  86 # Do we freeze?
  87 my $freeze = 0;
  88
  89 # $M4.
  90 my $m4 = $ENV{"M4"} || '@M4@';
  91 # Some non-GNU m4's don't reject the --help option, so give them /dev/null.
  92 fatal "need GNU m4 1.4 or later: $m4"
  93   if system "$m4 --help </dev/null 2>&1 | grep reload-state >/dev/null";
  94
  95 # Set some high recursion limit as the default limit, 250, has already
  96 # been hit with AC_OUTPUT.  Don't override the user's choice.
  97 $m4 .= ' --nesting-limit=1024'
  98   if " $m4 " !~ / (--nesting-limit(=[0-9]+)?|-L[0-9]*) /;
  99
 100
 101 # @M4_BUILTIN -- M4 builtins and a useful comment.
 102 my @m4_builtin = `echo dumpdef | $m4 2>&1 >/dev/null`;
 103 map { s/:.*//;s/\W// } @m4_builtin;
 104
 105
 106 # %M4_BUILTIN_ALTERNATE_NAME
 107 # --------------------------
 108 # The builtins are renamed, e.g., 'define' is renamed 'm4_define'.
 109 # So map 'define' to 'm4_define' and conversely.
 110 # Some macros don't follow this scheme: be sure to properly map to their
 111 # alternate name too.
 112 #
 113 # FIXME: Trace status of renamed builtins was fixed in M4 1.4.5, which
 114 # we now depend on; do we still need to do this mapping?
 115 #
 116 # So we will merge them, i.e., tracing 'BUILTIN' or tracing
 117 # 'm4_BUILTIN' will be the same: tracing both, but honoring the
 118 # *last* trace specification.
 119 #
 120 # FIXME: This is not enough: in the output '$0' will be 'BUILTIN'
 121 # sometimes and 'm4_BUILTIN' at others.  We should return a unique name,
 122 # the one specified by the user.
 123 #
 124 # FIXME: To be absolutely rigorous, I would say that given that we
 125 # _redefine_ divert (instead of _copying_ it), divert and the like
 126 # should not be part of this list.
 127 my %m4_builtin_alternate_name;
 128 @m4_builtin_alternate_name{"$_", "m4_$_"} = ("m4_$_", "$_")
 129   foreach (grep { !/m4wrap|m4exit|dnl|ifelse|__.*__/ } @m4_builtin);
 130 @m4_builtin_alternate_name{"ifelse", "m4_if"}   = ("m4_if", "ifelse");
 131 @m4_builtin_alternate_name{"m4exit", "m4_exit"} = ("m4_exit", "m4exit");
 132 @m4_builtin_alternate_name{"m4wrap", "m4_wrap"} = ("m4_wrap", "m4wrap");
 133
 134
 135 # $HELP
 136 # -----
 137 $help = "Usage: $0 [OPTION]... [FILES]
 138
 139 Run GNU M4 on the FILES, avoiding useless runs.  Output the traces if tracing,
 140 the frozen file if freezing, otherwise the expansion of the FILES.
 141
 142 If some of the FILES are named 'FILE.m4f' they are considered to be M4
 143 frozen files of all the previous files (which are therefore not loaded).
 144 If 'FILE.m4f' is not found, then 'FILE.m4' will be used, together with
 145 all the previous files.
 146
 147 Some files may be optional, i.e., will only be processed if found in the
 148 include path, but then must end in '.m4?';  the question mark is not part
 149 of the actual file name.
 150
 151 Operation modes:
 152   -h, --help               print this help, then exit
 153   -V, --version            print version number, then exit
 154   -v, --verbose            verbosely report processing
 155   -d, --debug              don't remove temporary files
 156   -o, --output=FILE        save output in FILE (defaults to '-', stdout)
 157   -f, --force              don't rely on cached values
 158   -W, --warnings=CATEGORY  report the warnings falling in CATEGORY
 159   -l, --language=LANG      specify the set of M4 macros to use
 160   -C, --cache=DIRECTORY    preserve results for future runs in DIRECTORY
 161       --no-cache           disable the cache
 162   -m, --mode=OCTAL         change the non trace output file mode (0666)
 163   -M, --melt               don't use M4 frozen files
 164
 165 Languages include:
 166   'Autoconf'   create Autoconf configure scripts
 167   'Autotest'   create Autotest test suites
 168   'M4sh'       create M4sh shell scripts
 169   'M4sugar'    create M4sugar output
 170
 171 " . Autom4te::ChannelDefs::usage . "
 172
 173 The environment variables 'M4' and 'WARNINGS' are honored.
 174
 175 Library directories:
 176   -B, --prepend-include=DIR  prepend directory DIR to search path
 177   -I, --include=DIR          append directory DIR to search path
 178
 179 Tracing:
 180   -t, --trace=MACRO[:FORMAT]  report the MACRO invocations
 181   -p, --preselect=MACRO       prepare to trace MACRO in a future run
 182
 183 Freezing:
 184   -F, --freeze   produce an M4 frozen state file for FILES
 185
 186 FORMAT defaults to '\$f:\$l:\$n:\$%', and can use the following escapes:
 187   \$\$     literal \$
 188   \$f     file where macro was called
 189   \$l     line where macro was called
 190   \$d     nesting depth of macro call
 191   \$n     name of the macro
 192   \$NUM   argument NUM, unquoted and with newlines
 193   \$SEP\@  all arguments, with newlines, quoted, and separated by SEP
 194   \$SEP*  all arguments, with newlines, unquoted, and separated by SEP
 195   \$SEP%  all arguments, without newlines, unquoted, and separated by SEP
 196 SEP can be empty for the default (comma for \@ and *, colon for %),
 197 a single character for that character, or {STRING} to use a string.
 198
 199 Report bugs to <bug-autoconf\@gnu.org>.
 200 GNU Autoconf home page: <http://www.gnu.org/software/autoconf/>.
 201 General help using GNU software: <http://www.gnu.org/gethelp/>.
 202 ";
 203
 204 # $VERSION
 205 # --------
 206 $version =  <<"EOF";
 207 autom4te (@PACKAGE_NAME@) @VERSION@
 208 Copyright (C) @RELEASE_YEAR@ Free Software Foundation, Inc.
 209 License GPLv3+/Autoconf: GNU GPL version 3 or later
 210 <http://gnu.org/licenses/gpl.html>, <http://gnu.org/licenses/exceptions.html>
 211 This is free software: you are free to change and redistribute it.
 212 There is NO WARRANTY, to the extent permitted by law.
 213
 214 Written by Akim Demaille.
 215 EOF
 216
 217
 218 ## ---------- ##
 219 ## Routines.  ##
 220 ## ---------- ##
 221
 222
 223 # $OPTION
 224 # files_to_options (@FILE)
 225 # ------------------------
 226 # Transform Autom4te conventions (e.g., using foo.m4f to designate a frozen
 227 # file) into a suitable command line for M4 (e.g., using --reload-state).
 228 # parse_args guarantees that we will see at most one frozen file, and that
 229 # if a frozen file is present, it is the first argument.
 230 sub files_to_options (@)
 231 {
 232   my (@file) = @_;
 233   my @res;
 234   foreach my $file (@file)
 235     {
 236       my $arg = shell_quote ($file);
 237       if ($file =~ /\.m4f$/)
 238         {
 239           $arg = "--reload-state=$arg";
 240           # If the user downgraded M4 from 1.6 to 1.4.x after freezing
 241           # the file, then we ensure the frozen __m4_version__ will
 242           # not cause m4_init to make the wrong decision about the
 243           # current M4 version.
 244           $arg .= " --undefine=__m4_version__"
 245             unless grep {/__m4_version__/} @m4_builtin;
 246         }
 247       push @res, $arg;
 248     }
 249   return join ' ', @res;
 250 }
 251
 252
 253 # load_configuration ($FILE)
 254 # --------------------------
 255 # Load the configuration $FILE.
 256 sub load_configuration ($)
 257 {
 258   my ($file) = @_;
 259   use Text::ParseWords;
 260
 261   my $cfg = new Autom4te::XFile ($file, "<");
 262   my $lang;
 263   while ($_ = $cfg->getline)
 264     {
 265       chomp;
 266       # Comments.
 267       next
 268         if /^\s*(\#.*)?$/;
 269
 270       my @words = shellwords ($_);
 271       my $type = shift @words;
 272       if ($type eq 'begin-language:')
 273         {
 274           fatal "$file:$.: end-language missing for: $lang"
 275             if defined $lang;
 276           $lang = lc $words[0];
 277         }
 278       elsif ($type eq 'end-language:')
 279         {
 280           error "$file:$.: end-language mismatch: $lang"
 281             if $lang ne lc $words[0];
 282           $lang = undef;
 283         }
 284       elsif ($type eq 'args:')
 285         {
 286           fatal "$file:$.: no current language"
 287             unless defined $lang;
 288           push @{$language{$lang}}, @words;
 289         }
 290       else
 291         {
 292           error "$file:$.: unknown directive: $type";
 293         }
 294     }
 295 }
 296
 297
 298 # parse_args ()
 299 # -------------
 300 # Process any command line arguments.
 301 sub parse_args ()
 302 {
 303   # We want to look for the early options, which should not be found
 304   # in the configuration file.  Prepend to the user arguments.
 305   # Perform this repeatedly so that we can use --language in language
 306   # definitions.  Beware that there can be several --language
 307   # invocations.
 308   my @language;
 309   do {
 310     @language = ();
 311     use Getopt::Long;
 312     Getopt::Long::Configure ("pass_through", "permute");
 313     GetOptions ("l|language=s" => \@language);
 314
 315     foreach (@language)
 316       {
 317         error "unknown language: $_"
 318           unless exists $language{lc $_};
 319         unshift @ARGV, @{$language{lc $_}};
 320       }
 321   } while @language;
 322
 323   # --debug is useless: it is parsed below.
 324   if (exists $ENV{'AUTOM4TE_DEBUG'})
 325     {
 326       print STDERR "$me: concrete arguments:\n";
 327       foreach my $arg (@ARGV)
 328         {
 329           print STDERR "| $arg\n";
 330         }
 331     }
 332
 333   # Process the arguments for real this time.
 334   my @trace;
 335   my @prepend_include;
 336   parse_WARNINGS;
 337   getopt
 338     (
 339      # Operation modes:
 340      "o|output=s"   => \$output,
 341      "W|warnings=s" => \&parse_warnings,
 342      "m|mode=s"     => \$mode,
 343      "M|melt"       => \$melt,
 344
 345      # Library directories:
 346      "B|prepend-include=s" => \@prepend_include,
 347      "I|include=s"         => \@include,
 348
 349      # Tracing:
 350      # Using a hash for traces is seducing.  Unfortunately, upon '-t FOO',
 351      # instead of mapping 'FOO' to undef, Getopt maps it to '1', preventing
 352      # us from distinguishing '-t FOO' from '-t FOO=1'.  So let's do it
 353      # by hand.
 354      "t|trace=s"     => \@trace,
 355      "p|preselect=s" => \@preselect,
 356
 357      # Freezing.
 358      "F|freeze" => \$freeze,
 359
 360      # Caching.
 361      "C|cache=s" => \$cache,
 362      "no-cache"  => sub { $cache = undef; },
 363     );
 364
 365   fatal "too few arguments
 366 Try '$me --help' for more information."
 367     unless @ARGV;
 368
 369   # Freezing:
 370   # We cannot trace at the same time (well, we can, but it sounds insane).
 371   # And it implies melting: there is risk not to update properly using
 372   # old frozen files, and worse yet: we could load a frozen file and
 373   # refreeze it!  A sort of caching :)
 374   fatal "cannot freeze and trace"
 375     if $freeze && @trace;
 376   $melt = 1
 377     if $freeze;
 378
 379   # Names of the cache directory, cache directory index, trace cache
 380   # prefix, and output cache prefix.  If the cache is not to be
 381   # preserved, default to a temporary directory (automatically removed
 382   # on exit).
 383   $cache = $tmp
 384     unless $cache;
 385   $icache = "$cache/requests";
 386   $tcache = "$cache/traces.";
 387   $ocache = "$cache/output.";
 388
 389   # Normalize the includes: the first occurrence is enough, several is
 390   # a pain since it introduces a useless difference in the path which
 391   # invalidates the cache.  And strip '.' which is implicit and always
 392   # first.
 393   @include = grep { !/^\.$/ } uniq (reverse(@prepend_include), @include);
 394
 395   # Convert @trace to %trace, and work around the M4 builtins tracing
 396   # problem.
 397   # The default format is '$f:$l:$n:$%'.
 398   foreach (@trace)
 399     {
 400       /^([^:]+)(?::(.*))?$/ms;
 401       $trace{$1} = defined $2 ? $2 : '$f:$l:$n:$%';
 402       $trace{$m4_builtin_alternate_name{$1}} = $trace{$1}
 403         if exists $m4_builtin_alternate_name{$1};
 404     }
 405
 406   # Work around the M4 builtins tracing problem for @PRESELECT.
 407   # FIXME: Is this still needed, now that we rely on M4 1.4.5?
 408   push (@preselect,
 409         map { $m4_builtin_alternate_name{$_} }
 410         grep { exists $m4_builtin_alternate_name{$_} } @preselect);
 411
 412   # If we find frozen files, then all the files before it are
 413   # discarded: the frozen file is supposed to include them all.
 414   #
 415   # We don't want to depend upon m4's --include to find the top level
 416   # files, so we use 'find_file' here.  Try to get a canonical name,
 417   # as it's part of the key for caching.  And some files are optional
 418   # (also handled by 'find_file').
 419   my @argv;
 420   foreach (@ARGV)
 421     {
 422       if ($_ eq '-')
 423         {
 424           push @argv, $_;
 425         }
 426       elsif (/\.m4f$/)
 427         {
 428           # Frozen files are optional => pass a '?' to 'find_file'.
 429           my $file = find_file ("$_?", @include);
 430           if (!$melt && $file)
 431             {
 432               @argv = ($file);
 433             }
 434           else
 435             {
 436               s/\.m4f$/.m4/;
 437               push @argv, find_file ($_, @include);
 438             }
 439         }
 440       else
 441         {
 442           my $file = find_file ($_, @include);
 443           push @argv, $file
 444             if $file;
 445         }
 446     }
 447   @ARGV = @argv;
 448 }
 449
 450
 451 # handle_m4 ($REQ, @MACRO)
 452 # ------------------------
 453 # Run m4 on the input files, and save the traces on the @MACRO.
 454 sub handle_m4 ($@)
 455 {
 456   my ($req, @macro) = @_;
 457
 458   # GNU m4 appends when using --debugfile/--error-output.
 459   unlink ($tcache . $req->id . "t");
 460
 461   # Run m4.
 462   #
 463   # We don't output directly to the cache files, to avoid problems
 464   # when we are interrupted (that leaves corrupted files).
 465   xsystem ("$m4 @M4_GNU@"
 466            . join (' --include=', '', map { shell_quote ($_) } @include)
 467            . ' --debug=aflq'
 468            . (!exists $ENV{'AUTOM4TE_NO_FATAL'} ? ' --fatal-warning' : '')
 469            . " @M4_DEBUGFILE@=" . shell_quote ("$tcache" . $req->id . "t")
 470            . join (' --trace=', '', map { shell_quote ($_) } sort @macro)
 471            . " " . files_to_options (@ARGV)
 472            . " > " . shell_quote ("$ocache" . $req->id . "t"));
 473
 474   # Everything went ok: preserve the outputs.
 475   foreach my $file (map { $_ . $req->id } ($tcache, $ocache))
 476     {
 477       use File::Copy;
 478       move ("${file}t", "$file")
 479         or fatal "cannot rename ${file}t as $file: $!";
 480     }
 481 }
 482
 483
 484 # warn_forbidden ($WHERE, $WORD, %FORBIDDEN)
 485 # ------------------------------------------
 486 # $WORD is forbidden.  Warn with a dedicated error message if in
 487 # %FORBIDDEN, otherwise a simple 'error: possibly undefined macro'
 488 # will do.
 489 my $first_warn_forbidden = 1;
 490 sub warn_forbidden ($$%)
 491 {
 492   my ($where, $word, %forbidden) = @_;
 493   my $message;
 494
 495   for my $re (sort keys %forbidden)
 496     {
 497       if ($word =~ $re)
 498         {
 499           $message = $forbidden{$re};
 500           last;
 501         }
 502     }
 503   $message ||= "possibly undefined macro: $word";
 504   warn "$where: error: $message\n";
 505   if ($first_warn_forbidden)
 506     {
 507       warn <<EOF;
 508       If this token and others are legitimate, please use m4_pattern_allow.
 509       See the Autoconf documentation.
 510 EOF
 511       $first_warn_forbidden = 0;
 512     }
 513 }
 514
 515
 516 # handle_output ($REQ, $OUTPUT)
 517 # -----------------------------
 518 # Run m4 on the input files, perform quadrigraphs substitution, check for
 519 # forbidden tokens, and save into $OUTPUT.
 520 sub handle_output ($$)
 521 {
 522   my ($req, $output) = @_;
 523
 524   verb "creating $output";
 525
 526   # Load the forbidden/allowed patterns.
 527   handle_traces ($req, "$tmp/patterns",
 528                  ('m4_pattern_forbid' => 'forbid:$1:$2',
 529                   'm4_pattern_allow'  => 'allow:$1'));
 530   my @patterns = new Autom4te::XFile ("$tmp/patterns", "<")->getlines;
 531   chomp @patterns;
 532   my %forbidden =
 533     map { /^forbid:([^:]+):.+$/ => /^forbid:[^:]+:(.+)$/ } @patterns;
 534   my $forbidden = join ('|', map { /^forbid:([^:]+)/ } @patterns) || "^\$";
 535   my $allowed   = join ('|', map { /^allow:([^:]+)/  } @patterns) || "^\$";
 536
 537   verb "forbidden tokens: $forbidden";
 538   verb "forbidden token : $_ => $forbidden{$_}"
 539     foreach (sort keys %forbidden);
 540   verb "allowed   tokens: $allowed";
 541
 542   # Read the (cached) raw M4 output, produce the actual result.  We
 543   # have to use the 2nd arg to have Autom4te::XFile honor the third, but then
 544   # stdout is to be handled by hand :(.  Don't use fdopen as it means
 545   # we will close STDOUT, which we already do in END.
 546   my $out = new Autom4te::XFile;
 547   if ($output eq '-')
 548     {
 549       $out->open (">$output");
 550     }
 551   else
 552     {
 553       $out->open ($output, O_CREAT | O_WRONLY | O_TRUNC, oct ($mode));
 554     }
 555   fatal "cannot create $output: $!"
 556     unless $out;
 557   my $in = new Autom4te::XFile ($ocache . $req->id, "<");
 558
 559   my %prohibited;
 560   my $res;
 561   while ($_ = $in->getline)
 562     {
 563       s/\s+$//;
 564       s/__oline__/$./g;
 565       s/\@<:\@/[/g;
 566       s/\@:>\@/]/g;
 567       s/\@\{:\@/(/g;
 568       s/\@:\}\@/)/g;
 569       s/\@S\|\@/\$/g;
 570       s/\@%:\@/#/g;
 571
 572       $res = $_;
 573
 574       # Don't complain in comments.  Well, until we have something
 575       # better, don't consider '#include' etc. are comments.
 576       s/\#.*//
 577         unless /^\#\s*(if|include|endif|ifdef|ifndef|define)\b/;
 578       foreach (split (/\W+/))
 579         {
 580           $prohibited{$_} = $.
 581             if !/^$/ && /$forbidden/o && !/$allowed/o && ! exists $prohibited{$_};
 582         }
 583
 584       # Performed *last*: the empty quadrigraph.
 585       $res =~ s/\@&t\@//g;
 586
 587       print $out "$res\n";
 588     }
 589
 590   $out->close();
 591
 592   # If no forbidden words, we're done.
 593   return
 594     if ! %prohibited;
 595
 596   # Locate the forbidden words in the last input file.
 597   # This is unsatisfying but...
 598   $exit_code = 1;
 599   if ($ARGV[$#ARGV] ne '-')
 600     {
 601       my $prohibited = '\b(' . join ('|', keys %prohibited) . ')\b';
 602       my $file = new Autom4te::XFile ($ARGV[$#ARGV], "<");
 603
 604       while ($_ = $file->getline)
 605         {
 606           # Don't complain in comments.  Well, until we have something
 607           # better, don't consider '#include' etc. to be comments.
 608           s/\#.*//
 609             unless /^\#(if|include|endif|ifdef|ifndef|define)\b/;
 610
 611           # Complain once per word, but possibly several times per line.
 612           while (/$prohibited/)
 613             {
 614               my $word = $1;
 615               warn_forbidden ("$ARGV[$#ARGV]:$.", $word, %forbidden);
 616               delete $prohibited{$word};
 617               # If we're done, exit.
 618               return
 619                 if ! %prohibited;
 620               $prohibited = '\b(' . join ('|', keys %prohibited) . ')\b';
 621             }
 622         }
 623     }
 624   warn_forbidden ("$output:$prohibited{$_}", $_, %forbidden)
 625     foreach (sort { $prohibited{$a} <=> $prohibited{$b} } keys %prohibited);
 626 }
 627
 628
 629 ## --------------------- ##
 630 ## Handling the traces.  ##
 631 ## --------------------- ##
 632
 633
 634 # $M4_MACRO
 635 # trace_format_to_m4 ($FORMAT)
 636 # ----------------------------
 637 # Convert a trace $FORMAT into a M4 trace processing macro's body.
 638 sub trace_format_to_m4 ($)
 639 {
 640   my ($format) = @_;
 641   my $underscore = $_;
 642   my %escape = (# File name.
 643                 'f' => '$1',
 644                 # Line number.
 645                 'l' => '$2',
 646                 # Depth.
 647                 'd' => '$3',
 648                 # Name (also available as $0).
 649                 'n' => '$4',
 650                 # Escaped dollar.
 651                 '$' => '$');
 652
 653   my $res = '';
 654   $_ = $format;
 655   while ($_)
 656     {
 657       # $n -> $(n + 4)
 658       if (s/^\$(\d+)//)
 659         {
 660           $res .= "\$" . ($1 + 4);
 661         }
 662       # $x, no separator given.
 663       elsif (s/^\$([fldn\$])//)
 664         {
 665           $res .= $escape{$1};
 666         }
 667       # $.x or ${sep}x.
 668       elsif (s/^\$\{([^}]*)\}([@*%])//
 669             || s/^\$(.?)([@*%])//)
 670         {
 671           # $@, list of quoted effective arguments.
 672           if ($2 eq '@')
 673             {
 674               $res .= ']at_at([' . ($1 ? $1 : ',') . '], $@)[';
 675             }
 676           # $*, list of unquoted effective arguments.
 677           elsif ($2 eq '*')
 678             {
 679               $res .= ']at_star([' . ($1 ? $1 : ',') . '], $@)[';
 680             }
 681           # $%, list of flattened unquoted effective arguments.
 682           elsif ($2 eq '%')
 683             {
 684               $res .= ']at_percent([' . ($1 ? $1 : ':') . '], $@)[';
 685             }
 686         }
 687       elsif (/^(\$.)/)
 688         {
 689           error "invalid escape: $1";
 690         }
 691       else
 692         {
 693           s/^([^\$]+)//;
 694           $res .= $1;
 695         }
 696     }
 697
 698   $_ = $underscore;
 699   return '[[' . $res . ']]';
 700 }
 701
 702
 703 # handle_traces($REQ, $OUTPUT, %TRACE)
 704 # ------------------------------------
 705 # We use M4 itself to process the traces.  But to avoid name clashes when
 706 # processing the traces, the builtins are disabled, and moved into 'at_'.
 707 # Actually, all the low level processing macros are in 'at_' (and '_at_').
 708 # To avoid clashes between user macros and 'at_' macros, the macros which
 709 # implement tracing are in 'AT_'.
 710 #
 711 # Having $REQ is needed to neutralize the macros which have been traced,
 712 # but are not wanted now.
 713 sub handle_traces ($$%)
 714 {
 715   my ($req, $output, %trace) = @_;
 716
 717   verb "formatting traces for '$output': " . join (', ', sort keys %trace);
 718
 719   # Processing the traces.
 720   my $trace_m4 = new Autom4te::XFile ("$tmp/traces.m4", ">");
 721
 722   $_ = <<'EOF';
 723   divert(-1)
 724   changequote([, ])
 725   # _at_MODE(SEPARATOR, ELT1, ELT2...)
 726   # ----------------------------------
 727   # List the elements, separating then with SEPARATOR.
 728   # MODE can be:
 729   #  'at'       -- the elements are enclosed in brackets.
 730   #  'star'     -- the elements are listed as are.
 731   #  'percent'  -- the elements are 'flattened': spaces are singled out,
 732   #                and no new line remains.
 733   define([_at_at],
 734   [at_ifelse([$#], [1], [],
 735              [$#], [2], [[[$2]]],
 736              [[[$2]][$1]$0([$1], at_shift(at_shift($@)))])])
 737
 738   define([_at_percent],
 739   [at_ifelse([$#], [1], [],
 740              [$#], [2], [at_flatten([$2])],
 741              [at_flatten([$2])[$1]$0([$1], at_shift(at_shift($@)))])])
 742
 743   define([_at_star],
 744   [at_ifelse([$#], [1], [],
 745              [$#], [2], [[$2]],
 746              [[$2][$1]$0([$1], at_shift(at_shift($@)))])])
 747
 748   # FLATTEN quotes its result.
 749   # Note that the second pattern is 'newline, tab or space'.  Don't lose
 750   # the tab!
 751   define([at_flatten],
 752   [at_patsubst(at_patsubst([[[$1]]], [\\\n]), [[\n\t ]+], [ ])])
 753
 754   define([at_args],    [at_shift(at_shift(at_shift(at_shift(at_shift($@)))))])
 755   define([at_at],      [_$0([$1], at_args($@))])
 756   define([at_percent], [_$0([$1], at_args($@))])
 757   define([at_star],    [_$0([$1], at_args($@))])
 758
 759 EOF
 760   s/^  //mg;s/\\t/\t/mg;s/\\n/\n/mg;
 761   print $trace_m4 $_;
 762
 763   # If you trace 'define', then on 'define([m4_exit], defn([m4exit])' you
 764   # will produce
 765   #
 766   #    AT_define([m4sugar.m4], [115], [1], [define], [m4_exit], <m4exit>)
 767   #
 768   # Since '<m4exit>' is not quoted, the outer m4, when processing
 769   # 'trace.m4' will exit prematurely.  Hence, move all the builtins to
 770   # the 'at_' name space.
 771
 772   print $trace_m4 "# Copy the builtins.\n";
 773   map { print $trace_m4 "define([at_$_], defn([$_]))\n" } @m4_builtin;
 774   print $trace_m4 "\n";
 775
 776   print $trace_m4 "# Disable them.\n";
 777   map { print $trace_m4 "at_undefine([$_])\n" } @m4_builtin;
 778   print $trace_m4 "\n";
 779
 780
 781   # Neutralize traces: we don't want traces of cached requests (%REQUEST).
 782   print $trace_m4
 783    "## -------------------------------------- ##\n",
 784    "## By default neutralize all the traces.  ##\n",
 785    "## -------------------------------------- ##\n",
 786    "\n";
 787   print $trace_m4 "at_define([AT_$_], [at_dnl])\n"
 788     foreach (sort keys %{$req->macro});
 789   print $trace_m4 "\n";
 790
 791   # Implement traces for current requests (%TRACE).
 792   print $trace_m4
 793     "## ------------------------- ##\n",
 794     "## Trace processing macros.  ##\n",
 795     "## ------------------------- ##\n",
 796     "\n";
 797   foreach (sort keys %trace)
 798     {
 799       # Trace request can be embed \n.
 800       (my $comment = "Trace $_:$trace{$_}") =~ s/^/\# /;
 801       print $trace_m4 "$comment\n";
 802       print $trace_m4 "at_define([AT_$_],\n";
 803       print $trace_m4 trace_format_to_m4 ($trace{$_}) . ")\n\n";
 804     }
 805   print $trace_m4 "\n";
 806
 807   # Reenable output.
 808   print $trace_m4 "at_divert(0)at_dnl\n";
 809
 810   # Transform the traces from m4 into an m4 input file.
 811   # Typically, transform:
 812   #
 813   # | m4trace:configure.ac:3: -1- AC_SUBST([exec_prefix], [NONE])
 814   #
 815   # into
 816   #
 817   # | AT_AC_SUBST([configure.ac], [3], [1], [AC_SUBST], [exec_prefix], [NONE])
 818   #
 819   # Pay attention that the file name might include colons, if under DOS
 820   # for instance, so we don't use '[^:]+'.
 821   my $traces = new Autom4te::XFile ($tcache . $req->id, "<");
 822   while ($_ = $traces->getline)
 823     {
 824       # Trace with arguments, as the example above.  We don't try
 825       # to match the trailing parenthesis as it might be on a
 826       # separate line.
 827       s{^m4trace:(.+):(\d+): -(\d+)- ([^(]+)\((.*)$}
 828        {AT_$4([$1], [$2], [$3], [$4], $5};
 829       # Traces without arguments, always on a single line.
 830       s{^m4trace:(.+):(\d+): -(\d+)- ([^)]*)\n$}
 831        {AT_$4([$1], [$2], [$3], [$4])\n};
 832       print $trace_m4 "$_";
 833     }
 834   $trace_m4->close;
 835
 836   my $in = new Autom4te::XFile ("$m4 " . shell_quote ("$tmp/traces.m4") . " |");
 837   my $out = new Autom4te::XFile;
 838   if ($output eq '-')
 839     {
 840       $out->open (">$output");
 841     }
 842   else
 843     {
 844       $out->open ($output, ">");
 845     }
 846
 847   # This is dubious: should we really transform the quadrigraphs in
 848   # traces?  It might break balanced [ ] etc. in the output.  The
 849   # consensus seems to be that traces are more useful this way.
 850   while ($_ = $in->getline)
 851     {
 852       # It makes no sense to try to transform __oline__.
 853       s/\@<:\@/[/g;
 854       s/\@:>\@/]/g;
 855       s/\@\{:\@/(/g;
 856       s/\@:\}\@/)/g;
 857       s/\@S\|\@/\$/g;
 858       s/\@%:\@/#/g;
 859       s/\@&t\@//g;
 860       print $out $_;
 861     }
 862 }
 863
 864
 865 # $BOOL
 866 # up_to_date ($REQ)
 867 # -----------------
 868 # Are the cache files of $REQ up to date?
 869 # $REQ is 'valid' if it corresponds to the request and exists, which
 870 # does not mean it is up to date.  It is up to date if, in addition,
 871 # its files are younger than its dependencies.
 872 sub up_to_date ($)
 873 {
 874   my ($req) = @_;
 875
 876   return 0
 877     if ! $req->valid;
 878
 879   my $tfile = $tcache . $req->id;
 880   my $ofile = $ocache . $req->id;
 881
 882   # We can't answer properly if the traces are not computed since we
 883   # need to know what other files were included.  Actually, if any of
 884   # the cache files is missing, we are not up to date.
 885   return 0
 886     if ! -f $tfile || ! -f $ofile;
 887
 888   # The youngest of the cache files must be older than the oldest of
 889   # the dependencies.
 890   my $tmtime = mtime ($tfile);
 891   my $omtime = mtime ($ofile);
 892   my ($file, $mtime) = ($tmtime < $omtime
 893                         ? ($ofile, $omtime) : ($tfile, $tmtime));
 894
 895   # We depend at least upon the arguments.
 896   my @dep = @ARGV;
 897
 898   # stdin is always out of date.
 899   if (grep { $_ eq '-' } @dep)
 900     { return 0 }
 901
 902   # Files may include others.  We can use traces since we just checked
 903   # if they are available.
 904   handle_traces ($req, "$tmp/dependencies",
 905                  ('include'    => '$1',
 906                   'm4_include' => '$1'));
 907   my $deps = new Autom4te::XFile ("$tmp/dependencies", "<");
 908   while ($_ = $deps->getline)
 909     {
 910       chomp;
 911       my $file = find_file ("$_?", @include);
 912       # If a file which used to be included is no longer there, then
 913       # don't say it's missing (it might no longer be included).  But
 914       # of course, that causes the output to be outdated (as if the
 915       # time stamp of that missing file was newer).
 916       return 0
 917         if ! $file;
 918       push @dep, $file;
 919     }
 920
 921   # If $FILE is younger than one of its dependencies, it is outdated.
 922   return up_to_date_p ($file, @dep);
 923 }
 924
 925
 926 ## ---------- ##
 927 ## Freezing.  ##
 928 ## ---------- ##
 929
 930 # freeze ($OUTPUT)
 931 # ----------------
 932 sub freeze ($)
 933 {
 934   my ($output) = @_;
 935
 936   # When processing the file with diversion disabled, there must be no
 937   # output but comments and empty lines.
 938   my $result = xqx ("$m4"
 939                     . ' --fatal-warning'
 940                     . join (' --include=', '', map { shell_quote ($_) } @include)
 941                     . ' --define=divert'
 942                     . " " . files_to_options (@ARGV)
 943                     . ' </dev/null');
 944   $result =~ s/#.*\n//g;
 945   $result =~ s/^\n//mg;
 946
 947   fatal "freezing produced output:\n$result"
 948     if $result;
 949
 950   # If freezing produces output, something went wrong: a bad 'divert',
 951   # or an improper paren etc.
 952   xsystem ("$m4"
 953            . ' --fatal-warning'
 954            . join (' --include=', '', map { shell_quote ($_) } @include)
 955            . " --freeze-state=" . shell_quote ($output)
 956            . " " . files_to_options (@ARGV)
 957            . ' </dev/null');
 958 }
 959
 960 ## -------------- ##
 961 ## Main program.  ##
 962 ## -------------- ##
 963
 964 mktmpdir ('am4t');
 965 load_configuration ($ENV{'AUTOM4TE_CFG'} || "$pkgdatadir/autom4te.cfg");
 966 load_configuration ("$ENV{'HOME'}/.autom4te.cfg")
 967   if exists $ENV{'HOME'} && -f "$ENV{'HOME'}/.autom4te.cfg";
 968 load_configuration (".autom4te.cfg")
 969   if -f ".autom4te.cfg";
 970 parse_args;
 971
 972 # Freezing does not involve the cache.
 973 if ($freeze)
 974   {
 975     freeze ($output);
 976     exit $exit_code;
 977   }
 978
 979 # We need our cache directory.  Don't fail with parallel creation.
 980 if (! -d "$cache")
 981   {
 982     mkdir "$cache", 0755
 983       or -d "$cache"
 984       or fatal "cannot create $cache: $!";
 985   }
 986
 987 # Open the index for update, and lock it.  autom4te handles several
 988 # files, but the index is the first and last file to be updated, so
 989 # locking it is sufficient.
 990 $icache_file = new Autom4te::XFile $icache, O_RDWR|O_CREAT;
 991 $icache_file->lock (LOCK_EX)
 992   if ($flock_implemented eq "yes");
 993
 994 # Read the cache index if available and older than autom4te itself.
 995 # If autom4te is younger, then some structures such as C4che might
 996 # have changed, which would corrupt its processing.
 997 Autom4te::C4che->load ($icache_file)
 998   if -f $icache && mtime ($icache) > mtime ($0);
 999
1000 # Add the new trace requests.
1001 my $req = Autom4te::C4che->request ('input' => \@ARGV,
1002                                     'path'  => \@include,
1003                                     'macro' => [keys %trace, @preselect]);
1004
1005 # If $REQ's cache files are not up to date, or simply if the user
1006 # discarded them (-f), declare it invalid.
1007 $req->valid (0)
1008   if $force || ! up_to_date ($req);
1009
1010 # We now know whether we can trust the Request object.  Say it.
1011 verb "the trace request object is:\n" . $req->marshall;
1012
1013 # We need to run M4 if (i) the user wants it (--force), (ii) $REQ is
1014 # invalid.
1015 handle_m4 ($req, keys %{$req->macro})
1016   if $force || ! $req->valid;
1017
1018 # Issue the warnings each time autom4te was run.
1019 my $separator = "\n" . ('-' x 25) . " END OF WARNING " . ('-' x 25) . "\n\n";
1020 handle_traces ($req, "$tmp/warnings",
1021                ('_m4_warn' => "\$1::\$f:\$l::\$2::\$3$separator"));
1022 # Swallow excessive newlines.
1023 for (split (/\n*$separator\n*/o, contents ("$tmp/warnings")))
1024 {
1025   # The message looks like:
1026   # | syntax::input.as:5::ouch
1027   # | ::input.as:4: baz is expanded from...
1028   # | input.as:2: bar is expanded from...
1029   # | input.as:3: foo is expanded from...
1030   # | input.as:5: the top level
1031   # In particular, m4_warn guarantees that either $stackdump is empty, or
1032   # it consists of lines where only the last line ends in "top level".
1033   my ($cat, $loc, $msg, $stacktrace) = split ('::', $_, 4);
1034   msg $cat, $loc, "warning: $msg",
1035     partial => ($stacktrace =~ /top level$/) + 0;
1036   for (split /\n/, $stacktrace)
1037     {
1038       my ($loc, $trace) = split (': ', $_, 2);
1039       msg $cat, $loc, $trace, partial => ($trace !~ /top level$/) + 0;
1040     }
1041 }
1042
1043 # Now output...
1044 if (%trace)
1045   {
1046     # Always produce traces, since even if the output is young enough,
1047     # there is no guarantee that the traces use the same *format*
1048     # (e.g., '-t FOO:foo' and '-t FOO:bar' are both using the same M4
1049     # traces, hence the M4 traces cache is usable, but its formatting
1050     # will yield different results).
1051     handle_traces ($req, $output, %trace);
1052   }
1053 else
1054   {
1055     # Actual M4 expansion, if the user wants it, or if $output is old
1056     # (STDOUT is pretty old).
1057     handle_output ($req, $output)
1058       if $force || mtime ($output) < mtime ($ocache . $req->id);
1059   }
1060
1061 # If we ran up to here, the cache is valid.
1062 $req->valid (1);
1063 Autom4te::C4che->save ($icache_file);
1064
1065 exit $exit_code;
1066
1067 ### Setup "GNU" style for perl-mode and cperl-mode.
1068 ## Local Variables:
1069 ## perl-indent-level: 2
1070 ## perl-continued-statement-offset: 2
1071 ## perl-continued-brace-offset: 0
1072 ## perl-brace-offset: 0
1073 ## perl-brace-imaginary-offset: 0
1074 ## perl-label-offset: -2
1075 ## cperl-indent-level: 2
1076 ## cperl-brace-offset: 0
1077 ## cperl-continued-brace-offset: 0
1078 ## cperl-label-offset: -2
1079 ## cperl-extra-newline-before-brace: t
1080 ## cperl-merge-trailing-else: nil
1081 ## cperl-continued-statement-offset: 2
1082 ## End: