| blob | 8a42c69494bcc90a97cc7cab8cf88dda4c3b53b1 |
1 #! @PERL@ -w
2 # -*- perl -*-
3 # autoupdate - modernize an Autoconf file.
4 # Copyright 1994, 1999, 2000, 2001 Free Software Foundation, Inc.
6 # This program is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2, or (at your option)
9 # any later version.
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program; if not, write to the Free Software
18 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
19 # 02111-1307, USA.
21 # Originally written by David MacKenzie <djm@gnu.ai.mit.edu>.
22 # Rewritten by Akim Demaille <akim@freefriends.org>.
24 use 5.005;
25 use Getopt::Long;
26 use File::Basename;
27 use strict;
29 (my $me = $0) =~ s,.*[\\/],,;
31 # Lib files.
32 my $autoconf_dir = $ENV{"AC_MACRODIR"} || "@datadir@";
33 my $autoconf = '';
34 my $debug = 0;
35 my $localdir = '.';
36 # m4.
37 my $m4 = $ENV{"M4"} || "@M4@";
38 my $verbose = 0;
39 my $SIMPLE_BACKUP_SUFFIX = $ENV{'SIMPLE_BACKUP_SUFFIX'} || '~';
40 my $tmp = '';
43 ## ---------- ##
44 ## Routines. ##
45 ## ---------- ##
48 # &mktmpdir ()
49 # ------------
50 sub mktmpdir ()
51 {
52 my $TMPDIR = $ENV{'TMPDIR'} || '/tmp';
54 # If mktemp supports dirs, use it to please Marc E.
55 $tmp = `(umask 077 && mktemp -d -q "$TMPDIR/auXXXXXX") 2>/dev/null`;
56 chomp $tmp;
58 if (!$tmp || !-d $tmp)
59 {
60 $tmp = "$TMPDIR/au" . int (rand 10000) . ".$$";
61 mkdir $tmp, 0700
62 or die "$me: cannot create $tmp: $!\n";
63 }
65 print STDERR "$me:$$: working in $tmp\n"
66 if $debug;
67 }
70 # END
71 # ---
72 # Exit nonzero whenever closing STDOUT fails.
73 sub END
74 {
75 use POSIX qw (_exit);
77 my ($q) = ($?);
79 # FIXME: Heelp! Can't find a means to properly catch system's
80 # exit status (without hair I mean).
81 # my $status = $? >> 8;
83 if (!$debug && -d $tmp)
84 {
85 unlink <$tmp/*>
86 or warn ("$me: cannot empty $tmp: $!\n"), _exit (1);
87 rmdir $tmp
88 or warn ("$me: cannot remove $tmp: $!\n"), _exit (1);
89 }
91 # This is required if the code might send any output to stdout
92 # E.g., even --version or --help. So it's best to do it unconditionally.
93 close STDOUT
94 or (warn "$me: closing standard output: $!\n"), _exit (1);
96 ($!, $?) = (0, $q);
97 }
100 # print_usage ()
101 # --------------
102 # Display usage (--help).
103 sub print_usage ()
104 {
105 print <<"END";
106 Usage: $0 [OPTION] ... [TEMPLATE-FILE...]
108 Update the TEMPLATE-FILE... if given, or \`configure.ac' if present,
109 or else \`configure.in', to the syntax of the current version of
110 Autoconf. The original files are backed up.
112 Operation modes:
113 -h, --help print this help, then exit
114 -V, --version print version number, then exit
115 -v, --verbose verbosely report processing
116 -d, --debug don't remove temporary files
118 Library directories:
119 -A, --autoconf-dir=ACDIR Autoconf's macro files location (rarely needed)
120 -l, --localdir=DIR location of \`aclocal.m4'
122 Environment variables:
123 M4 GNU M4 1.4 or above
124 AUTOCONF autoconf @VERSION@
126 Report bugs to <bug-autoconf\@gnu.org>.
127 END
128 exit 0;
129 }
132 # print_version ()
133 # ----------------
134 # Display version (--version).
135 sub print_version
136 {
137 print <<END;
138 autoupdate (@PACKAGE_NAME@) @VERSION@
139 Written by David J. MacKenzie and Akim Demaille.
141 Copyright 1994, 1999, 2000, 2001 Free Software Foundation, Inc.
142 This is free software; see the source for copying conditions. There is NO
143 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
144 END
145 exit 0;
146 }
149 # $CONFIGURE_AC
150 # &find_configure_ac ()
151 # ---------------------
152 sub find_configure_ac ()
153 {
154 if (-f 'configure.ac')
155 {
156 if (-f 'configure.in')
157 {
158 warn "warning: `configure.ac' and `configure.in' both present.\n";
159 warn "warning: proceeding with `configure.ac'.\n";
160 }
161 return 'configure.ac';
162 }
163 elsif (-f 'configure.in')
164 {
165 return 'configure.in';
166 }
167 return;
168 }
171 # parse_args ()
172 # -------------
173 # Process any command line arguments.
174 sub parse_args ()
175 {
176 my $srcdir;
177 # F*k. Getopt seems bogus and dies when given `-' with `bundling'.
178 # If fixed some day, use this: '' => sub { push @ARGV, "-" }
179 my $update_stdin = grep /^-$/, @ARGV;
180 @ARGV = grep !/^-$/, @ARGV;
181 Getopt::Long::config ("bundling");
182 Getopt::Long::GetOptions ('A|autoconf-dir|m|macrodir=s' => \$autoconf_dir,
183 'l|localdir=s' => \$localdir,
184 'd|debug' => \$debug,
185 'h|help' => \&print_usage,
186 'V|version' => \&print_version,
187 'v|verbose' => \$verbose)
188 or exit 1;
189 push @ARGV, '-'
190 if $update_stdin;
191 if (! @ARGV)
192 {
193 my $configure_ac = find_configure_ac;
194 die 'no input file'
195 unless $configure_ac;
196 push @ARGV, $configure_ac;
197 }
198 }
201 # find_slaves
202 # -----------
203 # Find the lib files and autoconf.
204 sub find_slaves ()
205 {
206 # Some non-GNU m4's don't reject the --help option, so give them /dev/null.
207 # die "Autoconf requires GNU m4 1.4 or later\n"
208 # if system "$m4 --help </dev/null 2>&1 | fgrep reload-state >/dev/null";
210 # autoconf.
211 (my $dir = $0) =~ s,[^\\/]*$,,;
213 # We test "$dir/autoconf" in case we are in the build tree, in which case
214 # the names are not transformed yet.
215 foreach my $file ($ENV{"AUTOCONF"} || '',
216 "$dir/@autoconf-name@",
217 "$dir/autoconf",
218 "@bindir@/@autoconf-name@")
219 {
220 if (-x $file)
221 {
222 $autoconf = $file;
223 last;
224 }
225 }
227 # This is needed because perl's '-x' isn't a smart as bash's; that
228 # is, it won't find autoconf.sh.
229 $autoconf = 'autoconf'
230 if !$autoconf;
231 }
234 ## -------------- ##
235 ## Main program. ##
236 ## -------------- ##
237 find_slaves;
238 parse_args;
239 mktmpdir;
240 $autoconf .= " --autoconf-dir $autoconf_dir --localdir $localdir";
243 # @M4_BUILTINS -- M4 builtins and a useful comment.
244 my @m4_builtins = `echo dumpdef | $m4 2>&1 >/dev/null`;
245 map { s/:.*//;s/\W// } @m4_builtins;
248 # m4.m4 -- enable the m4 builtins.
249 # unm4.m4 -- disable the m4 builtins.
250 # savem4.m4 -- save the m4 builtins.
251 open M4_M4, ">$tmp/m4.m4"
252 or die "$me: cannot open: $!\n";
253 open UNM4_M4, ">$tmp/unm4.m4"
254 or die "$me: cannot open: $!\n";
255 open M4SAVE_M4, ">$tmp/m4save.m4"
256 or die "$me: cannot open: $!\n";
257 foreach (@m4_builtins)
258 {
259 print M4_M4 "_au_define([$_], _au_defn([_au_$_]))\n";
260 print UNM4_M4 "_au_undefine([$_])\n";
261 print M4SAVE_M4 "define([_au_$_], defn([$_]))\n";
262 }
263 close M4SAVE_M4
264 or die "$me: cannot close: $!\n";
265 close UNM4_M4
266 or die "$me: cannot close: $!\n";
267 close M4_M4
268 or die "$me: cannot close: $!\n";
271 # @AU_MACROS & AC_MACROS -- AU and AC macros and yet another useful comment.
272 open MACROS, ("$autoconf "
273 . "--trace AU_DEFUN:'AU:\$f:\$1' --trace define:'AC:\$f:\$1' "
274 . "-i /dev/null |")
275 or die "$me: cannot open: $!\n";
276 my (%ac_macros, %au_macros);
277 while (<MACROS>)
278 {
279 chomp;
280 /^(AC|AU):(.*):([^:]*)$/ or next;
281 my $filename = basename ($2);
282 if ($1 eq "AC")
283 {
284 $ac_macros{$3} = $filename;
285 }
286 else
287 {
288 $au_macros{$3} = $filename;
289 }
290 }
291 close MACROS
292 or die "$me: cannot close: $!\n";
293 # Don't keep AU macros in @AC_MACROS.
294 delete $ac_macros{$_}
295 foreach (keys %au_macros);
296 if ($debug)
297 {
298 print STDERR "Current Autoconf macros:\n";
299 print STDERR join (' ', sort keys %ac_macros) . "\n\n";
300 print STDERR "Obsolete Autoconf macros:\n";
301 print STDERR join (' ', sort keys %au_macros) . "\n\n";
302 }
304 # $au_changequote -- enable the quote `[', `]' right before any AU macro.
305 my $au_changequote =
306 's/\b(' . join ('|', keys %au_macros) . ')\b/_au_changequote([,])$1/g';
308 # au.m4 -- definitions the AU macros.
309 system ("$autoconf --trace AU_DEFUN:'_au_defun(\@<:\@\$1\@:>\@,
310 \@<:\@\$2\@:>\@)' -i /dev/null "
311 . ">$tmp/au.m4");
313 # ac.m4 -- autoquoting definitions of the AC macros (M4sugar excluded).
314 # disable.m4 -- undefine the macros of AC and m4sugar.
315 open AC_M4, ">$tmp/ac.m4"
316 or die "$me: cannot open: $!\n";
317 open DISABLE_M4, ">$tmp/disable.m4"
318 or die "$me: cannot open: $!\n";
319 foreach (sort keys %ac_macros)
320 {
321 print AC_M4 "_au_define([$_], [[\$0(\$\@)]])\n"
322 unless $ac_macros{$_} eq "m4sugar.m4";
323 print DISABLE_M4 "_au_undefine([$_])\n";
324 }
325 close DISABLE_M4
326 or die "$me: cannot close: $!\n";
327 close AC_M4
328 or die "$me: cannot close: $!\n";
332 ## ------------------- ##
333 ## Process the files. ##
334 ## ------------------- ##
336 foreach my $file (@ARGV)
337 {
338 my $filename = $file;
339 # We need an actual file.
340 if ($file eq '-')
341 {
342 $file = "$tmp/stdin";
343 system "cat >$file";
344 }
345 elsif (! -r "$file")
346 {
347 die "$me: $file: No such file or directory";
348 }
350 # input.m4 -- m4 program to produce the updated file.
351 # Load the values, the dispatcher, neutralize m4, and the prepared
352 # input file.
353 my $input_m4 = <<EOF;
354 divert(-1) -*- Autoconf -*-
355 changequote([, ])
357 # Move all the builtins into the \`_au_' pseudo namespace
358 include([$tmp/m4save.m4])
360 # _au_defun(NAME, BODY)
361 # ---------------------
362 # Define NAME to BODY, plus AU activation/deactivation.
363 _au_define([_au_defun],
364 [_au_define([\$1],
365 [_au_enable()dnl
366 \$2[]dnl
367 _au_disable()])])
369 # Import the definition of the obsolete macros.
370 _au_include([$tmp/au.m4])
373 ## ------------------------ ##
374 ## _au_enable/_au_disable. ##
375 ## ------------------------ ##
377 # They work by pair: each time an AU macro is activated, it runs
378 # _au_enable, and at its end its runs _au_disable (see _au_defun
379 # above). But since AU macros might use AU macros, which should
380 # enable/disable only for the outter AU macros.
381 #
382 # \`_au_enabled' is used to this end, condionning whether we really
383 # enable/disable.
386 # __au_enable
387 # -----------
388 # Reenable the builtins, and m4sugar.
389 _au_define([__au_enable],
390 [_au_divert(-1)
391 # Enable special characters.
392 _au_changecom([#])
394 # Enable the m4 builtins, m4sugar and the autoquoting AC macros.
395 _au_include([$tmp/m4.m4])
396 _au_include([$autoconf_dir/m4sugar.m4])
397 _au_include([$tmp/ac.m4])
399 _au_divert(0)])
401 # _au_enable
402 # ----------
403 # Called at the beginning of all the obsolete macros. Reenable the
404 # builtins, and m4sugar if needed.
405 _au_define([_au_enable],
406 [_au_ifdef([_au_enabled],
407 [],
408 [__au_enable()])_au_dnl
409 _au_pushdef([_au_enabled])])
412 # __au_disable
413 # ------------
414 # Disable the builtins, and m4sugar.
415 _au_define([__au_disable],
416 [_au_divert(-1)
417 # Disable m4sugar, the AC autoquoting macros, and m4.
418 _au_include([$tmp/disable.m4])
419 _au_include([$tmp/unm4.m4])
421 # Disable special characters.
422 _au_changequote()
423 _au_changecom()
425 _au_divert(0)])
427 # _au_disable
428 # -----------
429 # Called at the end of all the obsolete macros. Disable the
430 # builtins, and m4sugar if needed..
431 _au_define([_au_disable],
432 [_au_popdef([_au_enabled])_au_dnl
433 _au_ifdef([_au_enabled],
434 [],
435 [__au_disable()])])
438 ## ------------------------------- ##
439 ## Disable, and process the file. ##
440 ## ------------------------------- ##
441 _au_disable()_au_dnl
442 EOF
444 $input_m4 =~ s/^ //mg;
446 # prepared input -- input, but reenables the quote before each AU macro.
447 open INPUT_M4, ">$tmp/input.m4"
448 or die "$me: cannot open: $!\n";
449 open FILE, "<$file"
450 or die "$me: cannot open: $!\n";
451 print INPUT_M4 "$input_m4";
452 while (<FILE>)
453 {
454 eval $au_changequote;
455 print INPUT_M4;
456 }
457 close FILE
458 or die "$me: cannot close: $!\n";
459 close INPUT_M4
460 or die "$me: cannot close: $!\n";
462 # Now ask m4 to perform the update.
463 print STDERR "$me: running $m4 $tmp/input.m4\n"
464 if $verbose;
465 if (system ("$m4 $tmp/input.m4 >$tmp/updated"))
466 {
467 # Exit status of system() is in the upper byte.
468 $! >>= 8;
469 die "$me: cannot update \`$filename'\n";
470 };
472 if ("$file" eq "$tmp/stdin")
473 {
474 system ("cat $tmp/updated");
475 }
476 elsif (! system ("cmp -s $tmp/updated $file"))
477 {
478 # File didn't change, so don't update its mod time.
479 print STDERR "$me: \`$file' is unchanged\n"
480 }
481 else
482 {
483 # Back up and install the new one.
484 if (system ("mv $file $file${SIMPLE_BACKUP_SUFFIX} && "
485 . "mv $tmp/updated $file") == 0)
486 {
487 print STDERR "$me: \`$file' is updated\n";
488 }
489 else
490 {
491 die "$me: cannot update \`$file'\n";
492 }
493 }
494 }
496 exit 0;
499 # ## ---------------------------- ##
500 # ## How `autoupdate' functions. ##
501 # ## ---------------------------- ##
502 #
503 # The task of `autoupdate' is not trivial: the biggest difficulty being
504 # that you must limit the changes to the parts that really need to be
505 # updated. Finding a satisfying implementation proved to be quite hard,
506 # as this is the fourth implementation of `autoupdate'.
507 #
508 # Below, we will use a simple example of obsolete macro:
509 #
510 # AU_DEFUN([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))])
511 # AC_DEFUN([NEW], [echo "sum($1) = $2"])
512 #
513 # the input file contains
514 #
515 # dnl The Unbelievable Truth
516 # OLD(1, 2)
517 # NEW([0, 0], [0])
518 #
519 # Of course the expected output is
520 #
521 # dnl The Unbelievable Truth
522 # NEW([1, 2], [3])
523 # NEW([0, 0], [0])
524 #
525 #
526 # # First implementation: sed
527 # # =========================
528 #
529 # The first implementation was only able to change the name of obsolete
530 # macros.
531 #
532 # The file `acoldnames.m4' defined the old names based on the new names.
533 # It was simple then to produce a sed script such as:
534 #
535 # s/OLD/NEW/g
536 #
537 # Updating merely consisted in running this script on the file to
538 # update.
539 #
540 # This scheme suffers an obvious limitation: that `autoupdate' was
541 # unable to cope with new macros that just swap some of its arguments
542 # compared to the old macro. Fortunately, that was enough to upgrade
543 # from Autoconf 1 to Autoconf 2. (But I have no idea whether the
544 # changes in Autoconf 2 were precisely limited by this constraint.)
545 #
546 #
547 # # Second implementation: hooks
548 # # ============================
549 #
550 # The version 2.15 of Autoconf brought a vast number of changes compared
551 # to 2.13, so a solution was needed. One could think to extend the
552 # `sed' scripts with specialized code for complex macros. But this
553 # approach is of course full of flaws:
554 #
555 # a. the Autoconf maintainers have to write these snippets, which we
556 # just don't want to,
557 #
558 # b. I really don't think you'll ever manage to handle the quoting of
559 # m4 from sed.
560 #
561 # To satisfy a., let's remark that the code which implements the old
562 # features in term of the new feature is exactly the code which should
563 # replace the old code.
564 #
565 # To answer point b, as usual in the history of Autoconf, the answer, at
566 # least on the paper, is simple: m4 is the best tool to parse m4, so
567 # let's use m4.
568 #
569 # Therefore the specification is:
570 #
571 # I want to be able to tell Autoconf, well, m4, that the macro I
572 # am currently defining is an obsolete macro (so that the user is
573 # warned), which code is the code to use when running autoconf,
574 # but that the very same code has to be used when running
575 # autoupdate. To summarize, the interface I want is
576 # `AU_DEFUN(OLD-NAME, NEW-CODE)'.
577 #
578 #
579 # Now for the technical details.
580 #
581 # When running autoconf, except for the warning, AU_DEFUN is basically
582 # AC_DEFUN.
583 #
584 # When running autoupdate, we want *only* OLD-NAMEs to be expanded.
585 # This obviously means that acgeneral.m4 and acspecific.m4 must not be
586 # loaded. Nonetheless, because we want to use a rich set of m4
587 # features, m4sugar.m4 is needed. Please note that the fact that
588 # Autoconf's macros are not loaded is positive on two points:
589 #
590 # - we do get an updated `configure.ac', not a `configure'!
591 #
592 # - the old macros are replaced by *calls* to the new-macros, not the
593 # body of the new macros, since their body is not defined!!!
594 # (Whoa, that's really beautiful!).
595 #
596 # Additionally we need to disable the quotes when reading the input for
597 # two reasons: first because otherwise `m4' will swallow the quotes of
598 # other macros:
599 #
600 # NEW([1, 2], 3)
601 # => NEW(1, 2, 3)
602 #
603 # and second, because we want to update the macro calls which are
604 # quoted, i.e., we want
605 #
606 # FOO([OLD(1, 2)])
607 # => FOO([NEW([1, 2], [3])])
608 #
609 # If we don't disable the quotes, only the macros called at the top
610 # level would be updated.
611 #
612 # So, let's disable the quotes.
613 #
614 # Well, not quite: m4sugar.m4 still needs to use quotes for some macros.
615 # Well, in this case, when running in autoupdate code, each macro first
616 # reestablishes the quotes, expands itself, and disables the quotes.
617 #
618 # Thinking a bit more, you realize that in fact, people may use `define'
619 # `ifelse' etc. in their files, and you certainly don't want to process
620 # them. Another example is `dnl': you don't want to remove the
621 # comments. You then realize you don't want exactly to import m4sugar:
622 # you want to specify when it is enabled (macros active), and disabled.
623 # m4sugar provides m4_disable/m4_enable to this end.
624 #
625 # You're getting close to it. Now remains one task: how to handle
626 # twofold definitions?
627 #
628 # Remember that the same AU_DEFUN must be understood in two different
629 # ways, the AC way, and the AU way.
630 #
631 # One first solution is to check whether acgeneral.m4 was loaded. But
632 # that's definitely not cute. Another is simply to install `hooks',
633 # that is to say, to keep in some place m4 knows, late `define' to be
634 # triggered *only* in AU mode.
635 #
636 # You first think to design AU_DEFUN like this:
637 #
638 # 1. AC_DEFUN(OLD-NAME,
639 # [Warn the user OLD-NAME is obsolete.
640 # NEW-CODE])
641 #
642 # 2. Store for late AU binding([define(OLD_NAME,
643 # [Reestablish the quotes.
644 # NEW-CODE
645 # Disable the quotes.])])
646 #
647 # but this will not work: NEW-CODE has probably $1, $2 etc. and these
648 # guys will be replaced with the argument of `Store for late AU binding'
649 # when you call it.
650 #
651 # I don't think there is a means to avoid this using this technology
652 # (remember that $1 etc. are *always* expanded in m4). You may also try
653 # to replace them with $[1] to preserve them for a later evaluation, but
654 # if `Store for late AU binding' is properly written, it will remain
655 # quoted till the end...
656 #
657 # You have to change technology. Since the problem is that `$1'
658 # etc. should be `consumed' right away, one solution is to define now a
659 # second macro, `AU_OLD-NAME', and to install a hook than binds OLD-NAME
660 # to AU_OLD-NAME. Then, autoupdate.m4 just need to run the hooks. By
661 # the way, the same method was used in autoheader.
662 #
663 #
664 # # Third implementation: m4 namespaces by m4sugar
665 # # ==============================================
666 #
667 # Actually, this implementation was just a clean up of the previous
668 # implementation: instead of defining hooks by hand, m4sugar was equipped
669 # with `namespaces'. What are they?
670 #
671 # Sometimes we want to disable some *set* of macros, and restore them
672 # later. We provide support for this via namespaces.
673 #
674 # There are basically three characters playing this scene: defining a
675 # macro in a namespace, disabling a namespace, and restoring a namespace
676 # (i.e., all the definitions it holds).
677 #
678 # Technically, to define a MACRO in NAMESPACE means to define the macro
679 # named `NAMESPACE::MACRO' to the VALUE. At the same time, we append
680 # `undefine(NAME)' in the macro named `m4_disable(NAMESPACE)', and
681 # similarly a binding of NAME to the value of `NAMESPACE::MACRO' in
682 # `m4_enable(NAMESPACE)'. These mechanisms allow to bind the macro of
683 # NAMESPACE and to unbind them at will.
684 #
685 # Of course this implementation is really inefficient: m4 has to grow
686 # strings which can become quickly huge, which slows it significantly.
687 #
688 # In particular one should avoid as much as possible to use `define' for
689 # temporaries. Now that `define' as quite a complex meaning, it is an
690 # expensive operations that should be limited to macros. Use
691 # `m4_define' for temporaries.
692 #
693 # Private copies of the macros we used in entering / exiting the m4sugar
694 # namespace. It is much more convenient than fighting with the renamed
695 # version of define etc.
696 #
697 #
698 #
699 # Those two implementations suffered from serious problems:
700 #
701 # - namespaces were really expensive, and incurred a major performance
702 # loss on `autoconf' itself, not only `autoupdate'. One solution
703 # would have been the limit the use of namespaces to `autoupdate', but
704 # that's again some complications on m4sugar, which really doesn't need
705 # this. So we wanted to get rid of the namespaces.
706 #
707 # - since the quotes were disabled, autoupdate was sometimes making
708 # wrong guesses, for instance on:
709 #
710 # foo([1, 2])
711 #
712 # m4 saw 2 arguments: `[1'and `2]'. A simple solution, somewhat
713 # fragile, is to reestablish the quotes right before all the obsolete
714 # macros, i.e., to use sed so that the previous text becomes
715 #
716 # changequote([, ])foo([1, 2])
717 #
718 # To this end, one wants to trace the definition of obsolete macros.
719 #
720 # It was there that the limitations of the namespace approach became
721 # painful: because it was a complex machinery playing a lot with the
722 # builtins of m4 (hence, quite fragile), tracing was almost impossible.
723 #
724 #
725 # So this approach was dropped.
726 #
727 #
728 # # The fourth implementation: two steps
729 # # ====================================
730 #
731 # If you drop the uses of namespaces, you no longer can compute the
732 # updated value, and replace the old call with it simultaneously.
733 #
734 # Obviously you will use m4 to compute the updated values, but you may
735 # use some other tool to achieve the replacement. Personally, I trust
736 # nobody but m4 to parse m4, so below, m4 will perform the two tasks.
737 #
738 # How can m4 be used to replace *some* macros calls with newer values.
739 # Well, that's dead simple: m4 should learn the definitions of obsolete
740 # macros, forget its builtins, disable the quotes, and then run on the
741 # input file, which amounts to doing this:
742 #
743 # divert(-1)dnl
744 # changequote([, ])
745 # define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
746 # undefine([dnl])
747 # undefine([m4_eval])
748 # # Some more undefines...
749 # changequote()
750 # divert(0)dnl
751 # dnl The Unbelievable Truth
752 # changequote([, ])OLD(1, 2)
753 # NEW([0, 0],
754 # 0)
755 #
756 # which will result in
757 #
758 # dnl The Unbelievable Truth
759 # NEW(1, 2, m4_eval(1 + 2))
760 # NEW([0, 0],
761 # 0)
762 #
763 # Grpmh. Two problems. A minor problem: it would have been much better
764 # to have the `m4_eval' computed, and a major problem: you lost the
765 # quotation in the result.
766 #
767 # Let's address the big problem first. One solution is to define any
768 # modern macro to rewrite its calls with the proper quotation, thanks to
769 # `$@'. Again, tracing the `define's makes it possible to know which
770 # are these macros, so you input is:
771 #
772 # divert(-1)dnl
773 # changequote([, ])
774 # define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
775 # define([NEW], [[NEW($@)]changequote()])
776 # undefine([dnl])
777 # undefine([m4_eval])
778 # # Some more undefines...
779 # changequote()
780 # divert(0)dnl
781 # dnl The Unbelievable Truth
782 # changequote([, ])OLD(1, 2)
783 # changequote([, ])NEW([0, 0],
784 # 0)
785 #
786 # which results in
787 #
788 # dnl The Unbelievable Truth
789 # NEW([1, 2],[m4_eval(1 + 2)])
790 # NEW([0, 0],[0])
791 #
792 # Our problem is solved, i.e., the first call to `NEW' is properly
793 # quoted, but introduced another problem: we changed the layout of the
794 # second calls, which can be a drama in the case of huge macro calls
795 # (think of `AC_TRY_RUN' for instance). This example didn't show it,
796 # but we also introduced parens to macros which did not have some:
797 #
798 # AC_INIT
799 # => AC_INIT()
800 #
801 # No big deal for the semantics (unless the macro depends upon $#, which
802 # is bad), but the users would not be happy.
803 #
804 # Additionally, we introduced quotes that we not there before, which is
805 # OK in most cases, but could change the semantics of the file.
806 #
807 # Cruel dilemma: we do want the auto-quoting definition of `NEW' when
808 # evaluating `OLD', but we don't when we evaluate the second `NEW'.
809 # Back to namespaces?
810 #
811 # No.
812 #
813 #
814 # # Second step: replacement
815 # # ------------------------
816 #
817 # No, as announced above, we will work in two steps: in a first step we
818 # compute the updated values, and in a second step we replace them. Our
819 # goal is something like this:
820 #
821 # divert(-1)dnl
822 # changequote([, ])
823 # define([OLD], [NEW([1, 2], [3])changequote()])
824 # undefine([dnl])
825 # undefine([m4_eval])
826 # # Some more undefines...
827 # changequote()
828 # divert(0)dnl
829 # dnl The Unbelievable Truth
830 # changequote([, ])OLD(1, 2)
831 # NEW([0, 0],
832 # 0)
833 #
834 # i.e., the new value of `OLD' is precomputed using the auto-quoting
835 # definition of `NEW' and the m4 builtins. We'll see how afterwards,
836 # let's finish with the replacement.
837 #
838 # Of course the solution above is wrong: if there were other calls to
839 # `OLD' with different values, we would smash them to the same value.
840 # But it is quite easy to generalize the scheme above:
841 #
842 # divert(-1)dnl
843 # changequote([, ])
844 # define([OLD([1],[2])], [NEW([1, 2], [3])])
845 # define([OLD], [defn([OLD($@)])changequote()])
846 # undefine([dnl])
847 # undefine([m4_eval])
848 # # Some more undefines...
849 # changequote()
850 # divert(0)dnl
851 # dnl The Unbelievable Truth
852 # changequote([, ])OLD(1, 2)
853 # NEW([0, 0],
854 # 0)
855 #
856 # i.e., for each call to obsolete macros, we build an array `call =>
857 # value', and use a macro to dispatch these values. This results in:
858 #
859 # dnl The Unbelievable Truth
860 # NEW([1, 2], [3])
861 # NEW([0, 0],
862 # 0)
863 #
864 # In French, we say `Youpi !', which you might roughly translate as
865 # `yipeee!'.
866 #
867 #
868 # # First step: computation
869 # # -----------------------
870 #
871 # Let's study the anatomy of the file, and name its sections:
872 #
873 # prologue
874 # divert(-1)dnl
875 # changequote([, ])
876 # values
877 # define([OLD([1],[2])], [NEW([1, 2], [3])])
878 # dispatcher
879 # define([OLD], [defn([OLD($@)])changequote()])
880 # disabler
881 # undefine([dnl])
882 # undefine([m4_eval])
883 # # Some more undefines...
884 # changequote()
885 # divert(0)dnl
886 # input
887 # dnl The Unbelievable Truth
888 # changequote([, ])OLD(1, 2)
889 # NEW([0, 0],
890 # 0)
891 #
892 #
893 # # Computing the `values' section
894 # # ..............................
895 #
896 # First we need to get the list of all the AU macro uses. To this end,
897 # first get the list of all the AU macros names by tracing `AU_DEFUN' in
898 # the initialization of autoconf. This list is computed in the file
899 # `au.txt' below.
900 #
901 # Then use this list to trace all the AU macro uses in the input. The
902 # goal is obtain in the case of our example:
903 #
904 # [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
905 #
906 # This is the file `values.in' below.
907 #
908 # We want to evaluate this with only the builtins (in fact m4sugar), the
909 # auto-quoting definitions of the new macros (`new.m4'), and the
910 # definition of the old macros (`old.m4'). Computing these last two
911 # files is easy: it's just a matter of using the right `--trace' option.
912 #
913 # So the content of `values.in' is:
914 #
915 # include($autoconf_dir/m4sugar.m4)
916 # m4_include(new.m4)
917 # m4_include(old.m4)
918 # divert(0)dnl
919 # [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
920 #
921 # We run m4 on it, which yields:
922 #
923 # define([OLD([1],[2])],@<<@NEW([1, 2], [3])@>>@)
924 #
925 # Transform `@<<@' and `@>>@' into quotes and we get
926 #
927 # define([OLD([1],[2])],[NEW([1, 2], [3])])
928 #
929 # This is `values.m4'.
930 #
931 #
932 # # Computing the `dispatcher' section
933 # # ..................................
934 #
935 # The `prologue', and the `disabler' are simple and need no commenting.
936 #
937 # To compute the `dispatcher' (`dispatch.m4'), again, it is a simple
938 # matter of using the right `--trace'.
939 #
940 # Finally, the input is not exactly the input file, rather it is the
941 # input file with the added `changequote'. To this end, we build
942 # `quote.sed'.
943 #
944 #
945 # # Putting it all together
946 # # .......................
947 #
948 # We build the file `input.m4' which contains:
949 #
950 # divert(-1)dnl
951 # changequote([, ])
952 # include(values.m4)
953 # include(dispatch.m4)
954 # undefine([dnl])
955 # undefine([eval])
956 # # Some more undefines...
957 # changequote()
958 # divert(0)dnl
959 # dnl The Unbelievable Truth
960 # changequote([, ])OLD(1, 2)
961 # NEW([0, 0],
962 # 0)
963 #
964 # And we just run m4 on it. Et voila`, Monsieur ! Mais oui, mais oui.
965 #
966 # Well, there are a few additional technicalities. For instance, we
967 # rely on `changequote', `ifelse' and `defn', but we don't want to
968 # interpret the changequotes of the user, so we simply use another name:
969 # `_au_changequote' etc.
970 #
971 #
972 # # Failure of the fourth approach
973 # # ------------------------------
974 #
975 # This approach is heavily based on traces, but then there is an obvious
976 # problem: non expanded code will never be seen/ In particular, the body
977 # of a `define' definition is not seen, so on the input
978 #
979 # define([idem], [OLD(0, [$1])])
980 #
981 # autoupdate would never see the `OLD', and wouldn't have updated it.
982 # Worse yet, if `idem(0)' was used later, then autoupdate sees that
983 # `OLD' is used, computes the result for `OLD(0, 0)' and sets up a
984 # dispatcher for `OLD'. Since there was no computed value for `OLD(0,
985 # [$1])', the dispatcher would have replaced with... nothinhg, leading
986 # to
987 #
988 # define([idem], [])
989 #
990 # With some more thinking, you see that the two step approach is wrong,
991 # the namespace approach was much saner.
992 #
993 # But you learned a lot, in particular you realized that using traces
994 # can make it possible to simulate namespaces!
995 #
996 #
997 #
998 # # The fifth implementation: m4 namespaces by files
999 # # ================================================
1000 #
1001 # The fourth implementation demonstrated something unsurprising: you
1002 # cannot precompute, i.e., the namespace approach was the right one.
1003 # Still, we no longer want them, they're too expensive. Let's have a
1004 # look at the way it worked.
1005 #
1006 # When updating
1007 #
1008 # dnl The Unbelievable Truth
1009 # OLD(1, 2)
1010 # NEW([0, 0], [0])
1011 #
1012 # you evaluate `input.m4':
1013 #
1014 # divert(-1)
1015 # changequote([, ])
1016 # define([OLD],
1017 # [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
1018 # ...
1019 # m4_disable()
1020 # dnl The Unbelievable Truth
1021 # OLD(1, 2)
1022 # NEW([0, 0], [0])
1023 #
1024 # where `m4_disable' undefines the m4 and m4sugar, and disables the quotes
1025 # and comments:
1026 #
1027 # define([m4_disable],
1028 # [undefine([__file__])
1029 # ...
1030 # changecom(#)
1031 # changequote()])
1032 #
1033 # `m4_enable' does the converse: reestablish quotes and comments
1034 # --easy--, reestablish m4sugar --easy: just load `m4sugar.m4' again-- and
1035 # reenable the builtins. This later task requires that you first save
1036 # the builtins. And BTW, the definition above of `m4_disable' cannot
1037 # work: you undefined `changequote' before using it! So you need to use
1038 # your privates copies of the builtins. Let's introduce three files for
1039 # this:
1040 #
1041 # `m4save.m4'
1042 # moves the m4 builtins into the `_au_' pseudo namespace
1043 # `unm4.m4'
1044 # undefines the builtins
1045 # `m4.m4'
1046 # restores them
1047 #
1048 # So `input.m4' is:
1049 #
1050 # divert(-1)
1051 # changequote([, ])
1052 #
1053 # include([m4save.m4])
1054 #
1055 # # Import AU.
1056 # define([OLD],
1057 # [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
1058 #
1059 # define([_au_enable],
1060 # [_au_changecom([#])
1061 # _au_include([m4.m4])
1062 # _au_include(m4sugar.m4)])
1063 #
1064 # define([_au_disable],
1065 # [# Disable m4sugar.
1066 # # Disable the m4 builtins.
1067 # _au_include([unm4.m4])
1068 # # 1. Disable special characters.
1069 # _au_changequote()
1070 # _au_changecom()])
1071 #
1072 # m4_disable()
1073 # dnl The Unbelievable Truth
1074 # OLD(1, 2)
1075 # NEW([0, 0], [0])
1076 #
1077 # Based on what we learned in the fourth implementation we know that we
1078 # have to enable the quotes *before* any AU macro, and we know we need
1079 # to build autoquoting versions of the AC macros. But the autoquoting
1080 # AC definitions must be disabled in the rest of the file, and enabled
1081 # inside AU macros.
1082 #
1083 # Using `autoconf --trace' it is easy to build the files
1084 #
1085 # `ac.m4'
1086 # define the autoquoting AC fake macros
1087 # `disable.m4'
1088 # undefine the m4sugar and AC autoquoting macros.
1089 # `au.m4'
1090 # definitions of the AU macros (such as `OLD' above).
1091 #
1092 # Now, `input.m4' is:
1093 #
1094 # divert(-1)
1095 # changequote([, ])
1096 #
1097 # include([m4save.m4])
1098 # # Import AU.
1099 # include([au.m4])
1100 #
1101 # define([_au_enable],
1102 # [_au_changecom([#])
1103 # _au_include([m4.m4])
1104 # _au_include(m4sugar.m4)
1105 # _au_include(ac.m4)])
1106 #
1107 # define([_au_disable],
1108 # [_au_include([disable.m4])
1109 # _au_include([unm4.m4])
1110 # # 1. Disable special characters.
1111 # _au_changequote()
1112 # _au_changecom()])
1113 #
1114 # m4_disable()
1115 # dnl The Unbelievable Truth
1116 # _au_changequote([, ])OLD(1, 2)
1117 # NEW([0, 0], [0])
1118 #
1119 # Finally, version V is ready.
1120 #
1121 # Well... almost.
1122 #
1123 # There is a slight problem that remains: if an AU macro OUTTER includes
1124 # an AU macro INNER, then _au_enable will be run when entering OUTTER
1125 # and when entering INNER (not good, but not too bad yet). But when
1126 # getting out of INNER, _au_disable will disable everything while we
1127 # were still in OUTTER. Badaboom.
1128 #
1129 # Therefore _au_enable and _au_disable have to be written to work by
1130 # pairs: each _au_enable pushdef's _au_enabled, and each _au_disable
1131 # popdef's _au_enabled. And of course _au_enable and _au_disable are
1132 # effective when _au_enabled is *not* defined.
1133 #
1134 # Finally, version V' is ready. And there is much rejoicing. (And I
1135 # have free time again. I think. Yeah, right.)