How we fixed one bug in CMake

Mar 23 2020

Author: Sergey Larin

What was wrong?
What does CMake do?
Problem
But how did Cotire work in this case?
Solution
Conclusion

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.

What was wrong?

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.

What does CMake do?

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.

Problem

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.

But how did Cotire work in this case?

Cotire is similar in structure to CMake, but the cxx file looked something like this:

#ifdef __cplusplus
#include "/path/to/header.hxx"
#endif

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.

Solution

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.

Conclusion

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.