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