| blob | d69211d6c192b3b0263c1ddcdbadd2aa21f77be7 |
1 #! @PERL@ -w
2 # -*- perl -*-
3 # @configure_input@
5 # autoupdate - modernize an Autoconf file.
6 # Copyright (C) 1994, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
7 # Free Software Foundation, Inc.
9 # This program is free software: you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
19 # You should have received a copy of the GNU General Public License
20 # along with this program. If not, see <http://www.gnu.org/licenses/>.
22 # Originally written by David MacKenzie <djm@gnu.ai.mit.edu>.
23 # Rewritten by Akim Demaille <akim@freefriends.org>.
25 eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac'
26 if 0;
28 BEGIN
29 {
30 my $datadir = $ENV{'autom4te_perllibdir'} || '@datadir@';
31 unshift @INC, $datadir;
33 # Override SHELL. On DJGPP SHELL may not be set to a shell
34 # that can handle redirection and quote arguments correctly,
35 # e.g.: COMMAND.COM. For DJGPP always use the shell that configure
36 # has detected.
37 $ENV{'SHELL'} = '@SHELL@' if ($^O eq 'dos');
38 }
40 use Autom4te::ChannelDefs;
41 use Autom4te::Channels;
42 use Autom4te::Configure_ac;
43 use Autom4te::FileUtils;
44 use Autom4te::General;
45 use Autom4te::XFile;
46 use File::Basename;
47 use strict;
49 # Lib files.
50 my $autom4te = $ENV{'AUTOM4TE'} || '@bindir@/@autom4te-name@';
51 my $autoconf = "$autom4te --language=autoconf";
52 # We need to find m4sugar.
53 my @prepend_include;
54 my @include = ('@datadir@');
55 my $force = 0;
56 # m4.
57 my $m4 = $ENV{"M4"} || '@M4@';
60 # $HELP
61 # -----
62 $help = "Usage: $0 [OPTION] ... [TEMPLATE-FILE...]
64 Update the TEMPLATE-FILE... if given, or `configure.ac' if present,
65 or else `configure.in', to the syntax of the current version of
66 Autoconf. The original files are backed up.
68 Operation modes:
69 -h, --help print this help, then exit
70 -V, --version print version number, then exit
71 -v, --verbose verbosely report processing
72 -d, --debug don't remove temporary files
73 -f, --force consider all files obsolete
75 Library directories:
76 -B, --prepend-include=DIR prepend directory DIR to search path
77 -I, --include=DIR append directory DIR to search path
79 Report bugs to <bug-autoconf\@gnu.org>.
80 ";
82 # $VERSION
83 # --------
84 $version = "autoupdate (@PACKAGE_NAME@) @VERSION@
85 Copyright (C) @RELEASE_YEAR@ Free Software Foundation, Inc.
86 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
87 This is free software: you are free to change and redistribute it.
88 There is NO WARRANTY, to the extent permitted by law.
90 Written by David J. MacKenzie and Akim Demaille.
91 ";
93 ## ---------- ##
94 ## Routines. ##
95 ## ---------- ##
98 # parse_args ()
99 # -------------
100 # Process any command line arguments.
101 sub parse_args ()
102 {
103 my $srcdir;
105 getopt ('I|include=s' => \@include,
106 'B|prepend-include=s' => \@prepend_include,
107 'f|force' => \$force);
109 if (! @ARGV)
110 {
111 my $configure_ac = require_configure_ac;
112 push @ARGV, $configure_ac;
113 }
114 }
118 # ----------------- #
119 # Autoconf macros. #
120 # ----------------- #
122 my (%ac_macros, %au_macros, %m4_builtins);
124 # HANDLE_AUTOCONF_MACROS ()
125 # -------------------------
126 # @M4_BUILTINS -- M4 builtins and a useful comment.
127 sub handle_autoconf_macros ()
128 {
129 # Get the builtins.
130 xsystem ("echo dumpdef | $m4 2>$tmp/m4.defs >/dev/null");
131 my $m4_defs = new Autom4te::XFile "$tmp/m4.defs";
132 while ($_ = $m4_defs->getline)
133 {
134 $m4_builtins{$1} = 1
135 if /^(\w+):/;
136 }
137 $m4_defs->close;
139 my $macros = new Autom4te::XFile ("$autoconf"
140 . " --trace AU_DEFINE:'AU:\$f:\$1'"
141 . " --trace define:'AC:\$f:\$1'"
142 . " --melt /dev/null |");
143 while ($_ = $macros->getline)
144 {
145 chomp;
146 my ($domain, $file, $macro) = /^(AC|AU):(.*):([^:]*)$/ or next;
147 if ($domain eq "AU")
148 {
149 $au_macros{$macro} = 1;
150 }
151 elsif ($file =~ /(^|\/)m4sugar\/(m4sugar|version)\.m4$/)
152 {
153 # Add the m4sugar macros to m4_builtins.
154 $m4_builtins{$macro} = 1;
155 }
156 else
157 {
158 # Autoconf, aclocal, and m4sh macros.
159 $ac_macros{$macro} = 1;
160 }
161 }
162 $macros->close;
165 # Don't keep AU macros in @AC_MACROS.
166 delete $ac_macros{$_}
167 foreach (keys %au_macros);
168 # Don't keep M4sugar macros which are redefined by Autoconf,
169 # such as `builtin', `changequote' etc. See autoconf/autoconf.m4.
170 delete $ac_macros{$_}
171 foreach (keys %m4_builtins);
172 error "no current Autoconf macros found"
173 unless keys %ac_macros;
174 error "no obsolete Autoconf macros found"
175 unless keys %au_macros;
177 if ($debug)
178 {
179 print STDERR "Current Autoconf macros:\n";
180 print STDERR join (' ', sort keys %ac_macros) . "\n\n";
181 print STDERR "Obsolete Autoconf macros:\n";
182 print STDERR join (' ', sort keys %au_macros) . "\n\n";
183 }
185 # ac.m4 -- autoquoting definitions of the AC macros (M4sugar excluded).
186 # unac.m4 -- undefine the AC macros.
187 my $ac_m4 = new Autom4te::XFile ">$tmp/ac.m4";
188 print $ac_m4 "# ac.m4 -- autoquoting definitions of the AC macros.\n";
189 my $unac_m4 = new Autom4te::XFile ">$tmp/unac.m4";
190 print $unac_m4 "# unac.m4 -- undefine the AC macros.\n";
191 foreach (sort keys %ac_macros)
192 {
193 print $ac_m4 "_au_m4_define([$_], [m4_if(\$#, 0, [[\$0]], [[\$0(\$\@)]])])\n";
194 print $unac_m4 "_au_m4_undefine([$_])\n";
195 }
197 # m4save.m4 -- save the m4 builtins.
198 # unm4.m4 -- disable the m4 builtins.
199 # m4.m4 -- enable the m4 builtins.
200 my $m4save_m4 = new Autom4te::XFile ">$tmp/m4save.m4";
201 print $m4save_m4 "# m4save.m4 -- save the m4 builtins.\n";
202 my $unm4_m4 = new Autom4te::XFile ">$tmp/unm4.m4";
203 print $unm4_m4 "# unm4.m4 -- disable the m4 builtins.\n";
204 my $m4_m4 = new Autom4te::XFile ">$tmp/m4.m4";
205 print $m4_m4 "# m4.m4 -- enable the m4 builtins.\n";
206 foreach (sort keys %m4_builtins)
207 {
208 print $m4save_m4 "_au__save([$_])\n";
209 print $unm4_m4 "_au__undefine([$_])\n";
210 print $m4_m4 "_au__restore([$_])\n";
211 }
212 }
215 ## -------------- ##
216 ## Main program. ##
217 ## -------------- ##
219 parse_args;
220 $autoconf .= " --debug" if $debug;
221 $autoconf .= " --force" if $force;
222 $autoconf .= " --verbose" if $verbose;
223 $autoconf .= join (' --include=', '', @include);
224 $autoconf .= join (' --prepend-include=', '', @prepend_include);
226 mktmpdir ('au');
227 handle_autoconf_macros;
229 # $au_changequote -- enable the quote `[', `]' right before any AU macro.
230 my $au_changequote =
231 's/\b(' . join ('|', keys %au_macros) . ')\b/_au_m4_changequote([,])$1/g';
233 # au.m4 -- definitions the AU macros.
234 xsystem ("$autoconf --trace AU_DEFINE:'_au_defun(\@<:\@\$1\@:>\@,
235 \@<:\@\$2\@:>\@)' --melt /dev/null "
236 . ">$tmp/au.m4");
240 ## ------------------- ##
241 ## Process the files. ##
242 ## ------------------- ##
244 foreach my $file (@ARGV)
245 {
246 # We need an actual file.
247 if ($file eq '-')
248 {
249 $file = "$tmp/stdin";
250 system "cat >$file";
251 }
252 elsif (! -r "$file")
253 {
254 die "$me: $file: No such file or directory";
255 }
257 # input.m4 -- m4 program to produce the updated file.
258 # Load the values, the dispatcher, neutralize m4, and the prepared
259 # input file.
260 my $input_m4 = <<\EOF;
261 divert(-1) -*- Autoconf -*-
262 changequote([,])
264 # Define our special macros:
265 define([_au__defn], defn([defn]))
266 define([_au__divert], defn([divert]))
267 define([_au__include], defn([include]))
268 define([_au__undefine], defn([undefine]))
269 define([_au__save], [m4_ifdef([$1], [m4_copy([$1], [_au_$1])])])
270 define([_au__restore],
271 [_au_m4_ifdef([_au_$1],
272 [_au_m4_define([$1], _au__defn([_au_$1]))])])
274 # Set up m4sugar.
275 include(m4sugar/m4sugar.m4)
277 # Redefine __file__ to make warnings nicer; $file is replaced below.
278 m4_define([__file__], [$file])
280 # Redefine m4_location to fix the line number.
281 m4_define([m4_location], [__file__:m4_eval(__line__ - _au__first_line)])
283 # Move all the builtins into the `_au_' pseudo namespace
284 m4_include([m4save.m4])
286 # _au_defun(NAME, BODY)
287 # ---------------------
288 # Define NAME to BODY, plus AU activation/deactivation.
289 _au_m4_define([_au_defun],
290 [_au_m4_define([$1],
291 [_au_enable()dnl
292 $2[]dnl
293 _au_disable()])])
295 # Import the definition of the obsolete macros.
296 _au__include([au.m4])
299 ## ------------------------ ##
300 ## _au_enable/_au_disable. ##
301 ## ------------------------ ##
303 # They work by pair: each time an AU macro is activated, it runs
304 # _au_enable, and at its end its runs _au_disable (see _au_defun
305 # above). AU macros might use AU macros, which should
306 # enable/disable only for the outer AU macros.
307 #
308 # `_au_enabled' is used to this end, determining whether we really
309 # enable/disable.
312 # __au_enable
313 # -----------
314 # Reenable the builtins, m4sugar, and the autoquoting AC macros.
315 _au_m4_define([__au_enable],
316 [_au__divert(-1)
317 # Enable special characters.
318 _au_m4_changecom([#])
320 _au__include([m4.m4])
321 _au__include([ac.m4])
323 _au__divert(0)])
325 # _au_enable
326 # ----------
327 # Called at the beginning of all the obsolete macros. If this is the
328 # outermost level, call __au_enable.
329 _au_m4_define([_au_enable],
330 [_au_m4_ifdef([_au_enabled],
331 [],
332 [__au_enable()])_au_dnl
333 _au_m4_pushdef([_au_enabled])])
336 # __au_disable
337 # ------------
338 # Disable the AC autoquoting macros, m4sugar, and m4.
339 _au_m4_define([__au_disable],
340 [_au__divert(-1)
341 _au__include([unac.m4])
342 _au__include([unm4.m4])
344 # Disable special characters.
345 _au_m4_changequote()
346 _au_m4_changecom()
348 _au__divert(0)])
350 # _au_disable
351 # -----------
352 # Called at the end of all the obsolete macros. If we are at the
353 # outermost level, call __au_disable.
354 _au_m4_define([_au_disable],
355 [_au_m4_popdef([_au_enabled])_au_dnl
356 _au_m4_ifdef([_au_enabled],
357 [],
358 [__au_disable()])])
361 ## ------------------------------- ##
362 ## Disable, and process the file. ##
363 ## ------------------------------- ##
364 # The AC autoquoting macros are not loaded yet, hence invoking
365 # `_au_disable' would be wrong.
366 _au__include([unm4.m4])
368 # Disable special characters, and set the first line number.
369 _au_m4_changequote()
370 _au_m4_changecom()
372 _au_m4_define(_au__first_line, _au___line__)_au__divert(0)_au_dnl
373 EOF
375 $input_m4 =~ s/^ //mg;
376 $input_m4 =~ s/\$file/$file/g;
378 # prepared input -- input, but reenables the quote before each AU macro.
379 open INPUT_M4, ">$tmp/input.m4"
380 or error "cannot open: $!";
381 open FILE, "<$file"
382 or error "cannot open: $!";
383 print INPUT_M4 "$input_m4";
384 while (<FILE>)
385 {
386 eval $au_changequote;
387 print INPUT_M4;
388 }
389 close FILE
390 or error "cannot close $file: $!";
391 close INPUT_M4
392 or error "cannot close $tmp/input.m4: $!";
394 # Now ask m4 to perform the update.
395 xsystem ("$m4 --include=$tmp"
396 . join (' --include=', '', reverse (@prepend_include))
397 . join (' --include=', '', @include)
398 . " $tmp/input.m4 >$tmp/updated");
399 update_file ("$tmp/updated",
400 "$file" eq "$tmp/stdin" ? '-' : "$file");
401 }
402 exit 0;
405 # ## ---------------------------- ##
406 # ## How `autoupdate' functions. ##
407 # ## ---------------------------- ##
408 #
409 # The task of `autoupdate' is not trivial: the biggest difficulty being
410 # that you must limit the changes to the parts that really need to be
411 # updated. Finding a satisfying implementation proved to be quite hard,
412 # as this is the fifth implementation of `autoupdate'.
413 #
414 # Below, we will use a simple example of obsolete macro:
415 #
416 # AU_DEFUN([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))])
417 # AC_DEFUN([NEW], [echo "sum($1) = $2"])
418 #
419 # the input file contains
420 #
421 # dnl The Unbelievable Truth
422 # OLD(1, 2)
423 # NEW([0, 0], [0])
424 #
425 # Of course the expected output is
426 #
427 # dnl The Unbelievable Truth
428 # NEW([1, 2], [3])
429 # NEW([0, 0], [0])
430 #
431 #
432 # # First implementation: sed
433 # # =========================
434 #
435 # The first implementation was only able to change the name of obsolete
436 # macros.
437 #
438 # The file `acoldnames.m4' defined the old names based on the new names.
439 # It was simple then to produce a sed script such as:
440 #
441 # s/OLD/NEW/g
442 #
443 # Updating merely consisted in running this script on the file to
444 # update.
445 #
446 # This scheme suffers an obvious limitation: that `autoupdate' was
447 # unable to cope with new macros that just swap some of its arguments
448 # compared to the old macro. Fortunately, that was enough to upgrade
449 # from Autoconf 1 to Autoconf 2. (But I have no idea whether the
450 # changes in Autoconf 2 were precisely limited by this constraint.)
451 #
452 #
453 # # Second implementation: hooks
454 # # ============================
455 #
456 # The version 2.15 of Autoconf brought a vast number of changes compared
457 # to 2.13, so a solution was needed. One could think to extend the
458 # `sed' scripts with specialized code for complex macros. But this
459 # approach is of course full of flaws:
460 #
461 # a. the Autoconf maintainers have to write these snippets, which we
462 # just don't want to,
463 #
464 # b. I really don't think you'll ever manage to handle the quoting of
465 # m4 from sed.
466 #
467 # To satisfy a., let's remark that the code which implements the old
468 # features in term of the new feature is exactly the code which should
469 # replace the old code.
470 #
471 # To answer point b, as usual in the history of Autoconf, the answer, at
472 # least on the paper, is simple: m4 is the best tool to parse m4, so
473 # let's use m4.
474 #
475 # Therefore the specification is:
476 #
477 # I want to be able to tell Autoconf, well, m4, that the macro I
478 # am currently defining is an obsolete macro (so that the user is
479 # warned), which code is the code to use when running autoconf,
480 # but that the very same code has to be used when running
481 # autoupdate. To summarize, the interface I want is
482 # `AU_DEFUN(OLD-NAME, NEW-CODE)'.
483 #
484 #
485 # Now for the technical details.
486 #
487 # When running autoconf, except for the warning, AU_DEFUN is basically
488 # AC_DEFUN.
489 #
490 # When running autoupdate, we want *only* OLD-NAMEs to be expanded.
491 # This obviously means that acgeneral.m4 and acspecific.m4 must not be
492 # loaded. Nonetheless, because we want to use a rich set of m4
493 # features, m4sugar.m4 is needed. Please note that the fact that
494 # Autoconf's macros are not loaded is positive on two points:
495 #
496 # - we do get an updated `configure.ac', not a `configure'!
497 #
498 # - the old macros are replaced by *calls* to the new-macros, not the
499 # body of the new macros, since their body is not defined!!!
500 # (Whoa, that's really beautiful!).
501 #
502 # Additionally we need to disable the quotes when reading the input for
503 # two reasons: first because otherwise `m4' will swallow the quotes of
504 # other macros:
505 #
506 # NEW([1, 2], 3)
507 # => NEW(1, 2, 3)
508 #
509 # and second, because we want to update the macro calls which are
510 # quoted, i.e., we want
511 #
512 # FOO([OLD(1, 2)])
513 # => FOO([NEW([1, 2], [3])])
514 #
515 # If we don't disable the quotes, only the macros called at the top
516 # level would be updated.
517 #
518 # So, let's disable the quotes.
519 #
520 # Well, not quite: m4sugar.m4 still needs to use quotes for some macros.
521 # Well, in this case, when running in autoupdate code, each macro first
522 # reestablishes the quotes, expands itself, and disables the quotes.
523 #
524 # Thinking a bit more, you realize that in fact, people may use `define'
525 # `ifelse' etc. in their files, and you certainly don't want to process
526 # them. Another example is `dnl': you don't want to remove the
527 # comments. You then realize you don't want exactly to import m4sugar:
528 # you want to specify when it is enabled (macros active), and disabled.
529 # m4sugar provides m4_disable/m4_enable to this end.
530 #
531 # You're getting close to it. Now remains one task: how to handle
532 # twofold definitions?
533 #
534 # Remember that the same AU_DEFUN must be understood in two different
535 # ways, the AC way, and the AU way.
536 #
537 # One first solution is to check whether acgeneral.m4 was loaded. But
538 # that's definitely not cute. Another is simply to install `hooks',
539 # that is to say, to keep in some place m4 knows, late `define' to be
540 # triggered *only* in AU mode.
541 #
542 # You first think to design AU_DEFUN like this:
543 #
544 # 1. AC_DEFUN(OLD-NAME,
545 # [Warn the user OLD-NAME is obsolete.
546 # NEW-CODE])
547 #
548 # 2. Store for late AU binding([define(OLD_NAME,
549 # [Reestablish the quotes.
550 # NEW-CODE
551 # Disable the quotes.])])
552 #
553 # but this will not work: NEW-CODE has probably $1, $2 etc. and these
554 # guys will be replaced with the argument of `Store for late AU binding'
555 # when you call it.
556 #
557 # I don't think there is a means to avoid this using this technology
558 # (remember that $1 etc. are *always* expanded in m4). You may also try
559 # to replace them with $[1] to preserve them for a later evaluation, but
560 # if `Store for late AU binding' is properly written, it will remain
561 # quoted till the end...
562 #
563 # You have to change technology. Since the problem is that `$1'
564 # etc. should be `consumed' right away, one solution is to define now a
565 # second macro, `AU_OLD-NAME', and to install a hook than binds OLD-NAME
566 # to AU_OLD-NAME. Then, autoupdate.m4 just need to run the hooks. By
567 # the way, the same method was used in autoheader.
568 #
569 #
570 # # Third implementation: m4 namespaces by m4sugar
571 # # ==============================================
572 #
573 # Actually, this implementation was just a clean up of the previous
574 # implementation: instead of defining hooks by hand, m4sugar was equipped
575 # with `namespaces'. What are they?
576 #
577 # Sometimes we want to disable some *set* of macros, and restore them
578 # later. We provide support for this via namespaces.
579 #
580 # There are basically three characters playing this scene: defining a
581 # macro in a namespace, disabling a namespace, and restoring a namespace
582 # (i.e., all the definitions it holds).
583 #
584 # Technically, to define a MACRO in NAMESPACE means to define the macro
585 # named `NAMESPACE::MACRO' to the VALUE. At the same time, we append
586 # `undefine(NAME)' in the macro named `m4_disable(NAMESPACE)', and
587 # similarly a binding of NAME to the value of `NAMESPACE::MACRO' in
588 # `m4_enable(NAMESPACE)'. These mechanisms allow to bind the macro of
589 # NAMESPACE and to unbind them at will.
590 #
591 # Of course this implementation is really inefficient: m4 has to grow
592 # strings which can become quickly huge, which slows it significantly.
593 #
594 # In particular one should avoid as much as possible to use `define' for
595 # temporaries. Now that `define' has quite a complex meaning, it is an
596 # expensive operations that should be limited to macros. Use
597 # `m4_define' for temporaries.
598 #
599 # Private copies of the macros we used in entering / exiting the m4sugar
600 # namespace. It is much more convenient than fighting with the renamed
601 # version of define etc.
602 #
603 #
604 #
605 # Those two implementations suffered from serious problems:
606 #
607 # - namespaces were really expensive, and incurred a major performance
608 # loss on `autoconf' itself, not only `autoupdate'. One solution
609 # would have been the limit the use of namespaces to `autoupdate', but
610 # that's again some complications on m4sugar, which really doesn't need
611 # this. So we wanted to get rid of the namespaces.
612 #
613 # - since the quotes were disabled, autoupdate was sometimes making
614 # wrong guesses, for instance on:
615 #
616 # foo([1, 2])
617 #
618 # m4 saw 2 arguments: `[1'and `2]'. A simple solution, somewhat
619 # fragile, is to reestablish the quotes right before all the obsolete
620 # macros, i.e., to use sed so that the previous text becomes
621 #
622 # changequote([, ])foo([1, 2])
623 #
624 # To this end, one wants to trace the definition of obsolete macros.
625 #
626 # It was there that the limitations of the namespace approach became
627 # painful: because it was a complex machinery playing a lot with the
628 # builtins of m4 (hence, quite fragile), tracing was almost impossible.
629 #
630 #
631 # So this approach was dropped.
632 #
633 #
634 # # The fourth implementation: two steps
635 # # ====================================
636 #
637 # If you drop the uses of namespaces, you no longer can compute the
638 # updated value, and replace the old call with it simultaneously.
639 #
640 # Obviously you will use m4 to compute the updated values, but you may
641 # use some other tool to achieve the replacement. Personally, I trust
642 # nobody but m4 to parse m4, so below, m4 will perform the two tasks.
643 #
644 # How can m4 be used to replace *some* macros calls with newer values.
645 # Well, that's dead simple: m4 should learn the definitions of obsolete
646 # macros, forget its builtins, disable the quotes, and then run on the
647 # input file, which amounts to doing this:
648 #
649 # divert(-1)dnl
650 # changequote([, ])
651 # define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
652 # undefine([dnl])
653 # undefine([m4_eval])
654 # # Some more undefines...
655 # changequote()
656 # divert(0)dnl
657 # dnl The Unbelievable Truth
658 # changequote([, ])OLD(1, 2)
659 # NEW([0, 0],
660 # 0)
661 #
662 # which will result in
663 #
664 # dnl The Unbelievable Truth
665 # NEW(1, 2, m4_eval(1 + 2))
666 # NEW([0, 0],
667 # 0)
668 #
669 # Grpmh. Two problems. A minor problem: it would have been much better
670 # to have the `m4_eval' computed, and a major problem: you lost the
671 # quotation in the result.
672 #
673 # Let's address the big problem first. One solution is to define any
674 # modern macro to rewrite its calls with the proper quotation, thanks to
675 # `$@'. Again, tracing the `define's makes it possible to know which
676 # are these macros, so you input is:
677 #
678 # divert(-1)dnl
679 # changequote([, ])
680 # define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
681 # define([NEW], [[NEW($@)]changequote()])
682 # undefine([dnl])
683 # undefine([m4_eval])
684 # # Some more undefines...
685 # changequote()
686 # divert(0)dnl
687 # dnl The Unbelievable Truth
688 # changequote([, ])OLD(1, 2)
689 # changequote([, ])NEW([0, 0],
690 # 0)
691 #
692 # which results in
693 #
694 # dnl The Unbelievable Truth
695 # NEW([1, 2],[m4_eval(1 + 2)])
696 # NEW([0, 0],[0])
697 #
698 # Our problem is solved, i.e., the first call to `NEW' is properly
699 # quoted, but introduced another problem: we changed the layout of the
700 # second calls, which can be a drama in the case of huge macro calls
701 # (think of `AC_TRY_RUN' for instance). This example didn't show it,
702 # but we also introduced parens to macros which did not have some:
703 #
704 # AC_INIT
705 # => AC_INIT()
706 #
707 # No big deal for the semantics (unless the macro depends upon $#, which
708 # is bad), but the users would not be happy.
709 #
710 # Additionally, we introduced quotes that were not there before, which is
711 # OK in most cases, but could change the semantics of the file.
712 #
713 # Cruel dilemma: we do want the auto-quoting definition of `NEW' when
714 # evaluating `OLD', but we don't when we evaluate the second `NEW'.
715 # Back to namespaces?
716 #
717 # No.
718 #
719 #
720 # # Second step: replacement
721 # # ------------------------
722 #
723 # No, as announced above, we will work in two steps: in a first step we
724 # compute the updated values, and in a second step we replace them. Our
725 # goal is something like this:
726 #
727 # divert(-1)dnl
728 # changequote([, ])
729 # define([OLD], [NEW([1, 2], [3])changequote()])
730 # undefine([dnl])
731 # undefine([m4_eval])
732 # # Some more undefines...
733 # changequote()
734 # divert(0)dnl
735 # dnl The Unbelievable Truth
736 # changequote([, ])OLD(1, 2)
737 # NEW([0, 0],
738 # 0)
739 #
740 # i.e., the new value of `OLD' is precomputed using the auto-quoting
741 # definition of `NEW' and the m4 builtins. We'll see how afterwards,
742 # let's finish with the replacement.
743 #
744 # Of course the solution above is wrong: if there were other calls to
745 # `OLD' with different values, we would smash them to the same value.
746 # But it is quite easy to generalize the scheme above:
747 #
748 # divert(-1)dnl
749 # changequote([, ])
750 # define([OLD([1],[2])], [NEW([1, 2], [3])])
751 # define([OLD], [defn([OLD($@)])changequote()])
752 # undefine([dnl])
753 # undefine([m4_eval])
754 # # Some more undefines...
755 # changequote()
756 # divert(0)dnl
757 # dnl The Unbelievable Truth
758 # changequote([, ])OLD(1, 2)
759 # NEW([0, 0],
760 # 0)
761 #
762 # i.e., for each call to obsolete macros, we build an array `call =>
763 # value', and use a macro to dispatch these values. This results in:
764 #
765 # dnl The Unbelievable Truth
766 # NEW([1, 2], [3])
767 # NEW([0, 0],
768 # 0)
769 #
770 # In French, we say `Youpi !', which you might roughly translate as
771 # `Yippee!'.
772 #
773 #
774 # # First step: computation
775 # # -----------------------
776 #
777 # Let's study the anatomy of the file, and name its sections:
778 #
779 # prologue
780 # divert(-1)dnl
781 # changequote([, ])
782 # values
783 # define([OLD([1],[2])], [NEW([1, 2], [3])])
784 # dispatcher
785 # define([OLD], [defn([OLD($@)])changequote()])
786 # disabler
787 # undefine([dnl])
788 # undefine([m4_eval])
789 # # Some more undefines...
790 # changequote()
791 # divert(0)dnl
792 # input
793 # dnl The Unbelievable Truth
794 # changequote([, ])OLD(1, 2)
795 # NEW([0, 0],
796 # 0)
797 #
798 #
799 # # Computing the `values' section
800 # # ..............................
801 #
802 # First we need to get the list of all the AU macro uses. To this end,
803 # first get the list of all the AU macros names by tracing `AU_DEFUN' in
804 # the initialization of autoconf. This list is computed in the file
805 # `au.txt' below.
806 #
807 # Then use this list to trace all the AU macro uses in the input. The
808 # goal is obtain in the case of our example:
809 #
810 # [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
811 #
812 # This is the file `values.in' below.
813 #
814 # We want to evaluate this with only the builtins (in fact m4sugar), the
815 # auto-quoting definitions of the new macros (`new.m4'), and the
816 # definition of the old macros (`old.m4'). Computing these last two
817 # files is easy: it's just a matter of using the right `--trace' option.
818 #
819 # So the content of `values.in' is:
820 #
821 # include($autoconf_dir/m4sugar.m4)
822 # m4_include(new.m4)
823 # m4_include(old.m4)
824 # divert(0)dnl
825 # [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
826 #
827 # We run m4 on it, which yields:
828 #
829 # define([OLD([1],[2])],@<<@NEW([1, 2], [3])@>>@)
830 #
831 # Transform `@<<@' and `@>>@' into quotes and we get
832 #
833 # define([OLD([1],[2])],[NEW([1, 2], [3])])
834 #
835 # This is `values.m4'.
836 #
837 #
838 # # Computing the `dispatcher' section
839 # # ..................................
840 #
841 # The `prologue', and the `disabler' are simple and need no commenting.
842 #
843 # To compute the `dispatcher' (`dispatch.m4'), again, it is a simple
844 # matter of using the right `--trace'.
845 #
846 # Finally, the input is not exactly the input file, rather it is the
847 # input file with the added `changequote'. To this end, we build
848 # `quote.sed'.
849 #
850 #
851 # # Putting it all together
852 # # .......................
853 #
854 # We build the file `input.m4' which contains:
855 #
856 # divert(-1)dnl
857 # changequote([, ])
858 # include(values.m4)
859 # include(dispatch.m4)
860 # undefine([dnl])
861 # undefine([eval])
862 # # Some more undefines...
863 # changequote()
864 # divert(0)dnl
865 # dnl The Unbelievable Truth
866 # changequote([, ])OLD(1, 2)
867 # NEW([0, 0],
868 # 0)
869 #
870 # And we just run m4 on it. Et voila`, Monsieur ! Mais oui, mais oui.
871 #
872 # Well, there are a few additional technicalities. For instance, we
873 # rely on `changequote', `ifelse' and `defn', but we don't want to
874 # interpret the changequotes of the user, so we simply use another name:
875 # `_au_changequote' etc.
876 #
877 #
878 # # Failure of the fourth approach
879 # # ------------------------------
880 #
881 # This approach is heavily based on traces, but then there is an obvious
882 # problem: non expanded code will never be seen. In particular, the body
883 # of a `define' definition is not seen, so on the input
884 #
885 # define([idem], [OLD(0, [$1])])
886 #
887 # autoupdate would never see the `OLD', and wouldn't have updated it.
888 # Worse yet, if `idem(0)' was used later, then autoupdate sees that
889 # `OLD' is used, computes the result for `OLD(0, 0)' and sets up a
890 # dispatcher for `OLD'. Since there was no computed value for `OLD(0,
891 # [$1])', the dispatcher would have replaced with... nothing, leading
892 # to
893 #
894 # define([idem], [])
895 #
896 # With some more thinking, you see that the two step approach is wrong,
897 # the namespace approach was much saner.
898 #
899 # But you learned a lot, in particular you realized that using traces
900 # can make it possible to simulate namespaces!
901 #
902 #
903 #
904 # # The fifth implementation: m4 namespaces by files
905 # # ================================================
906 #
907 # The fourth implementation demonstrated something unsurprising: you
908 # cannot precompute, i.e., the namespace approach was the right one.
909 # Still, we no longer want them, they're too expensive. Let's have a
910 # look at the way it worked.
911 #
912 # When updating
913 #
914 # dnl The Unbelievable Truth
915 # OLD(1, 2)
916 # NEW([0, 0], [0])
917 #
918 # you evaluate `input.m4':
919 #
920 # divert(-1)
921 # changequote([, ])
922 # define([OLD],
923 # [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
924 # ...
925 # m4_disable()
926 # dnl The Unbelievable Truth
927 # OLD(1, 2)
928 # NEW([0, 0], [0])
929 #
930 # where `m4_disable' undefines the m4 and m4sugar, and disables the quotes
931 # and comments:
932 #
933 # define([m4_disable],
934 # [undefine([__file__])
935 # ...
936 # changecom(#)
937 # changequote()])
938 #
939 # `m4_enable' does the converse: reestablish quotes and comments
940 # --easy--, reestablish m4sugar --easy: just load `m4sugar.m4' again-- and
941 # reenable the builtins. This later task requires that you first save
942 # the builtins. And BTW, the definition above of `m4_disable' cannot
943 # work: you undefined `changequote' before using it! So you need to use
944 # your privates copies of the builtins. Let's introduce three files for
945 # this:
946 #
947 # `m4save.m4'
948 # moves the m4 builtins into the `_au_' pseudo namespace,
949 # `unm4.m4'
950 # undefines the builtins,
951 # `m4.m4'
952 # restores them.
953 #
954 # So `input.m4' is:
955 #
956 # divert(-1)
957 # changequote([, ])
958 #
959 # include([m4save.m4])
960 #
961 # # Import AU.
962 # define([OLD],
963 # [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
964 #
965 # define([_au_enable],
966 # [_au_changecom([#])
967 # _au_include([m4.m4])
968 # _au_include(m4sugar.m4)])
969 #
970 # define([_au_disable],
971 # [# Disable m4sugar.
972 # # Disable the m4 builtins.
973 # _au_include([unm4.m4])
974 # # 1. Disable special characters.
975 # _au_changequote()
976 # _au_changecom()])
977 #
978 # m4_disable()
979 # dnl The Unbelievable Truth
980 # OLD(1, 2)
981 # NEW([0, 0], [0])
982 #
983 # Based on what we learned in the fourth implementation we know that we
984 # have to enable the quotes *before* any AU macro, and we know we need
985 # to build autoquoting versions of the AC macros. But the autoquoting
986 # AC definitions must be disabled in the rest of the file, and enabled
987 # inside AU macros.
988 #
989 # Using `autoconf --trace' it is easy to build the files
990 #
991 # `ac.m4'
992 # define the autoquoting AC fake macros
993 # `disable.m4'
994 # undefine the m4sugar and AC autoquoting macros.
995 # `au.m4'
996 # definitions of the AU macros (such as `OLD' above).
997 #
998 # Now, `input.m4' is:
999 #
1000 # divert(-1)
1001 # changequote([, ])
1002 #
1003 # include([m4save.m4])
1004 # # Import AU.
1005 # include([au.m4])
1006 #
1007 # define([_au_enable],
1008 # [_au_changecom([#])
1009 # _au_include([m4.m4])
1010 # _au_include(m4sugar.m4)
1011 # _au_include(ac.m4)])
1012 #
1013 # define([_au_disable],
1014 # [_au_include([disable.m4])
1015 # _au_include([unm4.m4])
1016 # # 1. Disable special characters.
1017 # _au_changequote()
1018 # _au_changecom()])
1019 #
1020 # m4_disable()
1021 # dnl The Unbelievable Truth
1022 # _au_changequote([, ])OLD(1, 2)
1023 # NEW([0, 0], [0])
1024 #
1025 # Finally, version V is ready.
1026 #
1027 # Well... almost.
1028 #
1029 # There is a slight problem that remains: if an AU macro OUTER includes
1030 # an AU macro INNER, then _au_enable will be run when entering OUTER
1031 # and when entering INNER (not good, but not too bad yet). But when
1032 # getting out of INNER, _au_disable will disable everything while we
1033 # were still in OUTER. Badaboom.
1034 #
1035 # Therefore _au_enable and _au_disable have to be written to work by
1036 # pairs: each _au_enable pushdef's _au_enabled, and each _au_disable
1037 # popdef's _au_enabled. And of course _au_enable and _au_disable are
1038 # effective when _au_enabled is *not* defined.
1039 #
1040 # Finally, version V' is ready. And there is much rejoicing. (And I
1041 # have free time again. I think. Yeah, right.)
1043 ### Setup "GNU" style for perl-mode and cperl-mode.
1044 ## Local Variables:
1045 ## perl-indent-level: 2
1046 ## perl-continued-statement-offset: 2
1047 ## perl-continued-brace-offset: 0
1048 ## perl-brace-offset: 0
1049 ## perl-brace-imaginary-offset: 0
1050 ## perl-label-offset: -2
1051 ## cperl-indent-level: 2
1052 ## cperl-brace-offset: 0
1053 ## cperl-continued-brace-offset: 0
1054 ## cperl-label-offset: -2
1055 ## cperl-extra-newline-before-brace: t
1056 ## cperl-merge-trailing-else: nil
1057 ## cperl-continued-statement-offset: 2
1058 ## End: