Hi Bruno,
At 2026-08-07T20:27:08+0200, Bruno Haible wrote:
> > Does GNU Automake support a better method of satisfying our
> > requirements?
>
> Yes, it does. Find attached a proposed patch that updates the rules
> for doc/gnu.{eps,png} and doc/line-layout.{eps,png}, so that
> * --enable-maintainer-mode is no longer necessary for building from
> a git checkout,I am starting to find it hard to conceptualize what "maintainer mode" _means_ in the context of Git-based development. How do you think of it? Is "maintainer mode" a relic that should be cast aside? > * a "make" run does no longer update doc/groff.dvi and doc/groff.pdf > when nothing has changed among the sources, That's certainly a desirable property. > Tested by > - running "make" and "make distcheck" in in-tree builds and VPATH > builds of the git checkout, > - verifying that the resulting tarball (from "make distcheck") has > the same contents in both cases, > - running "make" and "make distcheck" in in-tree builds and VPATH > builds from that tarball, > - building this tarball with VPATH builds on FreeBSD, NetBSD (with > the native 'make') and OpenBSD (with GNU make, because the OpenBSD > 'make' is known for not supporting VPATH builds well [1]), I have it working. But one must step carefully. https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/HACKING?id=0177f73f77c6ad64133929748cbd27fb223c90b8#n40 > - making small changes to doc/groff.texi.in and doing a VPATH build > then, then viewing the generated doc/groff.pdf pages 131 and 277. > > How does it work? I haven't tried it, because I've been wanting to roll 1.25.0.rc3 for _two months_, and this sort of churn to the build system is far too much for me to want to take on in this phase. Further, I fear your carve-out regarding OpenBSD Make support will produce a regression in the real world. We have a developer on the team who is an OpenBSD committer, but none from FreeBSD or NetBSD. I'll employ a term Deri commonly does, and observe that it seems "churlish" to frustrate the build environment of one of groff's small number of committers. > The main ingredient in the solution is to follow this advice from the > GNU Coding Standards [2]: > > "GNU distributions usually contain some files which are not source > files —for example, Info files, and the output from Autoconf, > Automake, Bison or Flex. Yes. I completely endorse and have tried to honor that principle. > Since these files normally appear in the source directory, they > should always appear in the source directory, not in the build > directory. So Makefile rules to update them should put the updated > files in the source directory." I agree with that. But when a stupid make(1) program refuses to look for them there, I become frustrated. > I remember that before I implemented this advice in my packages many > years ago, the alternate use of VPATH builds and in-tree builds > brought problems: > > - Sometimes a build step in a VPATH build picked up an outdated > artifact from a previous in-tree build, instead of the newer > artifact in the build directory. (Probably due to #include > handling; I don't remember the details.) We've certainly had problems in this area. It is, or used to be, pretty dangerous (as in unreliable) to do an out-of-tree build from a source directory that had at any time in the past been used for an in-tree build. > - Some Makefile rules had to be written in such a way that they > search for a file, first in the build directory, then in the > source directory. Yes. I dislike this rigmarole. > This advice thus > - makes the build more reliable and > - simplifies the Makefile rules. ...but, apparently, trades away support for OpenBSD Make. > So, the main change is to generate doc/line-layout.{eps,png} in the > source directory *and not in the build directory*. > > While doing this, the final "mv" in such a rule has to be avoided if > the file has not changed. Otherwise, one of the Automake "make > distcheck" checks, which > 1. unpacks the tarball and makes the source dir read-only, > 2. then does a VPATH build, > would attempt to overwrite a file in the read-only source dir and > fail. > > Even with this in place, I noticed that "make" in a VPATH build would > still regenerate doc/line-layout.eps and, accordingly, also > doc/line-layout.png > doc/groff.dvi > doc/groff.pdf > The reason is that the 'gs' command stores a "CreationDate" time stamp > in the doc/line-layout.eps file. Once I changed the rule to eliminate > the CreationDate line, the 4 files are no longer rebuilt without need. That part seems worth snarfing as soon as I can manage it. The reproducible builders of the world will, I suspect, appreciate it, too. The doc/line-layout stuff has continued to churn as recently as this week. It's proven quite devilish to get right. I feel like the Texinfo part of it will regress at the slightest provocation, and am flabbergasted at the lack of design invested in this area initially in the 1980s, and its neglect ever since.[A] > Then I did the same changes for doc/gnu.{eps,png}. Not because it's > needed to fix an actual build problem, but in order to keep doc/doc.am > consistent. I appreciate that. "doc/doc.am" is the biggest monster in our tree. > Next steps after this patch: > - You could apply said rule also to doc/groff.dvi and doc/groff.pdf, > as an exercise. Not that it would fix an actual build problem, > because no other build artifact depends on these two. > - You could un-recommend the use of --enable-maintainer-mode. This feels like post-1.25 work to me. Regards, Branden [A] I get the feeling that, just as groff is a dog wagged by its man(7) tail, Texinfo development is driven almost entirely by people who never leave Emacs. These are inimical field circumstances for systems that attempt to solve general problems, and if I get the chance I will chide Stallman for launching a bold new (in the late 1980s) TeX-based hypertext system for general use while drawing from a developer pool that stubbornly isolated itself in the GNU Emacs ghetto. This sampling bias was actively reinforced by pointless hazing of users of other editors, even when those editors were Free Software. It's like if the folks in 1910 Warsaw or Vilnius had a Whitehead and Russell who undertook to write _Principia Mathematica_, but only in Yiddish. To communicate in any other language would be a schande. In my work on groff, I endeavor to make frequent sorties beyond the pale of man page settlement.
signature.asc
Description: PGP signature
