Hi, Thank you for your very detailed review.
On Tue, Jul 31, 2018 at 11:12:12PM -0700, Paul Hardy wrote: > 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. Actually, this part needs some updates since recent debhelper depends on the dh-autoreconf package and runs it as the default behavior since debhelper 9.20160402/02 Apr 2016. After: | The package maintainer may wish to take care all steps 1 to 4. This is | realized by the “dh $@ --with autoreconf” command used in the | debian/rules file. This rebuilds all auto-generated files to the latest | version ones and provides better supports for the porting to the newer | architectures. Let's add: | For compat level 10 or newer, the simple “dh $@” command without | "--with autoreconf" option can take care all steps 1 to 4, too. > 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. Hmmm.... I had a different thought and intentionally chose "foreign". > 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. This tutorial is about packaging an upstream source ... not about creating an upstream source to be uploaded to the GNU project. I also find many packages on Debian uses "foreign". Upstream source on git may not have NEWS and ChangeLog. So making simpler example is good for entry level document. Another POV I checked is: https://autotools.io/automake/options.html#automake.options.flavors > 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 I think adding a short pointer to remind automake defaults to gnu flavor may be a good idea around Section 8.9. But I don't think I should elaborate too much in detail. If we do so, this tutorial get bloated and reader will lose important things to learn about the Debian packaging. After "configure.ac (v=1.6): " example, add: ---- TIP: Without "foreign" strictness level specified in AM_INIT_AUTOMAKE() as above, automake defaults to "gnu" strictness level requiring several files in the top-level directory. See "3.2 Strictness" in the automake document. ---- > 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 is fair point to be reminded. Place to do is at: 5.12. Customization of the Debian packaging Now: ---- * The Debian package build system can be customized through the debian/rules file (see Section 5.4.3, “Customized debian/rules”). * The Debian package installation path etc. can be customized through the addition of configuration files in the debian/ directory for the dh_* commands from the debhelper package (see Section 5.11, “Other debian/*”). ---- Proposed: ---- * The Debian package build system can be customized through the debian/rules file (see Section 5.4.3, “Customized debian/rules”). * The Debian package installation path etc. can be customized through the addition of configuration files such as "package.doc" and "package.install" in the debian/ directory for the dh_* commands from the debhelper package (see Section 5.11, “Other debian/*”). ---- > 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. Should we have to dwell on these? It's good practice but ... > Running "autoreconf -ivf" as described in Section 5.16.1 will create > a new INSTALL file even if one existed.i As written there, this is run by the upstream. > 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. ??? What ??? Files-Exclude field is for different purpose and effect. Please check the uscan manpage and mk-origtargz manpage. Files-Excluded or Files-Excluded-component stanzas are set in debian/copyright to make mk-origtargz invoked from uscan remove files from the upstream tarball and repack it. See "COPYRIGHT FILE EXAMPLES" and mk-origtargz(1). > Also list any files that "autoreconf -ivf" creates I would do that for my .gitignore but .... > 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. That's same for "foreign". And it's obvious by reading example in 8.9. Autotools (single-binary). > One of the standard "make" targets that automake creates is "distcheck". Yes. But I am not writing full tutorial on autotools. Nor this test build target also exist on other upstream build system. > 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] This s true but if I touch on this subject, I should do the same for others.... It is too much. Maybe, somewhere in 5.16. Upstream build systems, I should add some reminder to test build package. autotools: make distcheck cmake: ? setup.py: ? Let me think a bit on this. Good night. Osamu
