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.

-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

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

-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-32 или UTF-16, что соответствует ширине wchar_t. Как и в случае с -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 игнорируется. Директория по-прежнему просматривается, но как системная директория в её нормальном положении в цепочке системных 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 должны быть в комментариях. Это предупреждение включено по умолчанию.

Далее: Переменные окружения, Предыдущее: Детали реализации, Наверх: Главная [Оглавление][Индекс]