Update of bug #68716 (group groff):
Summary: doc/doc.am: per POSIX, any rule for a target
disables any single-suffix rule for it => [PATCH] doc/doc.am: in POSIX make,
any rule for a target disables any single-suffix rule for it
_______________________________________________________
Follow-up Comment #4:
Since Ingo's in a code-reviewin' mood today (bug #68727), I figure I'll throw
him something bigger than a one-liner. :)
$ git log --patch --reverse 010f4fbd6..3b47b948c
commit 07cb9c8aa7d7da93dd5cd6a5a9766a12a9da2002
Author: G. Branden Robinson <[email protected]>
Date: Thu Oct 1 01:37:49 2026 -0500
Makefile.am: Trivially resequence macro defns.
diff --git a/ChangeLog b/ChangeLog
index 5d3d12508..78b6cda6c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2026-10-01 G. Branden Robinson <[email protected]>
+
+ * Makefile.am: Trivially resequence macro definitions.
+
2026-10-01 G. Branden Robinson <[email protected]>
* src/utils/hpftodit/hpftodit.cpp (output_font_name): Use ISO
diff --git a/Makefile.am b/Makefile.am
index 1690909df..a73c72399 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -493,8 +493,8 @@ endif
# Path to binaries and flags used by contribs and doc to generated doc.
# These may be overridden if cross-compiling.
-GROFFBIN = $(abs_top_builddir)/groff
GROFF_BIN_PATH = $(abs_top_builddir)
+GROFFBIN = $(abs_top_builddir)/groff
PDFMOMBIN = $(abs_top_builddir)/pdfmom
SOELIMBIN = $(abs_top_builddir)/soelim
# Search for macro files and device/font description directories in
commit 062160064397f34596711276ba1137f956312b9e
Author: G. Branden Robinson <[email protected]>
Date: Thu Oct 1 01:34:09 2026 -0500
Fix Savannah #68716.
Revise build of man pages to avoid POSIX-unportable make(1) trick, which
worked with GNU but not BSD Make.
* Makefile.am (.man): Stop running all man pages through the built
soelim(1).
* doc/doc.am: Drop prerequisite-only rule of `GROFF_MAN_PAGES_ALL`
expansion on the built soelim.
* man/groff.7.man: Rename this file...
* man/groff.7.man.in: ...to this.
* man/man.am: Define new macro `man_srcdir`.
(EXTRA_DIST): Ship maintained form of groff(7) under its new name.
(man/groff.7.man): New target rule uses the built soelim(1) to
construct this file from its "*.in" counterpart.
Fixes <https://savannah.gnu.org/bugs/?68716>. Thanks to Ingo Schwarze
for the report and explanation.
diff --git a/ChangeLog b/ChangeLog
index 78b6cda6c..fe59ebd2c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2026-10-01 G. Branden Robinson <[email protected]>
+
+ Revise build of man pages to avoid POSIX-unportable make(1)
+ trick, which worked with GNU but not BSD Make.
+
+ * Makefile.am (.man): Stop running all man pages through the
+ built soelim(1).
+ * doc/doc.am: Drop prerequisite-only rule of
+ `GROFF_MAN_PAGES_ALL` expansion on the built soelim.
+ * man/groff.7.man: Rename this file...
+ * man/groff.7.man.in: ...to this.
+ * man/man.am: Define new macro `man_srcdir`.
+ (EXTRA_DIST): Ship maintained form of groff(7) under its new
+ name.
+ (man/groff.7.man): New target rule uses the built soelim(1) to
+ construct this file from its "*.in" counterpart.
+
+ Fixes <https://savannah.gnu.org/bugs/?68716>. Thanks to Ingo
+ Schwarze for the report and explanation.
+
2026-10-01 G. Branden Robinson <[email protected]>
* Makefile.am: Trivially resequence macro definitions.
diff --git a/Makefile.am b/Makefile.am
index a73c72399..d49a5eebc 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -866,7 +866,7 @@ SUFFIXES += .man
-e "s|[@]TMAC_MDIR[@]|`echo $(tmacdir) | sed -f
$(makevarescape)`/mm|g" \
-e "s|[@]TMAC_S_PREFIX[@]|\\\\%$(tmac_s_prefix)|g" \
-e "s|[@]VERSION[@]|$(VERSION)|g" \
- $< | $(SOELIMBIN) -I $(srcdir) -I $(builddir) \
+ $< \
> $@
# Version files - see script "build-aux/git-version-gen".
diff --git a/doc/doc.am b/doc/doc.am
index 0794c5c9d..e85409487 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -283,8 +283,6 @@ GROFF_MAN_PAGES3 = \
GROFF_MAN_PAGES_ALL = $(GROFF_MAN_PAGES1) $(GROFF_MAN_PAGES2) \
$(GROFF_MAN_PAGES3)
-$(GROFF_MAN_PAGES_ALL): soelim
-
# This is a convenience target for (re-)generating all the man pages.
man-all: $(GROFF_MAN_PAGES_ALL)
diff --git a/man/groff.7.man b/man/groff.7.man.in
similarity index 100%
rename from man/groff.7.man
rename to man/groff.7.man.in
diff --git a/man/man.am b/man/man.am
index 73e429be5..3ae46e5a8 100644
--- a/man/man.am
+++ b/man/man.am
@@ -15,6 +15,8 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
+man_srcdir = $(top_srcdir)/man
+
man5_MANS += \
man/groff_font.5 \
man/groff_out.5 \
@@ -25,20 +27,23 @@ man7_MANS += \
man/groff.7 \
man/roff.7
EXTRA_DIST += \
+ man/groff.7.man.in \
+ man/groff_char.7.man \
+ man/groff_diff.7.man \
man/groff_font.5.man \
man/groff_out.5.man \
man/groff_tmac.5.man \
- man/groff_char.7.man \
- man/groff_diff.7.man \
- man/groff.7.man \
man/roff.7.man
+man/groff.7.man: man/groff.7.man.in soelim
+ $(AM_V_at)$(MKDIR_P) $(top_builddir)/man
+ $(AM_V_GEN)$(SOELIMBIN) $(man_srcdir)/groff.7.man.in > $@
+
# Case of out-of-source build: we must create the 'man' directory.
BUILT_SOURCES += man
man:
$(MKDIR_P) $(top_builddir)/man
-
# Local Variables:
# mode: makefile-automake
# fill-column: 72
commit 26a05001070798e1aef17621c4d3bdf3a0ca9431
Author: G. Branden Robinson <[email protected]>
Date: Thu Oct 1 03:56:58 2026 -0500
doc/doc.am: Fix *.html generation with BSD Make.
* doc/doc.am (doc/pic.html, doc/webpage.html): Tweak recipes to work
with BSD Make by using a subshell to run the part of it that requires
a change of directory (which is in turn due to a limitation in
grohtml(1)'s `img` element population).
diff --git a/ChangeLog b/ChangeLog
index fe59ebd2c..3fdb88e95 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2026-10-01 G. Branden Robinson <[email protected]>
+
+ * doc/doc.am (doc/pic.html, doc/webpage.html): Tweak recipes to
+ work with BSD Make by using a subshell to run the part of it
+ that requires a change of directory (which is in turn due to a
+ limitation in grohtml(1)'s `img` element population).
+
2026-10-01 G. Branden Robinson <[email protected]>
Revise build of man pages to avoid POSIX-unportable make(1)
diff --git a/doc/doc.am b/doc/doc.am
index e85409487..54e11e2aa 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -433,9 +433,9 @@ doc/pic.html: eqn pic tbl
doc/pic.html: tmac/www.tmac
doc/pic.html: $(doc_srcdir)/pic.ms $(TMAC_PACKAGE_MS)
$(GROFF_V)$(MKDIR_P) $(doc_builddir) \
- && cd $(doc_builddir) \
+ && (cd $(doc_builddir) \
&& $(DOC_GROFF) -pet -P-Ipic -P-Dimg -P-jpic -Thtml -ms \
- $(doc_srcdir)/pic.ms > pic.html.tmp
+ $(doc_srcdir)/pic.ms > pic.html.tmp)
$(AM_V_at)mv [email protected] $@
# XXX: See XXX comment before "pic.html" target above.
@@ -448,10 +448,10 @@ doc/webpage.html: $(DOC_GNU_EPS) $(DOC_GNU_PNG)
tmac/www.tmac tbl
doc/webpage.html: $(doc_srcdir)/groff.css
doc/webpage.html: $(doc_srcdir)/webpage.ms $(TMAC_PACKAGE_MS)
$(GROFF_V)$(MKDIR_P) $(doc_builddir) \
- && cd $(doc_builddir) \
+ && (cd $(doc_builddir) \
&& $(DOC_GROFF) -t -I $(doc_srcdir) -I $(doc_builddir) \
-P-jwebpage -P-nrb -P-Iwebpage -P-Dimg -Thtml -ms \
- $(doc_srcdir)/webpage.ms > webpage.html.tmp
+ $(doc_srcdir)/webpage.ms > webpage.html.tmp)
$(AM_V_at)mv [email protected] $@
# XXX: ugly, but DRY
commit 3b47b948c3a128876ffb69a9194ef2f868b963ae
Author: G. Branden Robinson <[email protected]>
Date: Thu Oct 1 02:10:35 2026 -0500
HACKING: Revise and expand.
* HACKING: Rename "Automake" section to "Managing Makefiles", and
greatly expand.
diff --git a/ChangeLog b/ChangeLog
index 3fdb88e95..eaaceb400 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2026-10-01 G. Branden Robinson <[email protected]>
+
+ * HACKING: Rename "Automake" section to "Managing Makefiles",
+ and greatly expand.
+
2026-10-01 G. Branden Robinson <[email protected]>
* doc/doc.am (doc/pic.html, doc/webpage.html): Tweak recipes to
diff --git a/HACKING b/HACKING
index 5180e1943..0b139768e 100644
--- a/HACKING
+++ b/HACKING
@@ -37,8 +37,8 @@ Portability notes:
determines the contents of every array element.
-Automake
---------
+Managing Makefiles
+------------------
A document explaining the basics of GNU Automake and its usage in groff
is available in 'doc/automake.mom'; peruse a PDF rendering in
@@ -53,7 +53,61 @@ Tips:
* If you need to define a `_builddir` macro, give it a plain literal
value; do _not_ lead it with an interpolation of `top_builddir` or
anything else. Failure to heed this advice leads to out-of-tree build
- failures with BSD Make.
+ failures with BSD Make. See item D below for details.
+
+groff's *.am files are written in a particular idiom arising from the
+intersection of multiple constraints.
+
+1. We use GNU Automake.
+2. We don't run Make recursively. (Quod vide Peter Miller.)
+3. We try to support both in-tree and out-of-tree ("VPATH") builds.
+4. We try to support both GNU Make and BSD Make. (This is an unusual
+ and unpopular choice, and makes partisans of both tools angry.)
+
+If you're having problems with Makefile rules, double check that you
+haven't fallen into one of several traps.
+
+A. You can't use pattern rules ("%.foo: %.bar"). BSD Make doesn't
+ support them.
+
+B. You can use the special variable `$<` _only_ in suffix rules. POSIX
+ Issue 8 (2024) doesn't specify it as having meaning anywhere else.
+
+C. Because a separate build tree usually starts out empty, and highly
+ parallel builds in particular can generate targets in an
+ unpredictable order, you generally should start a recipe with a
+ silent command to create the target's destination directory. See
+ the example below.
+
+D. Prerequisites in the source tree must be written relative to the
+ source tree's location. We typically define macros to abbreviate
+ their names. Here's an example of a definition and its usage.
+
+ man_srcdir = $(top_srcdir)/man
+ ...
+ man/groff.7.man: man/groff.7.man.in soelim
+ $(AM_V_at)$(MKDIR_P) $(top_builddir)/man
+ $(AM_V_GEN)$(SOELIMBIN) $(man_srcdir)/groff.7.man.in > $@
+
+ Bear in mind that, roughly speaking, BSD Make populates the nodes in
+ its dependency graph with _strings_, and GNU Make populates the
+ nodes with _references to files_. For example, GNU Make knows that
+ '././foo' and './foo' are the same. BSD Make does not.
+
+E. Notice how we used `soelim` as the name of the target's
+ _prerequisite_, but the macro `SOELIMBIN` in the _recipe_. That's
+ because the prerequisite is interpreted by Make, and the recipe is
+ interpreted (after Make macro and special variable expansion) by the
+ shell.
+
+F. Machine-language programs that the groff build creates and then uses
+ to generate other build targets via shell commands should be
+ abstracted through a macro name, such as `SOELIMBIN` above, so that
+ a developer cross-compiling groff can override each such macro
+ definition to point to a program that runs on the build host. If
+ you are such a developer, please build the version of groff you're
+ working on natively first and use the executables it creates for
+ your cross build.
Testing
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?68716>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
