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

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