diff options
Diffstat (limited to 'gcc/doc/libgdiagnostics')
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/compatibility.rst | 33 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst | 26 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/graphs.rst | 197 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/index.rst | 1 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/topics/logical-locations.rst | 7 | ||||
| -rw-r--r-- | gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst | 11 |
6 files changed, 254 insertions, 21 deletions
diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst index 10adcc5..0e078d0 100644 --- a/gcc/doc/libgdiagnostics/topics/compatibility.rst +++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst @@ -178,6 +178,8 @@ acccessing values within a :type:`diagnostic_logical_location`: * :func:`diagnostic_logical_location_get_decorated_name` +.. _LIBGDIAGNOSTICS_ABI_2: + ``LIBGDIAGNOSTICS_ABI_2`` ------------------------- ``LIBGDIAGNOSTICS_ABI_2`` covers the addition of these functions for @@ -186,3 +188,34 @@ supporting command-line options and SARIF playback: * :func:`diagnostic_manager_add_sink_from_spec` * :func:`diagnostic_manager_set_analysis_target` + +.. _LIBGDIAGNOSTICS_ABI_3: + +``LIBGDIAGNOSTICS_ABI_3`` +------------------------- +``LIBGDIAGNOSTICS_ABI_3`` covers the addition of these functions for +working with directed graphs: + + * :func:`diagnostic_manager_new_graph` + + * :func:`diagnostic_manager_take_global_graph` + + * :func:`diagnostic_take_graph` + + * :func:`diagnostic_graph_release` + + * :func:`diagnostic_graph_set_description` + + * :func:`diagnostic_graph_add_node` + + * :func:`diagnostic_graph_add_edge` + + * :func:`diagnostic_graph_get_node_by_id` + + * :func:`diagnostic_graph_get_edge_by_id` + + * :func:`diagnostic_node_set_label` + + * :func:`diagnostic_node_set_location` + + * :func:`diagnostic_node_set_logical_location` diff --git a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst index 0390704..c94d19e 100644 --- a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst +++ b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst @@ -63,17 +63,17 @@ Responsibilities include: diagnostic_manager *control_mgr) This function can be used to support option processing similar to GCC's - :option:`-fdiagnostics-add-output=`. This allows command-line tools to - support the same domain-specific language for specifying output sink - as GCC does. - - The function will attempt to parse :param:`spec` as if it were - an argument to GCC's :option:`-fdiagnostics-add-output=OUTPUT-SPEC`. - If successful, it will add an output sink to :param:`affected_mgr` and return zero. - Otherwise, it will emit an error diagnostic to :param:`control_mgr` and + `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + This allows command-line tools to support the same domain-specific + language for specifying output sinks as GCC does. + + The function will attempt to parse ``spec`` as if it were + an argument to GCC's `-fdiagnostics-add-output= <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_. + If successful, it will add an output sink to ``affected_mgr`` and return zero. + Otherwise, it will emit an error diagnostic to ``control_mgr`` and return non-zero. - :param:`affected_mgr` and :param:`control_mgr` can be the same manager, + ``affected_mgr`` and ``control_mgr`` can be the same manager, or be different managers. This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can @@ -83,14 +83,14 @@ Responsibilities include: #ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_add_sink_from_spec - .. function:: void diagnostic_manager_set_analysis_target (diagnostic_manager *mgr, \ const diagnostic_file *file) - This function sets the "main input file" of :param:`mgr` to be - :param:`file`. + This function sets the "main input file" of ``mgr`` to be + ``file``. This affects the :code:`<title>` of generated HTML and - the :code:`role` of the artifact in SARIF output (SARIF v2.1.0 section 3.24.6). + the :code:`role` of the :code:`artifact` in SARIF output + (`SARIF v2.1.0 section 3.24.6 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790867>`_). This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can test for its presence using diff --git a/gcc/doc/libgdiagnostics/topics/graphs.rst b/gcc/doc/libgdiagnostics/topics/graphs.rst new file mode 100644 index 0000000..b976013 --- /dev/null +++ b/gcc/doc/libgdiagnostics/topics/graphs.rst @@ -0,0 +1,197 @@ +.. Copyright (C) 2025 Free Software Foundation, Inc. + Originally contributed by David Malcolm <dmalcolm@redhat.com> + + This 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. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <https://www.gnu.org/licenses/>. + +.. default-domain:: c + +Graphs +====== + +.. type:: diagnostic_graph + +SARIF has support for capturing directed graphs (such as callgraphs +and control flow graphs), both at the level of the run as a whole, +and at the level of individual results. + +libgdiagnostics supports this with the following entrypoints, allowing +directed graphs to be + +* created (with :func:`diagnostic_manager_new_graph`) + +* reported "globally" (with :func:`diagnostic_manager_take_global_graph`) + +* reported as part of a :type:`diagnostic` (with :func:`diagnostic_take_graph`), or + +* discarded (with :func:`diagnostic_graph_release`). + +.. function:: diagnostic_graph * diagnostic_manager_new_graph (diagnostic_manager *manager) + + Create a new directed graph. + + The resulting graph is owned by the caller and must have one of + :func:`diagnostic_manager_take_global_graph`, + :func:`diagnostic_take_graph`, + or :func:`diagnostic_graph_release` called on it to avoid leaks. + + The parameter ``manager`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_manager_take_global_graph (diagnostic_manager *manager, \ + diagnostic_graph *graph) + + Report this graph "globally", taking ownership of it. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theRun.graphs (SARIF v2.1.0 3.14.20). + + Parameters ``manager`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_take_graph (diagnostic *diag, \ + diagnostic_graph *graph) + + Add this graph to ``diag``, transferring ownership of it to ``diag``. + This won't appear in text sinks, but in SARIF sinks the graph will be + added to theResult.graphs (SARIF v2.1.0 3.27.19). + + Parameters ``diag`` and ``graph`` must both be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_graph_release (diagnostic_graph *graph) + + Release ``graph`` which must still be owned by the caller + i.e. it must *not* have had + :func:`diagnostic_manager_take_global_graph` or + :func:`diagnostic_take_graph` called on it. + + Parameters ``graph`` can be null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. function:: void diagnostic_graph_set_description (diagnostic_graph *graph, \ + const char *description) + + Set the description of ``graph`` for use in the value of the + SARIF ``description`` property (SARIF v2.1.0 section 3.39.2). + + The parameter ``graph`` must be non-null. + The parameter ``description`` can be null, for clearing any existing + description. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node * diagnostic_graph_add_node (diagnostic_graph *graph, \ + const char *node_id, \ + diagnostic_node *parent_node) + + Create and add a new node within ``graph`` with the given `id``. + The id must be unique within nodes in ``graph``. + + The parameters ``graph`` and ``id`` must be non-null. + + ``parent_node`` can be NULL (for a top-level node in the graph), + or non-null for a child node, allowing for arbitrary nesting of + nodes. + + The new node is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge * diagnostic_graph_add_edge (diagnostic_graph *graph, \ + const char *edge_id, \ + diagnostic_node *src_node, \ + diagnostic_node *dst_node, \ + const char *label) + + Create and add a new edge within ``graph``. + + The parameters ``graph``, ``src_node`` and ``dest_node`` + must be non-null. + + If non-null, then ``edge_id`` must be unique within ``graph``; + if ``edge_id`` is null then a unique id of the form "edge0", "edge1", + etc will be used automatically. + + If non-null, then ``label`` will be used for the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.41.3). + + The new edge is owned by ``graph``. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_node *diagnostic_graph_get_node_by_id (diagnostic_graph *graph, \ + const char *node_id) + + Get the node in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``node_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: diagnostic_edge *diagnostic_graph_get_edge_by_id (diagnostic_graph *graph, \ + const char *edge_id) + + Get the edge in ``graph`` with the given id, or null. + + The parameters ``graph`` and ``edge_id`` must be non-null. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + + +.. type:: diagnostic_node + +.. function:: void diagnostic_node_set_label (diagnostic_node *node, \ + const char *label) + + Set the label of ``node`` for use in the value of the + SARIF ``label`` property (SARIF v2.1.0 section 3.40.3). + + The parameter ``node`` must be non-null. + The parameter ``label`` can be null, for clearing any existing + label. + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_location (diagnostic_node *node, \ + const diagnostic_physical_location *loc) + + Set the physical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``loc`` can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. + +.. function:: void diagnostic_node_set_logical_location (diagnostic_node *node, \ + const diagnostic_logical_location *logical_loc) + + Set the logical location of ``node``, if any. + + The parameter ``node`` must be non-null. + The parameter ``logical_loc`` _can be null, for clearing any existing + location. + + If set, the value will be used by SARIF sinks within the + ``location`` property (SARIF v2.1.0 section 3.40.4). + + This function was added in :ref:`LIBGDIAGNOSTICS_ABI_3`. diff --git a/gcc/doc/libgdiagnostics/topics/index.rst b/gcc/doc/libgdiagnostics/topics/index.rst index 6eb3ed6..966f5ef 100644 --- a/gcc/doc/libgdiagnostics/topics/index.rst +++ b/gcc/doc/libgdiagnostics/topics/index.rst @@ -35,5 +35,6 @@ Topic reference execution-paths.rst text-output.rst sarif.rst + graphs.rst ux.rst compatibility.rst diff --git a/gcc/doc/libgdiagnostics/topics/logical-locations.rst b/gcc/doc/libgdiagnostics/topics/logical-locations.rst index 184b563..294d396 100644 --- a/gcc/doc/libgdiagnostics/topics/logical-locations.rst +++ b/gcc/doc/libgdiagnostics/topics/logical-locations.rst @@ -120,7 +120,7 @@ source location "equal" input values on the same :type:`diagnostic_manager` will return the same instance of :type:`diagnostic_logical_location`. "Equal" here includes different string buffers that compare as equal with - :func:``strcmp`. + :func:`strcmp`. .. function:: void diagnostic_manager_debug_dump_logical_location (const diagnostic_manager *diag_mgr, \ const diagnostic_logical_location *loc, \ @@ -147,8 +147,9 @@ Accessors The following functions can be used to access the data that was passed to a :type:`diagnostic_logical_location` when it was created. In each case, the -``loc`` parameter must be non-NULL. :type:`const char *` values will point -at copies of the original buffer. +``loc`` parameter must be non-NULL. The return values will point +at *copies* of the original buffer owned by the +:type:`diagnostic_logical_location`, or be null. .. function:: enum diagnostic_logical_location_kind_t diagnostic_logical_location_get_kind (const diagnostic_logical_location *loc) diff --git a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst index 95b95ca..e64b668 100644 --- a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst +++ b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst @@ -112,10 +112,10 @@ leading to output like this:: foo.c:17: error: can't find 'foo.h'" 17 | #include <foo.h> -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and quote the pertinent line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17: error: can't find 'foo.h' @@ -160,14 +160,15 @@ On compiling and running the program, we should get this output:: 17 | #include <foo.h> | ^~~~~ -where libgdiagnostics will attempt to load the source file and +where libgdiagnostics will attempt to load ``foo.c`` and underling the pertinent part of the given line. -If libgdiagnostics cannot open the file, it will merely print:: +If libgdiagnostics cannot open ``foo.c``, it will merely print:: foo.c:17:8: error: can't find 'foo.h' -A range can span multiple lines within the same file. +A range can span multiple lines within the same file, but cannot +span multiple files. As before, you can use :func:`diagnostic_manager_debug_dump_location` to dump the locations. For the above example:: |