3.7 Параметры управления форматированием сообщений об ошибках ¶

Традиционно сообщения об ошибках форматировались независимо от характеристик устройства вывода (например, его ширины). Вы можете использовать описанные ниже параметры для управления алгоритмом форматирования сообщений об ошибках, например, количеством символов в строке, частотой отображения информации о расположении источника. Обратите внимание, что некоторые передние части языка могут не учитывать эти параметры.

-fmessage-length=n

Попробуйте отформатировать сообщения об ошибках так, чтобы они помещались на строках примерно из n символов. Если n равно нулю, то перенос строк не выполняется; каждое сообщение об ошибке отображается на одной строке. Это значение по умолчанию для всех front-end.

Примечание - этот параметр также влияет на отображение директив препроцессора «#error» и «#warning», а также атрибута функции/типа/переменной «deprecated». Однако он не влияет на прагмы «pragma GCC warning» и «pragma GCC error».

-fdiagnostics-plain-output

Этот параметр запрашивает, чтобы вывод диагностики выглядел как можно более простым, что может быть полезно при запуске dejagnu или других утилит, которым нужно анализировать вывод диагностики и предпочитать его более стабильным со временем. -fdiagnostics-plain-output в настоящее время эквивалентен следующим параметрам:

-fno-diagnostics-show-caret 
-fno-diagnostics-show-line-numbers 
-fdiagnostics-color=never 
-fdiagnostics-urls=never 
-fdiagnostics-path-format=separate-events

В будущем, если GCC изменит стандартный вид своих диагностических сообщений, соответствующий параметр для отключения нового поведения будет добавлен в этот список.

-fdiagnostics-show-location=once

Значимо только в режиме переноса строк. Указывает репортеру сообщений диагностики выводить информацию о местоположении исходного кода один раз; то есть, если сообщение слишком длинное, чтобы поместиться на одной физической строке, и его необходимо переносить, информация о местоположении исходного кода (как префикс) не будет выводиться повторно на последующих строках продолжения. Это поведение по умолчанию.

-fdiagnostics-show-location=every-line

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

-fdiagnostics-color[=WHEN]

-fno-diagnostics-color

Использовать цвет в диагностике. WHEN может быть ‘never’, ‘always’ или ‘auto’. Значение по умолчанию зависит от того, как был настроен компилятор, может быть любым из вышеперечисленных вариантов WHEN, а также ‘never’, если переменная среды GCC_COLORS отсутствует в среде, и ‘auto’ в противном случае. ‘auto’ заставляет GCC использовать цвет только тогда, когда стандартный вывод ошибки является терминалом и когда выполнение не происходит в оболочке emacs. Формы -fdiagnostics-color и -fno-diagnostics-color являются псевдонимами для -fdiagnostics-color=always и -fdiagnostics-color=never соответственно.

Цвета определяются переменной среды GCC_COLORS. Ее значение представляет собой список, разделенный двоеточиями, возможностей и подстрок Select Graphic Rendition (SGR). Команды SGR интерпретируются терминалом или эмулятором терминала. (См. раздел в документации вашего текстового терминала для разрешенных значений и их значений в качестве атрибутов символов.) Эти значения подстрок являются целыми числами в десятичном представлении и могут быть объединены с точками с запятой. Общие значения для объединения включают ‘1’ для полужирного, ‘4’ для подчеркивания, ‘5’ для мигания, ‘7’ для инверсии, ‘39’ для стандартного цвета фона, ‘30’ до ‘37’ для цветов фона, ‘90’ до ‘97’ для цветов фона в 16-цветном режиме, ‘38;5;0’ до ‘38;5;255’ для цветов фона в режимах 88-цветного и 256-цветного, ‘49’ для стандартного цвета фона, ‘40’ до ‘47’ для цветов фона, ‘100’ до ‘107’ для цветов фона в 16-цветном режиме и ‘48;5;0’ до ‘48;5;255’ для цветов фона в режимах 88-цветного и 256-цветного.

Значение по умолчанию GCC_COLORS

error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\
diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
type-diff=01;32

где ‘01;31’ — полужирный красный, ‘01;35’ — полужирный пурпурный, ‘01;36’ — полужирный сине-зеленый, ‘32’ — зеленый, ‘34’ — синий, ‘01’ — полужирный, а ‘31’ — красный. Установка GCC_COLORS в пустую строку отключает цвета. Поддерживаемые возможности следующие.

error=

Подстрока SGR для маркеров ошибки.

warning=

Подстрока SGR для маркеров предупреждения.

note=

Подстрока SGR для маркеров замечаний.

path=

