2009-01-27 Eric Blake <ebb9@byu.net>
+ Use URLs in --help output, part 3: testsuite.
+ * doc/autoconf.texi (Writing Testsuites): Mention autotest
+ namespace.
+ (Writing Testsuites) <AT_INIT>: Mention mandatory macros.
+ (Making testsuite Scripts): Document AT_PACKAGE_URL.
+ * tests/Makefile.am (package.m4): Follow our own advice.
+ * lib/autotest/general.m4 (AT_INIT): Give the user a hint about
+ package.m4. Enhance --help output.
+ (_AT_COPYRIGHT_YEARS): New macro, to make copyright bump easier.
+
Use URLs in --help output, part 2: configure.
* lib/autoconf/general.m4 (_AC_INIT_COPYRIGHT): Bump copyright
date.
@cindex Autotest
@display
-@strong{N.B.: This section describes an experimental feature which will
-be part of Autoconf in a forthcoming release. Although we believe
-Autotest is stabilizing, this documentation describes an interface which
-might change in the future: do not depend upon Autotest without
-subscribing to the Autoconf mailing lists.}
+@strong{N.B.: This section describes a feature which is still
+stabilizing. Although we believe that Autotest is useful as-is, this
+documentation describes an interface which might change in the future:
+do not depend upon Autotest without subscribing to the Autoconf mailing
+lists.}
@end display
It is paradoxical that portable projects depend on nonportable tools
and then completes with a call to @code{AT_CLEANUP}. Multiple test
groups can be categorized by a call to @code{AT_BANNER}.
+All of the public Autotest macros have all-uppercase names in the
+namespace @samp{^AT_} to prevent them from accidentally conflicting with
+other text; Autoconf also reserves the namespace @samp{^_AT_} for
+internal macros. All shell variables used in the testsuite for internal
+purposes have mostly-lowercase names starting with @samp{at_}. Autotest
+also uses here-doc delimiters in the namespace @samp{^_AT[A-Z]}, and
+makes use of the file system namespace @samp{^at-}.
+
+Since Autoconf is built on top of M4sugar (@pxref{Programming in
+M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
+of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you
+@emph{should not use} the namespace of a package that does not own the
+macro or shell code you are writing.
+
@defmac AT_INIT (@ovar{name})
@atindex{INIT}
@c FIXME: Not clear, plus duplication of the information.
Initialize Autotest. Giving a @var{name} to the test suite is
-encouraged if your package includes several test suites. In any case,
-the test suite always displays the package name and version. It also
-inherits the package bug report address.
+encouraged if your package includes several test suites. Before this
+macro is called, @code{AT_PACKAGE_STRING} and
+@code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display
+information about the testsuite to the user. Typically, these macros
+are provided by a file @file{package.m4} built by @command{make}
+(@pxref{Making testsuite Scripts}), in order to inherit the package
+name, version, and bug reporting address from @file{configure.ac}.
@end defmac
@defmac AT_COPYRIGHT (@var{copyright-notice})
@atindex{PACKAGE_NAME}
@atindex{PACKAGE_TARNAME}
@atindex{PACKAGE_VERSION}
+@atindex{PACKAGE_URL}
Make sure to create the file @file{package.m4}, which defines the
identity of the package. It must define @code{AT_PACKAGE_STRING}, the
full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
address to which bug reports should be sent. For sake of completeness,
we suggest that you also define @code{AT_PACKAGE_NAME},
-@code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
+@code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and
+@code{AT_PACKAGE_URL}.
@xref{Initializing configure}, for a description of these variables.
Be sure to distribute @file{package.m4} and to put it into the source
hierarchy: the test suite ought to be shipped! See below for an example
echo ' [@@PACKAGE_STRING@@])' && \
echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \
echo ' [@@PACKAGE_BUGREPORT@@])'; \
+ echo 'm4_define([AT_PACKAGE_URL],' && \
+ echo ' [@@PACKAGE_URL@@])'; \
@} >'$(srcdir)/package.m4'
EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in
# This file is part of Autoconf. -*- Autoconf -*-
# M4 macros used in building test suites.
-
-# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
-# Free Software Foundation, Inc.
+m4_define([_AT_COPYRIGHT_YEARS],
+[Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
+2009 Free Software Foundation, Inc.])
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
m4_define([AT_INIT],
[m4_pushdef([AT_INIT], [m4_fatal([$0: invoked multiple times])])]
[m4_pattern_forbid([^_?AT_])]
-[m4_pattern_allow([^_AT_T_EOF$])]
+[m4_pattern_allow([^_ATEOF$])]
+[m4_ifndef([AT_PACKAGE_BUGREPORT], [m4_fatal(
+ [$1: AT_PACKAGE_BUGREPORT is missing, consider writing package.m4])])]
[m4_define([AT_TESTSUITE_NAME],
m4_defn([AT_PACKAGE_STRING])[ test suite]m4_ifval([$1],
[m4_expand([: $1])]))]
[m4_cleardivert([BODY])]dnl
[AS_ME_PREPARE[]]dnl
[m4_divert_push([DEFAULTS])]dnl
-[AT_COPYRIGHT(
-[Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
-Free Software Foundation, Inc.
+[AT_COPYRIGHT(m4_defn([_AT_COPYRIGHT_YEARS])[
This test suite is free software; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.])
AS_PREPARE
m4_divert_push([HELP_END])dnl
cat <<_ATEOF || at_write_fail=1
-Report bugs to <AT_PACKAGE_BUGREPORT>.
+Report bugs to <AT_PACKAGE_BUGREPORT>.dnl
+m4_ifdef([AT_PACKAGE_NAME],
+[m4_ifset([AT_PACKAGE_URL], [
+m4_defn([AT_PACKAGE_NAME]) home page: <AT_PACKAGE_URL>.])dnl
+m4_if(m4_index(m4_defn([AT_PACKAGE_NAME]), [GNU ]), [0], [
+General help using GNU software: <http://www.gnu.org/gethelp/>.])])
_ATEOF
exit $at_write_fail
fi
m4_divert_push([VERSION])dnl
if $at_version_p; then
AS_ECHO(["$as_me (AT_PACKAGE_STRING)"]) &&
- cat <<\_ACEOF || at_write_fail=1
+ cat <<\_ATEOF || at_write_fail=1
m4_divert_pop([VERSION])dnl
m4_divert_push([VERSION_END])dnl
-_ACEOF
+_ATEOF
exit $at_write_fail
fi
m4_divert_pop([VERSION_END])dnl
## Make Autoconf tests.
-# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
-# Free Software Foundation, Inc.
+# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
+# 2009 Free Software Foundation, Inc.
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
echo 'm4_define([AT_PACKAGE_TARNAME], [$(PACKAGE_TARNAME)])' && \
echo 'm4_define([AT_PACKAGE_VERSION], [$(PACKAGE_VERSION)])' && \
echo 'm4_define([AT_PACKAGE_STRING], [$(PACKAGE_STRING)])' && \
- echo 'm4_define([AT_PACKAGE_BUGREPORT], [$(PACKAGE_BUGREPORT)])'; \
+ echo 'm4_define([AT_PACKAGE_BUGREPORT], [$(PACKAGE_BUGREPORT)])' && \
+ echo 'm4_define([AT_PACKAGE_URL], [$(PACKAGE_URL)])'; \
} > $@-t
mv $@-t $@
projects / thirdparty / autoconf.git / commitdiff
