<html><head><title></title></head><body><!-- rte-version 0.2 9947551637294008b77bce25eb683dac --><div class="rte-style-maintainer rte-pre-wrap" bbg-color="default"data-bb-font-size="medium" bbg-font-size="medium" style="white-space: pre-wrap; font-size: small; font-family: "Courier New", Courier, "BB.FixedWidth";"style="white-space: pre-wrap; font-size: small; font-family: "Courier New", Courier, "BB.FixedWidth"; color: rgb(0, 0, 0);"><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">Hello Everyone,</div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";"><br></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">Below is an RFC on extending the clang `-fdiagnostics-format` option's to</div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">let clang to emit machine readable json diagnostics. Feedback is highly appreciated!<br><br># Why<br>Machine consumable diagnostics are important for writing generic static<br>analysis wrappers and harnesses that want to interact with code bases through<br>clang, There are two options to consider for the diagnostic format to use in<br>clang:<br><br>1. Mimic `gcc-9 -fdiagnostics-format=json`, covered in the previous work section<br>2. Emit [SARIF][0] diagnostic information, a cross-language standardized format<br> that is already supported in `clang/lib/StaticAnalyzer` (through `--analyzer-output=sarif`)<br><br>We propose (2) as it is a standardized format, which should make it easier for tools to</div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">implement support for it.<br><br>## Previous Work<br><br>### `gcc-9 -fdiagnostics-format=json`<br>GCC [recently][1] [implemented][2] serializing diagnostics to JSON. This option<br>could be implemented as a `-fdiagnostics-format=json-gcc` in clang to signal<br>users of its intended interoperability with the corresponding gcc option.<br>The schema for this format may be inferred from [current gcc code][3].<br><br>While not community standard, it can be expected to be reasonably stable as the<br>[original patch][2] states the flag emits machine readable diagnostics.<br><br>## SARIF diagnostics in LLVM<br><br>[SARIF][0] (Static Analysis Results Interchange Format) is a standard format<br>for the output for static analysis tools.<br><br>Clang StaticAnalyzer already implements a SARIF diagnostic consumer in<br>[D53814][4], this should allow us to implement (necessary, if any) extra fields<br>to the diagnostics output<br><br>### Mapping clang diagnostics to SARIF<br><br>This section assumes the typical compiler diagnostic which looks like what is<br>provided in the [expressive diagnostics page][5]<br><br>In SARIF, the attributes can be mapped to the [`results`][7] property as follows:<br>1. File name where the diagnostic occurs is relocated to the [`physicalLocation`][8]<br> property<br>2. Line/Column of the caret marking the error can be stored in the [`region`][9]<br> property, this can also encode the source range to which an error corresponds<br>3. The error message can be transferred to the [`message`][10]<br>4. Each of the locations can store the rendered caret & snippet from clang using the<br> [`snippet`][12] property for that region<br>5. Nested diagnostics (typically `note` level items) can be represented using the<br> [`locationRelationShip`][14] object <br>6. Fixit hints can be communicated through the [`fixes`][13] property <br><br><br>## Interface Changes<br><br>We propose the following interface changes:<br><br>- Input: Extend the `-fdiagnostics-format` flag to recognize: `-fdiagnostics-format=sarif`<br>- Output: Clang will emit SARIF formatted diagnostics when `-fdiagnostics-format=sarif` is provided.</div><div style=""><br></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">## Diagnostic Examples</div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";"><br></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">Various examples for what are available on this github gist (which also renders this message in markdown): <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://gist.github.com/envp/3a5fdd33115b91c391c22e5e8a5210f4#diagnostic-examples">https://gist.github.com/envp/3a5fdd33115b91c391c22e5e8a5210f4#diagnostic-examples</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";"><br></div><div style=""><br></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[0]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html">https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[1]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://developers.redhat.com/blog/2019/03/08/usability-improvements-in-gcc-9">https://developers.redhat.com/blog/2019/03/08/usability-improvements-in-gcc-9</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[2]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff;h=478dd60ddcf17773ebd1af367c9dcaee2401f797">https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff;h=478dd60ddcf17773ebd1af367c9dcaee2401f797</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[3]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://github.com/gcc-mirror/gcc/blob/master/gcc/diagnostic-format-json.cc">https://github.com/gcc-mirror/gcc/blob/master/gcc/diagnostic-format-json.cc</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[4]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://reviews.llvm.org/D53814">https://reviews.llvm.org/D53814</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[5]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://clang.llvm.org/diagnostics.html">https://clang.llvm.org/diagnostics.html</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[6]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://github.com/microsoft/sarif-tutorials/blob/main/docs/2-Basics.md#results">https://github.com/microsoft/sarif-tutorials/blob/main/docs/2-Basics.md#results</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[7]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012463">https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012463</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[8]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012634">https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012634</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[9]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012641">https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012641</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[10]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012655">https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012655</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[11]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012632">https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012632</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[12]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10127889">https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10127889</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[13]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10128072">https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10128072</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";">[14]: <a spellcheck="false"bbg-destination="rte:bind" data-destination="rte:bind" href="https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10127919">https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/sarif-v2.0-csprd02.html#_Toc10127919</a></div><div data-bb-font-size="small" bbg-font-size="small" style="font-size: x-small; font-family: Arial, "BB.Proportional";"><br></div></div></body></html>