Bug#905167: debmake-doc: Handling Upstream Autotools Packaging on Debian
On Thu, Aug 02, 2018 at 10:33:14PM -0700, Paul Hardy wrote: > On Thu, Aug 2, 2018 at 9:14 AM, Osamu Aoki wrote: ... > >> 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. Very true. (I was not thinking clearly) > Actually, I don't know if running automake with "foreign" strictness > re-creates INSTALL. I have only tried automake with "gnu" strictness. Let me think a bit when I have time. ... > > 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 ^ I think you have very good point here. > probably coming from an environment where they only cared about > building for the single architecture that they were using. I think I put some reminder already but I agree with your thought. I think we need reminder for: * Multi-arch * Reproducible build * Boot straping ... Regards, Osamu > Thanks, > > > Paul Hardy
Bug#905167: debmake-doc: Handling Upstream Autotools Packaging on Debian
On Thu, Aug 2, 2018 at 9:14 AM, Osamu Aoki 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/. > > 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
Bug#905167: debmake-doc: Handling Upstream Autotools Packaging on Debian
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/. 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
Bug#905167: debmake-doc: Handling Upstream Autotools Packaging on Debian
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/. 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
