Author: Fangrui Song Date: 2026-09-29T01:14:15-07:00 New Revision: e0bd48983e9d1d0de471a7689573622464c0b332
URL: https://github.com/llvm/llvm-project/commit/e0bd48983e9d1d0de471a7689573622464c0b332 DIFF: https://github.com/llvm/llvm-project/commit/e0bd48983e9d1d0de471a7689573622464c0b332.diff LOG: [docs] Pass -c when generating a PCH file (#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 Added: Modified: clang/docs/LibASTImporter.md clang/docs/UsersManual.md Removed: ################################################################################ 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..70c248724150d 100644 --- a/clang/docs/UsersManual.md +++ b/clang/docs/UsersManual.md @@ -1527,13 +1527,12 @@ 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 +1554,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 +1567,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 +1603,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 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
