What does #pragma hdrstop without parameter do when used in multiple files?

Question

What is the practical value ("what does it do") of putting #pragma hdrstop (no filename parameter) in a couple of source (cpp) files?

Note that the MSDN docs are (once again) as clear as mud to me.

Edit/Note: I'm asking this, because this answer and the article it links to seem to recommend that. But I do not understand what benefit it has to have a separate pch file for each compilation unit.

Answer 1

The answer to the original question is that the purpose of having #pragma hdrstop in a file with neither /Yc or /Yu set is that it's ignored and so you can set up a build configuration which builds without precompiled headers and other build configurations that build WITH precompiled headers and you don't need to change the code or the headers that are included at all to do so.

More detail...

The notes on MSDN say that "The hdrstop pragma gives you additional control over precompilation file names and over the location at which the compilation state is saved." which is true, but it's not especially obvious exactly how useful that can be...

In a nutshell.

• Putting #pragma hdrstop in a source file that isn't compiled with /Yc or /Yu has no effect at all.
• If you have /Yu set for the file then hdrstop tells the compiler to throw away everything before the line on which hdrstop appears and insert the precompiled header instead.
• If /Yc is set for the file then hdrstop means save all of the compiled state for everything up to the line on which hdrstop appears as the precompiled header.

The trick is using /Yc and /Yu without the optional header file name; just check the 'use' or 'create' radio button and leave the 'through header' edit box blank (or edit the project file...).

So you have 1 file, possibly called PrecompiledHeader.cpp which includes the headers that you want to include in the precompiled header and which has #pragma hdrstop at the end of the list of include files. This ONE file is compiled with /Yc.

You then have all your other cpp files with #pragma hdrstop after the include files that are in your precompiled header. These files are all compiled with /Yu.

This results in PrecompiledHeader.cpp building your (in this example) single pch file and all of the other files using that single pch file.

The advantage in doing this is that NONE of your files need to include a 'global' precompiled header building header file - so no stdafx.h or whatever. This means that you can set up a build configuration which builds WITHOUT precompiled headers where all of the #pragma hdrstop lines are simply ignored.

This is "good" because it means that you can have a single 'no precomp' build configuration which lets you develop quickly (you can change a single header and NOT force the world to rebuild) and other "normal" configurations that DO use precompiled headers.

Answer 2

All the code before #pragma hdrstop will be part of a precompiled header. If no filename parameter is given, the name of the header will be the base name of the source file with a .PCH extension, as mentioned in the documentation:

The name of the precompiled header file is determined according to the following rules, in order of precedence:

1. The argument to the /Fp compiler option

2. The filename argument to #pragma hdrstop

3. The base name of the source file with a .PCH extension

So, if you have that on a file named blah.cpp it will produce a file named blah.pch, IFF compiled with /Yc (which only one file should have set).