| 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. |