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

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

-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 и используемому для генерации кода порядку байтов — big-endian или little-endian. Как и с -fexec-charset, charset может быть любым кодированием, поддерживаемым системной библиотекой iconv ; однако у вас могут возникнуть проблемы с кодировками, которые не точно помещаются в wchar_t.

-finput-charset=charset

Установить входной набор символов, используемый для перевода из набора символов входного файла в набор символов источника, используемый GCC. Если в локали это не указано или GCC не может получить эту информацию из локали, по умолчанию используется UTF-8. Это можно переопределить либо с помощью локали, либо с помощью этого параметра командной строки. В настоящее время параметр командной строки имеет приоритет при конфликте. charset может быть любым кодированием, поддерживаемым системной библиотекой iconv.

-fworking-directory

Включить генерацию маркеров строк в выводе препроцессора, которые позволяют компилятору узнать текущий рабочий каталог на момент предварительной обработки. Когда этот параметр включён, препроцессор выводит после начального маркера строки второй маркер со текущим рабочим каталогом, после которого следуют две косые черты. GCC использует этот каталог, если он присутствует в входных данных предварительной обработки, как каталог, выведенный в качестве текущего рабочего каталога в некоторых форматах отладочной информации. Этот параметр неявно включён, если включена отладочная информация, но это можно отключить с помощью обратного параметра -fno-working-directory. Если в командной строке присутствует флаг -P, этот параметр не имеет эффекта, так как никакие директивы #line не выводятся вообще.

-A predicate=answer

Сделать утверждение с предикатом predicate и ответом answer. Эта форма предпочтительнее более старой формы -A predicate(answer), которая всё ещё поддерживается, потому что не использует специальные символы оболочки. См. Устаревшие функции.

-A -predicate=answer

Отменить утверждение с предикатом predicate и ответом answer.

-C

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

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

-CC

Не отбрасывать комментарии, включая при расширении макросов. Это похоже на -C, за исключением того, что комментарии, содержащиеся в макросах, также передаются в выходной файл, где расширяется макрос.

В дополнение к побочным эффектам параметра -C, параметр -CC заставляет все комментарии стиля C++ внутри макроса преобразовываться в комментарии стиля C. Это делается для предотвращения случайного комментирования остальной части строки кода при последующем использовании этого макроса.

Параметр -CC обычно используется для поддержки комментариев lint.

-P

Запретить генерацию маркеров строк в выводе препроцессора. Это может быть полезно при работе препроцессора с чем-то, что не является кодом C, и будет отправлено программе, которая может быть сбита с толку маркерами строк. См. Вывод препроцессора.

-traditional ¶

-traditional-cpp

Попытаться имитировать поведение препроцессоров C до стандарта, в отличие от препроцессоров ISO C. См. Традиционный режим.

Обратите внимание, что GCC иначе не пытается эмулировать компилятор C до стандарта, и эти параметры поддерживаются только с переключателем -E или при явном вызове CPP.

-trigraphs

Поддержка триграфов ISO C. Это трехсимвольные последовательности, все начинающиеся с ‘??’, которые по стандарту ISO C определены как отдельные символы. Например, ‘??/’ обозначает ‘\’, поэтому ‘'??/n'’ — это символьная константа для новой строки. См. Первичная обработка.

По умолчанию GCC игнорирует триграфы, но в соответствии со стандартом их преобразует. См. параметры -std и -ansi.

-remap

Включить специальный код для работы с файловыми системами, допускающими только очень короткие имена файлов, такие как MS-DOS.

-H

Выводит имя каждого используемого заголовочного файла, помимо других обычных действий. Каждое имя отступается, чтобы показать, насколько глубоко оно находится в стеке ‘#include’. Также выводятся прекомпилированные заголовочные файлы, даже если они оказались недействительными; недействительный прекомпилированный заголовочный файл выводится со значением ‘...x’, а действительный — со значением ‘...!’.

-dletters

Выполняет отладочные дампы во время компиляции, как указано в letters. Флаги, документированные здесь, относятся к препроцессору. Другие значения letters интерпретируются самим компилятором или зарезервированы для будущих версий GCC и, следовательно, игнорируются. Если вы укажете letters, поведение которых конфликтует, результат не определён.

-dM

Вместо обычного вывода генерирует список директив ‘#define’ для всех макросов, определённых во время работы препроцессора, включая предопределённые макросы. Это даёт вам возможность узнать, что предопределено в вашей версии препроцессора. Предполагая, что у вас нет файла foo.h, команда

touch foo.h; cpp -dM foo.h

показывает все предопределённые макросы.

-dD

Как -dM, но в двух отношениях: он не включает предопределённые макросы и выводит как директивы ‘#define’, так и результат предварительной обработки. Оба вида вывода отправляются в стандартный выходной файл.

-dN

Как -dD, но выводит только имена макросов, а не их расширения.

-dI

Выводит директивы ‘#include’ в дополнение к результату предварительной обработки.

-dU

Как -dD, за исключением того, что выводятся только макросы, которые расширяются или чьё определение проверяется в директивах препроцессора; вывод откладывается до использования или проверки макроса; и директивы ‘#undef’ также выводятся для макросов, которые проверялись, но не были определены на момент времени.

-fdebug-cpp

Этот параметр полезен только для отладки GCC. При использовании из CPP или с -E он выводит отладочную информацию о картах расположения. Каждый токен в выводе предваряется выводом карты, к которой принадлежит его расположение.

При использовании из GCC без -E этот параметр не имеет эффекта.

-I dir

-iquote dir

-isystem dir

-idirafter dir