Подстрока SGR для раскрашивания путей событий потока управления, как печатается с помощью -fdiagnostics-path-format=, например, идентификаторы отдельных событий и строки, указывающие межпроцедурные вызовы и возвраты.

range1=

Подстрока SGR для первого дополнительного диапазона.

range2=

Подстрока SGR для второго дополнительного диапазона.

locus=

Подстрока SGR для информации о местоположении, ‘file:line’ или ‘file:line:column’ и т. д.

quote=

Подстрока SGR для информации, напечатанной в кавычках.

fixit-insert=

Подстрока SGR для подсказок исправления, предлагающих текст для вставки или замены.

fixit-delete=

Подстрока SGR для подсказок исправления, предлагающих текст для удаления.

diff-filename=

Подстрока SGR для заголовков имен файлов в сгенерированных патчах.

diff-hunk=

Подстрока SGR для начала фрагментов в сгенерированных патчах.

diff-delete=

Подстрока SGR для удаленных строк в сгенерированных патчах.

diff-insert=

Подстрока SGR для вставленных строк в сгенерированных патчах.

type-diff=

Подстрока SGR для выделения несоответствующих типов в шаблонах аргументов в C++ front-end.

-fdiagnostics-urls[=WHEN]

Использовать последовательности escape для вставки URL-адресов в диагностику. Например, когда -fdiagnostics-show-option выводит текст, показывающий командную строку, управляющую диагностикой, вставить URL-адрес для документации этого параметра.

WHEN может быть ‘never’, ‘always’ или ‘auto’. ‘auto’ заставляет GCC использовать последовательности escape для URL-адресов только тогда, когда стандартный вывод ошибки является терминалом и когда выполнение не происходит в оболочке emacs или любом графическом терминале, который известен как несовместимый с этой функцией, см. ниже.

Значение по умолчанию зависит от того, как был настроен компилятор. Может быть любым из вышеперечисленных вариантов WHEN.

GCC также можно настроить (через параметр конфигурации --with-diagnostics-urls=auto-if-env) таким образом, чтобы значение по умолчанию зависело от переменных среды. В такой конфигурации GCC по умолчанию использует ‘auto’, если переменные среды GCC_URLS или TERM_URLS присутствуют и не пусты в среде компилятора, или ‘never’, если ни одна из них не присутствует.

Однако даже с -fdiagnostics-urls=always поведение зависит от этих переменных среды: если GCC_URLS установлено в пустую строку или ‘no’, URL-адреса в диагностике не вставляются. Если установлено ‘st’, URL-адреса используют последовательности escape ST. Если установлено ‘bel’, по умолчанию, URL-адреса используют последовательности escape BEL. Любое другое ненулевое значение включает функцию. Если GCC_URLS не установлено, используется TERM_URLS в качестве резервного варианта. Примечание: ST — это последовательность ANSI escape, терминатор строки ‘ESC \’, BEL — это символ ASCII, CTRL-G, который обычно звучит как звуковой сигнал.

В настоящее время GCC пытается определить также несколько терминалов, которые, как известно, не реализуют функцию URL и имеют ошибки или, по крайней мере, имели ошибки в некоторых версиях, которые все еще используются, где escape-последовательности URL, вероятно, будут работать неправильно, т. е. будут печатать мусор на экране. В настоящее время этот список включает xfce4-terminal, некоторые известные ошибочные версии gnome-terminal, консоль Linux и mingw. Этот проверку можно пропустить с помощью -fdiagnostics-urls=always.

-fno-diagnostics-show-option

По умолчанию каждое выводимое диагностическое сообщение включает текст, указывающий параметр командной строки, который непосредственно управляет диагностикой (если такая опция известна механизму диагностики). Указание флага -fno-diagnostics-show-option подавляет это поведение.

-fno-diagnostics-show-caret

По умолчанию каждое выводимое диагностическое сообщение включает исходную строку и символ «^», указывающий столбец. Этот параметр подавляет эту информацию. Строка исходного кода усекается до n символов, если задан параметр -fmessage-length=n. При выводе на терминал ширина ограничена шириной, заданной переменной среды COLUMNS, или, если она не задана, шириной терминала.

-fno-diagnostics-show-labels

По умолчанию при выводе исходного кода (через -fdiagnostics-show-caret) диагностика может помечать диапазоны исходного кода соответствующей информацией, такой как типы выражений:

printf ("foo %s bar", long_i + long_j);
             ~^       ~~~~~~~~~~~~~~~
              |              |
              char *         long int

Этот параметр подавляет вывод этих меток (на примере выше, вертикальные черты и текст «char *» и «long int»).

-fno-diagnostics-show-cwe

