rustc: document the jobserver

Explicitly document that the jobserver may be used by `rustc`, as well
as recommend the `+` indicator for integration of `rustc` into GNU Make.

In particular, show the warning to increase the chances that this document
is found when searching for solutions online.

In addition, add a note about the issue with GNU Make 4.3 since it is
important that users realize they should do this even if they do not
expect parallelism from `rustc`.

Finally, show how to workaround the issue of `$(shell ...)` calls in
recursive Make (which e.g. was needed for the Linux kernel).

The GNU Make 4.4 case under `--jobserver-style=pipe` is not added since
it got fixed after Rust 1.76.0 already (i.e. `rustc` will not warn if
it finds the negative file descriptors).

From: #120515
Cc: @petrochenkov @belovdv @weihanglo @bjorn3
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Author: ojeda

src/doc/rustc/src/SUMMARY.md

@@ -3,6 +3,7 @@
 - [What is rustc?](what-is-rustc.md)
 - [Command-line Arguments](command-line-arguments.md)
     - [Codegen Options](codegen-options/index.md)
+- [Jobserver](jobserver.md)
 - [Lints](lints/index.md)
     - [Lint Levels](lints/levels.md)
     - [Lint Groups](lints/groups.md)

src/doc/rustc/src/jobserver.md

@@ -0,0 +1,55 @@
+# Jobserver
+
+Internally, `rustc` may take advantage of parallelism. `rustc` will coordinate
+with the build system calling it if a [GNU Make jobserver] is passed in the
+`MAKEFLAGS` environment variable.
+
+Starting with Rust 1.76.0, `rustc` will warn if a jobserver appears to be
+available but is not accessible, e.g.:
+
+```console
+$ echo 'fn main() {}' | MAKEFLAGS=--jobserver-auth=3,4 rustc -
+warning: failed to connect to jobserver from environment variable `MAKEFLAGS="--jobserver-auth=3,4"`: cannot open file descriptor 3 from the jobserver environment variable value: Bad file descriptor (os error 9)
+  |
+  = note: the build environment is likely misconfigured
+```
+
+## Integration with build systems
+
+The following subsections contain recommendations on how to integrate `rustc`
+with build systems so that the jobserver is handled appropriately.
+
+### GNU Make
+
+When calling `rustc` from GNU Make, it is recommended that all `rustc`
+invocations are marked as recursive in the `Makefile` (by prefixing the command
+line with the `+` indicator), so that GNU Make enables the jobserver for them.
+For instance:
+
+<!-- ignore-tidy-tab -->
+
+```make
+x:
+	+@echo 'fn main() {}' | rustc -
+```
+
+In particular, GNU Make 4.3 (a widely used version as of 2024) passes a simple
+pipe jobserver in `MAKEFLAGS` even when it was not made available for the child
+process, which in turn means `rustc` will warn about it. For instance, if the
+`+` indicator is removed from the example above and GNU Make is called with e.g.
+`make -j2`, then the aforementioned warning will trigger.
+
+For calls to `rustc` inside `$(shell ...)` inside a recursive Make, one can
+disable the jobserver manually by clearing the `MAKEFLAGS` variable, e.g.:
+
+```make
+S := $(shell MAKEFLAGS= rustc --print sysroot)
+
+x:
+	@$(MAKE) y
+
+y:
+	@echo $(S)
+```
+
+[GNU Make jobserver]: https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html