Skip to content

Commit 07d1d3c

Browse files
zackmdavismark-i-m
authored andcommitted
subchapter with information about --error-format json
1 parent d785946 commit 07d1d3c

File tree

2 files changed

+37
-0
lines changed

2 files changed

+37
-0
lines changed

src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@
8383
- [Updating LLVM](./codegen/updating-llvm.md)
8484
- [Debugging LLVM](./codegen/debugging.md)
8585
- [Emitting Diagnostics](./diag.md)
86+
- [JSON diagnostic format](./diag/json-format.md)
8687

8788
---
8889

src/diag/json-format.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# JSON diagnostic output
2+
3+
The compiler accepts an `--error-format json` flag to output
4+
diagnostics as JSON objects (for the benefit of tools such as `cargo
5+
fix` or the RLS). It looks like this—
6+
7+
```ignore
8+
$ rustc json_error_demo.rs --error-format json
9+
{"message":"cannot add `&str` to `{integer}`","code":{"code":"E0277","explanation":"\nYou tried to use a type which doesn't implement some trait in a place which\nexpected that trait. Erroneous code example:\n\n```compile_fail,E0277\n// here we declare the Foo trait with a bar method\ntrait Foo {\n fn bar(&self);\n}\n\n// we now declare a function which takes an object implementing the Foo trait\nfn some_func<T: Foo>(foo: T) {\n foo.bar();\n}\n\nfn main() {\n // we now call the method with the i32 type, which doesn't implement\n // the Foo trait\n some_func(5i32); // error: the trait bound `i32 : Foo` is not satisfied\n}\n```\n\nIn order to fix this error, verify that the type you're using does implement\nthe trait. Example:\n\n```\ntrait Foo {\n fn bar(&self);\n}\n\nfn some_func<T: Foo>(foo: T) {\n foo.bar(); // we can now use this method since i32 implements the\n // Foo trait\n}\n\n// we implement the trait on the i32 type\nimpl Foo for i32 {\n fn bar(&self) {}\n}\n\nfn main() {\n some_func(5i32); // ok!\n}\n```\n\nOr in a generic context, an erroneous code example would look like:\n\n```compile_fail,E0277\nfn some_func<T>(foo: T) {\n println!(\"{:?}\", foo); // error: the trait `core::fmt::Debug` is not\n // implemented for the type `T`\n}\n\nfn main() {\n // We now call the method with the i32 type,\n // which *does* implement the Debug trait.\n some_func(5i32);\n}\n```\n\nNote that the error here is in the definition of the generic function: Although\nwe only call it with a parameter that does implement `Debug`, the compiler\nstill rejects the function: It must work with all possible input types. In\norder to make this example compile, we need to restrict the generic type we're\naccepting:\n\n```\nuse std::fmt;\n\n// Restrict the input type to types that implement Debug.\nfn some_func<T: fmt::Debug>(foo: T) {\n println!(\"{:?}\", foo);\n}\n\nfn main() {\n // Calling the method is still fine, as i32 implements Debug.\n some_func(5i32);\n\n // This would fail to compile now:\n // struct WithoutDebug;\n // some_func(WithoutDebug);\n}\n```\n\nRust only looks at the signature of the called function, as such it must\nalready specify all requirements that will be used for every type parameter.\n"},"level":"error","spans":[{"file_name":"json_error_demo.rs","byte_start":50,"byte_end":51,"line_start":4,"line_end":4,"column_start":7,"column_end":8,"is_primary":true,"text":[{"text":" a + b","highlight_start":7,"highlight_end":8}],"label":"no implementation for `{integer} + &str`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"the trait `std::ops::Add<&str>` is not implemented for `{integer}`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error[E0277]: cannot add `&str` to `{integer}`\n --> json_error_demo.rs:4:7\n |\n4 | a + b\n | ^ no implementation for `{integer} + &str`\n |\n = help: the trait `std::ops::Add<&str>` is not implemented for `{integer}`\n\n"}
10+
{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
11+
{"message":"For more information about this error, try `rustc --explain E0277`.","code":null,"level":"","spans":[],"children":[],"rendered":"For more information about this error, try `rustc --explain E0277`.\n"}
12+
```
13+
14+
Note that the output is a series of lines, each of which is a JSON
15+
object, but the series of lines taken together is, unfortunately, not
16+
valid JSON, thwarting tools and tricks (such as [piping to `python3 -m
17+
json.tool`](https://docs.python.org/3/library/json.html#module-json.tool))
18+
that require such. (One speculates that this was intentional for LSP
19+
performance purposes, so that each line/object can be sent to RLS as
20+
it is flushed?)
21+
22+
Also note the "rendered" field, which contains the "human" output as a
23+
string; this was introduced so that UI tests could both make use of
24+
the structured JSON and see the "human" output (well, _sans_ colors)
25+
without having to compile everything twice.
26+
27+
The JSON emitter currently lives in libsyntax/json.rs. (But arguably
28+
it should live in librustc_errors along with the "human" emitter? It's
29+
not obvious to the present author why it wasn't moved from libsyntax
30+
to librustc_errors at the same [time the "human" emitter was
31+
moved](https://github.com/rust-lang/rust/commit/6ae3502134).)
32+
33+
The JSON emitter defines [its own `Diagnostic`
34+
struct](https://github.com/rust-lang/rust/blob/b2c6b8c29f13f8d1f242da89e587960b95337819/src/libsyntax/json.rs#L85-L99)
35+
(and sub-structs) for the JSON serialization. Don't confuse this with
36+
[`errors::Diagnostic`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diagnostic.html)!

0 commit comments

Comments
 (0)