3.13 Параметры, управляющие предобработчиком ¶

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

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

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

-D name

Предопределить name как макрос с определением 1.

-D name=definition

Содержание definition токенизируется и обрабатывается так, как будто оно появилось во время этапа трансляции три в директиве ‘#define’. В частности, определение обрезается вложенными символами новой строки.

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

Если вы хотите определить макрос типа функции в командной строке, запишите его список аргументов в скобки перед знаком равенства (если таковой имеется). Скобки имеют значение для большинства оболочек, поэтому вы должны привести опцию в кавычки. С sh и csh, -D'name(args…)=definition' работает.

Опции -D и -U обрабатываются в порядке их указания в командной строке. Все опции -imacros file и -include file обрабатываются после всех опций -D и -U.

-U name

Отменить любое предыдущее определение name, встроенное или предоставленное опцией -D.

-include file

Обработать file, как будто #include "file" появилось как первая строка исходного файла. Однако, первый каталог, который будет просматриваться для file, — это рабочий каталог препроцессора вместо каталога, содержащего основной исходный файл. Если файл там не найден, он будет просматриваться в остальной части #include "…" цепочки поиска в обычном режиме.

Если указано несколько опций -include, файлы включаются в порядке их появления в командной строке.

-imacros file

Точно так же, как -include, за исключением того, что любой вывод, полученный при сканировании file, отбрасывается. Макросы, которые он определяет, остаются определенными. Это позволяет вам получить все макросы из заголовка без обработки его объявлений.

Все файлы, указанные с помощью -imacros, обрабатываются перед всеми файлами, указанными с помощью -include.

-undef

Не предопределять какие-либо системные или специфичные для GCC макросы. Стандартные предопределенные макросы остаются определенными.

-pthread

Определить дополнительные макросы, необходимые для использования библиотеки POSIX потоков. Вы должны использовать эту опцию последовательно как для компиляции, так и для компоновки. Эта опция поддерживается на целевых платформах GNU/Linux, большинстве других производных Unix, а также на целевых платформах x86 Cygwin и MinGW.

-M

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

Если не указано явно (с помощью -MT или -MQ), имя файла объекта состоит из имени исходного файла с заменой любого суффикса суффиксом файла объекта и удалением всех префиксных частей каталогов. Если включено много файлов, правило разбивается на несколько строк с использованием ‘\’-новая строка. Правило не содержит команд.

Эта опция не подавляет отладочный вывод препроцессора, такой как -dM. Чтобы избежать смешивания такого отладочного вывода с правилами зависимостей, вы должны явно указать файл вывода зависимостей с помощью -MF или использовать переменную среды, такую как DEPENDENCIES_OUTPUT (см. Переменные среды, влияющие на GCC). Отладочный вывод по-прежнему отправляется в обычный поток вывода, как обычно.

Передача -M драйверу подразумевает -E и подавляет предупреждения с неявным -w.

-MM

Как -M, но не упоминает файлы заголовков, которые находятся в системных каталогах заголовков, ни файлы заголовков, которые включаются, напрямую или косвенно, из такого заголовка.

Это подразумевает, что выбор угловых скобок или двойных кавычек в директиве ‘#include’ сам по себе не определяет, появляется ли этот заголовок в выводе зависимостей -MM.

-MF file

При использовании с -M или -MM, указывает файл для записи зависимостей. Если переключатель -MF не задан, препроцессор отправляет правила в то же место, куда он отправлял бы результат предварительной обработки.

При использовании с опциями драйвера -MD или -MMD, -MF переопределяет файл вывода зависимостей по умолчанию.

Если file равно -, то зависимости записываются в stdout.

-MG

В сочетании с такой опцией, как -M, запрашивающей создание зависимостей, -MG предполагает, что отсутствующие файлы заголовков являются сгенерированными файлами и добавляет их в список зависимостей без поднятия ошибки. Имя файла зависимости берётся непосредственно из директивы #include без добавления пути. -MG также подавляет вывод результатов предварительной обработки, так как отсутствующий файл заголовка делает это бесполезным.

Эта функция используется в автоматическом обновлении файлов make.

