diff options
author | Karl Berry <karl@freefriends.org> | 2021-07-01 18:21:51 -0700 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-07-01 18:21:51 -0700 |
commit | 16569085c531e884faa2124c5b02404a996921c8 (patch) | |
tree | 3aa480039a38c7b836611797dd61a8ac11153c80 | |
parent | e7724fb1b7b97f662caf154414e6f71ffcbd966c (diff) | |
download | automake-16569085c531e884faa2124c5b02404a996921c8.tar.gz |
dist: accept .md versions for README et al.
This change was suggested by madmurphy; some ideas were taken
from the patch he provided.
https://lists.gnu.org/archive/html/automake-patches/2021-06/msg00005.html
* bin/automake.in (@toplevelmd_ok): new global, listing the files
for which we will accept .md versions.
(@common_files): remove those files from there.
(handle_dist): check for .md if non-.md is absent.
(handle_minor_options): check for README-alpha.md.
(check_gnu_standards): accept .md version if present.
(check_gnits_standards): likewise.
(usage): output list of .md-accepted files.
* doc/automake.texi (Basics of Distribution): document.
* t/toplevelmd.sh: new test.
* t/list-of-tests.mk (handwritten_tests): add it.
* NEWS: mention new feature.
-rw-r--r-- | NEWS | 7 | ||||
-rw-r--r-- | bin/automake.in | 61 | ||||
-rw-r--r-- | doc/automake.texi | 231 | ||||
-rw-r--r-- | t/list-of-tests.mk | 3 | ||||
-rw-r--r-- | t/toplevelmd.sh | 68 |
5 files changed, 265 insertions, 105 deletions
@@ -7,6 +7,10 @@ New in ?.?.?: * New features added + - Common top-level files can be provided as .md; the non-md version is + used if both are present: + AUTHORS ChangeLog INSTALL NEWS README README-alpha THANKS + - CTAGS, ETAGS, SCOPE variables can be set via configure. - PYTHON_PREFIX and PYTHON_EXEC_PREFIX variables now set from Python's @@ -17,6 +21,7 @@ New in ?.?.?: * Bugs fixed - automake output reproducible. + - test-driver less likely to clash with tests writing to the same file. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -30,7 +35,7 @@ New in 1.16.3: * Bugs fixed - - Python 3.10 version number no longer considered to be 3.1. + - Python version number 3.10 no longer considered to be 3.1. - Broken links in manual fixed or removed, and new script contrib/checklinkx (a small modification of W3C checklink) added, diff --git a/bin/automake.in b/bin/automake.in index 19ea9538f..72c35793d 100644 --- a/bin/automake.in +++ b/bin/automake.in @@ -1,7 +1,7 @@ #!@PERL@ # automake - create Makefile.in from Makefile.am -*- perl -*- # @configure_input@ -# Copyright (C) 1994-2020 Free Software Foundation, Inc. +# Copyright (C) 1994-2021 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 @@ -199,11 +199,14 @@ my @libtool_files = qw(ltmain.sh config.guess config.sub); # ltconfig appears here for compatibility with old versions of libtool. my @libtool_sometimes = qw(ltconfig ltcf-c.sh ltcf-cxx.sh ltcf-gcj.sh); -# Commonly found files we look for and automatically include in -# DISTFILES. +# Top-level files that can be foo.md instead of foo. We assume that all +# but THANKS are required at strictness level gnu. +my @toplevelmd_ok = qw(AUTHORS ChangeLog INSTALL NEWS README THANKS); + +# Commonly found files we look for and automatically include in DISTFILES. my @common_files = - (qw(ABOUT-GNU ABOUT-NLS AUTHORS BACKLOG COPYING COPYING.DOC COPYING.LIB - COPYING.LESSER ChangeLog INSTALL NEWS README THANKS TODO + (qw(ABOUT-GNU ABOUT-NLS BACKLOG COPYING + COPYING.DOC COPYING.LIB COPYING.LESSER TODO ar-lib compile config.guess config.rpath config.sub depcomp install-sh libversion.in mdate-sh missing mkinstalldirs py-compile texinfo.tex ylwrap), @@ -3833,7 +3836,7 @@ sub handle_dist () $check_aux = 1; } } - foreach my $cfile (@common_files) + foreach my $cfile (@toplevelmd_ok, @common_files) { if (dir_has_case_matching_file ($relative_dir, $cfile) # The file might be absent, but if it can be built it's ok. @@ -3841,13 +3844,30 @@ sub handle_dist () { push_dist_common ($cfile); } + elsif (grep { $_ eq $cfile } @toplevelmd_ok) + { # Irritatingly, have to repeat the checks, now for .md files; + # we want to prefer non-.md, so do this second, and only "elsif". + if (dir_has_case_matching_file ($relative_dir, "$cfile.md") + || rule "$cfile.md") + { + push_dist_common ("$cfile.md"); + } + } # Don't use 'elsif' here because a file might meaningfully - # appear in both directories. + # appear in both $relative_dir and $config_aux_dir. if ($check_aux && dir_has_case_matching_file ($config_aux_dir, $cfile)) { push_dist_common ("$config_aux_dir/$cfile") } + elsif ($check_aux && grep { $_ eq $cfile } @toplevelmd_ok) + { + if (dir_has_case_matching_file ($config_aux_dir, "$cfile.md") + || rule "$cfile.md") + { + push_dist_common ("$cfile.md"); + } + } } # We might copy elements from @configure_dist_common to @@ -5119,11 +5139,12 @@ sub handle_minor_options () "version '$package_version' doesn't follow " . "Gnits standards"); } - if (defined $1 && -f 'README-alpha') + if (defined $1 && (-f 'README-alpha' || -f 'README-alpha.md')) { # This means we have an alpha release. See # GNITS_VERSION_PATTERN for details. - push_dist_common ('README-alpha'); + my $af = -f 'README-alpha' ? 'README-alpha' : 'README-alpha.md'; + push_dist_common ($af); } } } @@ -5610,8 +5631,16 @@ sub check_gnu_standards () if ($relative_dir eq '.') { # In top level (or only) directory. - require_file ("$am_file.am", GNU, - qw/INSTALL NEWS README AUTHORS ChangeLog/); + + foreach my $file (@toplevelmd_ok) + { + next if $file eq 'THANKS'; # gnits, checked below + # if non-.md is absent, and .md is present, require .md; + # otherwise require non-.md. + my $required + = (! -f $file && -f "$file.md") ? "$file.md" : $file; + require_file ("$am_file.am", GNU, $required); + } # Accept one of these three licenses; default to COPYING. # Make sure we do not overwrite an existing license. @@ -5642,7 +5671,10 @@ sub check_gnits_standards () if ($relative_dir eq '.') { # In top level (or only) directory. - require_file ("$am_file.am", GNITS, 'THANKS'); + my $file = 'THANKS'; + my $required + = (! -f $file && -f "$file.md") ? "$file.md" : $file; + require_file ("$am_file.am", GNITS, $file); } } @@ -8156,8 +8188,11 @@ Library files: "(always):\n"; print_autodist_files @common_files; print "\nFiles automatically distributed if found " . + "(as .md if needed):\n"; + print_autodist_files (map { "${_}[.md]" } @toplevelmd_ok); + print "\nFiles automatically distributed if found " . "(under certain conditions):\n"; - print_autodist_files @common_sometimes; + print_autodist_files @common_sometimes, 'README-alpha[.md]'; print ' Report bugs to <@PACKAGE_BUGREPORT@>. diff --git a/doc/automake.texi b/doc/automake.texi index 351b0a1bb..f1deff813 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -8515,60 +8515,91 @@ We recommend that you follow this same set of heuristics in your @vindex VERSION @trindex dist The @code{dist} rule in the generated @file{Makefile.in} can be used -to generate a gzipped @code{tar} file and other flavors of archive for -distribution. The file is named based on the @code{PACKAGE} and +to generate a gzipped @code{tar} file and/or other flavors of archives +for distribution. The file is named based on the @code{PACKAGE} and @code{VERSION} variables automatically defined by either the @code{AC_INIT} invocation or by a @emph{deprecated} two-arguments -invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros} -for how these variables get their values, from either defaults or explicit -values---it's slightly trickier than one would expect). -More precisely the gzipped @code{tar} file is named +invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public +Macros} for how these variables get their values, from either defaults +or explicit values---it's slightly trickier than one would expect). +More precisely, the gzipped @code{tar} file is named @samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}. -@vindex GZIP_ENV -You can use the @command{make} variable @code{GZIP_ENV} to control how gzip -is run. The default setting is @option{--best}. - @c See automake #9822. @vindex TAR You can set the environment variable @code{TAR} to override the tar -program used; it defaults to @code{tar}. +program used; it defaults to @code{tar}. @xref{The Types of +Distributions}, for how to generate other kinds of archives. + +For the most part, the files to distribute are automatically found by +Automake: + +@itemize @bullet +@item +All source files are automatically included in a distribution, as are +all @file{Makefile.am} and @file{Makefile.in} files. + +@acindex AC_CONFIG_FILES +@item +Files that are read by @command{configure} are automatically +distributed. These are the source files as specified in various +Autoconf macros such as @code{AC_CONFIG_FILES} and siblings. @cindex @code{m4_include}, distribution @cindex @code{include}, distribution @acindex m4_include @cmindex include -For the most part, the files to distribute are automatically found by -Automake: all source files are automatically included in a -distribution, as are all @file{Makefile.am} and @file{Makefile.in} -files. Automake also has a built-in list of commonly used files that -are automatically included if they are found in the current directory -(either physically, or as the target of a @file{Makefile.am} rule); -this list is printed by @samp{automake --help}. However, some files -in this list are distributed only if other certain conditions hold -(for example, +@item +Files included in a @file{Makefile.am} (using @code{include}) or in +@file{configure.ac} (using @code{m4_include}). + +@item +Automake has a built-in list of commonly used files automatically +included in the distribution if they are found in the current +directory (either physically, or as the target of a @file{Makefile.am} +rule). Some common examples: @file{ABOUT-GNU}, @file{COPYING}, +@file{TODO}. + +This list also includes helper scripts installed with @samp{automake +--add-missing}. Some common examples: @file{compile}, +@file{config.guess}, @file{config.rpath}, @file{config.sub}, +@file{texinfo.tex}. + +@item +Automake has another built-in list of files automatically distributed +if they are found either with the plain name, or with extension +@file{.md} (presumably MarkDown, though this not checked). They are +checked for in that order, so the plain name is preferred. These are: +@file{AUTHORS ChangeLog INSTALL NEWS README README-alpha THANKS}. + +@item +A final built-in list of files are those distributed only if other +certain conditions hold. For example, @c Keep in sync with autodist-config-headers.sh -the @file{config.h.top} and @file{config.h.bot} files are automatically -distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used -in @file{configure.ac}). Also, files that are read by @command{configure} -(i.e., the source files corresponding to the files specified in various -Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are -automatically distributed. Files included in a @file{Makefile.am} (using -@code{include}) or in @file{configure.ac} (using @code{m4_include}), and -helper scripts installed with @samp{automake --add-missing} are also -distributed. +the files @file{config.h.top} and @file{config.h.bot} are +automatically distributed only if, e.g., +@samp{AC_CONFIG_HEADERS([config.h])} is used in @file{configure.ac}). +@file{README-alpha} is another such file, with @file{README-alpha.md} +distributed if that is what is available; @pxref{Strictness}, for its +conditions for distribution. + +@end itemize + +@noindent +These three lists of files are given in their entirety in the output +from @code{automake --help}. @vindex EXTRA_DIST -Still, sometimes there are files that must be distributed, but which -are not covered in the automatic rules. These files should be listed in -the @code{EXTRA_DIST} variable. You can mention files from -subdirectories in @code{EXTRA_DIST}. - -You can also mention a directory in @code{EXTRA_DIST}; in this case the -entire directory will be recursively copied into the distribution. -Please note that this will also copy @emph{everything} in the directory, -including, e.g., Subversion's @file{.svn} private directories or CVS/RCS -version control files; thus we recommend against using this feature +Despite all this automatic inclusion, it is still common to have files +to be distributed which are not found by the automatic rules. You +should listed these files in the @code{EXTRA_DIST} variable. You can +mention files in subdirectories in @code{EXTRA_DIST}. + +You can also mention a directory in @code{EXTRA_DIST}; in this case +the entire directory will be recursively copied into the distribution. +To emphasize, this copies @emph{everything} in the directory, +including temporary editor files, intermediate build files, version +control files, etc.; thus we recommend against using this feature as-is. However, you can use the @code{dist-hook} feature to ameliorate the problem; @pxref{The dist Hook}. @@ -8623,20 +8654,20 @@ a directory in @code{EXTRA_DIST}: EXTRA_DIST = doc dist-hook: chmod -R u+w $(distdir)/doc - rm -rf `find $(distdir)/doc -type d -name .svn` + rm -rf `find $(distdir)/doc -type d -name RCS` @end example @c The caveats described here should be documented in 'disthook.sh'. @noindent -Note that the @code{dist-hook} recipe shouldn't assume that the regular -files in the distribution directory are writable; this might not be the -case if one is packaging from a read-only source tree, or when a -@code{make distcheck} is being done. For similar reasons, the recipe -shouldn't assume that the subdirectories put into the distribution -directory as an effect of having them listed in @code{EXTRA_DIST} are -writable. So, if the @code{dist-hook} recipe wants to modify the -content of an existing file (or @code{EXTRA_DIST} subdirectory) in the -distribution directory, it should explicitly to make it writable first: +The @code{dist-hook} recipe should not assume that the regular files +in the distribution directory are writable; this might not be the case +if one is packaging from a read-only source tree, or when a @code{make +distcheck} is being done. Similarly, the recipe should not assume +that the subdirectories put into the distribution directory as a +result of being listed in @code{EXTRA_DIST} are writable. So, if the +@code{dist-hook} recipe wants to modify the content of an existing +file (or @code{EXTRA_DIST} subdirectory) in the distribution +directory, it should explicitly to make it writable first: @example EXTRA_DIST = README doc @@ -8656,16 +8687,17 @@ will copy files from the current directory before creating the tarball. If you are at the top-level directory, then @samp{distdir = $(PACKAGE)-$(VERSION)}. When used from subdirectory named @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}. -@samp{$(distdir)} can be a relative or absolute path, do not assume -any form. +@samp{$(distdir)} can be either a relative or absolute path; do not +assume a particular form. @samp{$(top_distdir)} always points to the root directory of the -distributed tree. At the top-level it's equal to @samp{$(distdir)}. -In the @file{foo/} subdirectory -@samp{top_distdir = ../$(PACKAGE)-$(VERSION)}. -@samp{$(top_distdir)} too can be a relative or absolute path. +distributed tree. At the top level it's equal to @samp{$(distdir)}. +In the @file{foo/} subdirectory @samp{top_distdir = +../$(PACKAGE)-$(VERSION)}. @samp{$(top_distdir)} can also be either a +relative or absolute path. -Note that when packages are nested using @code{AC_CONFIG_SUBDIRS} +@acindex AC_CONFIG_SUBDIRS +When packages are nested using @code{AC_CONFIG_SUBDIRS} (@pxref{Subpackages}), then @samp{$(distdir)} and @samp{$(top_distdir)} are relative to the package where @samp{make dist} was run, not to any sub-packages involved. @@ -8855,70 +8887,89 @@ distributions in various formats. Their targets are: @table @asis @item @code{dist-gzip} -Generate a @samp{gzip} tar archive of the distribution. This is the -only format enabled by default. @trindex dist-gzip +@cmindex gzip +@vindex GZIP_ENV +Generate a @samp{gzip} tar archive of the distribution. This is the +only format enabled by default. By default, this rule makes +@command{gzip} use a compression option of @option{--best}. To make +it use a different one, set the @env{GZIP_ENV} environment variable. +For example, @samp{make dist-gzip GZIP_ENV=-7}. -@vindex BZIP2 @item @code{dist-bzip2} -Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives -are frequently smaller than gzipped archives. -By default, this rule makes @samp{bzip2} use a compression option of @option{-9}. -To make it use a different one, set the @env{BZIP2} environment variable. -For example, @samp{make dist-bzip2 BZIP2=-7}. @trindex dist-bzip2 +@cmindex bzip2 +@vindex BZIP2 +Generate a @samp{bzip2} tar archive of the distribution. bzip2 +archives are usually smaller than gzipped archives. By default, this +rule makes @samp{bzip2} use a compression option of @option{-9}. To +make it use a different one, set the @env{BZIP2} environment variable. @item @code{dist-lzip} -Generate an @samp{lzip} tar archive of the distribution. @command{lzip} -archives are frequently smaller than @command{bzip2}-compressed archives. @trindex dist-lzip +@cmindex lzip +@vindex LZIP_OPT +Generate an @samp{lzip} tar archive of the distribution. +@command{lzip} archives are usually smaller than +@command{bzip2}-compressed archives. By default, this rule makes +@samp{lzip} use a compression option of @option{-9}. To make it use a +different one, set the @env{LZIP_OPT} environment variable. -@vindex XZ_OPT @item @code{dist-xz} +@trindex dist-xz +@cmindex xz +@vindex XZ_OPT Generate an @samp{xz} tar archive of the distribution. @command{xz} -archives are frequently smaller than @command{bzip2}-compressed archives. +archives are usually smaller than @command{bzip2}-compressed archives. By default, this rule makes @samp{xz} use a compression option of @option{-e}. To make it use a different one, set the @env{XZ_OPT} environment variable. For example, run this command to use the -default compression ratio, but with a progress indicator: -@samp{make dist-xz XZ_OPT=-ve}. -@trindex dist-xz +default compression ratio, but with a progress indicator: @samp{make +dist-xz XZ_OPT=-ve}. +@trindex dist-zip +@cmindex zip @item @code{dist-zip} Generate a @samp{zip} archive of the distribution. -@trindex dist-zip -@item @code{dist-tarZ} -Generate a tar archive of the distribution, compressed with the -historical (and obsolescent) program @command{compress}. This -option is deprecated, and it and the corresponding functionality -will be removed altogether in Automake 2.0. -@trindex dist-tarZ +@item @code{dist-zstd} +@trindex dist-zstd +@cmindex zstd +@vindex ZSTD_OPT +@vindex ZSTD_CLEVEL +Generate a @code{zstd} tar archive of the distribution. By default, +this rule makes @command{zstd} use a compression option of +@option{-19}. To use a different setting, set the @env{ZSTD_OPT} +environment variable. For example, run this command to use the +default compression ratio, but with a progress indicator: @samp{make +dist-zstd ZSTD_OPT=-19v}. However, note that for compatibility with +@command{zstd} itself, you may instead set the @env{ZSTD_CLEVEL} +environment variable, in which case, any @env{ZSTD_OPT} setting is +ignored. @item @code{dist-shar} +@trindex dist-shar +@cmindex shar Generate a @samp{shar} archive of the distribution. This format archive is obsolescent, and use of this option is deprecated. It and the corresponding functionality will be removed altogether in Automake 2.0. -@trindex dist-shar -@vindex ZSTD_OPT -@vindex ZSTD_CLEVEL -@item @code{dist-zstd} -Generate a @samp{zstd} tar archive of the distribution. By default, this -rule makes @samp{zstd} use a compression option of @option{-19}. To -make it use a different one, set the @env{ZSTD_OPT} environment variable. -For example, run this command to use the default compression ratio, -but with a progress indicator: @samp{make dist-zstd ZSTD_OPT=-19v}. -However, note that for compatibility with zstd itself, you may instead set the @env{ZSTD_CLEVEL} environment variable, in which case, any @env{ZSTD_OPT} setting is ignored. -@trindex dist-zstd +@item @code{dist-tarZ} +@trindex dist-tarZ +@cmindex compress +Generate a tar archive of the distribution, compressed with the +historical (and obsolescent) program @command{compress}. This +option is deprecated, and it and the corresponding functionality +will be removed altogether in Automake 2.0. @end table +@trindex dist-all The rule @code{dist} (and its historical synonym @code{dist-all}) will create archives in all the enabled formats (@pxref{List of Automake options} for how to change this list). By default, only -the @code{dist-gzip} target is hooked to @code{dist}. +the @code{dist-gzip} target is enabled by @code{dist}. @node Tests diff --git a/t/list-of-tests.mk b/t/list-of-tests.mk index 51456ef51..934930b50 100644 --- a/t/list-of-tests.mk +++ b/t/list-of-tests.mk @@ -2,7 +2,7 @@ ## testsuite. This fragment is meant to be included by the Makefile.am, ## but also to be executed directly by make when bootstrapping automake. -## Copyright (C) 2011-2020 Free Software Foundation, Inc. +## Copyright (C) 2011-2021 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 @@ -848,6 +848,7 @@ t/test-trs-recover.sh \ t/test-trs-recover2.sh \ t/test-extensions.sh \ t/test-extensions-cond.sh \ +t/toplevelmd.sh \ t/parse.sh \ t/percent.sh \ t/percent2.sh \ diff --git a/t/toplevelmd.sh b/t/toplevelmd.sh new file mode 100644 index 000000000..0634c7490 --- /dev/null +++ b/t/toplevelmd.sh @@ -0,0 +1,68 @@ +#! /bin/sh +# Copyright (C) 2003-2021 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 +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +# Check that the top-level files (INSTALL, NEWS, README-alpha, etc.) +# can be .md, or not. (Based on alpha2.sh.) + +. test-init.sh + +cat > configure.ac << 'END' +AC_INIT([alpha], [1.0b]) +AM_INIT_AUTOMAKE([readme-alpha]) +AC_CONFIG_FILES([Makefile sub/Makefile]) +AC_OUTPUT +END + +cat > Makefile.am << 'END' +SUBDIRS = sub +check-local: distdir + for f in AUTHORS ChangeLog INSTALL NEWS README THANKS; do \ + test -f $(distdir)/$$f.md; done + test -f $(distdir)/COPYING + test -f $(distdir)/README-alpha.md + test ! -f $(distdir)/sub/README.md + test ! -f $(distdir)/sub/README-alpha.md # not distributed + : > works +END + +mkdir sub +: > sub/Makefile.am + +# do both md and non-md. +: > README-alpha.md +: > sub/README-alpha.md +: > sub/README + +# top level +: > AUTHORS.md +: > ChangeLog.md +: > INSTALL.md +: > NEWS.md +: > README.md +: > THANKS.md + +# not md +: > COPYING + + +$ACLOCAL +$AUTOCONF +$AUTOMAKE +./configure +$MAKE check +test -f works + +exit 33 |