potential (long-winded but on-topic) suggestion to improve (great) citation for jobserver protocol

danny mcClanahan <[email protected]> Sat, 21 Mar 2026 20:09:44 +0000
Newsgroups gmane.comp.gnu.make.bugs
Message-ID <1i3DKVfAlIHY3qyD0NW2oSOA3YgtDGt7SV9uJol-lwV6r4qAEsjsASPW8c4RxumORtyK_mlfYlR_dtsL0v1FFJPpCCvl3qLloBrBYvzuHYw=@amass.energy>
Hello bug-make!

I have another open-ended question I will put into a separate email, but I =
want
to first note: I was happily surprised to see cargo actually cite "GNU make=
" for
the jobserver protocol:
https://doc.rust-lang.org/cargo/reference/build-scripts.html#jobserver, whi=
ch
links to the truly astounding design document at
https://make.mad-scientist.net/papers/jobserver-implementation/.

I think if cargo is going to link to that page as advice for their users, i=
t
might be useful to extend that in-depth design discussion with
the "how to write against this in 2XYZ" that
https://www.gnu.org/software/make/manual/html_node/Job-Slots.html provides-=
-the
windows jobserver subpage in particular might be useful for their target
audience, who might also then learn to question phrasing like:
> developed for GNU make,

when "by" GNU make, "for" gcc would be my understanding...although I can't
actually seem to find *any* discussion of the make jobserver interaction in=
 the
gcc or gccint info docs! But:
> PAGER=3D'grep --color -F flto=3Djob -B 3 -A 4' man gcc
is a great reference for gcc 15.2.1.

I do not mean to pressure the mad-scientist to modify their personal labora=
tory
space--just to note that I think both citations (the deep methodology and t=
he
current application) are fantastic resources and complementary e.g. to
link together.

In fact, I think it could be neat to include in-tree. I really adore gzip's
`algorithm.doc`--the cgit at
https://cgit.git.savannah.gnu.org/cgit/gzip.git/tree/algorithm.doc is not
available, but that file was by far the best description of the 1977 ziv/le=
mpel
approach I could find (after a day or two searching) on the internet, inclu=
ding
the paper itself (I do not think streaming compression is a well-formed pro=
blem
statement and gzip effectively covers the space).

But the jobserver webpage as-is seems to be visible to search engines alrea=
dy!
So there is no discoverability issue here, or any problem.

Just: I have attempted similarly-framed problems to the jobserver before se=
veral
times, and learned so much from this wonderful document. I can conclude her=
e.

Thanks,
d@nny