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

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

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

Файл предварительно скомпилированного заголовка ищется при появлении #include в процессе компиляции. При поиске включаемого файла (см. Путь поиска) компилятор ищет предварительно скомпилированный заголовок в каждом каталоге непосредственно перед тем, как искать файл включения в этом каталоге. Искомое имя — это имя, указанное в #include, с добавлением «.gch». Если файл предварительно скомпилированного заголовка не может быть использован, он игнорируется.

Например, если у вас есть #include "all.h", и у вас есть all.h.gch в том же каталоге, что и all.h, то файл предварительно скомпилированного заголовка используется, если это возможно, в противном случае используется исходный заголовок.

В качестве альтернативы, вы можете поместить файл предварительно скомпилированного заголовка в каталог и использовать -I, чтобы убедиться, что этот каталог проверяется перед (или вместо) каталога, содержащего исходный заголовок. Затем, если вы хотите проверить, что файл предварительно скомпилированного заголовка всегда используется, вы можете поместить в этот каталог файл с тем же именем, что и исходный заголовок, содержащий команду #error.

Это также работает с -include. Таким образом, ещё один способ использования предварительно скомпилированных заголовков, подходящий для проектов, не предназначенных для предварительно скомпилированных заголовков, — просто взять большинство файлов заголовков, используемых проектом, включить их из другого файла заголовка, предварительно скомпилировать этот файл заголовка и -include предварительно скомпилированный заголовок. Если файлы заголовков имеют защиты от множественного включения, они пропускаются, так как уже были включены (в предварительно скомпилированный заголовок).

Если вам нужно предварительно скомпилировать один и тот же файл заголовка для разных языков, целей или параметров компилятора, вы можете вместо этого создать каталог с именем all.h.gch, и поместить каждый предварительно скомпилированный заголовок в каталог, возможно, используя -o. Не имеет значения, как вы называете файлы в каталоге; каждый предварительно скомпилированный заголовок в каталоге рассматривается. Первый встреченный предварительно скомпилированный заголовок в каталоге, который действителен для этой компиляции, используется; они ищутся в произвольном порядке.

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

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

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

  Опция -D — один из способов определения макроса перед включением предварительно скомпилированного заголовка; использование #define также может это сделать. Есть также некоторые опции, которые неявно определяют макросы, например -O и -Wdeprecated; то же правило применяется к макросам, определённым таким образом.

• Если при использовании предварительно скомпилированного заголовка выводятся данные отладки, используя -g или аналогичные, то такие же данные отладки должны были быть выведены при создании предварительно скомпилированного заголовка. Однако предварительно скомпилированный заголовок, созданный с помощью -g, может быть использован в компиляции, когда данные отладки не выводятся.
• В целом должны использоваться те же опции -m, как при создании, так и при использовании предварительно скомпилированного заголовка. См. Опции подмодели для случаев, когда это правило ослаблено.
• Каждый из следующих параметров должен быть одинаковым при создании и использовании предварительно скомпилированного заголовка:

  -fexceptions

• Некоторые другие параметры командной строки, начинающиеся с -f, -p, или -O, должны быть определены так же, как и при создании предварительно скомпилированного заголовка. В настоящее время неясно, какие параметры можно безопасно изменять, а какие нет; самый безопасный выбор — использовать точно такие же параметры при создании и использовании предварительно скомпилированного заголовка. Известно, что следующие параметры безопасны:

  -fmessage-length=  -fpreprocessed  -fsched-interblock 
  -fsched-spec  -fsched-spec-load  -fsched-spec-load-dangerous 
  -fsched-verbose=number  -fschedule-insns  -fvisibility= 
  -pedantic-errors

Для всех этих пунктов, кроме последнего, компилятор автоматически игнорирует предварительно скомпилированный заголовок, если условия не соблюдены. Если вы обнаружите сочетание параметров, которые не работают и не приводят к игнорированию предварительно скомпилированного заголовка, пожалуйста, отправьте сообщение об ошибке, см. Ошибки.

Если вы используете различные параметры при создании и использовании предварительно скомпилированного заголовка, фактическое поведение является смесью поведения для параметров. Например, если вы используете -g для создания предварительно скомпилированного заголовка, но не при его использовании, вы можете или не можете получить данные отладки для процедур в предварительно скомпилированном заголовке.