https://github.com/MaskRay updated https://github.com/llvm/llvm-project/pull/226850
>From f6c7923891e68ab57430466b783ef61655c5fb5e Mon Sep 17 00:00:00 2001 From: Fangrui Song <[email protected]> Date: Sun, 27 Sep 2026 15:21:12 -0700 Subject: [PATCH 1/2] [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 >From 7c984e3743572f5e301ec387eaa08fdadd59891a Mon Sep 17 00:00:00 2001 From: Fangrui Song <[email protected]> Date: Tue, 29 Sep 2026 01:08:08 -0700 Subject: [PATCH 2/2] foramt doc to one sentence per line. --- clang/docs/UsersManual.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md index a51ffe8928b9b..70c248724150d 100644 --- a/clang/docs/UsersManual.md +++ b/clang/docs/UsersManual.md @@ -1527,9 +1527,8 @@ compilation on systems with very large system headers (e.g., macOS). #### Generating a PCH File -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: +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 -c -x c-header test.h -o test.h.gch _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
