diff --git a/src/doc/man/README.md b/src/doc/man/README.md new file mode 100644 index 0000000000000..1e4cd3b12e1aa --- /dev/null +++ b/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 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"