I'm thinking of making AC_RUN_LOG, which has existed forever but is
undocumented, an official documented macro under the new name
AC_LOG_CMD. I'm renaming it because I also want to add AC_LOG_FILE, a
generalization of _AC_MSG_LOG_CONFTEST.
These are handy any time you want to record details of why some test got
the result it did in config.log; AC_COMPILE_IFELSE and friends have been
able to do this forever, but hand-written tests of the shell environment
or of interpreters can't without reaching into autoconf's guts.
Automake has been carrying around its own copy of AC_LOG_CMD (under the
name AM_LOG_CMD) forever as well...
I haven't *implemented* this yet, but here's the proposed documentation.
What do you think?
zw
+@node Logging
+@section Logging Details of Tests
+
+It is helpful to record details of @emph{why} each test got the result
+that it did, in @file{config.log}. The macros that compile test
+programs (@code{AC_COMPILE_IFELSE} etc.; @pxref{Writing Tests}) do this
+automatically, but if you write a test that only involves M4sh and basic
+shell commands, you will need to do it yourself, using the following macros.
+
+@anchor{AC_LOG_CMD}
+@defmac AC_LOG_CMD (@var{shell-command})
+Execute @var{shell-command}.
+Record @var{shell-command} in @file{config.log}, along with any error
+messages it printed (specifically, everything it wrote to its standard
+error) and its exit code.
+
+This macro may be used within a command substitution, or as the test
+argument of @code{AS_IF} or a regular shell @code{if} statement.
+@end defmac
+
+@anchor{AC_LOG_FILE}
+@defmac AC_LOG_FILE (@var{file}, @var{label})
+Record the contents of @var{file} in @file{config.log}, labeled with
+@var{label}.
+@end defmac
+
+Here is an example of how to use these macros to test for a feature of
+the system `awk'.
+
+@smallexample
+AC_PROG_AWK
+AC_MSG_CHECKING([whether $AWK supports 'asort'])
+cat > conftest.awk <<\EOF
+[@{ lines[NR] = $0 @}
+END @{
+ ORS=" "
+ asort(lines)
+ for (i in lines) @{
+print lines[i]
+ @}
+@}]
+EOF
+
+AS_IF([result=`AC_LOG_CMD([printf 'z\ny\n' | $AWK -f conftest.awk])` &&
+ test x"$result" = x"y z"],
+ [AWK_HAS_ASORT=yes],
+ [AWK_HAS_ASORT=no
+ AC_LOG_FILE([conftest.awk], [test awk script])])
+AC_MSG_RESULT([$AWK_HAS_ASORT])
+AC_SUBST([AWK_HAS_ASORT])
+rm -f conftest.awk
+@end smallexample
@c == Programming in M4.
