Package: debmake-doc Version: 1.9-1 Tags: patch Section 5.16.1 recommends running autoreconf when building a package on Debian GNU/Linux, to improve portability to new systems. That brings with it considerations about automake. The default "strictness" level of an automake setup is the "gnu" level, which requires files AUTHORS, ChangeLog, INSTALL, NEWS, and README along with the Makefile.am and configure.ac files that autoreconf will expect. That then brings other implications for using such a package on Debian.
Elsewhere, the document refers to the GNU Coding Standards, which is further reason to make mention of the above files, and which get installed and which do not get installed (COPYING and INSTALL) on Debian. I propose that wording like what follows be considered for the end of Section 8.9 or 8.11. Both of those examples set the automake strictness level to "foreign", which is good for a simple example but leaves out some details that could help someone new with Debian packaging. I tried to capture the major considerations for packages that follow GNU standards, and think something along these lines would help: [begin insert] The line AM_INIT_AUTOMAKE([foreign]) in configure.ac above tells automake to use a "foreign" strictness level, which has loose requirements for what files are in a package. The default strictness level for automake is "gnu", which expects the following files in the top-level directory: AUTHORS, INSTALL, NEWS, README, ChangeLog, and either COPYING (with a copy of a GPL license) or COPYING.LESSER (with a copy of a LGPL license). If you are building such a package, Section 5.16.1 [Autotools] of this guide recommends invoking autoreconf in debian/rules to provide better support for porting to new architectures, compared to just running "./configure && make". If you intend to run autoreconf on a package with automake set to a strictness level of "gnu", automake will complain if the files it expects in the top-level directory are not present. In this case the INSTALL and COPYING (or COPYING.LESSER) files must be present in the source directory. However, they are not installed on Debian systems because Debian uses its own package manager for installation, and keeps copies of common licenses in /usr/share/common-licenses. The other files besides Makefile.am and configure.ac that Autotools expects in the top-level directory (AUTHORS, NEWS, README, and ChangeLog) can be installed in /usr/share/doc/<package>. This can be done by listing those files in debian/doc. If you keep any Autotools-generated files in the Debian package, make sure that those files have their copyright and license information captured in the debian/copyright file. Their copyright notices and license terms differ slightly, so you will have to check every one. The GNU Project standard practice is to leave all such files in place if a "make distclean" leaves them, so asking upstream to remove them is probably not the correct solution. Running "autoreconf -ivf" as described in Section 5.16.1 will create a new INSTALL file even if one existed. That file will have a copyright, as will the GPL or LGPL in the COPYING or COPYING.LESSER file. Therefore, list those files in the Files-Exclude field in the first paragraph of debian/copyright. Also list any files that "autoreconf -ivf" creates but that remain following a "make distclean" in the Files-Exclude field, because autoreconf will recreate those files. Some maintainer discretion is allowed to leave a config.h file that should not change, etc. Apart from those files, the only other files that must exist with the "gnu" automake strictness level to run autoreconf in the top-level directory are Makefile.am and configure.ac. One of the standard "make" targets that automake creates is "distcheck". That builds a copy of the package in a staging directory by defining the DESTDIR variable, then creates a distribution tar file of the package from the newly-built copy, and finally tries building from that tar file a second time along with running various checks on the final result (see the GNU Automake manual for further details). It is advisable if you are using GNU Autotools to ensure that "make distcheck" succeeds on the upstream package before attempting to create a debianized version. If the upstream package fails a "make distcheck" with Autotools, it will probably have issues on Debian. [end insert] Thanks, Paul Hardy
