[clang] [docs] Pass -c when generating a PCH file (PR #226850)

[Fangrui Song via cfe-commits]

https://github.com/MaskRay created https://github.com/llvm/llvm-project/pull/226850

Without options like -fsyntax-only/-E/-S/-c, the driver runs in link
mode, and a header-only command line produces a PCH only incidentally: a
linker option such as -lm or -Wl,..., including one from a config file,
adds a link job. Use -c in the PCH examples.

Also fix two broken examples: -ignore-pch is a driver option (cc1
rejects -Xclang -ignore-pch), and the relocatable PCH example is
missing -o. In LibASTImporter.md, generate the C++ AST files with
-emit-ast instead of treating .cpp files as headers.

LLM-aided

>From f6c7923891e68ab57430466b783ef61655c5fb5e Mon Sep 17 00:00:00 2001
From: Fangrui Song <i at maskray.me>
Date: Sun, 27 Sep 2026 15:21:12 -0700
Subject: [PATCH] [docs] Pass -c when generating a PCH file

Without options like -fsyntax-only/-E/-S/-c, the driver runs in link
mode, and a header-only command line produces a PCH only incidentally: a
linker option such as -lm or -Wl,..., including one from a config file,
adds a link job. Use -c in the PCH examples.

Also fix two broken examples: -ignore-pch is a driver option (cc1
rejects -Xclang -ignore-pch), and the relocatable PCH example is
missing -o. In LibASTImporter.md, generate the C++ AST files with
-emit-ast instead of treating .cpp files as headers.

LLM-aided
---
 clang/docs/LibASTImporter.md |  4 ++--
 clang/docs/UsersManual.md    | 20 ++++++++++----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/clang/docs/LibASTImporter.md b/clang/docs/LibASTImporter.md
index 9c5a22d099a0d..3ea6e2d7505c2 100644
--- a/clang/docs/LibASTImporter.md
+++ b/clang/docs/LibASTImporter.md
@@ -588,8 +588,8 @@ int main() {
 We shall generate the AST files, merge them, create the executable and then run it:
 
 ```console
-$ clang++ -x c++-header -o foo.ast foo.cpp
-$ clang++ -x c++-header -o main.ast main.cpp
+$ clang++ -emit-ast foo.cpp
+$ clang++ -emit-ast main.cpp
 $ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -ast-dump
 $ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -emit-obj -o main.o
 $ clang++ -o a.out main.o
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 3bec20612c048..a51ffe8928b9b 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -1527,13 +1527,13 @@ compilation on systems with very large system headers (e.g., macOS).
 
 #### Generating a PCH File
 
-To generate a PCH file using Clang, one invokes Clang with the
-`-x <language>-header` option. This mirrors the interface in GCC
-for generating PCH files:
+To generate a PCH file, compile the header with `-c`, using
+`-x <language>-header` if the file extension does not identify it as a
+header. This mirrors the interface in GCC for generating PCH files:
 
 ```console
-$ gcc -x c-header test.h -o test.h.gch
-$ clang -x c-header test.h -o test.h.pch
+$ gcc -c -x c-header test.h -o test.h.gch
+$ clang -c -x c-header test.h -o test.h.pch
 ```
 
 #### Using a PCH File
@@ -1555,7 +1555,7 @@ included within a source file or indirectly via {option}`-include`.
 For example:
 
 ```console
-$ clang -x c-header test.h -o test.h.pch
+$ clang -c -x c-header test.h -o test.h.pch
 $ cat test.c
 #include "test.h"
 $ clang test.c -o test
@@ -1568,11 +1568,11 @@ specified on the command line using `-include-pch`.
 
 #### Ignoring a PCH File
 
-To ignore PCH options, a `-ignore-pch` option is passed to `clang`:
+To ignore PCH options, pass `-ignore-pch` to `clang`:
 
 ```console
-$ clang -x c-header test.h -Xclang -ignore-pch -o test.h.pch
-$ clang -include-pch test.h.pch -Xclang -ignore-pch test.c -o test
+$ clang -c -x c-header test.h -ignore-pch -o test.h.pch
+$ clang -include-pch test.h.pch -ignore-pch test.c -o test
 ```
 
 This option disables precompiled headers, overrides -emit-pch and -include-pch.
@@ -1604,7 +1604,7 @@ the resulting PCH file should be relocatable. Second, pass
 relative to the build directory. For example:
 
 ```console
-# clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+# clang -c -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h -o mylib.h.pch
 ```
 
 When loading the relocatable PCH file, the various headers used in the