The Meson Build System
http://mesonbuild.com/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
105 lines
3.8 KiB
105 lines
3.8 KiB
--- |
|
short-description: Using precompiled headers to reduce compilation time |
|
... |
|
|
|
# Precompiled headers |
|
|
|
Parsing header files of system libraries is surprisingly expensive. A |
|
typical source file has less than one thousand lines of code. In |
|
contrast the headers of large libraries can be tens of thousands of |
|
lines. This is especially problematic with C++, where header-only |
|
libraries are common and they may contain extremely complex code. This |
|
makes them slow to compile. |
|
|
|
Precompiled headers are a tool to mitigate this issue. Basically what |
|
they do is parse the headers and then serialize the compiler's |
|
internal state to disk. The downside of precompiled headers is that |
|
they are tricky to set up. Meson has native support for precompiled |
|
headers, but using them takes a little work. |
|
|
|
A precompiled header file is relatively simple. It is a header file |
|
that contains `#include` directives for the system headers to |
|
precompile. Here is a C++ example. |
|
|
|
```cpp |
|
#include<vector> |
|
#include<string> |
|
#include<map> |
|
``` |
|
|
|
In Meson, precompiled header files are always per-target. That is, the |
|
given precompiled header is used when compiling every single file in |
|
the target. Due to limitations of the underlying compilers, this |
|
header file must not be in the same subdirectory as any of the source |
|
files. It is strongly recommended that you create a subdirectory |
|
called `pch` in the target directory and put the header files (and |
|
nothing else) there. |
|
|
|
Toggling the usage of precompiled headers |
|
-- |
|
|
|
If you wish to compile your project without precompiled headers, you |
|
can change the value of the pch option by passing `-Db_pch=false` |
|
argument to Meson at configure time or later with `meson configure`. You can |
|
also toggle the use of pch in a configured build directory with the |
|
GUI tool. You don't have to do any changes to the source |
|
code. Typically this is done to test whether your project compiles |
|
cleanly without pch (that is, checking that its #includes are in |
|
order) and working around compiler bugs. |
|
|
|
Using precompiled headers with GCC and derivatives |
|
-- |
|
|
|
Once you have a file to precompile, you can enable the use of pch for |
|
a give target with a *pch* keyword argument. As an example, here's how |
|
you would use it with a C binary. |
|
|
|
```meson |
|
executable('myexe', sources : sourcelist, c_pch : 'pch/myexe_pch.h') |
|
``` |
|
|
|
You should note that your source files must _not_ include the file |
|
`myexe_pch.h` and you must _not_ add the pch subdirectory to your |
|
search path. Meson will make the compiler include the pch with |
|
compiler options. If you want to disable pch (because of, say, |
|
compiler bugs), it can be done entirely on the build system side with |
|
no changes to source code. |
|
|
|
You can use precompiled headers on any build target. If your target |
|
has multiple languages, you can specify multiple pch files like this. |
|
|
|
```meson |
|
executable('multilang', sources : srclist, |
|
c_pch : 'pch/c_pch.h', cpp_pch : 'pch/cpp_pch.h']) |
|
``` |
|
|
|
Using precompiled headers with MSVC |
|
-- |
|
|
|
MSVC is a bit trickier, because in addition to the header file, it |
|
also requires a corresponding source file. If your header is called |
|
`foo_pch.h`, the corresponding source file is usually called |
|
`foo_pch.cpp` and it resides in the same `pch` subdirectory as the |
|
header. Its contents are this: |
|
|
|
```cpp |
|
#if !defined(_MSC_VER) |
|
#error "This file is only for use with MSVC." |
|
#endif |
|
|
|
#include "foo_pch.h" |
|
``` |
|
|
|
To enable pch, simply list both files in the target definition: |
|
|
|
```meson |
|
executable('myexe', sources : srclist, |
|
cpp_pch : ['pch/foo_pch.h', 'pch/foo_pch.cpp']) |
|
``` |
|
|
|
This form will work with both GCC and msvc, because Meson knows that |
|
GCC does not need a `.cpp` file and thus just ignores it. |
|
|
|
It should be noted that due to implementation details of the MSVC |
|
compiler, having precompiled headers for multiple languages in the |
|
same target is not guaranteed to work.
|
|
|