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

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

-fmessage-length=n

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

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

-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++ фронте.

-fdiagnostics-urls[=WHEN]

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

WHEN может принимать значения «never», «always» или «auto». «auto» заставляет GCC использовать URL-escape-последовательности только тогда, когда стандартный вывод является терминалом и когда выполнение не происходит в оболочке 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

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

-fdiagnostics-generate-patch

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

--- 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-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": {
                    "column": 3,
                    "file": "misleading-indentation.c",
                    "line": 15
                },
                "finish": {
                    "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": {
                            "column": 5,
                            "file": "misleading-indentation.c",
                            "line": 17
                        }
                    }
                ],
                "message": "...this statement, but the latter is …"
            }
        ]
    },
    …
]

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

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

Диагностическое сообщение может содержать ноль или более расположений. Каждое расположение имеет до трёх позиций: позицию caret, и необязательные позиции start и finish. У расположения также может быть необязательная строка label. Например, эта ошибка:

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
        }
    }
]