From: Eric Blake Date: Tue, 27 Jan 2009 23:13:41 +0000 (-0700) Subject: Use URLs in --help output, part 3: testsuite. X-Git-Tag: v2.63b~32 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=758f763ddf778040333d9c4f7679a3f08ec0268d;p=thirdparty%2Fautoconf.git Use URLs in --help output, part 3: testsuite. * doc/autoconf.texi (Writing Testsuites): Mention autotest namespace. (Writing Testsuites) : 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. Signed-off-by: Eric Blake --- diff --git a/ChangeLog b/ChangeLog index a521e0c0b..e550b269f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,15 @@ 2009-01-27 Eric Blake + Use URLs in --help output, part 3: testsuite. + * doc/autoconf.texi (Writing Testsuites): Mention autotest + namespace. + (Writing Testsuites) : 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. diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 8a5dc2ed9..0d20f2a20 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -21807,11 +21807,11 @@ AC_COMPILE_IFELSE([AC_LANG_PROGRAM( @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 @@ -22035,13 +22035,31 @@ then an arbitrary number of shell commands or calls to @code{AT_CHECK}, 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}) @@ -22329,12 +22347,14 @@ check list of things to do. @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 @@ -22381,6 +22401,8 @@ $(srcdir)/package.m4: $(top_srcdir)/configure.ac 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 diff --git a/lib/autotest/general.m4 b/lib/autotest/general.m4 index 5f2db7977..a53c394e5 100644 --- a/lib/autotest/general.m4 +++ b/lib/autotest/general.m4 @@ -1,8 +1,8 @@ # 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 @@ -206,7 +206,9 @@ m4_define([_AT_DEFINE_SETUP], 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])]))] @@ -222,9 +224,7 @@ dnl This trick removes that banner, since it adds nothing to autotest. [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 @@ -704,7 +704,12 @@ m4_divert_pop([HELP_TUNING])dnl m4_divert_push([HELP_END])dnl cat <<_ATEOF || at_write_fail=1 -Report bugs to . +Report bugs to .dnl +m4_ifdef([AT_PACKAGE_NAME], +[m4_ifset([AT_PACKAGE_URL], [ +m4_defn([AT_PACKAGE_NAME]) home page: .])dnl +m4_if(m4_index(m4_defn([AT_PACKAGE_NAME]), [GNU ]), [0], [ +General help using GNU software: .])]) _ATEOF exit $at_write_fail fi @@ -764,10 +769,10 @@ m4_divert_pop([HELP_END])dnl 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 diff --git a/tests/Makefile.am b/tests/Makefile.am index 0556b2952..522236da5 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -1,7 +1,7 @@ ## 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 @@ -44,7 +44,8 @@ package.m4: Makefile 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 $@