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» означает, что цвет используется только тогда, когда стандартный вывод ошибок направлен на терминал. Формы -fdiagnostics-color и -fno-diagnostics-color являются псевдонимами для -fdiagnostics-color=always и -fdiagnostics-color=never соответственно.

Цвета определяются переменной среды GCC_COLORS. Её значение — список возможностей и подстрок 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: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 для заметок: маркеры.
range1=: Подстрока SGR для первого дополнительного диапазона.
range2=: Подстрока SGR для второго дополнительного диапазона.
locus=: Подстрока SGR для информации о расположении, например «файл:строка» или «файл:строка:столбец».
quote=: Подстрока SGR для информации, напечатанной в кавычках.
fixit-insert=: Подстрока SGR для подсказок исправления, предлагающих вставить или заменить текст.
fixit-delete=: Подстрока SGR для подсказок исправления, предлагающих удалить текст.
diff-filename=: Подстрока SGR для заголовков файлов в сгенерированных патчах.
diff-hunk=: Подстрока SGR для начала блоков в сгенерированных патчах.
diff-delete=: Подстрока SGR для удаленных строк в сгенерированных патчах.
diff-insert=: Подстрока SGR для вставленных строк в сгенерированных патчах.
type-diff=: Подстрока SGR для выделения несовпадающих типов в параметрах шаблонов в C++ фронтенде.

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

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

Далее: Параметры предупреждений, Предыдущее: Параметры диалектов Objective-C и Objective-C++, Выше: Вызов GCC [Оглавление][Индекс]

© Free Software Foundation
Licensed under the GNU Free Documentation License, Version 1.3.
https://gcc.gnu.org/onlinedocs/gcc-9.5.0/gcc/Diagnostic-Message-Formatting-Options.html