Subject: Re: bug#76735: Shepherd parallel make help2man issue

From: Simon Josefsson <[email-masked]>
Date: Sun, 09 Mar 2025 22:09:51 +0100

Ludovic Courtès <[email-masked]> writes:

> Hi Simon,
>
> Simon Josefsson <[email-masked]> skribis:
>
>> I got the build error below.  Presumably it happens because the jobs to
>> create the tools has not finished before the help2man jobs has started.
>
> Am I right that you’re building from a Git checkout?

This was during build of Debian packages of Shepherd.  They use the
tarballs.

> The problem is that the Makefile rules for man pages are meant for
> developers building the tarball; the tarball already includes man pages,
> so someone building from the tarball doesn’t trigger any of these
> rules.

Ah.  The Debian packaging intentionally removes the prebuilt manpages
because we want to know that we can rebuild them from source.  That is
what is triggering this problem!

execute_after_dh_auto_clean:
	rm -fv doc/shepherd.info doc/herd.1 doc/shepherd.1
	rm -fv doc/stamp-vti doc/version.texi

So maybe this is not so much of an upstream problem after all, and my
fault for trying to rebuild the manpages.

Maybe we should build from a 'git-archive' snapshot instead... but those
doesn't come with PGP signatures right now, although you could do that:

https://blog.josefsson.org/2024/04/13/reproducible-and-minimal-source-only-tarballs/

essentially just:

git archive --prefix=shepherd-vX.Y/ -o shepherd-vX.Y-src.tar.gz vX.Y
gpg --sign shepherd-vX.Y-src.tar.gz

> The changes below fix dependencies, but it also means that now everyone
> will be building man pages from source, even if they’re already included
> in the tarball.  That’s probably the right thing to do longer term, but
> I’d rather not do it in the middle of a stable series.

Thanks for developing that patch.  This problem is complex, and I'm not
sure what the best solution really is.  Your patch makes the man pages
depend on the binary, and I've had bad experiences with that.  If
someone is cross-compile Shepherd (not sure if that's a realistic
situation) then help2man can't run the binary, and in this situation it
would be preferable to fall back on the prebuilt manpages.  That doesn't
sound ideal.

Maybe an uglier solution is to try to run help2man, and if it works,
then fine, but if it doesn't, re-use the prebuilt manpage or fail.

/Simon