что такое precompiled headers

Precompiled Header Files

The compiler options for precompiled headers are /Y. In the project property pages, the options are located under Configuration Properties > C/C++ > Precompiled Headers. You can choose to not use precompiled headers, and you can specify the header file name and the name and path of the output file.

Custom precompiled code

For large projects that take significant time to build, you may want to consider creating custom precompiled files. The Microsoft C and C++ compilers provide options for precompiling any C or C++ code, including inline code. Using this performance feature, you can compile a stable body of code, store the compiled state of the code in a file, and, during subsequent compilations, combine the precompiled code with code that is still under development. Each subsequent compilation is faster because the stable code does not need to be recompiled.

When to Precompile Source Code

Precompiled code is useful during the development cycle to reduce compilation time, especially if:

You always use a large body of code that changes infrequently.

Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header.

The first compilation — the one that creates the precompiled header (PCH) file — takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code.

You can precompile both C and C++ programs. In C++ programming, it is common practice to separate class interface information into header files. These header files can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile.

Two Choices for Precompiling Code

You can precompile any C or C++ code; you are not limited to precompiling only header files.

Precompiling requires planning, but it offers significantly faster compilations if you precompile source code other than simple header files.

Precompile code when you know that your source files use common sets of header files but don’t include them in the same order, or when you want to include source code in your precompilation.

The precompiled-header options are /Yc (Create Precompiled Header File) and /Yu (Use Precompiled Header File). Use /Yc to create a precompiled header. When used with the optional hdrstop pragma, /Yc lets you precompile both header files and source code. Select /Yu to use an existing precompiled header in the existing compilation. You can also use /Fp with the /Yc and /Yu options to provide an alternative name for the precompiled header.

The compiler option reference topics for /Yu and /Yc discuss how to access this functionality in the development environment.

Precompiled Header Consistency Rules

Because PCH files contain information about the machine environment as well as memory address information about the program, you should only use a PCH file on the machine where it was created.

Consistency Rules for Per-File Use of Precompiled Headers

The /Yu compiler option lets you specify which PCH file to use.

When you use a PCH file, the compiler assumes the same compilation environment — one that uses consistent compiler options, pragmas, and so on — that was in effect when you created the PCH file, unless you specify otherwise. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings do not necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections.

Compiler Option Consistency

The following compiler options can trigger an inconsistency warning when using a PCH file:

Macros created using the Preprocessor (/D) option must be the same between the compilation that created the PCH file and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if these change.

PCH files do not work with the /E and /EP options.

PCH files must be created using either the Generate Browse Info (/FR) option or the Exclude Local Variables (/Fr) option before subsequent compilations that use the PCH file can use these options.

C 7.0-Compatible (/Z7)

If this option is in effect when the PCH file is created, subsequent compilations that use the PCH file can use the debugging information.

Include Path Consistency

A PCH file does not contain information about the include path that was in effect when it was created. When you use a PCH file, the compiler always uses the include path specified in the current compilation.

Source File Consistency

When you specify the Use Precompiled Header File (/Yu) option, the compiler ignores all preprocessor directives (including pragmas) that appear in the source code that will be precompiled. The compilation specified by such preprocessor directives must be the same as the compilation used for the Create Precompiled Header File (/Yc) option.

Pragma Consistency

Pragmas processed during the creation of a PCH file usually affect the file with which the PCH file is subsequently used. The comment and message pragmas do not affect the remainder of the compilation.

These pragmas affect only the code within the PCH file; they do not affect code that subsequently uses the PCH file:

These pragmas are retained as part of a precompiled header, and affect the remainder of a compilation that uses the precompiled header:

alloc_text
auto_inline
check_stack
code_seg
data_seg

function
include_alias
init_seg
inline_depth

inline_recursion
intrinsic
optimize
pack

pointers_to_members
setlocale
vtordisp
warning

Consistency Rules for /Yc and /Yu

When you use a precompiled header created using /Yc or /Yu, the compiler compares the current compilation environment to the one that existed when you created the PCH file. Be sure to specify an environment consistent with the previous one (using consistent compiler options, pragmas, and so on) for the current compilation. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don’t necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. The following sections explain the consistency requirements for precompiled headers.

Compiler Option Consistency

This table lists compiler options that might trigger an inconsistency warning when using a precompiled header:

The precompiled header facility is intended for use only in C and C++ source files.

Using Precompiled Headers in a Project

Previous sections present an overview of precompiled headers: /Yc and /Yu, the /Fp option, and the hdrstop pragma. This section describes a method for using the manual precompiled-header options in a project; it ends with an example makefile and the code that it manages.

For another approach to using the manual precompiled-header options in a project, study one of the makefiles located in the MFC\SRC directory that is created during the default setup of Visual Studio. These makefiles take a similar approach to the one presented in this section but make greater use of Microsoft Program Maintenance Utility (NMAKE) macros, and offer greater control of the build process.

