On Thu, Aug 2, 2018 at 9:14 AM, Osamu Aoki <os...@debian.org> wrote: > Hi, > > Thank you for your very detailed review.
I realized when I wrote it that it was probably _too much_ detail (I tried to keep everything on one screen but went a little past that). I figured I would get all my thoughts down for others to pick and choose what they wanted to use. > 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 > ... > 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. Yes. I brought up the "gnu" strictness level for automake because the _Guide for Debian Maintainers_ already refers the reader to consult the GNU Coding Standards. It was not with a goal of packaging for the GNU Project. Maybe that is going too far though. > 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/*”). > ---- Sounds good. >> 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. Well, building in debian/rules with autoreconf will run that too. Actually, I don't know if running automake with "foreign" strictness re-creates INSTALL. I have only tried automake with "gnu" strictness. >> 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. I realize that. I should have said use Files-Exclude to handle the case where uscan is downloading upstream files automatically. >> 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. I have never used CDBS, cmake, etc., so I don't know how they work. I think a quick mention of using distcheck as a warm-up exercise for pbuilder (for example) is useful, because that lets a packager know that the package builds correctly when builddir is not the same as srcdir. Maybe it is worth mentioning that in some more general way in the beginning. Most people packaging for Debian for the first time are probably coming from an environment where they only cared about building for the single architecture that they were using. Thanks, Paul Hardy
