user/dev discussion of public-inbox itself
 help / color / Atom feed
From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH] build: support doc generation w/o GNU make
Date: Sun, 1 Dec 2019 10:50:19 +0000
Message-ID: <20191201105019.GA23137@dcvr> (raw)
In-Reply-To: <20191129110914.4306-1-e@80x24.org>

Eric Wong <e@80x24.org> wrote:
> GNU make is one of my favorite tools (or even languages),
> but "make" is not always the GNU implementation...  So,
> throw in some minor fixes before I write more Perl5 to
> write portable make...

Actually, I think replacing the previous 2 patch series
with a single patch with more Perl, less GNU-isms is
the way to go.

Only a few developer/maintainer targets remain GNU make;
and those will probably end up on the chopping block
sooner-or-later.

--------8<--------
Subject: [PATCH] build: support doc generation w/o GNU make

We can replace the GNU-isms for building docs with Perl5
equivalents.  The only downside is the resulting Makefile
gets larger, but that's the price of portability.
---
 Documentation/include.mk | 123 +++++----------------------------------
 Documentation/txt2pre    |   6 ++
 INSTALL                  |   2 +-
 Makefile.PL              | 100 ++++++++++++++++++++++++++++---
 4 files changed, 112 insertions(+), 119 deletions(-)

diff --git a/Documentation/include.mk b/Documentation/include.mk
index 651fdf30..ea2946d1 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -2,10 +2,6 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 all::
 
-# Note: some GNU-isms present and required to build docs
-# (including manpages), but at least this should not trigger
-# warnings with BSD make(1) when running "make check"
-# Maybe it's not worth it to support non-GNU make, though...
 RSYNC = rsync
 RSYNC_DEST = public-inbox.org:/srv/public-inbox/
 AWK = awk
@@ -17,13 +13,6 @@ XMLSTARLET = xmlstarlet
 # same as pod2text
 COLUMNS = 76
 
-txt := INSTALL README COPYING TODO HACKING
-dtxt := design_notes.txt design_www.txt dc-dlvr-spam-flow.txt hosted.txt
-dtxt += marketing.txt
-dtxt += standards.txt
-dtxt := $(addprefix Documentation/, $(dtxt))
-docs := $(txt) $(dtxt)
-
 INSTALL = install
 PODMAN = pod2man
 PODMAN_OPTS = -v --stderr -d 1993-10-02 -c 'public-inbox user manual'
@@ -33,36 +22,7 @@ PODTEXT = pod2text
 PODTEXT_OPTS = --stderr
 podtext = $(PODTEXT) $(PODTEXT_OPTS)
 
-# MakeMaker only seems to support manpage sections 1 and 3...
-m1 =
-m1 += public-inbox-compact
-m1 += public-inbox-convert
-m1 += public-inbox.cgi
-m1 += public-inbox-edit
-m1 += public-inbox-httpd
-m1 += public-inbox-index
-m1 += public-inbox-init
-m1 += public-inbox-learn
-m1 += public-inbox-mda
-m1 += public-inbox-nntpd
-m1 += public-inbox-purge
-m1 += public-inbox-watch
-m1 += public-inbox-xcpdb
-m5 =
-m5 += public-inbox-config
-m5 += public-inbox-v1-format
-m5 += public-inbox-v2-format
-m7 =
-m7 += public-inbox-overview
-m8 =
-m8 += public-inbox-daemon
-
-man1 := $(addsuffix .1, $(m1))
-man5 := $(addsuffix .5, $(m5))
-man7 := $(addsuffix .7, $(m7))
-man8 := $(addsuffix .8, $(m8))
-
-all:: man html
+all:: man
 
 manpages = $(man1) $(man5) $(man7) $(man8)
 
@@ -70,60 +30,37 @@ man: $(manpages)
 
 prefix ?= $(PREFIX)
 prefix ?= $(HOME)
-mandir ?= $(prefix)/share/man
-man1dir = $(mandir)/man1
+mandir ?= $(INSTALLMAN1DIR)/..
 man5dir = $(mandir)/man5
 man7dir = $(mandir)/man7
 man8dir = $(mandir)/man8
 
 install-man: man
-	$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(INSTALLMAN1DIR)
 	$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
 	$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
 	$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir)
