In August 2019, CMake introduced the long-awaited support for precompiled headers. Before that, one had to use different plugins, for example, Cotire. Right after the release of CMake with new functionality, there were several more improvements. But in the fall, we decided that we could already start using this feature, and rewrote our scripts. Later, we found a bug that generated incorrect parameters of the Clang compiler and prevented the launch of the PVS-Studio analyzer. The bug had to be fixed by ourselves.
The problem was that the source file, which used the precompiled header, was not correctly preprocessed if the Clang compiler was used. There was empty space instead of the header file. But in GCC and MSVC, everything worked fine.
It is worth talking about how CMake forms a precompiled header. For each target (starting from CMake 3.17 and for each type of the build - Debug, Release, ...), 2 files are created: cmake_pch.hxx and cmake_pch.cxx. An hxx file is a header file from which a precompiled header will be generated. cxx - is an empty file with the following contents:
/* Generated by CMake */
It is needed to generate a precompiled header - it is used as a source when the compiler starts.
During the project build the header file is included by passing the compiler flags. For Clang, these are:
-Xclang -include-pch -Xclang <PCH_FILE>
In other words, the already created precompiled header is passed in the compilation command. As a result, launch commands are saved in the file compile_commands.json, used by the analyzer for checking the project.
However, at this point, the name of the original header file gets lost. When the preprocessor starts, Clang tries to get the name of the header file from the generated precompiled header and eventually uses the empty cmake_pch.cxx file. Why? If you look into the Clang documentation, you can see their way of creating precompiled headers:
To generate PCH files using clang -cc1, use the option -emit-pch:
$ clang -cc1 test.h -emit-pch -o test.h.pch
The test.h header file is used as the source file. Whereas CMake operates in the following way:
-Xclang -emit-pch -Xclang -include -Xclang <PCH_HEADER>
It includes it through a special flag, and then passes cmake_pch.cxx as the source. Information about included files passed through the command line, unfortunately, gets lost, but the information about the source file remains. You can find this out by looking into the Clang documentation:
Original file name
The full path of the header that was used to generate the AST file.
Cotire is similar in structure to CMake, but the cxx file looked something like this:
In the source, it had an include directive, so the preprocessor worked fine. This is the first thing we wanted to offer as a fix.
However, with this approach, problems appeared - the encoding of the files was different (the compiler can convert the source file to its own encoding). Also the work of other compilers could break, and in CMake 3.17 the cmake_pch.cxx file was created only for each type of a build, while the hxx files could differ.
As a result, the decision was to pass the original source file to the compilation line as well:
-Xclang -include-pch -Xclang <PCH_FILE> -Xclang -include -Xclang <PCH_HEADER>
Thanks to the -Xclang option, the next flag is passed directly to the preprocessor, bypassing the driver, which searches for the corresponding .pch/.gch file header. Link to the patch: PCH: Clang: Update PCH usage flags to include original header.
Our small patch has become a part of CMake 3.17, fixing the problem. I hope it was interesting, and you learned a little more about the work of CMake.
We can recommend using this feature in real projects.
Date: Jan 12 2024
Author: Gleb Aslamov
Date: Dec 07 2023
Author: Anastasiya Vorobeva
Date: Dec 05 2023
Author: Anastasiya Vorobeva
Date: Nov 21 2023
Author: Andrey Karpov
Date: Oct 24 2023
Author: Uliana Grishina