A lot of effort has been put into making rustc have great error messages.
This chapter is about how to emit compile errors and lints from the compiler.
Span is the primary data structure in rustc used to represent a
location in the code being compiled. Spans are attached to most constructs in
HIR and MIR, allowing for more informative error reporting.
A Span can be looked up in a SourceMap to get a "snippet"
useful for displaying errors with span_to_snippet and other
similar methods on the SourceMap.
The rustc_errors crate defines most of the utilities used for
reporting errors.
Session and ParseSess have
methods (or fields with methods) that allow reporting errors. These methods
usually have names like span_err or struct_span_err or span_warn, etc...
There are lots of them; they emit different types of "errors", such as
warnings, errors, fatal errors, suggestions, etc.
In general, there are two class of such methods: ones that emit an error
directly and ones that allow finer control over what to emit. For example,
span_err emits the given error message at the given Span, but
struct_span_err instead returns a
DiagnosticBuilder.
DiagnosticBuilder allows you to add related notes and suggestions to an error
before emitting it by calling the emit method. (Failing to either
emit or cancel a DiagnosticBuilder will result in an ICE.) See the
docs for more info on what you can do.
// Get a DiagnosticBuilder. This does _not_ emit an error yet.
let mut err = sess.struct_span_err(sp, "oh no! this is an error!");
// In some cases, you might need to check if `sp` is generated by a macro to
// avoid printing weird errors about macro-generated code.
if let Ok(snippet) = sess.source_map().span_to_snippet(sp) {
// Use the snippet to generate a suggested fix
err.span_suggestion(suggestion_sp, "try using a qux here", format!("qux {}", snip));
} else {
// If we weren't able to generate a snippet, then emit a "help" message
// instead of a concrete "suggestion". In practice this is unlikely to be
// reached.
err.span_help(suggestion_sp, "you could use a qux here instead");
}
// emit the error
err.emit();In addition to telling the user exactly why their code is wrong, it's
oftentimes furthermore possible to tell them how to fix it. To this end,
DiagnosticBuilder offers a structured suggestions API, which formats code
suggestions pleasingly in the terminal, or (when the --error-format json flag
is passed) as JSON for consumption by tools, most notably the Rust Language
Server and rustfix.
Not all suggestions should be applied mechanically. Use the
span_suggestion method of DiagnosticBuilder to
make a suggestion. The last argument provides a hint to tools whether
the suggestion is mechanically applicable or not.
For example, to make our qux suggestion machine-applicable, we would do:
let mut err = sess.struct_span_err(sp, "oh no! this is an error!");
if let Ok(snippet) = sess.source_map().span_to_snippet(sp) {
err.span_suggestion(
suggestion_sp,
"try using a qux here",
format!("qux {}", snip),
Applicability::MachineApplicable,
);
} else {
err.span_help(suggestion_sp, "you could use a qux here instead");
}
err.emit();This might emit an error like
$ rustc mycode.rs
error[E0999]: oh no! this is an error!
--> mycode.rs:3:5
|
3 | sad()
| ^ help: try using a qux here: `qux sad()`
error: aborting due to previous error
For more information about this error, try `rustc --explain E0999`.In some cases, like when the suggestion spans multiple lines or when there are multiple suggestions, the suggestions are displayed on their own:
error[E0999]: oh no! this is an error!
--> mycode.rs:3:5
|
3 | sad()
| ^
help: try using a qux here:
|
3 | qux sad()
| ^^^
error: aborting due to previous error
For more information about this error, try `rustc --explain E0999`.The possible values of Applicability are:
MachineApplicable: Can be applied mechanically.HasPlaceholders: Cannot be applied mechanically because it has placeholder text in the suggestions. For example, "Try adding a type: `let x: <type>`".MaybeIncorrect: Cannot be applied mechanically because the suggestion may or may not be a good one.Unspecified: Cannot be applied mechanically because we don't know which of the above cases it falls into.
The compiler linting infrastructure is defined in the rustc::lint
module.
The built-in compiler lints are defined in the rustc_lint
crate.
Every lint is implemented via a struct that implements the LintPass trait
(you also implement one of the more specific lint pass traits, either
EarlyLintPass or LateLintPass). The trait implementation allows you to
check certain syntactic constructs as the linter walks the source code. You can
then choose to emit lints in a very similar way to compile errors.
You also declare the metadata of a particular lint via the declare_lint!
macro. This includes the name, the default level, a short description, and some
more details.
Note that the lint and the lint pass must be registered with the compiler.
For example, the following lint checks for uses
of while true { ... } and suggests using loop { ... } instead.
// Declare a lint called `WHILE_TRUE`
declare_lint! {
WHILE_TRUE,
// warn-by-default
Warn,
// This string is the lint description
"suggest using `loop { }` instead of `while true { }`"
}
// Define a struct and `impl LintPass` for it.
#[derive(Copy, Clone)]
pub struct WhileTrue;
// This declares a lint pass, providing a list of associated lints. The
// compiler currently doesn't use the associated lints directly (e.g., to not
// run the pass or otherwise check that the pass emits the appropriate set of
// lints). However, it's good to be accurate here as it's possible that we're
// going to register the lints via the get_lints method on our lint pass (that
// this macro generates).
impl_lint_pass!(
WhileTrue => [WHILE_TRUE],
);
// LateLintPass has lots of methods. We only override the definition of
// `check_expr` for this lint because that's all we need, but you could
// override other methods for your own lint. See the rustc docs for a full
// list of methods.
impl<'a, 'tcx> LateLintPass<'a, 'tcx> for WhileTrue {
fn check_expr(&mut self, cx: &LateContext, e: &hir::Expr) {
if let hir::ExprWhile(ref cond, ..) = e.node {
if let hir::ExprLit(ref lit) = cond.node {
if let ast::LitKind::Bool(true) = lit.node {
if lit.span.ctxt() == SyntaxContext::empty() {
let msg = "denote infinite loops with `loop { ... }`";
let condition_span = cx.tcx.sess.source_map().def_span(e.span);
let mut err = cx.struct_span_lint(WHILE_TRUE, condition_span, msg);
err.span_suggestion_short(condition_span, "use `loop`", "loop".to_owned());
err.emit();
}
}
}
}
}
}Sometimes we want to change the behavior of a lint in a new edition. To do this,
we just add the transition to our invocation of declare_lint!:
declare_lint! {
pub ANONYMOUS_PARAMETERS,
Allow,
"detects anonymous parameters",
Edition::Edition2018 => Warn,
}This makes the ANONYMOUS_PARAMETERS lint allow-by-default in the 2015 edition
but warn-by-default in the 2018 edition.
A future-incompatible lint should be declared with the @future_incompatible
additional "field":
declare_lint! {
pub ANONYMOUS_PARAMETERS,
Allow,
"detects anonymous parameters",
@future_incompatible = FutureIncompatibleInfo {
reference: "issue #41686 <https://github.com/rust-lang/rust/issues/41686>",
edition: Some(Edition::Edition2018),
};
}If you need a combination of options that's not supported by the
declare_lint! macro, you can always define your own static with a type of
&Lint but this is currently linted against in the compiler tree.
Lints can be turned on in groups. These groups are declared in the
register_builtins function in rustc_lint::lib. The
add_lint_group! macro is used to declare a new group.
For example,
add_lint_group!(sess,
"nonstandard_style",
NON_CAMEL_CASE_TYPES,
NON_SNAKE_CASE,
NON_UPPER_CASE_GLOBALS);This defines the nonstandard_style group which turns on the listed lints. A
user can turn on these lints with a !#[warn(nonstandard_style)] attribute in
the source code, or by passing -W nonstandard-style on the command line.
On occasion, you may need to define a lint that runs before the linting system has been initialized (e.g. during parsing or macro expansion). This is problematic because we need to have computed lint levels to know whether we should emit a warning or an error or nothing at all.
To solve this problem, we buffer the lints until the linting system is
processed. Session and ParseSess both have
buffer_lint methods that allow you to buffer a lint for later. The linting
system automatically takes care of handling buffered lints later.
Thus, to define a lint that runs early in the compilation, one defines a lint
like normal but invokes the lint with buffer_lint.
The parser (libsyntax) is interesting in that it cannot have dependencies on
any of the other librustc* crates. In particular, it cannot depend on
librustc::lint or librustc_lint, where all of the compiler linting
infrastructure is defined. That's troublesome!
To solve this, libsyntax defines its own buffered lint type, which
ParseSess::buffer_lint uses. After macro expansion, these buffered lints are
then dumped into the Session::buffered_lints used by the rest of the compiler.
Usage for buffered lints in libsyntax is pretty much the same as the rest of
the compiler with one exception because we cannot import the LintIds for
lints we want to emit. Instead, the BufferedEarlyLintId type is used. If you
are defining a new lint, you will want to add an entry to this enum. Then, add
an appropriate mapping to the body of Lint::from_parser_lint_id.
The compiler accepts an --error-format json flag to output
diagnostics as JSON objects (for the benefit of tools such as cargo fix or the RLS). It looks like this—
$ rustc json_error_demo.rs --error-format json
{"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"}
{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
{"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"}Note that the output is a series of lines, each of which is a JSON
object, but the series of lines taken together is, unfortunately, not
valid JSON, thwarting tools and tricks (such as piping to python3 -m json.tool)
that require such. (One speculates that this was intentional for LSP
performance purposes, so that each line/object can be sent to RLS as
it is flushed?)
Also note the "rendered" field, which contains the "human" output as a string; this was introduced so that UI tests could both make use of the structured JSON and see the "human" output (well, sans colors) without having to compile everything twice.
The JSON emitter currently lives in libsyntax/json.rs. (But arguably it should live in librustc_errors along with the "human" emitter? It's not obvious to the present author why it wasn't moved from libsyntax to librustc_errors at the same time the "human" emitter was moved.)
The JSON emitter defines its own Diagnostic
struct
(and sub-structs) for the JSON serialization. Don't confuse this with
errors::Diagnostic!