-	$(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+	$(INSTALL) -m 644 $(man1) $(DESTDIR)$(INSTALLMAN1DIR)
 	$(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
 	$(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
 	$(INSTALL) -m 644 $(man8) $(DESTDIR)$(man8dir)
 
 doc_install :: install-man
 
-%.1 %.5 %.7 %.8 : Documentation/%.pod
-	$(podman) -s $(subst .,,$(suffix $@)) $< $@+ && mv $@+ $@
-
 check :: check-man
-check_man = @echo CHECK80 $<;COLUMNS=80 $(MAN) ./$^ | \
-	$(AWK) '{gsub(/\b./,"")}length>80{print;err=1}END{exit(err)}' >&2 \
-	&& >$@
-
-.%.1.cols : %.1; $(check_man)
-.%.5.cols : %.5; $(check_man)
-.%.7.cols : %.7; $(check_man)
-.%.8.cols : %.8; $(check_man)
-
-check-man :: $(addprefix .,$(addsuffix .cols, $(manpages)))
+check_man = $(AWK) '{gsub(/\b./,"")}length>80{print;err=1}END{exit(err)}'\
+	>&2 && >$@
 
-manuals :=
-manuals += $(m1)
-manuals += $(m5)
-manuals += $(m7)
-manuals += $(m8)
-
-mantxt = $(addprefix Documentation/, $(addsuffix .txt, $(manuals)))
-docs += $(mantxt)
-dtxt += $(mantxt)
-docs += NEWS
+check-man :: $(check_80)
 
 all :: $(docs)
 
-Documentation/%.txt : Documentation/%.pod
-	$(podtext) $< $@+ && touch -r $< $@+ && mv $@+ $@
-
-txt2pre = $(PERL) -I lib ./Documentation/txt2pre <$< >$@+ && \
-	touch -r $< $@+ && mv $@+ $@
+txt2pre = $(PERL) -I lib ./Documentation/txt2pre >$@
 
 Documentation/standards.txt : Documentation/standards.perl
-	$(PERL) $< >$@+ && touch -r $< $@+ && mv $@+ $@
+	$(PERL) -w Documentation/standards.perl >$@+
+	touch -r Documentation/standards.perl $@+
+	mv $@+ $@
 
 RELEASES =
 RELEASES += v1.2.0
@@ -140,39 +77,11 @@ check-NEWS.atom: NEWS.atom
 	$(XMLSTARLET) val NEWS.atom || \
 		{ e=$$?; test $$e -eq 0 || test $$e -eq 127; }
 
-Documentation/%.html: Documentation/%.txt
-	$(txt2pre)
-
-%.html: %
-	$(txt2pre)
-
-docs_html := $(addsuffix .html, $(subst .txt,,$(dtxt)) $(txt)) NEWS.html
 html: $(docs_html)
-gz_docs := $(addsuffix .gz, $(docs) $(docs_html))
-rsync_docs := $(gz_docs) $(docs) $(docs_html) NEWS.atom NEWS.atom.gz
-
-# external manpages which we host ourselves, since some packages
-# (currently just Xapian) doesn't host manpages themselves.
-xtxt :=
-xtxt += .copydatabase.1
-xtxt += .xapian-compact.1
-xtxt := $(addprefix Documentation/.x/, $(addsuffix .txt, $(xtxt)))
-xdocs := $(xtxt)
-xdocs_html := $(addsuffix .html, $(subst .txt,,$(xtxt)))
-gz_xdocs := $(addsuffix .gz, $(xdocs) $(xdocs_html))
-rsync_xdocs := $(gz_xdocs) $(xdocs_html) $(xdocs)
-xdoc: $(xdocs) $(xdocs_html)
 
 Documentation/.x:
 	mkdir -p $@
 
-Documentation/.x/%.txt :: | Documentation/.x
-	$(PERL) -w Documentation/extman.perl $@ >$@+
-	mv $@+ $@
-
-Documentation/.x/%.html: Documentation/.x/%.txt
-	$(txt2pre)
-
 doc: $(docs)
 
 %.gz: %
@@ -192,16 +101,12 @@ rsync-doc: NEWS.atom.gz
 	$(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(rsync_xdocs) $(RSYNC_DEST)
 
 clean-doc:
-	$(RM) $(man1) $(man5) $(man7) $(man8) $(gz_docs) $(docs_html) $(mantxt)
-	$(RM) $(gz_xdocs) $(xdocs_html) $(xdocs)
-	$(RM) NEWS NEWS.atom NEWS.html Documentation/standards.txt
+	$(RM_F) $(man1) $(man5) $(man7) $(man8) $(gz_docs) $(docs_html) \
+		$(mantxt) $(rsync_xdocs) \
+		NEWS NEWS.atom NEWS.html Documentation/standards.txt
 
 clean :: clean-doc
 
-pure_all ::
-	@if test x"$(addprefix g, make)" != xgmake; then \
-	echo W: gmake is currently required to build manpages; fi
-
 # No camel-cased tarballs or pathnames which MakeMaker creates,
 # this may not always be a Perl project.
 git-dist :: ver = $(shell git describe |sed -ne 's/v//p')
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index 6f2a8c8a..7cab0fa2 100755
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -22,3 +22,9 @@ print '<html><head>',
   qq(<meta\nhttp-equiv="Content-Type"\ncontent="text/html; charset=utf-8"\n/>),
   "<title>$title</title>",
   "</head><body><pre>",  $str , '</pre></body></html>';
+
+# keep mtime on website consistent so clients can cache
+if (-f STDIN && -f STDOUT) {
+	my @st = stat(STDIN);
+	utime($st[8], $st[9], \*STDOUT);
+}
diff --git a/INSTALL b/INSTALL
index 4d54e6a0..a6ca7772 100644
--- a/INSTALL
+++ b/INSTALL
@@ -185,7 +185,7 @@ Once the dependencies are installed, you should be able to build and
 install the system (into /usr/local) with:
 
         perl Makefile.PL
-        make # GNU make is preferred, `gmake' on BSD systems
+        make
         make test
         make install # root permissions may be needed
 
diff --git a/Makefile.PL b/Makefile.PL
index 4aa0caa7..c4495c4f 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -6,7 +6,89 @@ use ExtUtils::MakeMaker;
 open my $m, '<', 'MANIFEST' or die "open(MANIFEST): $!\n";
 chomp(my @manifest = (<$m>));
 my @EXE_FILES = grep(m!^script/!, @manifest);
-my $PM_FILES = join(' ', grep(m!^lib/.*\.pm$!, @manifest));
+my $v = {};
+my $t = {};
+$v->{txt} = [ qw(INSTALL README COPYING TODO HACKING) ];
+my @dtxt = grep(m!\ADocumentation/.*\.txt\z!, @manifest);
+push @dtxt, 'Documentation/standards.txt';
+for my $txt (@dtxt) {
+	my $html = $txt;
+	$html =~ s/\.txt\z/.html/;
+	$t->{"$html : $txt"} = [ "\$(txt2pre) <$txt" ];
+}
+$v->{t_slash_star_dot_t} = [ grep(m!\At/.*\.t\z!, @manifest) ];
+my @scripts = qw(scripts/ssoma-replay); # legacy
+my @syn = (@EXE_FILES, grep(m!^lib/.*\.pm$!, @manifest), @scripts);
+@syn = grep(!/DSKQXS\.pm/, @syn) if !eval { require IO::KQueue };
+@syn = grep(!/Unsubscribe\.pm/, @syn) if !eval { require Crypt::CBC };
+@syn = grep(!/SaPlugin/, @syn) if !eval { require Mail::SpamAssasin };
+$v->{my_syntax} = [map { "$_.syntax" } @syn];
+$v->{-m1} = [ map { (split('/'))[-1] } @EXE_FILES ];
+$v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format
+		public-inbox-v2-format) ];
+$v->{-m7} = [ qw(public-inbox-overview) ];
+$v->{-m8} = [ qw(public-inbox-daemon) ];
+my @sections = (1, 5, 7, 8);
+$v->{check_80} = [];
+$v->{manuals} = [];
+$v->{mantxt} = [];
+for my $i (@sections) {
+	my $ary = $v->{"-m$i"};
+	$v->{"m$i"} = $ary;
+	for my $m (@$ary) {
+		my $pod = "Documentation/$m.pod";
+		my $txt = "Documentation/$m.txt";
+		$t->{"$m.$i : $pod"} = [ "\$(podman) -s$i $pod \$@" ];
+		$t->{"$txt : $pod"} = [ "\$(podtext) $pod \$\@+",
+					"touch -r $pod \$\@+",
+					"mv \$\@+ \$@" ];
+		$t->{"Documentation/$m.html : $txt"} = [ "\$(txt2pre) <$txt" ];
+		$t->{".$m.cols : $m.$i"} = [
+			"\@echo CHECK80 $m.$i;".
+			"COLUMNS=80 \$(MAN) ./$m.$i | \$(check_man)" ];
+	}
+	push @{$v->{check_80}}, map { ".$_.cols" } @$ary;
+	my $manuals = $v->{"man$i"} = [ map { "$_.$i" } @$ary ];
+	push @{$v->{manuals}}, @$manuals;
+	push @{$v->{mantxt}}, map { "Documentation/$_.txt" } @$ary;
+}
+push @dtxt, @{$v->{mantxt}};
+$v->{docs} = [ @dtxt, 'NEWS' ];
+$v->{docs_html} = [ map {;
+		my $x = $_;
+		$x =~ s/\.txt\z//;
+		"$x.html"
+	} @{$v->{docs}} ];
+$v->{gz_docs} = [ map { "$_.gz" } (@{$v->{docs}},@{$v->{docs_html}}) ];
+$v->{rsync_docs} = [ @{$v->{gz_docs}}, @{$v->{docs}},
+	@{$v->{docs_html}}, qw(NEWS.atom NEWS.atom.gz)];
+
+# external manpages which we host ourselves, since some packages
+# (currently just Xapian) doesn't host manpages themselves.
+my @xman = qw(copydatabase.1 xapian-compact.1);
+$v->{xdocs} = [ map { "Documentation/.x/.$_.txt" } @xman ];
+$v->{xdocs_html} = [ map { "Documentation/.x/.$_.html" } @xman ];
+for (@{$v->{xdocs}}) {
+	$t->{"$_ : | Documentation/.x"} = [
+		'$(PERL) -w Documentation/extman.perl >$@',
+	];
+	my $html = $_;
+	$html =~ s/\.txt\z/.html/;
+	$t->{"$html : $_"} = [ "\$(txt2pre) <$_" ];
+}
+$v->{gz_xdocs} = [ map { "$_.gz" } (@{$v->{xdocs_html}}, @{$v->{xdocs}}) ];
+$v->{rsync_xdocs} = [ @{$v->{gz_xdocs}}, @{$v->{xdocs_html}}, @{$v->{xdocs}} ];
+
+my $TGTS = join("\n", map {;
+	my $tgt_prereq = $_;
+	my $cmds = $t->{$_};
+	"$tgt_prereq\n".join('', map { "\t$_\n" } @$cmds);
+} keys %$t);
+
+my $VARS = join("\n", map {;
+	my $varname = $_;
+	join('', map { "$varname += $_\n" } @{$v->{$varname}});
+} grep(!/^-/, keys %$v));
 
 # Don't waste user's disk space by installing some pods from
 # imported code or internal use only
@@ -69,17 +151,17 @@ sub MY::postamble {
 EATMYDATA =
 N = \$\$(( \$\$(nproc 2>/dev/null || gnproc 2>/dev/null || echo 2) + 1 ))
 -include config.mak
+$VARS
 -include Documentation/include.mk
-SCRIPTS := scripts/ssoma-replay
-syn_files = $PM_FILES \$(EXE_FILES) \$(SCRIPTS) \$(wildcard t/*.t)
-my_syntax = \$(addsuffix .syntax, \$(syn_files))
-changed = \$(shell git ls-files -m)
+$TGTS
 
-%.syntax ::
-	@\$(PERL) -w -I lib -c \$(subst .syntax,,\$@)
+# syntax checks are currently GNU make only:
+%.syntax :: %
+	@\$(PERL) -w -I lib -c \$<
 
-syntax:: \$(filter-out lib/PublicInbox/DSKQXS.pm.syntax,\$(my_syntax))
+syntax:: \$(my_syntax)
 
+changed = \$(shell git ls-files -m)
 dsyn :: \$(addsuffix .syntax, \$(filter \$(changed), \$(syn_files)))
 
 check-manifest :: MANIFEST
@@ -94,7 +176,7 @@ lib/PublicInbox/UserContent.pm :: contrib/css/216dark.css
 # Ensure new .pm files will always be installed by updating
 # the timestamp of Makefile.PL which forces Makefile to be remade
 Makefile.PL : MANIFEST
-	touch -r \$< \$@
+	touch -r MANIFEST \$@
 	\$(PERLRUN) \$@
 
 EOF

      parent reply index

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-11-29 11:09 [PATCH 0/2] minor fixes for OpenBSD make(1) Eric Wong
2019-11-29 11:09 ` [PATCH 1/2] Makefile.PL: avoid non-portable $< Eric Wong
2019-11-29 11:09 ` [PATCH 2/2] doc: don't attempt to install non-existent manpages Eric Wong
2019-12-01 10:50 ` Eric Wong [this message]

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://public-inbox.org/README

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191201105019.GA23137@dcvr \
    --to=e@80x24.org \
    --cc=meta@public-inbox.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

user/dev discussion of public-inbox itself

Archives are clonable:
	git clone --mirror http://public-inbox.org/meta
	git clone --mirror http://czquwvybam4bgbro.onion/meta
	git clone --mirror http://hjrcffqmbrq6wope.onion/meta
	git clone --mirror http://ou63pmih66umazou.onion/meta

Example config snippet for mirrors

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta
	nntp://ou63pmih66umazou.onion/inbox.comp.mail.public-inbox.meta
	nntp://czquwvybam4bgbro.onion/inbox.comp.mail.public-inbox.meta
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.mail.public-inbox.meta
	nntp://news.gmane.org/gmane.mail.public-inbox.general

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git