Flymake backends are Lisp functions placed in the special hook
A backend's responsibility is to diagnose the contents of a buffer for
problems, registering the problem's positions, type, and summary
description. This information is collected in the form of diagnostic
objects created by the function
(see Flymake utility functions), and
then handed over to Flymake, which proceeds to annotate the
A request for a buffer check, and the subsequent delivery of diagnostics, are two key events of the interaction between Flymake and backend. Each such event corresponds to a well-defined function calling convention: one for calls made by Flymake into the backend via the backend function, the other in the reverse direction via a callback. To be usable, backends must adhere to both.
Backend functions must accept an arbitrary number of arguments:
...). Currently, Flymake provides no such arguments, but backend functions must be prepared to accept (and possibly ignore) any number of them.
Whenever Flymake or the user decide to re-check the buffer, backend functions are called as detailed above, and are expected to initiate this check, but aren't in any way required to complete it before exiting: if the computation involved is expensive, as is often the case with large buffers, that slower task should be scheduled for the future using asynchronous sub-processes (see Asynchronous Processes) or other asynchronous mechanisms.
In any case, backend functions are expected to return quickly or signal an error, in which case the backend is disabled (see Backend exceptions).
If the function returns, Flymake considers the backend to be
running. If it has not done so already, the backend is expected
to call the function report-fn passed to it, at which point
Flymake considers the backend to be reporting. Backends call
report-fn by passing it a single argument report-action
followed by an optional list of keyword-value pairs of the form
Currently accepted values for report-action are:
flymake-make-diagnostic, causing Flymake to annotate the buffer with this information.
A backend may call report-fn repeatedly in this manner, but only until Flymake considers that the most recently requested buffer check is now obsolete, because, say, buffer contents have changed in the meantime. The backend is only given notice of this via a renewed call to the backend function. Thus, to prevent making obsolete reports and wasting resources, backend functions should first cancel any ongoing processing from previous calls.
:panic, signaling that the backend has encountered an exceptional situation and should be disabled.
Currently accepted report-key arguments are:
:explanation, whose value should give user-readable details of the situation encountered, if any.
:force, whose value should be a boolean suggesting that Flymake consider the report even if it was somehow unexpected.