Flymake backends are Lisp functions placed in the special hook
flymake-diagnostic-functions.
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 flymake-make-diagnostic
(see Flymake utility functions), and
then handed over to Flymake, which proceeds to annotate the
buffer.
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.
The first argument passed to a backend function is always
report-fn, a callback function detailed below. Beyond it,
functions must be prepared to accept (and possibly ignore) an
arbitrary number of keyword-value pairs of the form
(:key value :key2 value2...).
Currently, Flymake may pass the following keywords and values to the backend function:
:recent-changes
The value is a list recent changes since the last time the backend
function was called for the buffer. If the list is empty, this
indicates that no changes have been recorded. If it is the first time
that this backend function is called for this activation of
flymake-mode, then this argument isn’t provided at all
(i.e. it’s not merely nil).
Each element is in the form (beg end text) where beg and end are buffer positions, and text is a string containing the text contained between those positions (if any), after the change was performed.
:changes-start and :changes-end
The value is, respectively, the minimum and maximum buffer positions
touched by the recent changes. These are provided for convenience and
only if :recent-changes is also provided.
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 in The Emacs Lisp reference manual) 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 Troubleshooting).
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
(:report-key value :report-key2 value2...).
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.
:region, a cons (beg . end) of buffer positions
indicating that the report applies to that region and that previous
reports targeting other parts of the buffer remain valid.