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.

-Mno-modules

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

-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 для указания альтернативного препроцессора или выполнения дополнительной обработки исходного кода между обычной предварительной обработкой и компиляцией.

-flarge-source-files

Настраивает GCC для работы с большими исходными файлами за счёт более медленной компиляции и большего использования памяти.

В частности, GCC обычно отслеживает номера столбцов и строк в исходных файлах, и обычно выводит оба этих номера в диагностических сообщениях. Однако после обработки определённого количества строк исходного кода он перестаёт отслеживать номера столбцов и отслеживает только номера строк. Это означает, что диагностические сообщения для последующих строк не включают номера столбцов. Это также означает, что такие параметры, как -Wmisleading-indentation, перестают работать в этот момент, хотя компилятор выводит сообщение, если это происходит. Передача -flarge-source-files значительно увеличивает количество строк исходного кода, которые GCC может обработать, прежде чем перестанет отслеживать столбцы.