From 6257a2d7efa0c0762b5a023355039fd3c479a5c2 Mon Sep 17 00:00:00 2001 From: Josh Kelley Date: Tue, 16 Dec 2025 13:16:20 -0500 Subject: [PATCH 1/2] Generate rustc.1 man file from rustc --help output using help2man MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Generate the rustc.1 man page from `rustc --help -v` using help2man to ensure the documentation stays in sync with the compiler’s actual CLI behavior. The generation logic lives in src/doc/man and writes rustc.1 to the same directory, independent of the current working directory. --- src/doc/man/README.md | 66 +++++++++++++++++++++++++++++++++ src/doc/man/update-rustc-man.sh | 18 +++++++++ 2 files changed, 84 insertions(+) create mode 100644 src/doc/man/README.md create mode 100755 src/doc/man/update-rustc-man.sh diff --git a/src/doc/man/README.md b/src/doc/man/README.md new file mode 100644 index 0000000000000..9abc3a4a66db4 --- /dev/null +++ b/src/doc/man/README.md @@ -0,0 +1,66 @@ +# Generating the `rustc(1)` Man Page + +This document describes how the `rustc(1)` man page is generated, where the generation logic lives, and how it reliably targets the correct `rustc` binary regardless of the working directory. + +## Goal + +Ensure the `rustc(1)` man page is generated **entirely from `rustc --help -v` output** so that the documentation reflects the compiler’s actual behavior and does not drift over time. + +## Source of Truth + +The man page is generated from: + +``` +rustc --help -v +``` + +This output is treated as authoritative. No hand-written sections are maintained. + +## Tooling + + `help2man` to generate the man page: + +* `help2man` parses CLI help output +* `--help -v` is passed explicitly to include verbose options + +## Script Location + +The generation logic lives alongside the artifact it produces: + +This keeps documentation tooling local and avoids coupling it to the main build system. + +## Generation Script + +`generate-rustc-man.sh` is the canonical way to regenerate the man page. + +* The script resolves its own location to find the repository root +* The path to `rustc` is passed explicitly via an environment variable +* No relative assumptions are made about execution location + +### Script Behavior + +* Resolve repository root via the script’s directory +* Resolve the `rustc` binary path (provided by the build system or caller) +* Invoke `help2man` with an explicit binary path +* Write output deterministically to `src/doc/man/rustc.1` + +The build or release tooling invoking this script **must pass the correct `rustc` binary** (e.g., the freshly built compiler) via environment or explicit path. + +## Regenerating the Man Page + +From the repository root: + +``` +RUSTC=path/to/rustc ./src/doc/man/generate-rustc-man.sh +``` + +This guarantees: + +* The correct compiler is documented +* Output is written to the correct location + +## Rationale + +* Keeps the man page in sync with real compiler behavior +* Avoids manual duplication of CLI documentation +* Makes regeneration explicit and reproducible diff --git a/src/doc/man/update-rustc-man.sh b/src/doc/man/update-rustc-man.sh new file mode 100755 index 0000000000000..813aff6f26854 --- /dev/null +++ b/src/doc/man/update-rustc-man.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env sh +set -eu + +if [ $# -ne 1 ]; then + echo "usage: $0 /path/to/rustc" >&2 + exit 1 +fi + +RUSTC="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")" +OUT_DIR="$(cd "$(dirname "$0")" && pwd)" + +echo "Genererating rustc.1 man page with $RUSTC binary and placing it in $OUT_DIR" + +help2man "$RUSTC" \ + -h "--help -v" \ + -o "$OUT_DIR/rustc.1" + +echo "Man page generated" From 54efbdc9b2d34735a315ec9e5b2bab9ac96678e1 Mon Sep 17 00:00:00 2001 From: Josh Kelley Date: Tue, 16 Dec 2025 13:23:15 -0500 Subject: [PATCH 2/2] Add reproducible man page generation for rustc using help2man MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Introduce `src/doc/man/generate-rustc-man.sh`, a robust script that generates the `rustc(1)` man page entirely from the current built binary’s `--help -v` output using help2man. - Add `README.md` in the same directory to document the rationale, instructions, and prerequisites for this process. - Ensures the man page always reflects the actual compiler behavior, avoids manual edits or duplication, and is easy to update as CLI options evolve. --- src/doc/man/README.md | 61 +++++++++++++++++-------------- src/doc/man/generate-rustc-man.sh | 17 +++++++++ src/doc/man/update-rustc-man.sh | 18 --------- 3 files changed, 51 insertions(+), 45 deletions(-) create mode 100644 src/doc/man/generate-rustc-man.sh delete mode 100755 src/doc/man/update-rustc-man.sh diff --git a/src/doc/man/README.md b/src/doc/man/README.md index 9abc3a4a66db4..1e4cd3b12e1aa 100644 --- a/src/doc/man/README.md +++ b/src/doc/man/README.md @@ -1,10 +1,10 @@ # Generating the `rustc(1)` Man Page -This document describes how the `rustc(1)` man page is generated, where the generation logic lives, and how it reliably targets the correct `rustc` binary regardless of the working directory. +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 the documentation reflects the compiler’s actual behavior and does not drift over time. +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 @@ -14,53 +14,60 @@ The man page is generated from: rustc --help -v ``` -This output is treated as authoritative. No hand-written sections are maintained. +This output is treated as authoritative. No manual sections are maintained. ## Tooling - `help2man` to generate the man page: - -* `help2man` parses CLI help output -* `--help -v` is passed explicitly to include verbose options +- [`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 -The generation logic lives alongside the artifact it produces: - -This keeps documentation tooling local and avoids coupling it to the main build system. +- 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 canonical way to regenerate the man page. +`generate-rustc-man.sh` is the reproducible way to regenerate the man page. -* The script resolves its own location to find the repository root -* The path to `rustc` is passed explicitly via an environment variable -* No relative assumptions are made about execution location +- 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 -* Resolve repository root via the script’s directory -* Resolve the `rustc` binary path (provided by the build system or caller) -* Invoke `help2man` with an explicit binary path -* Write output deterministically to `src/doc/man/rustc.1` +- 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., the freshly built compiler) via environment or explicit path. +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: +From the repository root *after building rustc*: -``` -RUSTC=path/to/rustc ./src/doc/man/generate-rustc-man.sh +```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 -* The correct compiler is documented -* Output is written to the correct location +- `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 -* Makes regeneration explicit and reproducible +- 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 diff --git a/src/doc/man/generate-rustc-man.sh b/src/doc/man/generate-rustc-man.sh new file mode 100644 index 0000000000000..43c2eac95b48f --- /dev/null +++ b/src/doc/man/generate-rustc-man.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env sh +set -eu + +if [ $# -ne 1 ]; then + echo "usage: $0 /path/to/rustc" >&2 + exit 1 +fi + +RUSTC="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")" +OUT_DIR="$(cd "$(dirname "$0")" && pwd)" + +echo "Generating rustc.1 man page with $RUSTC binary and placing it in $OUT_DIR" + +help2man --help-option="--help -v" --no-discard-stderr --name="Rust language compiler" \ + "$RUSTC" -o "$OUT_DIR/rustc.1" + +echo "Man page generated: $OUT_DIR/rustc.1" diff --git a/src/doc/man/update-rustc-man.sh b/src/doc/man/update-rustc-man.sh deleted file mode 100755 index 813aff6f26854..0000000000000 --- a/src/doc/man/update-rustc-man.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env sh -set -eu - -if [ $# -ne 1 ]; then - echo "usage: $0 /path/to/rustc" >&2 - exit 1 -fi - -RUSTC="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")" -OUT_DIR="$(cd "$(dirname "$0")" && pwd)" - -echo "Genererating rustc.1 man page with $RUSTC binary and placing it in $OUT_DIR" - -help2man "$RUSTC" \ - -h "--help -v" \ - -o "$OUT_DIR/rustc.1" - -echo "Man page generated"