3.14 Параметры управления препроцессором

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

Если использовать параметр -E, выполняется только препроцессирование. Некоторые из этих параметров имеют смысл только вместе с -E, поскольку они делают вывод препроцессора непригодным для непосредственной компиляции.

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

-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 (см. раздел Переменные окружения, влияющие на GCC). Отладочный вывод, как обычно, по-прежнему направляется в стандартный поток вывода.

Передача параметра -M драйверу подразумевает -E и подавляет предупреждения, как если бы был неявно задан параметр -w.

-MM

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

Это означает, что выбор угловых скобок или двойных кавычек в директиве «#include» сам по себе не определяет, будет ли этот заголовок указан в выводе зависимостей -MM.

-MF file

При использовании с -M или -MM задаёт файл, в который следует записать зависимости. Если параметр -MF не указан, препроцессор выводит правила туда же, куда и предварительно обработанный текст.

При использовании с параметрами драйвера -MD или -MMD параметр -MF переопределяет файл вывода зависимостей по умолчанию.

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

-MG

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

Эта возможность используется для автоматического обновления make-файлов.

-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.

-fsearch-include-path[=kind]

Искать входные файлы по пути поиска #include, а не только в текущем каталоге. Это особенно полезно для модулей C++20, для которых непосредственно компилируются как единицы заголовков, так и единицы интерфейсов модулей:

g++ -c -std=c++20 -fmodules -fsearch-include-path bits/stdc++.h bits/std.cc

По умолчанию kind имеет значение «user», при котором используется путь поиска #include "…"; также можно явно указать «system» для пути поиска #include <…>.

-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 и -fcanon-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.

-fpch-deps

При использовании предварительно скомпилированных заголовков (см. раздел Использование предварительно скомпилированных заголовков) этот флаг заставляет параметры вывода зависимостей также перечислять файлы, от которых зависит предварительно скомпилированный заголовок. Если флаг не указан, перечисляется только сам предварительно скомпилированный заголовок, но не файлы, использованные для его создания, поскольку при использовании предварительно скомпилированного заголовка к этим файлам не обращаются.

-fpch-preprocess

Этот параметр позволяет использовать предварительно скомпилированный заголовок (см. раздел Использование предварительно скомпилированных заголовков) вместе с -E. В вывод вставляется специальная #pragma, #pragma GCC pch_preprocess "filename", отмечающая место, где был найден предварительно скомпилированный заголовок, и его filename. При использовании -fpreprocessed GCC распознаёт эту #pragma и загружает PCH.

По умолчанию этот параметр отключён, поскольку полученный предварительно обработанный вывод фактически подходит только в качестве входных данных для GCC. Его включает параметр -save-temps.

Не следует записывать эту #pragma в собственном коде, но имя файла можно безопасно изменить, если PCH-файл находится в другом месте. Имя файла может быть абсолютным или относительным к текущему каталогу GCC.

-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. Подробности см. в руководстве GNU CPP.

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

-trigraphs

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

Девять триграфов и соответствующие им символы:

Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    {    }    #    \    ^    |    ~

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

-remap

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

-H

В дополнение к обычным действиям выводить имя каждого используемого заголовочного файла. Отступ перед каждым именем показывает глубину его вложенности в стеке «#include». Также выводятся предварительно скомпилированные заголовочные файлы, даже если они оказались недействительными: недействительный предварительно скомпилированный заголовочный файл помечается «...x», а действительный — «...!».

-dletters

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

-dM

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

touch foo.h; cpp -dM foo.h

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

Если использовать -dM без параметра -E, -dM трактуется как синоним -fdump-rtl-mach. См. раздел (gcc)Параметры разработчика.

-dD

Работает как -dM, но выводит и директивы «#define», и результат препроцессирования. Оба вида вывода направляются в стандартный файл вывода.

-dN

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

-dI

Помимо результата препроцессирования выводить директивы «#include».

-dU

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

-fdebug-cpp

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

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

-Wp,option

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

-Xpreprocessor option

Передать option препроцессору в качестве параметра. Так можно указать системные параметры препроцессора, которые GCC не распознаёт.

Чтобы передать параметр, которому требуется аргумент, необходимо дважды использовать -Xpreprocessor: один раз для параметра и один раз для аргумента.

-no-integrated-cpp

Выполнять препроцессирование отдельным этапом перед компиляцией. По умолчанию GCC выполняет препроцессирование как интегрированную часть токенизации и синтаксического анализа входных данных. Если указан этот параметр, соответствующий языковой интерфейс (cc1, cc1plus или cc1obj для C, C++ и Objective-C соответственно) запускается дважды: сначала только для препроцессирования, а затем для фактической компиляции предварительно обработанных входных данных. Этот параметр может быть полезен в сочетании с параметрами -B или -wrapper для указания альтернативного препроцессора или выполнения дополнительной обработки исходного кода между обычным препроцессированием и компиляцией.