PCH Files in the Build Process

The code base of a software project is usually contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with those in the example code found in Sample Makefile for PCH and Example Code for PCH.

The figure uses three diagrammatic devices to show the flow of the build process. Named rectangles represent each file or macro; the three macros represent one or more files. Shaded areas represent each compile or link action. Arrows show which files and macros are combined during the compilation or linking process.

Structure of a Makefile That Uses a Precompiled Header File

Beginning at the top of the diagram, both STABLEHDRS and BOUNDRY are NMAKE macros in which you list files not likely to need recompilation. These files are compiled by the command string

CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp

only if the precompiled header file (STABLE.pch) does not exist or if you make changes to the files listed in the two macros. In either case, the precompiled header file will contain code only from the files listed in the STABLEHDRS macro. List the last file you want precompiled in the BOUNDRY macro.

The files you list in these macros can be either header files or C or C++ source files. (A single PCH file cannot be used with both C and C++ modules.) Note that you can use the hdrstop macro to stop precompilation at some point within the BOUNDRY file. See hdrstop for more information.

Continuing down the diagram, APPLIB.obj represents the support code used in your final application. It is created from APPLIB.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header.

MYAPP.obj represents your final application. It is created from MYAPP.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header.

Finally, the executable file (MYAPP.EXE) is created by linking the files listed in the OBJS macro (APPLIB.obj and MYAPP.obj).

Sample Makefile for PCH

Aside from the STABLEHDRS, BOUNDRY, and UNSTABLEHDRS macros shown in the figure «Structure of a Makefile That Uses a Precompiled Header File» in PCH Files in the Build Process, this makefile provides a CLFLAGS macro and a LINKFLAGS macro. You must use these macros to list compiler and linker options that apply whether you build a debug or final version of the application’s executable file. There is also a LIBS macro where you list the libraries your project requires.

This feature makes it possible for you to use the same makefile during development and for the final versions of your program — use DEBUG=0 for the final versions. The following command lines are equivalent:

For more information on makefiles, see NMAKE Reference. Also see MSVC Compiler Options and the MSVC Linker Options.

Example Code for PCH

The following source files are used in the makefile described in PCH Files in the Build Process and Sample Makefile for PCH. Note that the comments contain important information.

Источник

Файлы предварительно скомпилированных заголовков

Параметры компилятора для предкомпилированных заголовков — /Y. На страницах свойств проекта параметры находятся в разделе Свойства конфигурации > C/C++ > Предварительно скомпилированные заголовки. Можно не использовать предкомпилированные заголовки, а также указать имя файла заголовка и путь к выходному файлу.

Настраиваемый предварительно скомпилированный код

Для больших проектов, для которых требуется значительное время, может потребоваться создать настраиваемые предварительно скомпилированные файлы. Компиляторы Microsoft C и C++ содержат параметры для предварительной компиляции любого кода C или C++, включая встроенный код. Данная возможность позволяет скомпилировать стабильное тело кода, сохранять скомпилированное состояние кода в файле, а при последующих компиляциях объединять предварительно скомпилированный код с кодом, который еще находится в стадии разработки. Каждая последующая компиляция выполняется быстрее, так как стабильный код не нужно компилировать повторно.

Случаи использования предварительной компиляции исходного кода

Предварительно скомпилированный код полезен во время цикла разработки, чтобы сократить время компиляции, особенно если:

Всегда используется большой текст кода, в который редко вносятся изменения.

Программа состоит из нескольких модулей, каждый из которых использует стандартный набор включаемых файлов, а также одни и те же параметры компиляции. В этом случае все включаемые файлы можно предварительно скомпилировать в один предкомпилированный заголовок.

Первая компиляция, которая создает файл предкомпилированного заголовка (PCH), занимает немного больше времени, чем последующие компиляции. Последующие компиляции могут выполняться быстрее, включая предварительно скомпилированный код.

Можно предварительно скомпилировать программы C и C++. В программировании на языке C++ распространенной практикой является отделение сведений об интерфейсе класса в файлы заголовков. Впоследствии эти файлы заголовков можно будет включать в программы, использующие класс. Предварительная компиляция этих заголовков позволяет сократить время, затрачиваемое программой на компиляцию.

Хотя для каждого исходного файла можно использовать только один файл предкомпилированного заголовка (PCH), в проекте можно использовать несколько файлов PCH.

Два варианта предварительной компиляции кода

Можно предварительно скомпилировать любой код C или C++ — вы не ограничены предварительной компиляцией только файлов заголовков.

Для предварительной компиляции требуется планирование, но при предварительной компиляции исходного кода, отличного от простых файлов заголовков, обеспечивается значительно более быстрая компиляция.

