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 переопределяет файл вывода зависимостей по умолчанию.

-MG

В сочетании с такой опцией, как -M, запрашивающей генерацию зависимостей, -MG предполагает, что отсутствующие файлы заголовков являются сгенерированными файлами и добавляет их в список зависимостей без повышения ошибки. Имя файла зависимости берется непосредственно из директивы #include без добавления пути. -MG также подавляет вывод предварительной обработки, так как отсутствующий файл заголовка делает его бесполезным.

Эта функция используется в автоматическом обновлении makefile.

-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 активировано по умолчанию.

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

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