Precompiled Header Wizard

ToolsPrecompiled Header Wizard

Use this wizard to create a master precompiled header for your C++ project. The wizard analyzes the project, collects header file information, selects headers based on criteria that you set, and then generates a master precompiled header file that can be used to precompile.

Including a precompiled header binary can significantly reduce the number of lines of code that the compiler must process. Theoretically, a well-selected precompiled header can also significantly reduce the time required to compile your project.

Note: Not all of the features described here are present for every instance of the wizard.

Gather Information page

You can choose the method to be used for getting header file information: either by analyzing the project or by loading from cache based on data from the previous time the wizard was run on this project. A third choice is to run the wizard to remove the header file previously included by the wizard.

Item	Description
Perform a full analysis of the project using the current build configuration	Requests a full analysis of the project using the current build configuration.
Load header file information from cache	Specifies that header file information is to be loaded from the cache generated on the displayed date. Use this option with care, because any changes you have made to the project since the cache was generated will not be seen.
Remove implicitly included precompiled header	If, on a previous run of the wizard, you chose to have the resulting precompiled header automatically included during compilation, select this option to remove the implicitly included precompiled header.

Analyze Project page (optional)

If you selected Perform full analysis on the Gather Information page, the next step is to analyze the project. The include tree is generated, collated, and cached for quicker subsequent runs of the wizard. A message window self-documents the tasks performed on this page.

Filter Criteria page

Allows you to set the filter criteria that control the contents of your master precompiled header file.

Item	Description
Include headers referenced by at least nn source files	Specifies the number of source files that must reference a given header file in order to include the header file in the master precompiled header.
Exclude unguarded headers (recommended)	Omits headers files without a header guard. A header guard is a construct using #define to ensure that the compiler reads that header only ONCE during any compilation, even though it might be referenced by many other headers.
Exclude headers that are part of the project (recommended)	Includes only headers that are external to the current project. This option is recommended because typically headers are more likely to change in a project that is under development.
Include/Exclude by filename	Specify files that you want to include or exclude: Include files matching: Exclude files matching: You can use wildcards to specify filenames (such as .hpp) and directory names (such as $(BDS)/include). To add file or directory names to these entry fields, use the buttons located on the right edge of the dialog box . To move between the Include files matching* list and the Exclude files matching list, use the directional arrows on the keyboard.
Restore Defaults	Restores the initial default values for all options in the Precompiled Header Wizard and clears the two fields Include file matching and Exclude files matching. This button is useful if you have created a precompiled header that has caused unexpected results. If you are looking for a Panic button, this is it.

Select Files page

This page lists:

Header files that match the filter criteria
Header files that do not match the filter criteria
Files that can be ignored because they are included by other header files

On this page, you can specify exactly the header files that are to be included in (or excluded from) your master precompiled header. Every file that is checked is added to the master precompiled header.

Included	Lists the files that match the filter criteria you selected on the previous page. In the Included list, uncheck the names of the files that you want to exclude from the master header.
Excluded	Lists the files that do not match the filter criteria. In the Excluded list, files that you check are included in the master header.
Ignored (implicitly included by other headers)	Lists the header files that match the filter criteria but would be redundant in the precompiled header because they are included by other matching header files. To add a file to the precompiled header, click the checkbox for the file in this list.
Run a test build	Run a test build using the results selected on this page. If you select this option, the wizard attempts to generate the actual precompiled header binary and ensure that it can be used to build the project.

Test Build page (optional)

This page appears only if you selected Run a test build on the Select Files page. This page verifies the integrity of the master precompiled header file that the wizard will generate if you continue to the end without changing any filter criteria.

During the test build, the wizard performs three steps:

Verifies that all headers included in the results page can be precompiled. The wizard attempts to determine which headers are problematic and removes them.
Checks for initialized data in headers and removes the headers from the master precompiled header file. (Headers that contain initialized data will fail PCH creation.)
Runs the test build and the compiler. Any files that do not build are tagged to not use the master precompiled header file (auto pch).

message field	The test build is self-documenting and displays its own informational messages as well as compiler errors.
Stop/Restart/Next buttons	The test build starts automatically, but the Stop button is immediately available. After the test build completes, the Stop button becomes the Restart button. You need to click Next to advance to the final page of the wizard.

Filename and Settings

This is the Finish page for the Precompiled Header Wizard.

Implicitly include for all compilation units	Specifies that the wizard is to perform auto PCH inclusion. That is, the wizard will set up the project to automatically use the master precompiled header for all source files. Sets the BCC32 -Hi and -Hh options to “Inject precompiled header file.”
Just generate the file, I will include it explicitly.	Specifies that the wizard is only going to create the master precompiled header file. You are required to add a #include command (located before #pragma hdrstop) in each source file that you want to use the master precompiled header file.
Output filename	Specifies the location and name of the master precompiled header file. The default file name is pch<n>.h.
Open in editor	Creates the master precompiled header file and then opens it in the Code Editor.