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

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

-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 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-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), которая всё ещё поддерживается, потому что она не использует специальные символы оболочки. См. Obsolete Features.

-A -predicate=answer

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

-C

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

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

-CC

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

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

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

-P

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

-traditional

-traditional-cpp

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

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

-trigraphs

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

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

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