-MP

Эта опция инструктирует CPP добавить фиктивную цель для каждой зависимости, отличной от основного файла, заставляя каждую зависеть ни от чего. Эти фиктивные правила обходят ошибки, которые make выдаёт, если вы удаляете файлы заголовков без обновления файла Makefile для соответствия.

Это типичный вывод:

test.o: test.c test.h

test.h:

-MT target

Изменить цель правила, выводимого генерированием зависимостей. По умолчанию CPP берёт имя основного входного файла, удаляет все компоненты каталогов и любой суффикс файла, такой как ‘.c’, и добавляет обычный системный суффикс файла объекта. Результат — цель.

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

Например, -MT '$(objpfx)foo.o' может дать

$(objpfx)foo.o: foo.c

-MQ target

То же самое, что и -MT, но цитирует любые символы, которые являются специальными для Make. -MQ '$(objpfx)foo.o' даёт

$$(objpfx)foo.o: foo.c

Целевая цель автоматически приводится в кавычки, как если бы она была задана с -MQ.

-MD

-MD эквивалентно -M -MF file, за исключением того, что -E не подразумевается. Драйвер определяет file в зависимости от того, указана ли опция -o. Если она указана, драйвер использует её аргумент, но с суффиксом .d, в противном случае он берёт имя входного файла, удаляет все компоненты каталога и суффикс, и применяет суффикс .d.

Если -MD используется совместно с -E, любая опция -o понимается как указание файла вывода зависимостей (см. -MF), но если она используется без -E, каждая -o понимается как указание целевого файла объекта.

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

-MMD

Как -MD, за исключением того, что упоминаются только пользовательские файлы заголовков, а не системные файлы заголовков.

-fpreprocessed

Укажите препроцессору, что входной файл уже был предварительно обработан. Это подавляет такие операции, как расширение макросов, преобразование триграфов, объединение экранированных новых строк и обработку большинства директив. Препроцессор по-прежнему распознаёт и удаляет комментарии, так что вы можете передать файл, предварительно обработанный с помощью -C, компилятору без проблем. В этом режиме встроенный препроцессор — это в основном токенизатор для фронтендов.

-fpreprocessed неявный, если входной файл имеет один из расширений ‘.i’, ‘.ii’ или ‘.mi’. Это расширения, используемые GCC для файлов предварительно обработанных файлов, созданных с помощью -save-temps.

-fdirectives-only

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

Поведение опции зависит от опций -E и -fpreprocessed.

При -E предварительная обработка ограничена обработкой таких директив, как #define, #ifdef, и #error. Другие операции препроцессора, такие как расширение макросов и преобразование триграфов, не выполняются. Кроме того, опция -dD неявно включена.

При -fpreprocessed, предопределение макросов командной строки и большинства встроенных макросов отключено. Макросы, такие как __LINE__, которые контекстуально зависят, обрабатываются нормально. Это позволяет компилировать файлы, предварительно обработанные с помощью -E -fdirectives-only.

При использовании -E и -fpreprocessed, правила для -fpreprocessed имеют приоритет. Это позволяет полностью обработать файлы, предварительно обработанные с помощью -E -fdirectives-only.

-fdollars-in-identifiers

Принимать ‘$’ в идентификаторах.

-fextended-identifiers

Принимать универсальные имена символов и расширенные символы в идентификаторах. Эта опция включена по умолчанию для C99 (и более поздних версий стандарта C) и C++.

-fno-canonical-system-headers

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

-fmax-include-depth=depth

Установить максимальную глубину вложенных #include. По умолчанию 200.

-ftabstop=width

Установите расстояние между табуляцией. Это помогает препроцессору сообщать правильные номера столбцов в предупреждениях или ошибках, даже если табуляции появляются на строке. Если значение меньше 1 или больше 100, опция игнорируется. По умолчанию значение равно 8.

-ftrack-macro-expansion[=level]

