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