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

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

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

-I-

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