meson/docs/markdown/Precompiled-headers.md

short-description
Using precompiled headers to reduce compilation time

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 given target with a pch keyword argument. As an example, let's assume you want to build a small C binary with precompiled headers. Let's say the source files of the binary use the system headers stdio.h and string.h. Then you create a header file pch/myexe_pch.h with this content:

#include <stdio.h>
#include <string.h>

And add this to meson:

executable('myexe', sources : sourcelist, c_pch : 'pch/myexe_pch.h')

That's all. 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. Any modification of the original program files is not necessary. 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.

executable('multilang', sources : srclist,
           c_pch : 'pch/c_pch.h', cpp_pch : 'pch/cpp_pch.h')

Using precompiled headers with MSVC

Since Meson version 0.50.0, precompiled headers with MSVC work just like with GCC. Meson will automatically create the matching pch implementation file for you.

Before version 0.50.0, in addition to the header file, Meson 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:

#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:

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.