Отслеживать расположение токенов при макроподстановках. Это позволяет компилятору выводить диагностику о текущей стеке макроподстановок, когда возникает ошибка компиляции в макроподстановке. Использование этой опции увеличивает потребление памяти препроцессором и компилятором. Параметр level может быть использован для выбора уровня точности отслеживания расположения токенов, тем самым уменьшая потребление памяти при необходимости. Значение ‘0’ параметра level деактивирует эту опцию. Значение ‘1’ отслеживает расположения токенов в режиме пониженной точности для минимизации нагрузки на память. В этом режиме все токены, полученные в результате расширения аргумента функции-макроса, имеют одинаковое расположение. Значение ‘2’ отслеживает расположения токенов полностью. Это значение наиболее ресурсоёмко. При отсутствии аргумента, значение параметра по умолчанию равно ‘2’.

Обратите внимание, что -ftrack-macro-expansion=2 активирована по умолчанию.

-fmacro-prefix-map=old=new

При предварительной обработке файлов, находящихся в директории old, расширять макросы __FILE__ и __BASE_FILE__ так, как будто файлы находятся в директории new. Это может быть использовано для изменения абсолютного пути на относительный, используя . для new, что может привести к более воспроизводимым сборкам, не зависящим от расположения. Эта опция также влияет на __builtin_FILE() во время компиляции. См. также -ffile-prefix-map.

-fexec-charset=charset

Установить кодировку символов выполнения, используемую для строковых и символьных констант. По умолчанию используется UTF-8. charset может быть любой кодировкой, поддерживаемой системной библиотекой iconv.

-fwide-exec-charset=charset

Установить расширенную кодировку символов выполнения, используемую для широких строковых и символьных констант. По умолчанию используется одна из UTF-32BE, UTF-32LE, UTF-16BE или UTF-16LE, которая соответствует ширине wchar_t и порядку байтов (big-endian или little-endian), используемому для генерации кода. Как и в случае с -fexec-charset, charset может быть любой кодировкой, поддерживаемой системной библиотекой iconv; однако, у вас могут возникнуть проблемы с кодировками, которые не точно помещаются в wchar_t.

-finput-charset=charset

Установить кодировку входных символов, используемую для перевода из кодировки входного файла в исходную кодировку, используемую GCC. Если в локали не указано или GCC не может получить эту информацию из локали, по умолчанию используется UTF-8. Это можно переопределить либо в локали, либо с помощью этой опции командной строки. В настоящее время опция командной строки имеет приоритет в случае конфликта. charset может быть любой кодировкой, поддерживаемой системной библиотекой iconv.

-fpch-deps

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

-fpch-preprocess

Эта опция позволяет использовать предварительно скомпилированный заголовок (см. Использование предварительно скомпилированных заголовков) вместе с -E. Она вставляет специальный #pragma, #pragma GCC pch_preprocess "filename" в вывод, чтобы отметить место, где был найден предварительно скомпилированный заголовок, и его имя файла filename. При использовании -fpreprocessed, GCC распознаёт этот #pragma и загружает PCH.

Эта опция выключена по умолчанию, так как полученный предварительно обработанный вывод подходит только как вход для GCC. Она включается с помощью -save-temps.

Вы не должны вписывать этот #pragma в свой код, но можете безопасно изменить имя файла, если файл PCH доступен в другом месте. Имя файла может быть абсолютным или относительным к текущей директории GCC.

-fworking-directory

Включить генерацию маркеров строк в выводе препроцессора, которые позволяют компилятору узнать текущую рабочую директорию во время предварительной обработки. При включении этой опции препроцессор выводит после начального маркера строки второй маркер со значением текущей рабочей директории, за которым следуют две косые черты. GCC использует эту директорию, когда она присутствует в предварительно обработанном вводе, как директорию, выводимую в качестве текущей рабочей директории в некоторых форматах отладки. Эта опция подразумевается включенной, если включена отладка, но это можно отключить с помощью противоположной опции -fno-working-directory. Если флаг -P присутствует в командной строке, эта опция не имеет эффекта, так как никакие директивы #line не выводятся.

-A predicate=answer

Выполнить утверждение с предикатом predicate и ответом answer. Эта форма предпочтительнее старой формы -A predicate(answer), которая всё ещё поддерживается, так как не использует специальные символы оболочки.

-A -predicate=answer

