mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-27 10:54:40 +00:00
Improve the Flymake manual
* doc/misc/flymake.texi: Add a 'coding' cookie. Add a @syncodeindex directive for @vindex. Use 2 spaces between sentences. Lower-case @cindex entries. (Overview of Flymake): Fix use of @itemize and @pxref. Fix punctuation and markup. (Backend exceptions): Use @emph instead of @dfn. Add more indexing. (Customizable variables, Extending Flymake): Improve wording. (Flymake error types): Fix usage of @itemize. Improve wording. (Backend functions): Fix punctuation. Fix markup. Add a cross-reference to ELisp manual. (Flymake utility functions): Add a cross-reference to ELisp manual. (An annotated example backend): Fix punctuation and typos. (Flymake mode, Running the syntax check) (Navigating to error lines, Backend exceptions) (Customizable variables, Flymake error types, Backend functions) (Flymake utility functions, Proc customization variables) (Locating a master file, Locating the buildfile) (Starting the syntax check process, Parsing the output) (Interaction with other modes): Fix indexing. Add index entries for functions, variables, and concepts.
This commit is contained in:
Eli Zaretskii
parent
44c6401733
commit
00adeb43e9
@ -1,4 +1,4 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
\input texinfo @c -*-texinfo; coding: utf-8 -*-
|
||||
@comment %**start of header
|
||||
@setfilename ../../info/flymake.info
|
||||
@set VERSION 0.3
|
||||
@ -6,6 +6,8 @@
|
||||
@settitle GNU Flymake @value{VERSION}
|
||||
@include docstyle.texi
|
||||
@syncodeindex pg cp
|
||||
@syncodeindex vr cp
|
||||
@syncodeindex fn cp
|
||||
@comment %**end of header
|
||||
|
||||
@copying
|
||||
@ -61,20 +63,20 @@ modify this GNU manual.''
|
||||
|
||||
@node Overview of Flymake
|
||||
@chapter Overview
|
||||
@cindex Overview of Flymake
|
||||
@cindex overview of flymake
|
||||
|
||||
Flymake is a universal on-the-fly buffer checker implemented as an
|
||||
Emacs minor mode. When enabled, Flymake visually annotates the buffer
|
||||
Emacs minor mode. When enabled, Flymake visually annotates the buffer
|
||||
with diagnostic information coming from one or more different sources,
|
||||
or @dfn{backends}.
|
||||
|
||||
Flymake annotates the buffer by highlighting problematic buffer
|
||||
regions with a special space. It displays an overall buffer status in
|
||||
regions with a special space. It displays an overall buffer status in
|
||||
the mode line containing totals for different types of diagnostics.
|
||||
|
||||
@code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are
|
||||
commands that allow easy navigation to the next/previous erroneous
|
||||
line, respectively. If might be a good idea to map them to @kbd{M-n}
|
||||
line, respectively. If might be a good idea to map them to @kbd{M-n}
|
||||
and @kbd{M-p} in @code{flymake-mode}, by adding to your init file:
|
||||
|
||||
@lisp
|
||||
@ -85,42 +87,44 @@ and @kbd{M-p} in @code{flymake-mode}, by adding to your init file:
|
||||
Syntax check is done ``on-the-fly''. It is started whenever
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{flymake-mode} is started, unless
|
||||
@code{flymake-start-on-flymake-mode} is nil.
|
||||
@item
|
||||
@code{flymake-mode} is started, unless
|
||||
@code{flymake-start-on-flymake-mode} is nil.
|
||||
|
||||
@item a newline character is added to the buffer, unless
|
||||
@code{flymake-start-syntax-check-on-newline} is nil.
|
||||
@item
|
||||
a newline character is added to the buffer, unless
|
||||
@code{flymake-start-syntax-check-on-newline} is nil.
|
||||
|
||||
@item some changes were made to the buffer more than @code{0.5}
|
||||
seconds ago (the delay is configurable in
|
||||
@code{flymake-no-changes-timeout}).
|
||||
@item
|
||||
some changes were made to the buffer more than @code{0.5} seconds ago
|
||||
(the delay is configurable in @code{flymake-no-changes-timeout}).
|
||||
@end itemize
|
||||
|
||||
Flymake is a universal syntax checker in the sense that it's easily
|
||||
extended to support new backends @pxref{Extending Flymake}.
|
||||
extended to support new backends (@pxref{Extending Flymake}).
|
||||
|
||||
Historically, Flymake used to accept diagnostics from a single, albeit
|
||||
reasonably flexible, backend.
|
||||
|
||||
This backend isn't (yet) obsolete and so is still available as a
|
||||
fallback and active by default(@pxref{The legacy Proc backend}). It works by
|
||||
This backend isn't (yet) obsolete, and so is still available as a
|
||||
fallback and active by default (@pxref{The legacy Proc backend}). It works by
|
||||
selecting a syntax check tool from a preconfigured list (compiler for
|
||||
C++ files, @code{perl} for perl files, etc.), and executing it in the
|
||||
C@t{++} files, @command{perl} for Perl files, etc.), and executing it in the
|
||||
background, passing it a temporary file which is a copy of the current
|
||||
buffer, and parsing the output for known error/warning message
|
||||
patterns.
|
||||
|
||||
@node Installing Flymake
|
||||
@chapter Installing
|
||||
@cindex Installing Flymake
|
||||
@cindex installing flymake
|
||||
|
||||
Flymake is included with Emacs and its main commands, like
|
||||
@code{flymake-mode}, are autoloaded. This means there is usually
|
||||
@code{flymake-mode}, are autoloaded. This means there is usually
|
||||
nothing to do by way of installation.
|
||||
|
||||
@node Using Flymake
|
||||
@chapter Using Flymake
|
||||
@cindex Using Flymake
|
||||
@cindex using flymake
|
||||
|
||||
@menu
|
||||
* Flymake mode::
|
||||
@ -134,15 +138,16 @@ nothing to do by way of installation.
|
||||
@node Flymake mode
|
||||
@section Flymake mode
|
||||
@cindex flymake-mode
|
||||
@cindex activating flymake-mode
|
||||
|
||||
Flymake is an Emacs minor mode. To use Flymake, you
|
||||
must first activate @code{flymake-mode} by using the
|
||||
@code{flymake-mode} function.
|
||||
must first activate @code{flymake-mode} by using the command
|
||||
@kbd{flymake-mode}.
|
||||
|
||||
Instead of manually activating @code{flymake-mode}, you can configure
|
||||
Flymake to automatically enable @code{flymake-mode} upon opening any
|
||||
Emacs to automatically enable @code{flymake-mode} upon opening any
|
||||
file for which syntax check is possible. To do so, place the following
|
||||
line in @code{.emacs}:
|
||||
line in your @file{~/.emacs}:
|
||||
|
||||
@lisp
|
||||
(add-hook 'find-file-hook 'flymake-find-file-hook)
|
||||
@ -150,30 +155,32 @@ line in @code{.emacs}:
|
||||
|
||||
@node Running the syntax check
|
||||
@section Running the syntax check
|
||||
@cindex Manually starting the syntax check
|
||||
@cindex manually starting syntax check
|
||||
@cindex syntax check, start manually
|
||||
|
||||
@findex flymake-start
|
||||
When @code{flymake-mode} is active, syntax check is started
|
||||
automatically on any of the three conditions mentioned above. Syntax
|
||||
check can also be started manually by using the @code{flymake-start}
|
||||
command.
|
||||
automatically on any of the three conditions mentioned in
|
||||
@ref{Overview of Flymake}. Syntax check can also be started manually
|
||||
by typing the @kbd{M-x flymake-start @key{RET}} command.
|
||||
|
||||
@node Navigating to error lines
|
||||
@section Navigating to error lines
|
||||
@cindex Navigating to error lines
|
||||
@cindex navigating to error lines
|
||||
|
||||
After syntax check is completed, lines for which at least one error or
|
||||
warning has been reported are highlighted, and total number of errors
|
||||
warning has been reported are highlighted, and the total number of errors
|
||||
and warning is shown in the mode line. Use the following functions to
|
||||
navigate the highlighted lines:
|
||||
|
||||
@table @code
|
||||
|
||||
@findex flymake-goto-next-error
|
||||
@item flymake-goto-next-error
|
||||
Moves point to the next erroneous line, if any.
|
||||
|
||||
@findex flymake-goto-prev-error
|
||||
@item flymake-goto-prev-error
|
||||
Moves point to the previous erroneous line.
|
||||
|
||||
@end table
|
||||
|
||||
If the user option @code{flymake-wrap-around} is active
|
||||
@ -196,7 +203,7 @@ where questioned.
|
||||
@item @code{!}
|
||||
@tab All the configured Flymake backends have disabled themselves.
|
||||
Left-clicking Flymake's mode line indicator pops up a menu listing the
|
||||
option to visit Flymake's log buffer. In this buffer these situations
|
||||
option to visit Flymake's log buffer. In this buffer these situations
|
||||
can be investigated.
|
||||
|
||||
@item @code{?}
|
||||
@ -210,38 +217,48 @@ check process.
|
||||
|
||||
@node Backend exceptions
|
||||
@section Backend exceptions
|
||||
@cindex Logging
|
||||
@cindex Backend exceptions
|
||||
@cindex backend exceptions
|
||||
|
||||
@cindex disabled backends
|
||||
@cindex backends, disabled
|
||||
Some backends may take longer than others to respond or complete, and
|
||||
some may decide to @dfn{disable} themselves if they are not suitable
|
||||
for the current buffer. A disabled backend is not tried again for
|
||||
some may decide to @emph{disable} themselves if they are not suitable
|
||||
for the current buffer. A disabled backend is not tried again for
|
||||
future checks of the current buffer.
|
||||
|
||||
@findex flymake-reporting-backends
|
||||
@findex flymake-running-backends
|
||||
@findex flymake-disabled-backends
|
||||
The commands @code{flymake-reporting-backends},
|
||||
@code{flymake-running-backends} and @code{flymake-disabled-backends}
|
||||
inform on the specific situation.
|
||||
show the backends currently used and those which are disabled.
|
||||
|
||||
Toggling @code{flymake-mode} off and on again or invoking
|
||||
@cindex reset disabled backends
|
||||
Toggling @code{flymake-mode} off and on again, or invoking
|
||||
@code{flymake-start} with a prefix argument is one way to reset the
|
||||
disabled backend list so they will be tried again in the next check.
|
||||
disabled backend list, so that they will be tried again in the next check.
|
||||
|
||||
@cindex logging
|
||||
@cindex flymake logging
|
||||
Flymake also uses a simple logging facility for indicating important points
|
||||
in the control flow. The logging facility sends logging messages to
|
||||
the @file{*Flymake log*} buffer. The information logged can be used for
|
||||
resolving various problems related to Flymake.
|
||||
|
||||
@vindex warning-minimum-log-level
|
||||
@vindex warning-minimum-level
|
||||
Logging output is controlled by the Emacs @code{warning-minimum-log-level}
|
||||
and @code{warning-minimum-level} variables.
|
||||
|
||||
@node Customizable variables
|
||||
@section Customizable variables
|
||||
@cindex Customizable variables
|
||||
@cindex customizable variables
|
||||
@cindex variables for customizing flymake
|
||||
|
||||
This section summarizes customization variables used for the
|
||||
configuration of the Flymake user interface.
|
||||
|
||||
@table @code
|
||||
@vtable @code
|
||||
@item flymake-no-changes-timeout
|
||||
If any changes are made to the buffer, syntax check is automatically
|
||||
started after this many seconds, unless the user makes another change,
|
||||
@ -249,7 +266,7 @@ which resets the timer.
|
||||
|
||||
@item flymake-start-syntax-check-on-newline
|
||||
A boolean flag indicating whether to start syntax check immediately
|
||||
after a newline character is added to the buffer.
|
||||
after a newline character is inserted into the buffer.
|
||||
|
||||
@item flymake-start-on-flymake-mode
|
||||
A boolean flag indicating whether to start syntax check immediately
|
||||
@ -281,12 +298,11 @@ Which fringe (if any) should show the warning/error bitmaps.
|
||||
@item flymake-wrap-around
|
||||
If non-nil, moving to errors with @code{flymake-goto-next-error} and
|
||||
@code{flymake-goto-prev-error} wraps around buffer boundaries.
|
||||
|
||||
@end table
|
||||
@end vtable
|
||||
|
||||
@node Extending Flymake
|
||||
@chapter Extending Flymake
|
||||
@cindex Extending Flymake
|
||||
@cindex extending flymake
|
||||
|
||||
Flymake can primarily be extended in one of two ways:
|
||||
|
||||
@ -299,7 +315,7 @@ different backends.
|
||||
By adding a new buffer-checking backend.
|
||||
@end enumerate
|
||||
|
||||
The following sections discuss each approach in detail:
|
||||
The following sections discuss each approach in detail.
|
||||
|
||||
@menu
|
||||
* Flymake error types::
|
||||
@ -308,7 +324,10 @@ The following sections discuss each approach in detail:
|
||||
|
||||
@node Flymake error types
|
||||
@section Customizing Flymake error types
|
||||
@cindex customizing error types
|
||||
@cindex error types, customization
|
||||
|
||||
@vindex flymake-diagnostic-types-alist
|
||||
The variable @code{flymake-diagnostic-types-alist} is looked up by
|
||||
Flymake every time an annotation for a diagnostic is created in the
|
||||
buffer. Specifically, this variable holds a table of correspondence
|
||||
@ -326,49 +345,60 @@ presents the diagnostic:
|
||||
|
||||
@itemize
|
||||
|
||||
@item @code{bitmap}, an image displayed in the fringe according to
|
||||
@item
|
||||
@cindex bitmap of diagnostic
|
||||
@code{bitmap}, an image displayed in the fringe according to
|
||||
@code{flymake-fringe-indicator-position}. The value actually follows
|
||||
the syntax of @code{flymake-error-bitmap}(@pxref{Customizable
|
||||
the syntax of @code{flymake-error-bitmap} (@pxref{Customizable
|
||||
variables}). It is overridden by any @code{before-string} overlay
|
||||
property.
|
||||
|
||||
@item @code{severity} is a non-negative integer specifying the diagnostic's
|
||||
severity. The higher, the more serious. If the overlay property
|
||||
@code{priority} is not specified, @code{severity} is used to set it
|
||||
and help sort overlapping overlays.
|
||||
@item
|
||||
@cindex severity of diagnostic
|
||||
@code{severity} is a non-negative integer specifying the diagnostic's
|
||||
severity. The higher the value, the more serious is the error. If
|
||||
the overlay property @code{priority} is not specified, @code{severity}
|
||||
is used to set it and help sort overlapping overlays.
|
||||
|
||||
@item Every property pertaining to overlays (@pxref{Overlay
|
||||
Properties,,, elisp, The Emacs Lisp Reference Manual}), except
|
||||
@code{category} and @code{evaporate}. These properties are used to
|
||||
affect the appearance of Flymake annotations.
|
||||
@item
|
||||
Every property pertaining to overlays (@pxref{Overlay Properties,,,
|
||||
elisp, The Emacs Lisp Reference Manual}), except @code{category} and
|
||||
@code{evaporate}. These properties are used to affect the appearance
|
||||
of Flymake annotations.
|
||||
|
||||
As an example, here's how to make errors (diagnostics of the type
|
||||
@code{:error}) stand out even more prominently in the buffer, by
|
||||
raising the characters with a @code{display} overlay property.
|
||||
raising the characters using a @code{display} overlay property.
|
||||
|
||||
@example
|
||||
(push '(display . (raise 1.2))
|
||||
(cdr (assoc :error flymake-diagnostic-types-alist)))
|
||||
@end example
|
||||
|
||||
@item @code{flymake-category} is a symbol whose property list is considered
|
||||
a default for missing values of any other properties.
|
||||
@item
|
||||
@vindex flymake-category
|
||||
@code{flymake-category} is a symbol whose property list is considered
|
||||
the default for missing values of any other properties.
|
||||
@end itemize
|
||||
|
||||
@cindex predefined diagnostic types
|
||||
@vindex flymake-error
|
||||
@vindex flymake-warning
|
||||
@vindex flymake-note
|
||||
Three default diagnostic types, @code{:error}, @code{:warning} and
|
||||
@code{:note} are predefined in
|
||||
@code{flymake-diagnostic-types-alist}. By default each lists a single
|
||||
@code{flymake-diagnostic-types-alist}. By default each lists a single
|
||||
@code{flymake-category} property whose value is, respectively, the
|
||||
symbols @code{flymake-error}, @code{flymake-warning} and
|
||||
@code{flymake-note}.
|
||||
|
||||
These category symbols' plists is where the values of customizable
|
||||
variables and faces such as @code{flymake-error-bitmap} are found.
|
||||
Thus, if you change their plists, Flymake may stop honouring these
|
||||
Thus, if you change their plists, Flymake may stop honoring these
|
||||
user customizations.
|
||||
|
||||
The @code{flymake-category} special property is also especially useful
|
||||
to backend authors that create diagnostics objects with non-default
|
||||
for backends which create diagnostics objects with non-default
|
||||
types that differ from an existing type by only a few properties
|
||||
(@pxref{Flymake utility functions}).
|
||||
|
||||
@ -383,8 +413,9 @@ priority but without an overlay face.
|
||||
(flymake-category . flymake-note))))
|
||||
@end example
|
||||
|
||||
@vindex flymake-text
|
||||
As you might have guessed, Flymake's annotations are implemented as
|
||||
overlays(@pxref{Overlays,,, elisp, The Emacs Lisp Reference Manual}).
|
||||
overlays (@pxref{Overlays,,, elisp, The Emacs Lisp Reference Manual}).
|
||||
Along with the properties that you specify for the specific type of
|
||||
diagnostic, Flymake adds the property @code{flymake-text} to these
|
||||
overlays, and sets it to the message string that the backend used to
|
||||
@ -392,8 +423,8 @@ describe the diagnostic.
|
||||
|
||||
Since overlays also support arbitrary keymaps, you can use this
|
||||
property @code{flymake-text} to create interactive annotations, such
|
||||
as in the following example binding a @kbd{mouse-3} event (middle
|
||||
mouse button click) to an internet search for the text of a
|
||||
as in the following example of binding a @kbd{mouse-3} event (middle
|
||||
mouse button click) to an Internet search for the text of a
|
||||
@code{:warning} or @code{:error}.
|
||||
|
||||
@example
|
||||
@ -424,82 +455,92 @@ mouse button click) to an internet search for the text of a
|
||||
|
||||
@node Backend functions
|
||||
@section Backend functions
|
||||
@cindex backend functions
|
||||
|
||||
@vindex flymake-diagnostic-functions
|
||||
Flymake backends are Lisp functions placed in the special hook
|
||||
@code{flymake-diagnostic-functions}.
|
||||
|
||||
A backend's responsibility is to diagnose the contents of a buffer for
|
||||
problems, registering these problem's positions, type and summarized
|
||||
description. This information is collected in the form of diagnostic
|
||||
objects created with the function @code{flymake-make-diagnostic} and
|
||||
then handed over to Flymake, which then proceeds to annotate the
|
||||
problems, registering the problem's positions, type, and summary
|
||||
description. This information is collected in the form of diagnostic
|
||||
objects created by the function @code{flymake-make-diagnostic}
|
||||
(@pxref{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 the two key events of the interaction between Flymake
|
||||
and backend. Each such event corresponds to a well-defined function
|
||||
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, and second one in the reverse direction via a
|
||||
callback. To be usable, backends must adhere to both.
|
||||
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:
|
||||
|
||||
@itemize
|
||||
@item the first argument is always @var{report-fn}, a callback function
|
||||
@item
|
||||
the first argument is always @var{report-fn}, a callback function
|
||||
detailed below;
|
||||
|
||||
@item the remaining arguments are keyword-value pairs in the
|
||||
form (@var{:key} @var{value} @var{:key2} @var{value2}...). Currently,
|
||||
@item
|
||||
the remaining arguments are keyword-value pairs of the
|
||||
form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. Currently,
|
||||
Flymake provides no such arguments, but backend functions must be
|
||||
prepared to accept (and possibly ignore) any number of them.
|
||||
@end itemize
|
||||
|
||||
Whenever Flymake or the user decides to re-check the buffer, backend
|
||||
functions are called as detailed above and are expected to initiate
|
||||
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 computationally expensive, as
|
||||
is often the case in large buffers, that slower task should be
|
||||
scheduled for the future using asynchronous processes or other
|
||||
asynchronous mechanisms.
|
||||
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
|
||||
(@pxref{Asynchronous Processes,,, elisp, 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
|
||||
(@pxref{Backend exceptions}).
|
||||
|
||||
If the function returns, Flymake considers the backend to be
|
||||
@dfn{running}. If it has not done so already, the backend is expected
|
||||
@dfn{running}. If it has not done so already, the backend is expected
|
||||
to call the function @var{report-fn} passed to it, at which point
|
||||
Flymake considers the backend to be @dfn{reporting}. Backends call
|
||||
Flymake considers the backend to be @dfn{reporting}. Backends call
|
||||
@var{report-fn} by passing it a single argument @var{report-action}
|
||||
followed by an optional list of keyword-value pairs in the form
|
||||
(@var{:report-key} @var{value} @var{:report-key2} @var{value2}...).
|
||||
followed by an optional list of keyword-value pairs of the form
|
||||
@w{@code{(@var{:report-key} @var{value} @var{:report-key2} @var{value2}...)}}.
|
||||
|
||||
Currently accepted values for @var{report-action} are:
|
||||
|
||||
@itemize
|
||||
@item A (possibly empty) list of diagnostic objects created with
|
||||
@item
|
||||
A (possibly empty) list of diagnostic objects created by
|
||||
@code{flymake-make-diagnostic}, causing Flymake to annotate the
|
||||
buffer with this information.
|
||||
|
||||
A backend may call @var{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
|
||||
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.
|
||||
|
||||
@item The symbol @code{:panic}, signaling that the backend has encountered
|
||||
@item
|
||||
The symbol @code{:panic}, signaling that the backend has encountered
|
||||
an exceptional situation and should be disabled.
|
||||
@end itemize
|
||||
|
||||
Currently accepted @var{report-key} arguments are:
|
||||
|
||||
@itemize
|
||||
@item @code{:explanation}: value should give user-readable
|
||||
@item
|
||||
@code{:explanation}, whose value should give user-readable
|
||||
details of the situation encountered, if any.
|
||||
|
||||
@item @code{:force}: value should be a boolean suggesting
|
||||
@item
|
||||
@code{:force}, whose value should be a boolean suggesting
|
||||
that Flymake consider the report even if it was somehow
|
||||
unexpected.
|
||||
@end itemize
|
||||
@ -511,7 +552,9 @@ unexpected.
|
||||
|
||||
@node Flymake utility functions
|
||||
@subsection Flymake utility functions
|
||||
@cindex utility functions
|
||||
|
||||
@cindex create diagnostic object
|
||||
Before delivering them to Flymake, backends create diagnostic objects
|
||||
by calling the function @code{flymake-make-diagnostic}.
|
||||
|
||||
@ -522,36 +565,41 @@ Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to
|
||||
of the problem detected in this region.
|
||||
@end deffn
|
||||
|
||||
@cindex buffer position from line and column number
|
||||
It is often the case with external syntax tools that a diagnostic's
|
||||
position is reported in terms of a line number, and sometimes a column
|
||||
number. To convert this information into a buffer position, backends
|
||||
number. To convert this information into a buffer position, backends
|
||||
can use the following function:
|
||||
|
||||
@deffn Function flymake-diag-region buffer line &optional col
|
||||
Compute @var{buffer}'s region (@var{beg} . @var{end}) corresponding to
|
||||
Compute @var{buffer}'s region (@var{beg} . @var{end}) corresponding to
|
||||
@var{line} and @var{col}. If @var{col} is nil, return a region just
|
||||
for @var{line}. Return nil if the region is invalid.
|
||||
@end deffn
|
||||
|
||||
@cindex add a log message
|
||||
For troubleshooting purposes, backends may record arbitrary
|
||||
exceptional or erroneous situations into the Flymake log
|
||||
buffer (@pxref{Backend exceptions}):
|
||||
|
||||
@deffn Macro flymake-log level msg &optional args
|
||||
Log, at level @var{level}, the message @var{msg} formatted with
|
||||
@var{args}. @var{level} is passed to @code{display-warning}, which is
|
||||
@var{args}. @var{level} is passed to @code{display-warning}
|
||||
(@pxref{Warning Basics,,, elisp, The Emacs Lisp reference Manual}), which is
|
||||
used to display the warning in Flymake's log buffer.
|
||||
@end deffn
|
||||
|
||||
@node An annotated example backend
|
||||
@subsection An annotated example backend
|
||||
@cindex example of backend
|
||||
@cindex backend, annotated example
|
||||
|
||||
This section presents an annotated example of a complete working
|
||||
Flymake backend. The example illustrates the process of writing a
|
||||
Flymake backend. The example illustrates the process of writing a
|
||||
backend as outlined above.
|
||||
|
||||
The backend in question is used for checking Ruby source files. It
|
||||
uses asynchronous processes (@pxref{Asynchronous Processes,,, elisp,
|
||||
The backend in question is used for checking Ruby source files. It
|
||||
uses asynchronous sub-processes (@pxref{Asynchronous Processes,,, elisp,
|
||||
The Emacs Lisp Reference Manual}), a common technique for performing
|
||||
parallel processing in Emacs.
|
||||
|
||||
@ -569,39 +617,39 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
|
||||
(unless (executable-find
|
||||
"ruby") (error "Cannot find a suitable ruby"))
|
||||
;; If a live process launched in an earlier check was found, that
|
||||
;; process is killed. When that process's sentinel eventually runs,
|
||||
;; it will notice its obsoletion, since if have since reset
|
||||
;; process is killed. When that process's sentinel eventually runs,
|
||||
;; it will notice its obsoletion, since it have since reset
|
||||
;; `ruby-flymake-proc' to a different value
|
||||
;;
|
||||
(when (process-live-p ruby--flymake-proc)
|
||||
(kill-process ruby--flymake-proc))
|
||||
|
||||
;; save the current buffer, the narrowing restrinction, remove any
|
||||
;; narrowing restriction
|
||||
;; Save the current buffer, the narrowing restriction, remove any
|
||||
;; narrowing restriction.
|
||||
;;
|
||||
(let ((source (current-buffer)))
|
||||
(save-restriction
|
||||
(widen)
|
||||
;; reset the `ruby--flymake-proc' process to a new process
|
||||
;; calling the ruby tool
|
||||
;; Reset the `ruby--flymake-proc' process to a new process
|
||||
;; calling the ruby tool.
|
||||
;;
|
||||
(setq
|
||||
ruby--flymake-proc
|
||||
(make-process
|
||||
:name "ruby-flymake" :noquery t :connection-type 'pipe
|
||||
;; make output goes to a temporary buffer
|
||||
;; Make output go to a temporary buffer.
|
||||
;;
|
||||
:buffer (generate-new-buffer " *ruby-flymake*")
|
||||
:command '("ruby" "-w" "-c")
|
||||
:sentinel
|
||||
(lambda (proc _event)
|
||||
;; Check that the process as indeed exited, as it might
|
||||
;; be simply suspended
|
||||
;; Check that the process has indeed exited, as it might
|
||||
;; be simply suspended.
|
||||
;;
|
||||
(when (eq 'exit (process-status proc))
|
||||
(unwind-protect
|
||||
;; Only proceed if `proc' is the same as
|
||||
;; `ruby--flymake-proc' which indicates that
|
||||
;; `ruby--flymake-proc', which indicates that
|
||||
;; `proc' is not an obsolete process.
|
||||
;;
|
||||
(if (eq proc ruby--flymake-proc)
|
||||
@ -635,8 +683,8 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
|
||||
;; check's output.
|
||||
;;
|
||||
(kill-buffer (process-buffer proc)))))))
|
||||
;; send the buffer contents to the process's stdin, followed by
|
||||
;; an EOF
|
||||
;; Send the buffer contents to the process's stdin, followed by
|
||||
;; an EOF.
|
||||
;;
|
||||
(process-send-region ruby--flymake-proc (point-min) (point-max))
|
||||
(process-send-eof ruby--flymake-proc))))
|
||||
@ -649,7 +697,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
|
||||
|
||||
@node The legacy Proc backend
|
||||
@chapter The legacy ``Proc'' backend
|
||||
@cindex The legacy Proc backend
|
||||
@cindex legacy proc backend
|
||||
|
||||
@menu
|
||||
* Proc customization variables::
|
||||
@ -664,15 +712,16 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
|
||||
* Interaction with other modes::
|
||||
@end menu
|
||||
|
||||
@findex flymake-proc-legacy-backend
|
||||
The backend @code{flymake-proc-legacy-backend} was originally designed
|
||||
to be extended for supporting new syntax check tools and error message
|
||||
patterns. It is also controlled by its own set of customization variables
|
||||
patterns. It is also controlled by its own set of customization variables
|
||||
|
||||
@node Proc customization variables
|
||||
@section Customization variables for the Proc backend
|
||||
@cindex Proc customization variables
|
||||
@cindex proc backend customization variables
|
||||
|
||||
@table @code
|
||||
@vtable @code
|
||||
@item flymake-proc-allowed-file-name-masks
|
||||
A list of @code{(filename-regexp, init-function, cleanup-function
|
||||
getfname-function)} for configuring syntax check tools. @xref{Adding
|
||||
@ -696,22 +745,22 @@ line-idx col-idx err-text-idx)}. @xref{Parsing the output}.
|
||||
|
||||
@item flymake-proc-diagnostic-type-pred
|
||||
A function to classify a diagnostic text as particular type of
|
||||
error. Should be a function taking an error text and returning one of
|
||||
the symbols indexing @code{flymake-diagnostic-types-alist}. If non-nil
|
||||
error. Should be a function taking an error text and returning one of
|
||||
the symbols indexing @code{flymake-diagnostic-types-alist}. If non-nil
|
||||
is returned but there is no such symbol in that table, a warning is
|
||||
assumed. If nil is returned, an error is assumed. Can also be a
|
||||
assumed. If nil is returned, an error is assumed. Can also be a
|
||||
regular expression that should match only warnings. This variable
|
||||
replaces the old @code{flymake-warning-re} and
|
||||
@code{flymake-warning-predicate}.
|
||||
|
||||
@item flymake-proc-compilation-prevents-syntax-check
|
||||
A flag indicating whether compilation and syntax check of the same
|
||||
file cannot be run simultaneously.
|
||||
@end table
|
||||
file cannot be run simultaneously. @xref{Interaction with other modes}.
|
||||
@end vtable
|
||||
|
||||
@node Adding support for a new syntax check tool
|
||||
@section Adding support for a new syntax check tool
|
||||
@cindex Adding support for a new syntax check tool
|
||||
@cindex adding support for a new syntax check tool
|
||||
|
||||
@menu
|
||||
* Example---Configuring a tool called directly::
|
||||
@ -753,10 +802,9 @@ will be different from the real ones, as actually the tool works with
|
||||
the temporary copy. In most cases, the default implementation
|
||||
provided by Flymake, @code{flymake-proc-get-real-file-name}, can be
|
||||
used as @code{getfname-function}.
|
||||
|
||||
@end table
|
||||
|
||||
To add support for a new syntax check tool, write corresponding
|
||||
To add support for a new syntax check tool, write the corresponding
|
||||
@code{init-function} and, optionally, @code{cleanup-function} and
|
||||
@code{getfname-function}. If the format of error messages reported by
|
||||
the new tool is not yet supported by Flymake, add a new entry to
|
||||
@ -767,10 +815,10 @@ support for various syntax check tools.
|
||||
|
||||
@node Example---Configuring a tool called directly
|
||||
@subsection Example---Configuring a tool called directly
|
||||
@cindex Adding support for perl
|
||||
@cindex adding support for perl
|
||||
|
||||
In this example, we will add support for @code{perl} as a syntax check
|
||||
tool. @code{perl} supports the @code{-c} option which does syntax
|
||||
In this example, we will add support for @command{perl} as a syntax check
|
||||
tool. @command{perl} supports the @option{-c} option which does syntax
|
||||
checking.
|
||||
|
||||
First, we write the @code{init-function}:
|
||||
@ -816,7 +864,7 @@ Finally, we add an entry to @code{flymake-proc-err-line-patterns}:
|
||||
|
||||
@node Example---Configuring a tool called via make
|
||||
@subsection Example---Configuring a tool called via make
|
||||
@cindex Adding support for C (gcc+make)
|
||||
@cindex adding support for C (gcc+make)
|
||||
|
||||
In this example we will add support for C files syntax checked by
|
||||
@command{gcc} called via @command{make}.
|
||||
@ -846,9 +894,10 @@ command line:
|
||||
"check-syntax"))
|
||||
@end lisp
|
||||
|
||||
@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}.
|
||||
@code{base-dir} is a directory containing the @file{Makefile}, see
|
||||
@ref{Locating the buildfile}.
|
||||
|
||||
Thus, @code{Makefile} must contain the @code{check-syntax} target. In
|
||||
Thus, @file{Makefile} must contain the @code{check-syntax} target. In
|
||||
our case this target might look like this:
|
||||
|
||||
@verbatim
|
||||
@ -870,11 +919,11 @@ check-syntax:
|
||||
|
||||
@node Implementation overview
|
||||
@section Implementation overview
|
||||
@cindex Syntax check models
|
||||
@cindex Master file
|
||||
@cindex syntax check models
|
||||
@cindex master file
|
||||
|
||||
@code{flymake-proc-legacy-backend} saves a copy of the buffer in a
|
||||
temporary file in the buffer's directory (or in the system temp
|
||||
temporary file in the buffer's directory (or in the system temporary
|
||||
directory, for Java files), creates a syntax check command and
|
||||
launches a process with this command. The output is parsed using a
|
||||
list of error message patterns, and error information (file name, line
|
||||
@ -893,15 +942,15 @@ Two syntax check modes are distinguished:
|
||||
@item
|
||||
Buffer can be syntax checked in a standalone fashion, that is, the
|
||||
file (its temporary copy, in fact) can be passed over to the compiler to
|
||||
do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java)
|
||||
sources.
|
||||
do the syntax check. Examples are C/C@t{++} sources (@file{.c},
|
||||
@file{.cpp}) and Java (@file{.java}).
|
||||
|
||||
@item
|
||||
Buffer can be syntax checked, but additional file, called master file,
|
||||
is required to perform this operation. A master file is a file that
|
||||
includes the current file, so that running a syntax check tool on it
|
||||
will also check syntax in the current file. Examples are C/C++ (.h,
|
||||
.hpp) headers.
|
||||
will also check syntax in the current file. Examples are C/C@t{++}
|
||||
headers (@file{.h}, @file{.hpp}).
|
||||
|
||||
@end enumerate
|
||||
|
||||
@ -916,8 +965,7 @@ tool-specific (routines for Make, Ant, etc.)@: code.
|
||||
|
||||
@node Making a temporary copy
|
||||
@section Making a temporary copy
|
||||
@cindex Temporary copy of the buffer
|
||||
@cindex Master file
|
||||
@cindex temporary copy of the buffer
|
||||
|
||||
After the possibility of the syntax check has been determined, a
|
||||
temporary copy of the current buffer is made so that the most recent
|
||||
@ -929,9 +977,10 @@ Things get trickier, however, when master file is involved, as it
|
||||
requires to
|
||||
|
||||
@itemize @bullet
|
||||
@item locate a master file
|
||||
@item patch it to include the current file using its new (temporary)
|
||||
name.
|
||||
@item
|
||||
locate a master file
|
||||
@item
|
||||
patch it to include the current file using its new (temporary) name.
|
||||
@end itemize
|
||||
|
||||
Locating a master file is discussed in the following section.
|
||||
@ -947,37 +996,39 @@ the syntax check tool.
|
||||
|
||||
@node Locating a master file
|
||||
@section Locating a master file
|
||||
@cindex Master file
|
||||
@cindex locating a master file
|
||||
@cindex master file, locating
|
||||
|
||||
Master file is located in two steps.
|
||||
|
||||
First, a list of possible master files is built. A simple name
|
||||
matching is used to find the files. For a C++ header @code{file.h},
|
||||
the Proc backend searches for all @code{.cpp} files in the directories
|
||||
matching is used to find the files. For a C++ header @file{file.h},
|
||||
the Proc backend searches for all @file{.cpp} files in the directories
|
||||
whose relative paths are stored in a customizable variable
|
||||
@code{flymake-proc-master-file-dirs}, which usually contains something
|
||||
like @code{("." "./src")}. No more than
|
||||
@code{flymake-proc-master-file-count-limit} entries is added to the
|
||||
master file list. The list is then sorted to move files with names
|
||||
@code{file.cpp} to the top.
|
||||
@file{file.cpp} to the top.
|
||||
|
||||
Next, each master file in a list is checked to contain the appropriate
|
||||
include directives. No more than @code{flymake-proc-check-file-limit} of each
|
||||
file are parsed.
|
||||
|
||||
For @code{file.h}, the include directives to look for are
|
||||
For @file{file.h}, the include directives to look for are
|
||||
@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each
|
||||
include is checked against a list of include directories
|
||||
(see @ref{Getting the include directories}) to be sure it points to the
|
||||
correct @code{file.h}.
|
||||
correct @file{file.h}.
|
||||
|
||||
First matching master file found stops the search. The master file is then
|
||||
patched and saved to disk. In case no master file is found, syntax check is
|
||||
aborted, and corresponding status (!) is reported in the mode line.
|
||||
aborted, and corresponding status (@samp{!}) is reported in the mode line.
|
||||
@xref{Syntax check statuses}.
|
||||
|
||||
@node Getting the include directories
|
||||
@section Getting the include directories
|
||||
@cindex Include directories (C/C++ specific)
|
||||
@cindex include directories (C/C++ specific)
|
||||
|
||||
Two sets of include directories are distinguished: system include directories
|
||||
and project include directories. The former is just the contents of the
|
||||
@ -997,25 +1048,26 @@ of every syntax check attempt.
|
||||
|
||||
@node Locating the buildfile
|
||||
@section Locating the buildfile
|
||||
@cindex Locating the buildfile
|
||||
@cindex locating the buildfile
|
||||
@cindex buildfile, locating
|
||||
@cindex Makefile, locating
|
||||
|
||||
The Proc backend can be configured to use different tools for
|
||||
performing syntax checks. For example, it can use direct compiler
|
||||
call to syntax check a perl script or a call to @command{make} for a
|
||||
more complicated case of a @code{C/C++} source. The general idea is
|
||||
that simple files, like perl scripts and html pages, can be checked by
|
||||
more complicated case of a C/C@t{++} source. The general idea is
|
||||
that simple files, like Perl scripts and @acronym{HTML} pages, can be checked by
|
||||
directly invoking a corresponding tool. Files that are usually more
|
||||
complex and generally used as part of larger projects, might require
|
||||
non-trivial options to be passed to the syntax check tool, like
|
||||
include directories for C++. The latter files are syntax checked
|
||||
include directories for C@t{++}. The latter files are syntax checked
|
||||
using some build tool, like Make or Ant.
|
||||
|
||||
All Make configuration data is usually stored in a file called
|
||||
@code{Makefile}. To allow for future extensions, Flymake uses a notion of
|
||||
buildfile to reference the 'project configuration' file.
|
||||
@file{Makefile}. To allow for future extensions, Flymake uses a notion of
|
||||
buildfile to reference the @dfn{project configuration} file.
|
||||
|
||||
@findex flymake-proc-find-buildfile
|
||||
Special function, @code{flymake-proc-find-buildfile} is provided for locating buildfiles.
|
||||
Searching for a buildfile is done in a manner similar to that of searching
|
||||
for possible master files.
|
||||
@ -1024,13 +1076,13 @@ A customizable variable
|
||||
@code{flymake-proc-buildfile-dirs} holds a list of relative paths to the
|
||||
buildfile. They are checked sequentially until a buildfile is found.
|
||||
@end ignore
|
||||
In case there's no build file, syntax check is aborted.
|
||||
In case there's no build file, the syntax check is aborted.
|
||||
|
||||
Buildfile values are also cached.
|
||||
|
||||
@node Starting the syntax check process
|
||||
@section Starting the syntax check process
|
||||
@cindex Syntax check process
|
||||
@cindex syntax check process, legacy proc backend
|
||||
|
||||
The command line (command name and the list of arguments) for
|
||||
launching a process is returned by the initialization function. The
|
||||
@ -1041,16 +1093,16 @@ be killed without prompting the user.
|
||||
|
||||
@node Parsing the output
|
||||
@section Parsing the output
|
||||
@cindex Parsing the output
|
||||
@cindex parsing the output, legacy proc backend
|
||||
|
||||
The output generated by the syntax check tool is parsed in the process
|
||||
filter/sentinel using the error message patterns stored in the
|
||||
@code{flymake-proc-err-line-patterns} variable. This variable contains a
|
||||
list of items of the form @code{(regexp file-idx line-idx
|
||||
err-text-idx)}, used to determine whether a particular line is an
|
||||
list of items of the form @w{@code{(regexp file-idx line-idx
|
||||
err-text-idx)}}, used to determine whether a particular line is an
|
||||
error message and extract file name, line number and error text,
|
||||
respectively. Error type (error/warning) is also guessed by matching
|
||||
error text with the '@code{^[wW]arning}' pattern. Anything that was not
|
||||
error text with the @samp{^[wW]arning} pattern. Anything that was not
|
||||
classified as a warning is considered an error. Type is then used to
|
||||
sort error menu items, which shows error messages first.
|
||||
|
||||
@ -1058,7 +1110,7 @@ The Proc backend is also able to interpret error message patterns
|
||||
missing err-text-idx information. This is done by merely taking the
|
||||
rest of the matched line (@code{(substring line (match-end 0))}) as
|
||||
error text. This trick allows making use of a huge collection of
|
||||
error message line patterns from @code{compile.el}. All these error
|
||||
error message line patterns from @file{compile.el}. All these error
|
||||
patterns are appended to the end of
|
||||
@code{flymake-proc-err-line-patterns}.
|
||||
|
||||
@ -1069,8 +1121,8 @@ after every process launch/exit.
|
||||
|
||||
@node Interaction with other modes
|
||||
@section Interaction with other modes
|
||||
@cindex Interaction with other modes
|
||||
@cindex Interaction with compile mode
|
||||
@cindex interaction with other modes, legacy proc backend
|
||||
@cindex interaction with compile mode, legacy proc backend
|
||||
|
||||
The only mode the Proc backend currently knows about is
|
||||
@code{compile}.
|
||||
@ -1084,8 +1136,9 @@ though, was working around a locking problem with MS Visual C++
|
||||
compiler. The variable in question is
|
||||
@code{flymake-proc-compilation-prevents-syntax-check}.
|
||||
|
||||
@findex flymake-proc-compile
|
||||
The Proc backend also provides an alternative command for starting
|
||||
compilation, @code{flymake-proc-compile}. It just kills all the active
|
||||
compilation, @code{flymake-proc-compile}. It just kills all the active
|
||||
syntax check processes before calling @code{compile}.
|
||||
|
||||
@node GNU Free Documentation License
|
||||
|
||||
Loading…
Reference in New Issue
Block a user