Предварительная компиляция кода рекомендуется, когда известно, что исходные файлы используют общие наборы файлов заголовков, но не содержат их в том же порядке, или если требуется включить исходный код в предварительную компиляцию.

Параметры предкомпилированного заголовка см. в разделах /Yc (создание файла предкомпилированного заголовка) и /Yu (использование файла предкомпилированного заголовка). Для создания предкомпилированного заголовка используйте /Yc. При использовании с необязательной прагмой hdrstop параметр /Yc позволяет предварительно компилировать как файлы заголовков, так и исходный код. Выберите /Yu, чтобы использовать существующий предкомпилированный заголовок в существующей компиляции. Можно также использовать /Fp с параметрами /Yc и /Yu, чтобы предоставить альтернативное имя предкомпилированному заголовку.

В справочных разделах, посвященных параметрам компилятора /Yu и /Yc, обсуждаются способы доступа к этой функции в среде разработки.

Правила согласованности предкомпилированных заголовков

Поскольку файлы PCH содержат сведения о среде компьютера, а также сведения об адресах памяти для программы, файл PCH следует использовать только на том компьютере, на котором он был создан.

Правила целостности для пофайлового использования предкомпилированных заголовков

Параметр компилятора /Yu позволяет указать, какой файл PCH следует использовать.

При использовании файла PCH компилятор предполагает ту же среду компиляции, которая использует последовательные параметры компилятора, прагмы и т. д., которые действуют при создании файла PCH, если не указано иное. Если компилятор обнаруживает несогласованность, он выдает предупреждение и по возможности определяет несогласованность. Такие предупреждения не обязательно указывают на проблему с файлом PCH. Они просто предупреждают о возможных конфликтах. Требования к согласованности для файлов PCH описаны в следующих разделах.

Согласованность параметров компилятора

Следующие параметры компилятора могут вызвать предупреждение о несогласованности при использовании файла PCH:

Макросы, созданные с помощью параметра препроцессора (/D), должны быть одинаковыми в компиляциях, создавшими файл PCH, и текущей компиляцией. Состояние определенных констант не проверяется, но при их изменениях могут возникать непредсказуемые результаты.

Файлы PCH не работают с параметрами/E и /EP.

Файлы PCH должны быть созданы с помощью параметра создания сведений о просмотре (/FR) или исключения локальных переменных (/Fr), прежде чем последующие компиляции, использующие файл PCH, смогут использовать эти параметры.

C7 совместимо (/Z7)

Если при создании файла PCH этот параметр включен, последующие компиляции, использующие файл PCH, могут использовать отладочную информацию.

Если при создании файла PCH параметр «C7 совместимо (/Z7)» отключен, последующие компиляции, использующие файл PCH и/Z7, вызывают предупреждение. Отладочная информация помещается в текущий OBJ-файл, а локальные символы, определенные в файле PCH, недоступны отладчику.

Согласованность пути включаемых файлов

В файле PCH не содержатся сведения о пути включаемых файлов, который применялся при создании. При использовании файла PCH компилятор всегда использует путь включаемых файлов, указанный в текущей компиляции.

Согласованность исходного файла

При указании параметра использования файла предкомпилированного заголовка (/Yu) компилятор игнорирует все директивы препроцессора (включая прагмы), отображаемые в исходном коде, который будет предварительно скомпилирован. Компиляция, указанная такими директивами препроцессора, должна совпадать с компиляцией, используемой для параметра создания файла предкомпилированного заголовка (/Yc).

Согласованность прагмы

Прагмы, обработанные во время создания файла PCH, обычно влияют на файл, с которым впоследствии используется файл PCH. Прагмы comment и message не влияют на оставшуюся часть компиляции.

Они влияют только на код в файле PCH; они не влияют на код, который впоследствии использует файл PCH:

Эти прагмы сохраняются как часть предкомпилированного заголовка и влияют на оставшуюся часть компиляции, использующую предкомпилированный заголовок:

alloc_text
auto_inline
check_stack
code_seg
data_seg

function
include_alias
init_seg
inline_depth

inline_recursion
intrinsic
optimize
pack

pointers_to_members
setlocale
vtordisp
warning

Правила целостности для параметров компилятора /Yc и /Yu

При использовании предкомпилированного заголовка, созданного с помощью параметра /Yc или/Yu, компилятор сравнивает текущую среду компиляции с той, которая существовала при создании файла PCH. Не забудьте указать среду, соответствующую предыдущей (с помощью параметров компилятора, прагм и т. д.) для текущей компиляции. Если компилятор обнаруживает несогласованность, он выдает предупреждение и по возможности определяет несогласованность. Такие предупреждения не обязательно указывают на проблему с файлом PCH. Они просто предупреждают о возможных конфликтах. В следующих разделах объясняются требования к согласованности для предкомпилированных заголовков.

