12 Вызов

Чаще всего при использовании препроцессора C вам не нужно вызывать его явно: компилятор C делает это автоматически. Однако препроцессор иногда бывает полезен сам по себе. Вы можете вызвать препроцессор либо с помощью команды cpp, либо через gcc -E. В GCC препроцессор фактически интегрирован в компилятор, а не является отдельной программой, и обе эти команды вызывают GCC и говорят ему остановиться после фазы предварительной обработки.

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

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

Команда cpp ожидает два имени файлов в качестве аргументов, infile и outfile. Препроцессор считывает infile вместе с любыми другими файлами, которые он указывает с помощью ‘#include’. Весь вывод, сгенерированный объединенными входными файлами, записывается в outfile.

Файл infile или outfile может быть -, что, как infile, означает чтение из стандартного ввода, а как outfile означает запись в стандартный вывод. Если любой файл опущен, это означает то же самое, что если для этого файла был указан -. Вы также можете использовать параметр -o outfile для указания выходного файла.

Если не указано иное, или параметр заканчивается на ‘=’, все параметры, которые принимают аргумент, могут иметь этот аргумент, появляющийся либо непосредственно после параметра, либо с пробелом между параметром и аргументом: -Ifoo и -I foo имеют одинаковый эффект.

Многие параметры имеют многобуквенные имена; поэтому несколько однобуквенных параметров не могут быть объединены: -dM сильно отличается от ‘-d -M’.

-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 (см. Переменные среды). Вывод отладки все равно направляется в обычный поток вывода.

Передача -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.

-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. См. Традиционный режим.

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

-trigraphs

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

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

-remap

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

-H

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

-dletters

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

-dM

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

touch foo.h; cpp -dM foo.h

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

-dD

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

-dN

Подобно -dD, но выводит только имена макросов, а не их развёртывания.

-dI

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

-dU

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

-fdebug-cpp

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

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

-I dir

-iquote dir

-isystem dir

-idirafter dir

Добавить директорию dir в список директорий, которые будут проверяться на наличие заголовочных файлов во время предварительной обработки. См. Путь поиска. Если dir начинается с ‘=’ или $SYSROOT, то ‘=’ или $SYSROOT заменяются префиксом sysroot; см. --sysroot и -isysroot.

Директории, указанные с помощью -iquote, применяются только к форме директивы в кавычках, #include "file". Директории, указанные с помощью -I, -isystem или -idirafter, применяются к поиску как для директивы в кавычках, так и для #include "file" и #include <file> директив.

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

1. Для формы директивы include в кавычках, сначала проверяется директория текущего файла.
2. Для формы директивы include в кавычках, директории, указанные с помощью опций -iquote, проверяются слева направо в порядке их появления в командной строке.
3. Директории, указанные с помощью опций -I, сканируются слева направо.
4. Директории, указанные с помощью опций -isystem, сканируются слева направо.
5. Сканируются стандартные системные директории.
6. Директории, указанные с помощью опций -idirafter, сканируются слева направо.

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

Опции -isystem и -idirafter также помечают директорию как системную, чтобы она получала такое же специальное лечение, что и стандартные системные директории. См. Системные заголовки.

Если стандартная системная директория include или директория, указанная с помощью -isystem, также указана с помощью -I, опция -I игнорируется. Директория всё ещё проверяется, но как системная директория в её нормальном положении в цепочке системных include. Это делается для того, чтобы процедура GCC по исправлению ошибочных системных заголовков и порядок директивы #include_next не были непреднамеренно изменены. Если вам действительно нужно изменить порядок поиска системных директорий, используйте опции -nostdinc и/или -isystem. См. Системные заголовки.

-I-

Разделить путь include. Эта опция устарела. Пожалуйста, используйте -iquote вместо -I директорий перед -I- и удалите опцию -I-.

Любые директории, указанные с помощью опций -I перед -I-, проверяются только на наличие заголовков, запрошенных с #include "file"; они не проверяются на наличие #include <file>. Если дополнительные директории указаны с помощью опций -I после -I-, эти директории проверяются на все директивы ‘#include’.

Кроме того, -I- запрещает использование директории текущего файла в качестве первой директории поиска для #include "file". Нет способа переопределить это действие -I-. См. Путь поиска.

-iprefix prefix

Укажите prefix в качестве префикса для последующих опций -iwithprefix. Если префикс представляет директорию, вы должны включить конечный ‘/’.

-iwithprefix dir

-iwithprefixbefore dir

Добавить dir к префиксу, указанному ранее с помощью -iprefix, и добавить полученную директорию в путь поиска include. -iwithprefixbefore помещает её в то же место, что и -I; -iwithprefix помещает её туда, где находилась бы -idirafter.

-isysroot dir

Эта опция похожа на опцию --sysroot, но применяется только к заголовочным файлам (кроме целей Darwin, где она применяется как к заголовочным файлам, так и к библиотекам). См. опцию --sysroot для получения дополнительной информации.

-imultilib dir

Использовать dir как поддиректорию директории, содержащей специфичные для цели заголовочные файлы C++.

-nostdinc

Не искать стандартные системные директории заголовочных файлов. Проверяются только директории, явно указанные с помощью опций -I, -iquote, -isystem и/или -idirafter (и директория текущего файла, если это необходимо).

-nostdinc++

Не искать заголовочные файлы в стандартных директориях, специфичных для C++, но всё ещё искать в других стандартных директориях. (Эта опция используется при построении библиотеки C++).

-Wcomment

-Wcomments

Выдавать предупреждение всякий раз, когда последовательность начала комментария ‘/*’ появляется в комментарии ‘/*’, или всякий раз, когда обратный слэш-новая строка появляется в комментарии ‘//’. Это предупреждение включается с помощью -Wall.

-Wtrigraphs

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

Эта опция подразумевается опцией -Wall. Если -Wall не задана, эта опция всё ещё включена, если триграммы не включены. Чтобы получить преобразование триграмм без предупреждений, но получить остальные предупреждения -Wall, используйте ‘-trigraphs -Wall -Wno-trigraphs’.

-Wundef

Выдавать предупреждение, если неопределённый идентификатор оценивается в директиве #if. Такие идентификаторы заменяются нулём.

-Wexpansion-to-defined

Выдавать предупреждение всякий раз, когда встречается ‘defined’ в расширении макроса (включая случай, когда макрос расширяется директивой ‘#if’). Такое использование не является переносимым. Это предупреждение также включено с помощью -Wpedantic и -Wextra.

-Wunused-macros

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

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

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

#if defined the_macro_causing_the_warning
#endif

-Wno-endif-labels

Не выдавать предупреждение всякий раз, когда #else или #endif следуют за текстом. Это иногда случается в старых программах с кодом в форме

#if FOO
…
#else FOO
…
#endif FOO

Вторая и третья FOO должны быть в комментариях. Это предупреждение включено по умолчанию.