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

Предопределить имя как макрос с определением 1.

-D name=definition

Содержимое определения токенизируется и обрабатывается так, как если бы оно появилось во время фазы обработки трансляции три в директиве «#define». В частности, определение усекается встроенными символами новой строки.

Если вы вызываете препроцессор из оболочки или подобной ей программы, вам может потребоваться использовать синтаксис цитирования оболочки для защиты символов, таких как пробелы, которые имеют значение в синтаксисе оболочки.

Если вы хотите определить макрос, похожий на функцию, в командной строке, запишите его список аргументов в круглых скобках перед знаком равенства (если таковой имеется). Скобки имеют значение для большинства оболочек, поэтому вы должны привести опцию в кавычки. С sh и csh, -D'имя(аргументы…)=определение' работает.

Опции -D и -U обрабатываются в порядке их указания в командной строке. Все опции -imacros файл и -include файл обрабатываются после всех опций -D и -U.

-U name

Отменить любое предыдущее определение имя, встроенное или предоставленное с опцией -D.

-include file

Обработать файл так, как если бы #include "file" появилось в качестве первой строки исходного файла. Однако первой директорией, в которой будет искаться файл, является рабочая директория препроцессора вместо директории, содержащей основной исходный файл. Если файл не найден там, он будет искаться в остальной части #include "…" цепочки поиска в обычном режиме.

Если задано несколько опций -include, файлы включаются в порядке их появления в командной строке.

-imacros file

Точно так же, как -include, за исключением того, что любой вывод, созданный при сканировании файл, отбрасывается. Макросы, которые он определяет, остаются определенными. Это позволяет вам получить все макросы из заголовка без обработки его объявлений.

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

Если файл равен -, то зависимости записываются в stdout.

-MG

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

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

-Mno-modules

Отключить создание зависимостей для интерфейсов скомпилированных модулей.

-MP

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

Это типичный вывод:

test.o: test.c test.h

test.h:

-MT target

Изменить цель правила, генерируемого при создании зависимостей. По умолчанию CPP берёт имя основного входного файла, удаляет все компоненты директорий и любые суффиксы файлов, такие как ‘.c’, и добавляет обычный системный суффикс файла объекта. Результат — это цель.

Опция -MT устанавливает цель в точное значение, которое вы указываете. Если вам нужны несколько целей, вы можете указать их как один аргумент в -MT или использовать несколько опций -MT.

Например, -MT '$(objpfx)foo.o' может дать

$(objpfx)foo.o: foo.c

-MQ target

То же, что и -MT, но цитирует любые символы, которые являются специальными для Make. -MQ '$(objpfx)foo.o' даёт

$$(objpfx)foo.o: foo.c

Целью по умолчанию автоматически добавляются кавычки, как если бы она была задана с помощью -MQ.

-MD

-MD эквивалентно -M -MF файл, за исключением того, что -E не подразумевается. Драйвер определяет файл в зависимости от того, указана ли опция -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.

-fexec-charset=charset

Установить исполняемый набор символов, используемый для строковых и символьных констант. По умолчанию UTF-8. charset может быть любым кодированием, поддерживаемым системной библиотекой iconv.

-fwide-exec-charset=charset

Установить расширенный исполняемый набор символов, используемый для широких строковых и символьных констант. По умолчанию — один из наборов UTF-32BE, UTF-32LE, UTF-16BE или UTF-16LE, соответствующий ширине 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. Для формы включения с кавычками сначала ищется директория текущего файла.
2. Для формы включения с кавычками директории, указанные опциями -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 должны быть в комментариях. Это предупреждение включено по умолчанию.