This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}),
which is a universal on-the-fly syntax checker for GNU Emacs.
-Copyright @copyright{} 2004-2011
-Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs misc features
@direntry
* Flymake: (flymake). A universal on-the-fly syntax checker.
@end direntry
@ifnottex
@node Top
@top GNU Flymake
-@insertcopying
+@insertcopying
@end ifnottex
@menu
Flymake is a universal on-the-fly syntax checker implemented as an
Emacs minor mode. Flymake runs the pre-configured syntax check tool
-(compiler for C++ files, @code{perl} for perl files, etc.) in the
+(compiler for C++ files, @code{perl} for perl files, etc.)@: in the
background, passing it a temporary copy of the current buffer, and
parses the output for known error/warning message patterns. Flymake
-then highlights erroneous lines (i.e. lines for which at least one
+then highlights erroneous lines (i.e., lines for which at least one
error or warning has been reported by the syntax check tool), and
displays an overall buffer status in the mode line. Status information
displayed by Flymake contains total number of errors and warnings
@multitable @columnfractions 0.25 0.75
@item Flymake* or Flymake:E/W*
@tab Flymake is currently running. For the second case, E/W contains the
- error and warning count for the previous run.
+error and warning count for the previous run.
@item Flymake
@tab Syntax check is not running. Usually this means syntax check was
- successfully passed (no errors, no warnings). Other possibilities are:
- syntax check was killed as a result of executing
- @code{flymake-compile}, or syntax check cannot start as compilation
- is currently in progress.
+successfully passed (no errors, no warnings). Other possibilities are:
+syntax check was killed as a result of executing
+@code{flymake-compile}, or syntax check cannot start as compilation
+is currently in progress.
@item Flymake:E/W
@tab Number of errors/warnings found by the syntax check process.
@multitable @columnfractions 0.25 0.75
@item CFGERR
@tab Syntax check process returned nonzero exit code, but no
- errors/warnings were reported. This indicates a possible configuration
- error (for example, no suitable error message patterns for the
- syntax check tool).
+errors/warnings were reported. This indicates a possible configuration
+error (for example, no suitable error message patterns for the
+syntax check tool).
@item NOMASTER
@tab Flymake was unable to find master file for the current buffer.
getfname-function)} for configuring syntax check tools. @xref{Adding
support for a new syntax check tool}.
+@ignore
@item flymake-buildfile-dirs
A list of directories (relative paths) for searching a
buildfile. @xref{Locating the buildfile}.
+@end ignore
@item flymake-master-file-dirs
A list of directories for searching a master file. @xref{Locating a
A custom face for highlighting lines for which at least one warning
and no errors have been reported.
+@item flymake-error-bitmap
+A bitmap used in the fringe to mark lines for which an error has
+been reported.
+
+@item flymake-warning-bitmap
+A bitmap used in the fringe to mark lines for which a warning has
+been reported.
+
+@item flymake-fringe-indicator-position
+Which fringe (if any) should show the warning/error bitmaps.
+
@end table
@node Adding support for a new syntax check tool
@cindex Adding support for a new syntax check tool
@menu
-* Example -- Configuring a tool called directly::
-* Example -- Configuring a tool called via make::
+* Example---Configuring a tool called directly::
+* Example---Configuring a tool called via make::
@end menu
Syntax check tools are configured using the
The following sections contain some examples of configuring Flymake
support for various syntax check tools.
-@node Example -- Configuring a tool called directly
-@subsection Example -- Configuring a tool called directly
+@node Example---Configuring a tool called directly
+@subsection Example---Configuring a tool called directly
@cindex Adding support for perl
In this example, we will add support for @code{perl} as a syntax check
flymake-err-line-patterns))
@end lisp
-@node Example -- Configuring a tool called via make
-@subsection Example -- Configuring a tool called via make
+@node Example---Configuring a tool called via make
+@subsection Example---Configuring a tool called via make
@cindex Adding support for C (gcc+make)
In this example we will add support for C files syntax checked by
-@code{gcc} called via @code{make}.
+@command{gcc} called via @command{make}.
We're not required to write any new functions, as Flymake already has
-functions for @code{make}. We just add a new entry to the
+functions for @command{make}. We just add a new entry to the
@code{flymake-allowed-file-name-masks}:
@lisp
flymake-allowed-file-name-masks))
@end lisp
-@code{flymake-simple-make-init} builds the following @code{make}
+@code{flymake-simple-make-init} builds the following @command{make}
command line:
@lisp
@verbatim
check-syntax:
- gcc -o nul -S ${CHK_SOURCES}
+ gcc -o /dev/null -S ${CHK_SOURCES}
@end verbatim
-The format of error messages reported by @code{gcc} is already
+@noindent
+The format of error messages reported by @command{gcc} is already
supported by Flymake, so we don't have to add a new entry to
-@code{flymake-err-line-patterns}.
+@code{flymake-err-line-patterns}. Note that if you are using
+Automake, you may want to replace @code{gcc} with the standard
+Automake variable @code{COMPILE}:
+
+@verbatim
+check-syntax:
+ $(COMPILE) -o /dev/null -S ${CHK_SOURCES}
+@end verbatim
@node Flymake Implementation
@chapter Flymake Implementation
Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}.
Flymake first determines whether it is able to do syntax
check. It then saves a copy of the buffer in a temporary file in the
-buffer's directory (or in the system temp directory -- for java
+buffer's directory (or in the system temp 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 number, type and text) is
@ref{Adding support for a new syntax check tool}.
Flymake contains implementations of all functionality required to
-support different syntax check modes described above (making
-temporary copies, finding master files, etc.), as well as some
-tool-specific (routines for @code{make}, @code{Ant}, etc.) code.
+support different syntax check modes described above (making temporary
+copies, finding master files, etc.), as well as some tool-specific
+(routines for Make, Ant, etc.)@: code.
@node Making a temporary copy
way to implement the desired behavior.
The default implementation, @code{flymake-get-project-include-dirs-imp},
-uses a @code{make} call. This requires a correct base directory, that is, a
-directory containing a correct @code{Makefile}, to be determined.
+uses a @command{make} call. This requires a correct base directory, that is, a
+directory containing a correct @file{Makefile}, to be determined.
As obtaining the project include directories might be a costly operation, its
return value is cached in the hash table. The cache is cleared in the beginning
Flymake 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 @code{make} for a more complicated case of a
+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 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 using some build tool, like
-@code{make} or @code{Ant}.
+Make or Ant.
-All @code{make} configuration data is usually stored in a file called
+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.
Special function, @code{flymake-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. A customizable variable
+for possible master files.
+@ignore
+A customizable variable
@code{flymake-buildfile-dirs} holds a list of relative paths to the
-buildfile. They are checked sequentially until a buildfile is found. In case
-there's no build file, syntax check is aborted.
+buildfile. They are checked sequentially until a buildfile is found.
+@end ignore
+In case there's no build file, syntax check is aborted.
Buildfile values are also cached.
@code{flymake-warnline}. Errors belonging outside the current
buffer are considered to belong to line 1 of the current buffer.
+@c This manual does not use vindex.
+@c @vindex flymake-fringe-indicator-position
+@c @vindex flymake-error-bitmap
+@c @vindex flymake-warning-bitmap
+If the option @code{flymake-fringe-indicator-position} is non-@code{nil},
+errors and warnings are also highlighted in the left or right fringe,
+using the bitmaps specified by @code{flymake-error-bitmap}
+and @code{flymake-warning-bitmap}.
+
@node Interaction with other modes
@section Interaction with other modes
@cindex Interaction with other modes