3.13 Параметры управления препроцессором

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

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

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

-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 threads. Вы должны использовать эту опцию последовательно как для компиляции, так и для компоновки. Эта опция поддерживается на целевых платформах 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 и -fcanon-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 может обработать, прежде чем он перестанет отслеживать столбцы.