Сообщения об ошибках могут иметь связанный идентификатор CWE. Сам GCC предоставляет такую ​​метаданные только для некоторых диагностик -fanalyzer. Плагины GCC также могут предоставлять сообщения об ошибках с такими метаданными. По умолчанию, если эта информация присутствует, она будет выводиться с диагностикой. Этот параметр подавляет вывод этих метаданных.

-fno-diagnostics-show-line-numbers

По умолчанию при выводе исходного кода (через -fdiagnostics-show-caret) выводится левый отступ, показывающий номера строк. Этот параметр подавляет этот левый отступ.

-fdiagnostics-minimum-margin-width=width

Этот параметр управляет минимальной шириной левого отступа, выводимого параметром -fdiagnostics-show-line-numbers. По умолчанию он равен 6.

-fdiagnostics-parseable-fixits

Выводить подсказки исправления в формате, распознаваемом машиной, подходящем для обработки IDE. Для каждого исправления будет напечатана строка после соответствующего диагностического сообщения, начинающаяся со строки «fix-it:». Например:

fix-it:"test.c":{45:3-45:21}:"gtk_widget_show_all"

Расположение выражается как полуоткрытый интервал, выраженный как количество байтов, начиная с байта 1 для начального столбца. В приведенном выше примере байты с 3 по 20 строки 45 файла «test.c» должны быть заменены указанной строкой:

00000000011111111112222222222
12345678901234567890123456789
  gtk_widget_showall (dlg);
  ^^^^^^^^^^^^^^^^^^
  gtk_widget_show_all

Имя файла и строка замены экранируют обратную косую черту как «\\», табуляцию как «\t», перевод строки как «\n», двойные кавычки как «\"», непечатаемые символы как восьмеричные (например, вертикальная табуляция как «\013»).

Пустая строка замены указывает на удаление указанного диапазона. Пустой диапазон (например, «45:3-45:3») указывает, что строка должна быть вставлена в указанную позицию.

-fdiagnostics-generate-patch

Печатать подсказки исправления в stderr в формате unified diff после вывода всех диагностических сообщений. Например:

--- test.c
+++ test.c
@ -42,5 +42,5 @

 void show_cb(GtkDialog *dlg)
 {
-  gtk_widget_showall(dlg);
+  gtk_widget_show_all(dlg);
 }

Диф может быть или не быть цветным, следуя тем же правилам, что и для диагностических сообщений (см. -fdiagnostics-color).

-fdiagnostics-show-template-tree

В фронтенде C++, при печати диагностических сообщений, показывающих несоответствие шаблонов типов, например:

could not convert 'std::map<int, std::vector<double> >()'
  from 'map<[...],vector<double>>' to 'map<[...],vector<float>>

флаг -fdiagnostics-show-template-tree включает печать древовидной структуры, отображающей общие и отличительные части типов, например:

map<
  [...],
  vector<
    [double != float]>>

Различающиеся части выделены цветом («double» и «float» в данном случае).

-fno-elide-type

По умолчанию, когда фронтенд C++ печатает диагностические сообщения о несоответствующих типах шаблонов, общие части типов отображаются как «[...]», чтобы упростить сообщение об ошибке. Например:

could not convert 'std::map<int, std::vector<double> >()'
  from 'map<[...],vector<double>>' to 'map<[...],vector<float>>

Указание флага -fno-elide-type подавляет это поведение. Этот флаг также влияет на вывод флага -fdiagnostics-show-template-tree.

-fdiagnostics-path-format=KIND

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

KIND — ‘none’, ‘separate-events’, или ‘inline-events’, по умолчанию.

‘none’ означает не выводить пути диагностики.

‘separate-events’ означает печать отдельного диагностического «примечания» для каждого события внутри диагностического сообщения. Например:

test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter
test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL
test.c:27:3: note: (2) when 'i < count'
test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1

‘inline-events’ означает печать событий «внутри» исходного кода. Этот вид пытается объединить события в серии достаточно близких событий, печатая их как помеченные диапазоны в исходном коде.

Например, те же события, что и выше, могут быть напечатаны как:

'test': events 1-3
  |
  |   25 |   list = PyList_New(0);
  |      |          ^~~~~~~~~~~~~
  |      |          |
  |      |          (1) when 'PyList_New' fails, returning NULL
  |   26 |
  |   27 |   for (i = 0; i < count; i++) {
  |      |   ~~~
  |      |   |
  |      |   (2) when 'i < count'
  |   28 |     item = PyLong_FromLong(random());
  |   29 |     PyList_Append(list, item);
  |      |     ~~~~~~~~~~~~~~~~~~~~~~~~~
  |      |     |
  |      |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
  |

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

Например:

'test': events 1-2
    |
    |  133 | {
    |      | ^
    |      | |
    |      | (1) entering 'test'
    |  134 |   boxed_int *obj = make_boxed_int (i);
    |      |                    ~~~~~~~~~~~~~~~~~~
    |      |                    |
    |      |                    (2) calling 'make_boxed_int'
    |
    +--> 'make_boxed_int': events 3-4
           |
           |  120 | {
           |      | ^
           |      | |
           |      | (3) entering 'make_boxed_int'
           |  121 |   boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int));
           |      |                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           |      |                                    |
           |      |                                    (4) calling 'wrapped_malloc'
           |
           +--> 'wrapped_malloc': events 5-6
                  |
                  |    7 | {
                  |      | ^
                  |      | |
                  |      | (5) entering 'wrapped_malloc'
                  |    8 |   return malloc (size);
                  |      |          ~~~~~~~~~~~~~
                  |      |          |
                  |      |          (6) calling 'malloc'
                  |
    <-------------+
    |
 'test': event 7
    |
    |  138 |   free_boxed_int (obj);
    |      |   ^~~~~~~~~~~~~~~~~~~~
    |      |   |
    |      |   (7) calling 'free_boxed_int'
    |
(etc)

-fdiagnostics-show-path-depths

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

Если этот параметр указан, глубина стека будет выводиться для каждой серии событий внутри -fdiagnostics-path-format=separate-events.

Этот параметр предназначен для использования разработчиками GCC и разработчиками плагинов при отладке диагностики, которая сообщает о межпроцедурном потоке управления.

-fno-show-column

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

-fdiagnostics-column-unit=UNIT

Выберите единицы для номера столбца. Это влияет на традиционные диагностические сообщения (при отсутствии -fno-show-column), а также на диагностические сообщения в формате JSON, если они запрошены.

По умолчанию UNIT, ‘display’, учитывает количество отображаемых столбцов, занимаемых каждым символом. Это может быть больше, чем количество байтов, необходимых для кодирования символа, в случае символов табуляции, или меньше, в случае многобайтовых символов. Например, символ «ГРЕЧЕСКАЯ МАЛЕНЬКАЯ БУКВА ПИ (U+03C0)» занимает один столбец, а его кодировка UTF-8 требует двух байтов; символ «НЕМНОГО УЛЫБАЮЩЕЕСЯ ЛИЦО (U+1F642)» занимает два столбца, а его кодировка UTF-8 требует четырех байтов.

Указание UNIT на ‘byte’ изменяет номер столбца на количество байтов в сыром виде во всех случаях, как это традиционно выводилось GCC до версии 11.1.0.

-fdiagnostics-column-origin=ORIGIN

Выберите начало для номеров столбцов, т.е. номер столбца, присваиваемый первому столбцу. Значение по умолчанию 1 соответствует традиционному поведению GCC и руководству по стилю GNU. Некоторые утилиты могут работать лучше со значением начала 0; может быть указано любое неотрицательное значение.

-fdiagnostics-format=FORMAT

Выберите другой формат вывода диагностических сообщений. FORMAT — ‘text’ или ‘json’. По умолчанию — ‘text’.

Формат ‘json’ представляет собой массив JSON верхнего уровня, содержащий объекты JSON, представляющие диагностические сообщения.

JSON выводится в одной строке без форматирования; приведенные ниже примеры отформатированы для ясности.

Диагностические сообщения могут иметь дочерние диагностические сообщения. Например, эта ошибка и примечание:

misleading-indentation.c:15:3: warning: this 'if' clause does not
  guard... [-Wmisleading-indentation]
   15 |   if (flag)
      |   ^~
misleading-indentation.c:17:5: note: ...this statement, but the latter
  is misleadingly indented as if it were guarded by the 'if'
   17 |     y = 2;
      |     ^

могут быть напечатаны в формате JSON (после форматирования) так:

[
    {
        "kind": "warning",
        "locations": [
            {
                "caret": {
		    "display-column": 3,
		    "byte-column": 3,
                    "column": 3,
                    "file": "misleading-indentation.c",
                    "line": 15
                },
                "finish": {
		    "display-column": 4,
		    "byte-column": 4,
                    "column": 4,
                    "file": "misleading-indentation.c",
                    "line": 15
                }
            }
        ],
        "message": "this \u2018if\u2019 clause does not guard...",
        "option": "-Wmisleading-indentation",
        "option_url": "https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation",
        "children": [
            {
                "kind": "note",
                "locations": [
                    {
                        "caret": {
			    "display-column": 5,
			    "byte-column": 5,
                            "column": 5,
                            "file": "misleading-indentation.c",
                            "line": 17
                        }
                    }
                ],
                "message": "...this statement, but the latter is …"
            }
        ]
	"column-origin": 1,
    },
    …
]

где note является дочерним элементом warning.

Диагностическое сообщение имеет kind. Если это warning, то есть ключ option, описывающий параметр командной строки, управляющий предупреждением.

Диагностическое сообщение может содержать ноль или более расположений. Каждое расположение имеет необязательную строку label и до трех позиций внутри нее: позиция caret и необязательные позиции start и finish. Позиция описывается именем file, номером line и тремя числами, указывающими позицию столбца:

• display-column подсчитывает отображаемые столбцы, учитывая табуляции и многобайтовые символы.
• byte-column подсчитывает количество байтов.
• column равно одному из двух предыдущих, как задано опцией -fdiagnostics-column-unit.

Все три столбца относительны к началу, заданному -fdiagnostics-column-origin, которое обычно равно 1, но может быть установлено, например, на 0 для совместимости с другими утилитами, которые нумеруют столбцы с 0. Начало столбца записывается в выводе JSON в теге column-origin. В оставшихся примерах ниже дополнительные выводы номера столбца опушены для краткости.

Например, эта ошибка:

bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' {aka
   'struct s'} and 'T' {aka 'struct t'})
   64 |   return callee_4a () + callee_4b ();
      |          ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
      |          |              |
      |          |              T {aka struct t}
      |          S {aka struct s}

