CMake Compilation Optimization – Precompiled Header Files

<span>target_precompile_headers</span> is a feature introduced in CMake 3.16, used to generate precompiled header files (Precompiled Headers, PCH) for specific targets (such as executables or libraries). Precompiled header files can significantly speed up compilation, especially when there are many repeated header file inclusions in the project.

1. The Role of Precompiled Header Files

1. Reduce Redundant Compilation:

• Precompiled header files compile commonly used headers (such as standard libraries and third-party libraries) into binary form in advance.

• During subsequent compilations, the precompiled results are used directly, avoiding repeated parsing and compilation.

Speed Up Compilation:

• For large projects, precompiled header files can significantly reduce compilation time.

Optimize Header File Dependencies:

• Manage frequently used header files centrally, reducing dependencies of compilation units.

2. <span><span>target_precompile_headers</span></span> Syntax

target_precompile_headers(<target>    <INTERFACE|PUBLIC|PRIVATE> [header1.h] [header2.h] ...)

• <span><target></span>: Target name (such as an executable or library).

• <span><INTERFACE|PUBLIC|PRIVATE></span>: Specifies the visibility of the header files.

• <span>PUBLIC</span>: The header files are visible to the target and its dependencies.

• <span>PRIVATE</span>: The header files are only visible to the target.

• <span>INTERFACE</span>: The header files are only visible to dependencies.

• <span>[header1.h] [header2.h] ...</span>: List of header files to be precompiled.

For example:

target_precompile_headers(my_target PUBLIC "stdafx.h")

1. Generate precompiled header files for <span>my_target</span> target:

• <span>stdafx.h</span> is the entry file for the precompiled header.

• CMake will precompile <span>stdafx.h</span> and all its included header files into binary form.

<span>PUBLIC</span> Keyword Function:

• <span>stdafx.h</span> is visible to <span>my_target</span> and its dependencies.

• If other targets depend on <span>my_target</span>, they will also use the same precompiled header file.

<span>Content of stdafx.h</span>:

• <span>stdafx.h</span> typically includes frequently used header files in the project, such as:

// stdafx.h#include <iostream>#include <vector>#include <string>#include "common_utils.h"

3. Complete Example

Project Structure

project/├── CMakeLists.txt├── src/│   ├── main.cpp│   ├── stdafx.h│   └── common_utils.h

<span>stdafx.h</span> File

// stdafx.h#pragma once#include <iostream>#include <vector>#include <string>#include "common_utils.h"

<span>CMakeLists.txt</span> File

cmake_minimum_required(VERSION 3.16)project(MyProject)
# Add executable target
add_executable(my_target src/main.cpp)
# Enable precompiled header files
target_precompile_headers(my_target PUBLIC "stdafx.h")

<span>main.cpp</span> File

#include "stdafx.h"
int main() {    std::vector<int> vec = {1, 2, 3};    for (auto& v : vec) {        std::cout << v << std::endl;    }    return 0;}

4. Principle Explanation

1. Precompilation Stage:

• CMake generates a precompiled header file (such as <span>stdafx.h.gch</span> or <span>stdafx.h.pch</span>).

• This file contains the binary form of <span>stdafx.h</span> and all its dependent header files.

Compilation Stage:

• When compiling <span>main.cpp</span>, the compiler will prioritize using the precompiled header file instead of re-parsing <span>stdafx.h</span> and its dependencies.

Dependency Propagation:

• Since <span>PUBLIC</span> is used, other targets that depend on <span>my_target</span> will also use the same precompiled header file.

5. Extensions

1. Multiple Precompiled Header Files

Different precompiled header files can be set for different targets.

target_precompile_headers(my_target PRIVATE "stdafx.h")
target_precompile_headers(my_library PRIVATE "library_headers.h")

2. Conditional Precompiled Header Files

Select different precompiled header files based on platform or configuration.

if(WIN32)    target_precompile_headers(my_target PUBLIC "stdafx_win.h")else()    target_precompile_headers(my_target PUBLIC "stdafx_linux.h")endif()

3. Disable Precompiled Header Files

If you need to disable precompiled header files, you can set:

target_precompile_headers(my_target PUBLIC "")

Previous CMake articles links:cmake –foreach CMake Compilation Optimization – Symbol SeparationCMake Compilation Optimization – Using Ninja GeneratorSeveral Reasons and Solutions for CMake Cache Issues Leading to New Code Not Being Compiled CorrectlyCMake Cross CompilationCMake get_filename_componentCMake — Library QueryCMake — Library OperationsCMake File OperationsCMake — Install CommandCMake — Custom CommandsCMake — String CommandCMake Macros and FunctionsCMake — Compilation OptionsCMake Common Built-in VariablesCMake — Modules and FindPackageCMake — Targets and DependenciesCMake — Control Flow StatementsCMake Variables and CacheCMake Introduction – Getting Started with CMake