Отменить утверждение с предикатом predicate и ответом answer.

-C

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

Вы должны быть готовы к побочным эффектам при использовании -C; это заставляет препроцессор обрабатывать комментарии как токены сами по себе. Например, комментарии в начале строки, которая должна быть директивой, имеют эффект превращения этой строки в обычную строку исходного кода, так как первый токен в строке больше не является ‘#’.

-CC

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

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

Опция -CC обычно используется для поддержки комментариев lint.

-P

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

-traditional ¶

-traditional-cpp

Попытка имитировать поведение препроцессоров C до стандарта, в отличие от препроцессоров ISO C. Подробности смотрите в руководстве GNU CPP.

Обратите внимание, что GCC не пытается эмулировать компилятор C до стандарта, а эти опции поддерживаются только с переключателем -E или при явном вызове CPP.

-trigraphs

Поддержка триграфов ISO C. Это трехсимвольные последовательности, все начинающиеся с ‘??’, которые в ISO C определены для обозначения отдельных символов. Например, ‘??/’ обозначает ‘\’, поэтому ‘'??/n'’ — это символьная константа для новой строки.

Девять триграфов и их замены:

Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    {    }    #    \    ^    |    ~

По умолчанию GCC игнорирует триграфы, но в соответствии со стандартом их преобразует. См. опции -std и -ansi.

-remap

Включить специальный код для работы с файловыми системами, которые допускают только очень короткие имена файлов, например, MS-DOS.

-H

Вывести имя каждого заголовочного файла, используемого, помимо других обычных действий. Каждое имя отступается для отображения глубины вложенности ‘#include’. Файлы предварительно скомпилированных заголовков также выводятся, даже если они оказались недействительными; недействительный предварительно скомпилированный заголовок выводится с ‘...x’, а действительный — с ‘...!’.

-dletters

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

-dM

Вместо обычного вывода генерируется список директив ‘#define’ для всех макросов, определённых во время выполнения препроцессора, включая предопределённые макросы. Это даёт вам способ узнать, что предопределено в вашей версии препроцессора. Предполагая, что у вас нет файла foo.h, команда

touch foo.h; cpp -dM foo.h

показывает все предопределённые макросы.

Если вы используете -dM без опции -E, -dM интерпретируется как синоним -fdump-rtl-mach. См. (gcc)Параметры разработчика.

-dD

Подобно -dM, за исключением двух моментов: он не включает предопределённые макросы, и он выводит как директивы ‘#define’, так и результат препроцессирования. Оба вида вывода направляются в стандартный вывод.

-dN

Как -dD, но выводит только имена макросов, а не их расширения.

-dI

Выводит директивы ‘#include’ в дополнение к результату препроцессирования.

-dU

Подобно -dD, за исключением того, что выводятся только те макросы, которые расширяются или чьё определение проверяется в директивах препроцессора; вывод откладывается до использования или проверки макроса; и директивы ‘#undef’ также выводятся для макросов, проверенных, но неопределённых на данный момент.

-fdebug-cpp

Эта опция полезна только для отладки GCC. При использовании из CPP или с -E она выводит отладочную информацию о картах расположения. Каждый токен в выводе предваряется дампом карты, к которой принадлежит его расположение.

При использовании из GCC без -E эта опция не имеет эффекта.

-Wp,option

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

-Xpreprocessor option

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

Если вы хотите передать опцию, принимающую аргумент, вы должны использовать -Xpreprocessor дважды, один раз для опции и один раз для аргумента.

-no-integrated-cpp

Выполнить препроцессирование как отдельный этап перед компиляцией. По умолчанию GCC выполняет препроцессирование как интегрированную часть токенизации и анализа входных данных. Если эта опция задана, соответствующая языковая передняя часть (cc1, cc1plus, или cc1obj для C, C++ и Objective-C соответственно) вызывается дважды, один раз только для препроцессирования и один раз для фактической компиляции препроцессированного ввода. Эта опция может быть полезна в сочетании с опциями -B или -wrapper для указания альтернативного препроцессора или выполнения дополнительной обработки исходного кода программы между обычным препроцессированием и компиляцией.