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