Automate rustc(1) man page generation using help2man script

src/doc/man/README.md

@@ -0,0 +1,73 @@
+# Generating the `rustc(1)` Man Page
+
+This document describes how the `rustc(1)` man page is generated, where the logic lives, and how it robustly targets the correct `rustc` binary regardless of execution context.
+
+## Goal
+
+Ensure the `rustc(1)` man page is generated **entirely from `rustc --help -v` output** so that documentation reflects the real compiler and does not drift.
+
+## Source of Truth
+
+The man page is generated from:
+
+```
+rustc --help -v
+```
+
+This output is treated as authoritative. No manual sections are maintained.
+
+## Tooling
+
+- [`help2man`](https://www.gnu.org/software/help2man/) to generate the man page:
+  - Parses CLI help output (`rustc --help -v`)
+  - Provides a formatted groff man page
+
+## Script Location
+
+- All logic and artifacts are in `src/doc/man`.
+- This avoids coupling to the main build system.
+
+## Generation Script
+
+`generate-rustc-man.sh` is the reproducible way to regenerate the man page.
+
+- The script resolves its own location and output directory.
+- The path to the *actual* `rustc` binary is passed as an argument.
+- No assumptions made about the working directory.
+
+### Script Behavior
+
+- Resolves absolute path to provided `rustc` binary.
+- Runs `help2man` with `--help -v` on that binary.
+- Writes output to `src/doc/man/rustc.1`.
+
+The build or release tooling invoking this script **must pass the correct `rustc` binary** (e.g., a freshly built compiler).
+
+## Regenerating the Man Page
+
+From the repository root *after building rustc*:
+
+```bash
+./src/doc/man/generate-rustc-man.sh path/to/rustc
+```
+
+This guarantees:
+- The correct (built) compiler is documented
+- Output always lands in the right place
+
+## Prerequisites
+
+- `help2man` must be installed and in your `$PATH`.
+
+On most Linux distros: `sudo apt install help2man` (Debian/Ubuntu) or `sudo dnf install help2man` (Fedora).
+
+## Rationale
+
+- Keeps the man page in sync with real compiler behavior
+- Avoids manual duplication of CLI documentation
+- Regeneration is explicit and reproducible
+
+## Notes
+
+- The generated `rustc.1` can be `.gitignore`d as desired, depending on release/build process.
+- If you change how `rustc` outputs help, rerun this process to update the man page

src/doc/man/generate-rustc-man.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+set -euo pipefail
+
+RUSTC="${1:?Usage: $0 <path-to-rustc>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+OUTPUT="$SCRIPT_DIR/rustc.1"
+INCLUDE_FILE="$(mktemp)"
+trap "rm -f '$INCLUDE_FILE'" EXIT
+
+# Parse -C help output into man format
+generate_codegen_section() {
+    "$RUSTC" -C help 2>&1 | awk '
+    /^    -C / {
+        sub(/^    -C +/, "")
+        split($0, parts, / -- /)
+        option = parts[1]
+        desc = parts[2]
+        gsub(/=val$/, "", option)
+        printf ".TP\n\\fB-C %s\\fR=\\fIval\\fR\n%s\n", option, desc
+    }'
+}
+
+# Build the include file with proper section ordering
+generate_include_file() {
+    cat <<'EOF'
+[name]
+rustc \- The Rust compiler
+
+[description]
+This program is a compiler for the Rust language, available at https://www.rust-lang.org.
+
+[>options]
+.SH "CODEGEN OPTIONS"
+These options affect code generation. Run \fBrustc -C help\fR for the full list.
+
+EOF
+
+    # Dynamic codegen options
+    generate_codegen_section
+
+    cat <<'EOF'
+
+.SH ENVIRONMENT
+Some of these affect only test harness programs (generated via rustc --test);
+others affect all programs which link to the Rust standard library.
+.TP
+\fBRUST_BACKTRACE\fR
+If set to a value different than "0", produces a backtrace in the output of a program which panics.
+.TP
+\fBRUST_TEST_THREADS\fR
+The test framework Rust provides executes tests in parallel. This variable sets the maximum number of threads used for this purpose. This setting is overridden by the --test-threads option.
+.TP
+\fBRUST_TEST_NOCAPTURE\fR
+If set to a value other than "0", a synonym for the --nocapture flag.
+.TP
+\fBRUST_MIN_STACK\fR
+Sets the minimum stack size for new threads.
+
+.SH EXAMPLES
+To build an executable from a source file with a main function:
+    $ rustc -o hello hello.rs
+
+To build a library from a source file:
+    $ rustc --crate-type=lib hello-lib.rs
+
+To build either with a crate (.rs) file:
+    $ rustc hello.rs
+
+To build an executable with debug info:
+    $ rustc -g -o hello hello.rs
+
+[see also]
+.BR rustdoc (1)
+
+[bugs]
+See https://github.com/rust-lang/rust/issues for issues.
+
+[author]
+See https://github.com/rust-lang/rust/graphs/contributors or use `git log --all --format='%cN <%cE>' | sort -u` in the rust source distribution.
+
+[copyright]
+This work is dual-licensed under Apache 2.0 and MIT terms.
+See COPYRIGHT file in the rust source distribution.
+EOF
+}
+
+# Generate the include file
+generate_include_file >"$INCLUDE_FILE"
+
+# Generate man page
+help2man \
+    --include="$INCLUDE_FILE" \
+    --no-info \
+    --no-discard-stderr \
+    "$RUSTC" >"$OUTPUT"
+
+echo "Generated $OUTPUT from $RUSTC help output"