имеет три расположения. Основное расположение находится у токена «+» в столбце 23. Есть два вторичных расположения, описывающие левую и правую части выражения, которые имеют метки. Оно может быть напечатано в формате JSON как:

{
    "children": [],
    "kind": "error",
    "locations": [
        {
            "caret": {
                "column": 23, "file": "bad-binary-ops.c", "line": 64
            }
        },
        {
            "caret": {
                "column": 10, "file": "bad-binary-ops.c", "line": 64
            },
            "finish": {
                "column": 21, "file": "bad-binary-ops.c", "line": 64
            },
            "label": "S {aka struct s}"
        },
        {
            "caret": {
                "column": 25, "file": "bad-binary-ops.c", "line": 64
            },
            "finish": {
                "column": 36, "file": "bad-binary-ops.c", "line": 64
            },
            "label": "T {aka struct t}"
        }
    ],
    "message": "invalid operands to binary + …"
}

Если диагностическое сообщение содержит подсказки исправления, у него есть массив fixits, состоящий из полуоткрытых интервалов, аналогично выводу -fdiagnostics-parseable-fixits. Например, это диагностическое сообщение с подсказкой замены исправления:

demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
  mean 'color'?
    8 |   return ptr->colour;
      |               ^~~~~~
      |               color

может быть напечатано в формате JSON как:

{
    "children": [],
    "fixits": [
        {
            "next": {
                "column": 21,
                "file": "demo.c",
                "line": 8
            },
            "start": {
                "column": 15,
                "file": "demo.c",
                "line": 8
            },
            "string": "color"
        }
    ],
    "kind": "error",
    "locations": [
        {
            "caret": {
                "column": 15,
                "file": "demo.c",
                "line": 8
            },
            "finish": {
                "column": 20,
                "file": "demo.c",
                "line": 8
            }
        }
    ],
    "message": "\u2018struct s\u2019 has no member named …"
}

где подсказка исправления предполагает замену текста с start до, но не включая next на значение string. Удаления выражаются через пустое значение для string, вставки — с start равным next.

Если у диагностического сообщения есть путь событий потока управления, ассоциированных с ним, у него есть массив path объектов, представляющих события. Каждый объект события содержит строку description, объект location, а также строку function и число depth для представления межпроцедурных путей. function представляет текущую функцию в данном событии, а depth представляет глубину стека относительно некоторой базы: чем больше, тем больше кадров внутри стека.

Например, внутрипроцедурный пример, показанный для -fdiagnostics-path-format=, может иметь такой JSON для своего пути:

"path": [
    {
        "depth": 0,
        "description": "when 'PyList_New' fails, returning NULL",
        "function": "test",
        "location": {
            "column": 10,
            "file": "test.c",
            "line": 25
        }
    },
    {
        "depth": 0,
        "description": "when 'i < count'",
        "function": "test",
        "location": {
            "column": 3,
            "file": "test.c",
            "line": 27
        }
    },
    {
        "depth": 0,
        "description": "when calling 'PyList_Append', passing NULL from (1) as argument 1",
        "function": "test",
        "location": {
            "column": 5,
            "file": "test.c",
            "line": 29
        }
    }
]