2.2.2 Foreign and list-only diagnostics

It is possible for a given backend’s implementation to use flymake-make-diagnostic to create diagnostics for buffers or files other than the “source” buffer where Flymake was enabled. For instance, this is useful when a given backend has access to information about the health of neighboring files that are not yet visited or whose diagnostics depend on the current buffer’s state. There are two alternative ways to go about doing this:

  1. If the information about neighboring diagnostics is obtained regularly, like when each syntax-checking iteration of a .c file also reports a number of associated problems in an neighboring .h file, it is better to create so-called “foreign” diagnostics.

    This is done by passing a file name to flymake-make-diagnostic (see Flymake utility functions). Then, the resulting object is simply reported along with the other “domestic” diagnostics for the source buffer (see Backend functions). When the neighboring file is visited as a buffer and Flymake is active there, a number of supplemental annotations will appear and automatically update whenever as the “source” buffer is syntax-checked.

  2. If information about neighboring diagnostics is obtained infrequently, like when running a time-consuming and sporadic check of a large project, it is easier for the backend to modify the global variable flymake-list-only-diagnostics.

    Flymake will look up this variable when asked to compile project-wide lists of diagnostics. The backend should add one or more alist entries that look like (file-name . diags). file-name is the absolute name of the neighboring file presumed not to be visited in Emacs already, as that would mean that that buffer contains more up-to-date information on its diagnostics. diags is a list of diagnostic objects. When the neighboring file file-name is visited as a buffer and Flymake is activated there, the “list-only” diagnostics will not produce annotations for diags, as Flymake assumes that the Flymake activation in the new buffer will take care of that.