Debian Codegraph @

subprojects/meson-docs/docs/markdown/Precompiled-headers.md

raw
1 ---
2 short-description: Using precompiled headers to reduce compilation time
3 ...
4
5 # Precompiled headers
6
7 Parsing header files of system libraries is surprisingly expensive. A
8 typical source file has less than one thousand lines of code. In
9 contrast the headers of large libraries can be tens of thousands of
10 lines. This is especially problematic with C++, where header-only
11 libraries are common and they may contain extremely complex code. This
12 makes them slow to compile.
13
14 Precompiled headers are a tool to mitigate this issue. Basically what
15 they do is parse the headers and then serialize the compiler's
16 internal state to disk. The downside of precompiled headers is that
17 they are tricky to set up. Meson has native support for precompiled
18 headers, but using them takes a little work.
19
20 A precompiled header file is relatively simple. It is a header file
21 that contains `#include` directives for the system headers to
22 precompile. Here is a C++ example.
23
24 ```cpp
25 #include<vector>
26 #include<string>
27 #include<map>
28 ```
29
30 In Meson, precompiled header files are always per-target. That is, the
31 given precompiled header is used when compiling every single file in
32 the target. Due to limitations of the underlying compilers, this
33 header file must not be in the same subdirectory as any of the source
34 files. It is strongly recommended that you create a subdirectory
35 called `pch` in the target directory and put the header files (and
36 nothing else) there.
37
38 Toggling the usage of precompiled headers
39 --
40
41 If you wish to compile your project without precompiled headers, you
42 can change the value of the pch option by passing `-Db_pch=false`
43 argument to Meson at configure time or later with `meson configure`.
44 You can also toggle the use of pch in a configured build directory
45 with the GUI tool. You don't have to do any changes to the source
46 code. Typically this is done to test whether your project compiles
47 cleanly without pch (that is, checking that its #includes are in
48 order) and working around compiler bugs.
49
50 Using precompiled headers with GCC and derivatives
51 --
52
53 Once you have a file to precompile, you can enable the use of pch for
54 a given target with a *pch* keyword argument. As an example, let's
55 assume you want to build a small C binary with precompiled headers.
56 Let's say the source files of the binary use the system headers
57 `stdio.h` and `string.h`. Then you create a header file
58 `pch/myexe_pch.h` with this content:
59
60 ```c
61 #include <stdio.h>
62 #include <string.h>
63 ```
64
65 And add this to Meson:
66
67 ```meson
68 executable('myexe', sources : sourcelist, c_pch : 'pch/myexe_pch.h')
69 ```
70
71 That's all. You should note that your source files must _not_ include
72 the file `myexe_pch.h` and you must _not_ add the pch subdirectory to
73 your search path. Any modification of the original program files is
74 not necessary. Meson will make the compiler include the pch with
75 compiler options. If you want to disable pch (because of, say,
76 compiler bugs), it can be done entirely on the build system side with
77 no changes to source code.
78
79 You can use precompiled headers on any build target. If your target
80 has multiple languages, you can specify multiple pch files like this.
81
82 ```meson
83 executable('multilang', sources : srclist,
84 c_pch : 'pch/c_pch.h', cpp_pch : 'pch/cpp_pch.h')
85 ```
86
87 Using precompiled headers with MSVC
88 --
89 Since Meson version 0.50.0, precompiled headers with MSVC work just like
90 with GCC. Meson will automatically create the matching pch implementation
91 file for you.
92
93 Before version 0.50.0, in addition to the header file, Meson
94 also requires a corresponding source file. If your header is called
95 `foo_pch.h`, the corresponding source file is usually called
96 `foo_pch.cpp` and it resides in the same `pch` subdirectory as the
97 header. Its contents are this:
98
99 ```cpp
100 #if !defined(_MSC_VER)
101 #error "This file is only for use with MSVC."
102 #endif
103
104 #include "foo_pch.h"
105 ```
106
107 To enable pch, simply list both files in the target definition:
108
109 ```meson
110 executable('myexe', sources : srclist,
111 cpp_pch : ['pch/foo_pch.h', 'pch/foo_pch.cpp'])
112 ```
113
114 This form will work with both GCC and msvc, because Meson knows that
115 GCC does not need a `.cpp` file and thus just ignores it.
116
117 It should be noted that due to implementation details of the MSVC
118 compiler, having precompiled headers for multiple languages in the
119 same target is not guaranteed to work.