Diagnostics
Core
Diagnostics are clang's errors and warnings on an open file, clang-tidy's findings, and clice's own messages about the setup.
- A client that pulls diagnostics (
textDocument/diagnostic) asks for them; any other client gets them pushed when a compile finishes. - Every missing
#includeis reported, not just the first, and the code after it is still checked. - Warnings raised by directives in the preamble (
#warning,#pragma message, macro redefinitions) show like any other. - A compile command clang rejects before parsing (an unknown target) shows clang's reason at the top of the file.
- Errors of template instantiations inside headers show once the background index has compiled the file, and at once in a module unit or a file importing a module (clangd#137).
Errors in Included Headers
An error inside a header is reported on the #include that brings it in, so it shows in the file you are editing.
Errors in included headers
An error inside an included header shows on the line that includes it
The first error of each included header is reported on its #include line, with a note at the place in the header where it occurred. The header's other errors belong to the header and show when it is opened.
Errors in headers' function bodies
An error inside a function body of a header shows once the background index has compiled the file as saved
The editor's compile of a file skips the bodies of the functions in the headers it includes at its top, as clangd does: the file opens and rebuilds after an edit several times faster. The background index compiles those bodies, and what it finds in them, an inline function's errors, a template's for the arguments the file instantiates it with, or those of the file's own generic lambda such a template calls, shows on the file while the file holds the text it compiled: an edit takes them down until the file is saved and compiled again. A rule setting skip_function_body = false for a header parses its bodies in the editor too; one setting skip_function_body = true, for third-party code, skips them in the background index as well, and what goes wrong in them never shows.
Template Instantiations
An error or a warning inside a template is reported on the code that instantiates it.
Errors in template instantiations
An error inside a template shows where the code asks for the instantiation
When a template fails for the arguments it is instantiated with, the error is reported on the code that requested the instantiation, not inside the template. Its notes lead through the chain of instantiations to the place in the template where it failed. A template in a header the file includes at its top is instantiated by the background index, not by the editor's compile, which skips the header's function bodies: its errors show once the index has compiled the file as saved.
Notes
The notes clang attaches to an error travel with it as related information; a client that takes no related information gets them in the message.
Notes as related information
The notes clang attaches to an error point to the places they name
An error comes with the notes that explain it, such as where a name was first defined or which candidate a call could not use. Each note is related information of the error, so an editor shows it beside the error and jumps to its place.
Files Without a Compilation Database
A file the compilation database does not list still compiles, with a command clice guesses.
No compilation database
A file no compilation database lists compiles with a guessed command and says so
Without a compile_commands.json entry, a file still compiles, with a command clice guesses. A project without any database is told so in a message the editor shows, and when the guess leaves an include unresolved, a warning at the top of the file explains why and links to the setup guide. Once the database lists the file, the warning goes, and the errors left are the code's own.
Tags
Deprecatedmarks-Wdeprecateddiagnostics and clang-tidy findings about deprecated headers and aliases.Unnecessarymarks unused variable and parameter warnings andmisc-unused-*findings.
Publishing
- A client that takes only pushed diagnostics gets them when a compile of the file finishes, and anew when it saves an edited file; closing the file clears them.
- A saved header, or an edited
.clang-tidy, brings the open files it affects up to date: a client that pulls diagnostics is asked to pull them again — Neovim 0.10 and 0.11 take no such request and show them at their next pull, after an edit — and the others get them recompiled and pushed. Diagnostics follow headers as saved, not their unsaved buffers, as in clangd. - In VS Code, Problems lists a file's diagnostics only while an editor or a tab shows the file, even when another extension keeps the file open after it is closed.
- Each diagnostic carries a
code— a warning's option (-Wunused-variable), clang's name for any other diagnostic, the clang-tidy check, or a name of clice's own (module-not-built,inferred-compile-command) — and itssource: clang, clang-tidy or clice. A clang-tidy finding links to its check's documentation, a worker crash to clice's issue tracker.
Diagnostic Suppression
A diagnostic clang gets wrong can be hidden by its code in the configuration, and comments silence the lines they are on.
Suppressing diagnostics
suppress hides diagnostics by their code
A diagnostic clang gets wrong on some code can be hidden by the code it shows with: a compiler warning's option, clang's name for any other diagnostic, or a clang-tidy check. The file's other features work as before, and clice lint still reports it.
// NOLINT, // NOLINTNEXTLINE and // NOLINTBEGIN / // NOLINTEND comments silence clang-tidy's findings on their lines, and the compiler's warnings too while clang-tidy runs on the file.
Diagnostic Actions
- The fixes the compiler and clang-tidy attach to their diagnostics are offered as quick fixes.
- A clang-tidy fix is cleaned up as
clang-tidy --fixcleans it: no,or:left dangling by what it removes. - An include a fix adds to a module unit goes into its global module fragment, opened once.
Header Diagnostics
- A
static inlinefunction a header defines and the file does not call raises no-Wunused-function(clangd#1211). - A declaration used only inside a header's function body, which the editor skips, raises no false
-Wunused-functionor-Wunused-member-function: the background index reports the ones that are unused (clangd#363, clangd#636).
clang-tidy Integration
clang-tidy runs on open files with the checks the project's .clang-tidy enables, and its findings show beside the compiler's.
clang-tidy findings
clang-tidy runs on open files with the checks the nearest .clang-tidy enables
Each finding names its check and links to the check's documentation. The checks come from the nearest .clang-tidy above the file, as clang-tidy itself reads it.
Without a configuration file
Without a .clang-tidy, a small set of checks runs
A project with no .clang-tidy still gets a few checks that rarely misfire, such as unused declarations, which an editor shows faded.
Checks left out
A check too slow for an editor is named, not dropped silently
Open files run neither the checks too slow for an editor nor those unreliable on code being edited. clice names the slow ones the .clang-tidy enables once, with how to run them; clice lint runs both.
Silencing with NOLINT
NOLINT comments silence findings on their line, and compiler warnings too
// NOLINT silences its own line and // NOLINTNEXTLINE the next, for every check or the ones named in parentheses. While clang-tidy runs on the file, they silence compiler warnings on those lines as well.
Fixes as quick fixes
A finding that carries a fix offers it as a quick fix
The fix a check attaches to its finding is offered among the quick fixes at the finding; applying it clears the finding.
Turning clang-tidy off
clang_tidy = false keeps clang-tidy off open files
With clang-tidy off, open files show only the compiler's diagnostics, whatever the .clang-tidy enables.
Running the slow checks
slow_clang_tidy_checks = true also runs the checks too slow for an editor
Checks too slow for an editor, such as misc-const-correctness, run on open files only when asked for: every compile of the file waits for them.
- Checks too slow for an editor run on open files only when
[diagnostics] slow_clang_tidy_checksasks for them, and unless it saysfalseclice names the ones it leaves out; those unreliable on code being edited are always left out;clice lintruns them all. performance-use-std-moveis left out of both the editor andclice lint: in the LLVM clice is built on, it crashes on classes read from a PCH or a module..clang-tidyedits apply to open files at their next compile.- A crash of a clang-tidy check pauses clang-tidy on that file, not its other features.
- clang-tidy's warnings that originate in macros of system headers are left out (clangd#1587, clangd#2000).
- A malformed
.clang-tidyis reported at the top of the files it configures, and runs no check (clangd#2313). clice lintlists the warnings of the whole project (clangd#1973).
