libgdiagnostics

This document describes libgdiagnostics, an API for programs to use to emit diagnostics (such as for “lint”-style checker tools), supporting:

  • text output similar to GCC’s errors and warnings:

    test-typo.c:19:13: error: unknown field 'colour'
   19 |   return p->colour;
      |             ^~~~~~

    quoting pertinent source code (with a cache), and underlining points and ranges in the files being tested, possibly with labels:

    test-labelled-ranges.c:9:6: error: mismatching types: 'int' and 'const char *'
   19 |   42 + "foo"
      |   ~~ ^ ~~~~~
      |   |    |
      |   int  const char *

  • emitting fix-it hints:

    test-fix-it-hint.c:19:13: error: unknown field 'colour'; did you mean 'color'
   19 |   return p->colour;
      |             ^~~~~~
      |             color

    and generating patches from them:

    @@ -16,7 +16,7 @@
 struct rgb
 get_color (struct object *p)
 {
-  return p->colour;
+  return p->color;
 }

  • capturing execution paths through code:

    In function 'make_a_list_of_random_ints_badly':
test-warning-with-path.c:30:5: warning: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter"
   30 |     PyList_Append(list, item);
      |     ^~~~~~~~~~~~~~~~~~~~~~~~~
make_a_list_of_random_ints_badly': events 1-3
   26 |   list = PyList_New(0);
      |          ^~~~~~~~~~~~~
      |          |
      |          (1) when 'PyList_New' fails, returning NULL
   27 |
   28 |   for (i = 0; i < count; i++) {
      |               ~~~~~~~~~
      |               |
      |               (2) when 'i < count'
   29 |     item = PyLong_FromLong(random());
   30 |     PyList_Append(list, item);
      |     ~~~~~~~~~~~~~~~~~~~~~~~~~
      |     |
      |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1

  • support for emitting machine-readable representations of the above using the SARIF file format

There are actually two APIs for the library:

  • a pure C API: libgdiagnostics.h

  • a C++ wrapper API: libgdiagnostics+.h. This is a header-only collection of wrapper classes around the C API to give a less verbose API.

This documentation covers the C API.

Contents

libgdiagnostics is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Indices and tables