Добавить директорию dir в список директорий, которые будут просматриваться при поиске заголовочных файлов во время предварительной обработки. См. Путь поиска. Если dir начинается с ‘=’ или $SYSROOT, тогда ‘=’ или $SYSROOT заменяется префиксом sysroot; см. --sysroot и -isysroot.

Директории, указанные с помощью -iquote, применяются только к форме директивы с кавычками, #include "file". Директории, указанные с помощью -I, -isystem или -idirafter, применяются к поиску для обеих директивы #include "file" и #include <file>.

Вы можете указать любое количество или комбинацию этих параметров в командной строке для поиска заголовочных файлов в нескольких директориях. Порядок поиска следующий:

1. Сначала ищется директория текущего файла для формы директивы include с кавычками.
2. Для формы директивы include с кавычками, директории, указанные с помощью -iquote параметров, ищутся слева направо в том порядке, в котором они появляются в командной строке.
3. Директории, указанные с помощью -I параметров, сканируются слева направо.
4. Директории, указанные с помощью -isystem параметров, сканируются слева направо.
5. Сканируются стандартные системные директории.
6. Директории, указанные с помощью -idirafter параметров, сканируются слева направо.

Вы можете использовать -I для переопределения системного заголовочного файла, заменив его своей собственной версией, поскольку эти директории просматриваются перед стандартными системными директориями заголовочных файлов. Однако вы не должны использовать этот параметр для добавления директорий, содержащих системные заголовочные файлы, предоставляемые поставщиком; используйте -isystem для этого.

Параметры -isystem и -idirafter также отмечают директорию как системную директорию, чтобы она получила такое же специальное обращение, которое применяется к стандартным системным директориям. См. Системные заголовки.

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

-I-

Разделить путь включения. Этот параметр устарел. Пожалуйста, используйте -iquote вместо -I директорий перед -I- и удалите параметр -I-.

Любые директории, указанные с помощью -I параметров перед -I-, ищутся только для заголовков, запрошенных с #include "file"; они не ищутся для #include <file>. Если дополнительные директории указаны с помощью -I параметров после -I-, эти директории просматриваются для всех директивы ‘#include’.

Кроме того, -I- запрещает использование директории текущего файла в качестве первой директории поиска для #include "file". Нет способа переопределить это действие -I-. См. Путь поиска.

-iprefix prefix

Указать prefix в качестве префикса для последующих параметров -iwithprefix. Если префикс представляет собой директорию, вы должны включить конечный ‘/’.

-iwithprefix dir

-iwithprefixbefore dir

Добавить dir к префиксу, указанному ранее с помощью -iprefix, и добавить полученную директорию в путь поиска включений. -iwithprefixbefore помещает его в то же место, где был бы -I; -iwithprefix помещает его туда, где был бы -idirafter.

-isysroot dir

Этот параметр похож на параметр --sysroot, но применяется только к заголовочным файлам (за исключением целей Darwin, где он применяется как к заголовочным файлам, так и к библиотекам). См. параметр --sysroot для получения дополнительной информации.

-imultilib dir

Использовать dir в качестве подкаталога каталога, содержащего целевые C++ заголовочные файлы.

-nostdinc

Не искать стандартные системные директории для заголовочных файлов. Просматриваются только директории, явно указанные с помощью параметров -I, -iquote, -isystem и/или -idirafter (и директория текущего файла, если это уместно).

-nostdinc++

Не искать заголовочные файлы в стандартных директориях, специфичных для C++, но все еще искать другие стандартные директории. (Этот параметр используется при построении библиотеки C++).

-Wcomment

-Wcomments

Выводить предупреждение всякий раз, когда последовательность начала комментария ‘/*’ появляется в комментарии ‘/*’ или когда обратный слеш с новой строкой появляется в комментарии ‘//’. Это предупреждение включено параметром -Wall.

-Wtrigraphs

Выводить предупреждение, если встречаются какие-либо триграфы, которые могут изменить смысл программы. Предупреждения о триграфах внутри комментариев не выводятся, за исключением тех, которые сформируют экранированные новые строки.

Этот параметр подразумевается параметром -Wall. Если -Wall не указан, этот параметр все равно включён, если триграфы не включены. Чтобы получить преобразование триграфов без предупреждений, но получить другие предупреждения -Wall, используйте ‘-trigraphs -Wall -Wno-trigraphs’.

-Wundef

Выводить предупреждение, если неопределённый идентификатор оценивается в директиве #if. Такие идентификаторы заменяются нулём.

-Wexpansion-to-defined

Выводить предупреждение всякий раз, когда встречается ‘defined’ при развёртывании макроса (включая случай, когда макрос развёртывается директивой ‘#if’). Такое использование не переносимо. Это предупреждение также включено параметрами -Wpedantic и -Wextra.

-Wunused-macros

Выводить предупреждение о макросах, определённых в основном файле, которые не используются. Макрос используется, если он развёртывается или проверяется на существование хотя бы один раз. Препроцессор также выводит предупреждение, если макрос не использовался во время его повторного определения или отмены определения.

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

Примечание: Если макрос фактически используется, но только в пропущенных условных блоках, то препроцессор сообщает о нём как об неупотребимом. Чтобы избежать предупреждения в таком случае, вы можете улучшить область определения макроса, например, переместив его в первый пропущенный блок. В качестве альтернативы, вы можете предоставить фиктивное использование с помощью чего-то вроде:

#if defined the_macro_causing_the_warning
#endif

-Wno-endif-labels

Не выводить предупреждение всякий раз, когда #else или #endif следуют за текстом. Иногда это происходит в старых программах с кодом вида

#if FOO
…
#else FOO
…
#endif FOO

Вторая и третья FOO должны быть в комментариях. Это предупреждение включено по умолчанию.