Согласованность параметров компилятора

В таблице ниже перечислены параметры компилятора, которые могут вызвать предупреждение о несогласованности при использовании предкомпилированного заголовка.

Средство предварительно откомпилированных заголовков предназначено для использования только в исходных файлах C и C++.

Использование предкомпилированных заголовков в проекте

В предыдущих разделах представлен обзор предкомпилированных заголовков: /Yc и /Yu, параметра /FP и прагмы hdrstop. В этом разделе описывается метод использования в проекте параметров заголовков, предкомпилированных вручную. В конце раздела приводится пример файла makefile и кода, который управляет им.

Чтобы ознакомиться с другим подходом к использованию в проекте параметров заголовков, предкомпилированных вручную, изучите один из файлов makefile, расположенных в каталоге MFC\SRC, который создается во время установки Visual Studio по умолчанию. Подход в этих файлах makefile аналогичен представленному в этом разделе, однако в них используются макросы служебной программы обслуживания Майкрософт (NMAKE) и обеспечивается больший контроль над процессом сборки.

PCH-файлы в процессе построения

База кода проекта программного обеспечения обычно содержится в нескольких исходных файлах C или C++, объектных файлах, библиотеках и файлах заголовков. Как правило, файл makefile координирует объединение этих элементов в исполняемый файл. На следующем рисунке показана структура файла makefile, использующего файл предкомпилированного заголовка. Имена макросов и имена файлов на рисунке соответствуют приведенным в примере кода в разделах Пример файла makefile для PCH и Пример кода для PCH.

На рисунке для отображения последовательности процесса сборки используются три схематических элемента. Прямоугольники представляют каждый файл или макрос; три макроса представляют один или несколько файлов. Затененные области представляют каждое действие компиляции или компоновки. Стрелки показывают, какие файлы и макросы объединяются во время процесса компиляции или компоновки.

Структура файла makefile, использующего файл предкомпилированного заголовка

Начиная с верхней части диаграммы, STABLEHDRS и BOUNDRY являются макросами NMAKE, в которых вы перечислите файлы, которые, скорее всего, не потребуют перекомпиляции. Эти файлы компилируются с помощью командной строки

CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp

только если файл предкомпилированного заголовка (STABLE.pch) не существует или если вы вносите изменения в файлы, перечисленные в двух макросах. В любом случае файл предкомпилированного заголовка будет содержать код только из файлов, перечисленных в макросе STABLEHDRS. Перечислите последний файл, который необходимо предварительно откомпилировать в макросе BOUNDRY.

Файлы, перечисленные в этих макросах, могут быть файлами заголовков или файлами исходного кода C или C++. (Один файл PCH нельзя использовать одновременно с модулями C и C++.) Обратите внимание, что можно использовать макрос hdrstop, чтобы прервать предварительную компиляцию в любой момент в файле BOUNDRY. Дополнительные сведения см. в разделе hdrstop.

Далее APPLIB.obj на схеме представляет код поддержки, используемый в окончательном приложении. Он создается из APPLIB.cpp, файлов, перечисленных в макросе UNSTABLEHDRS, и предварительно скомпилированного кода из предкомпилированного заголовка.

MYAPP.obj представляет конечное приложение. Он создается из файла MYAPP.cpp, файлов, перечисленных в макросе UNSTABLEHDRS, и предварительно скомпилированного кода из предкомпилированного заголовка.

Наконец, создается исполняемый файл (MYAPP.EXE) путем связывания файлов, перечисленных в макросе OBJS (APPLIB.obj и MYAPP.obj).

Образец файла makefile для PCH

Помимо макросов STABLEHDRS, BOUNDRY и UNSTABLEHDRS, показанных на рисунке «Структура файла makefile, использующего файл предкомпилированного заголовка» в разделе PCH-файлы в процессе сборки, этот файл makefile предоставляет макрос CLFLAGS и макрос LINKFLAGS. Эти макросы необходимо использовать для перечисления параметров компилятора и компоновщика, которые применяются при сборке отладочной или финальной версии исполняемого файла приложения. Также имеется макрос LIBS, в котором перечислены библиотеки, необходимые для проекта.

Эта функция позволяет использовать один и тот же файл makefile во время разработки и для финальных версий программы — используйте DEBUG=0 для финальных версий. Следующие строки команды являются эквивалентными.

Дополнительные сведения о файлах makefile см. в разделе Справочник по NMAKE. См. также разделы Параметры компилятора MSVC и Параметры компоновщика MSVC.

Пример кода для PCH

Следующие исходные файлы используются в файле makefile, который описан в разделах PCH-файлы в процессе сборки и Образец файла makefile для PCH. Обратите внимание, что комментарии содержат важную информацию.

Источник