如何使用 Clang++ 生成和使用预编译头文件？

Question

The official docs state how precompiled headers are to be used through the -cc1 interface, like so to generate them:

$ clang -cc1 test.h -emit-pch -o test.h.pch

And to use them:

$ clang -cc1 -include-pch test.h.pch test.c -o test.s

The problem is that the -cc1 interface is way too low-level to be used by developers from the CLI. In fact, the regular high-level interface ultimately calls into the low-level -cc1 interface by supplying it with a very large set of arguments that are necessary for its correct operation, for example the include paths appropriate for the compile time system. Without these arguments, the -cc1 interface has no prayer of working:

$ clang++ -cc1 /usr/include/x86_64-linux-gnu/c++/7/bits/stdc++.h -emit-pch -o std.pch
/usr/include/x86_64-linux-gnu/c++/7/bits/stdc++.h:33:10: fatal error: 'cassert' file not found
#include <cassert>
         ^~~~~~~~~
         1 error generated.

Is there a way to use precompiled headers from the high-level interface, such that a developer may conveniently tap into this feature during their daily work?

Answer 1

I think the root of your problem is that your filename is test.h and clang thinks you are compiling C code, not C++ code. Hence, when you include <cassert> , clang doesn't know it should be looking at the C++ include path. Try naming your file test.hpp . You only have to name the file you want as the precomp header with .hpp . You can keep all your header files with .h extensions.

In any case, I might be getting this confused with gcc/g++, but Clang follows the same behavior whenever I compile my code on Mac. This is how I make use of precompiled headers. Read on...

If you've got a C++ header file you want to precompile, just compile it as any other .cpp file. Notice that I'm using .hpp as the file extension so the compiler picks it up as a C++ header file.

clang -c precomp.hpp

This will produce precomp.hpp.gch

Now to use the precomp by any other ordinary C++ file, just include the ordinary .hpp file:

// main.cpp
#include "precomp.hpp"

void func1() {...}
void main() {...}

The compiler will automatically use the corresponding .gch file if its present in place of the original .hpp file.

Answer 2

I don't know why the clang docs do not explain this, but indeed as @selbie surmises, it is possible to use Clang precompiled headers (PCH) without using -cc1 .

To generate a PCH file:

$ clang -c -o big-header.hh.pch big-header.hh <other options>

This is the normal compile command, except the input file has the .hh (C++ header) extension. clang will recognize that means to generate a PCH. Alternatively, pass -xc++-header before the header file name if you do not want to use that extension (or another, like .H or .hpp , that is unambiguously C++).

You can tell that big-header.hh.pch is not object code (despite the -c on the command line) because file will say it is "data" (at least my version does) rather than object code. To be extra sure, run strings big-header.hh.pch | head strings big-header.hh.pch | head . The first line should be "CPCH" (meaning "Clang PCH").

To use the PCH file:

$ clang -c -include-pch big-header.hh.pch <other compile options>

The addition of -include-pch big-header.hh.pch is the key step that is different compared to gcc . Clang will not automatically pick up PCH files just due their name.

The above was tested with Clang+LLVM-14.0.0 on Linux.