1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename ../../info/flymake
5 @set UPDATED April 2004
6 @settitle GNU Flymake @value{VERSION}
8 @documentencoding UTF-8
10 @comment %**end of header
13 This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}),
14 which is a universal on-the-fly syntax checker for GNU Emacs.
16 Copyright @copyright{} 2004--2013 Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
23 and with the Back-Cover Texts as in (a) below. A copy of the license
24 is included in the section entitled ``GNU Free Documentation License''.
26 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
27 modify this GNU manual.''
31 @dircategory Emacs misc features
33 * Flymake: (flymake). A universal on-the-fly syntax checker.
38 @subtitle for version @value{VERSION}, @value{UPDATED}
39 @author Pavel Kobiakov(@email{pk_at_work@@yahoo.com})
41 @vskip 0pt plus 1filll
54 * Overview of Flymake::
55 * Installing Flymake::
57 * Configuring Flymake::
58 * Flymake Implementation::
59 * GNU Free Documentation License::
63 @node Overview of Flymake
65 @cindex Overview of Flymake
67 Flymake is a universal on-the-fly syntax checker implemented as an
68 Emacs minor mode. Flymake runs the pre-configured syntax check tool
69 (compiler for C++ files, @code{perl} for perl files, etc.)@: in the
70 background, passing it a temporary copy of the current buffer, and
71 parses the output for known error/warning message patterns. Flymake
72 then highlights erroneous lines (i.e., lines for which at least one
73 error or warning has been reported by the syntax check tool), and
74 displays an overall buffer status in the mode line. Status information
75 displayed by Flymake contains total number of errors and warnings
76 reported for the buffer during the last syntax check.
78 @code{flymake-goto-next-error} and @code{flymake-goto-prev-error}
79 functions allow for easy navigation to the next/previous erroneous
82 Calling @code{flymake-display-err-menu-for-current-line} will popup a
83 menu containing error messages reported by the syntax check tool for
84 the current line. Errors/warnings belonging to another file, such as a
85 @code{.h} header file included by a @code{.c} file, are shown in the
86 current buffer as belonging to the first line. Menu items for such
87 messages also contain a filename and a line number. Selecting such a
88 menu item will automatically open the file and jump to the line with
91 Syntax check is done 'on-the-fly'. It is started whenever
94 @item buffer is loaded
95 @item a newline character is added to the buffer
96 @item some changes were made to the buffer more than @code{0.5} seconds ago (the
97 delay is configurable).
100 Flymake is a universal syntax checker in the sense that it's easily
101 extended to support new syntax check tools and error message
102 patterns. @xref{Configuring Flymake}.
104 @node Installing Flymake
106 @cindex Installing Flymake
109 Flymake is packaged in a single file, @code{flymake.el}.
111 To install/update Flymake, place @code{flymake.el} to a directory
112 somewhere on Emacs load path. You might also want to byte-compile
113 @code{flymake.el} to improve performance.
115 Also, place the following line in the @code{.emacs} file.
121 You might also map the most frequently used Flymake functions, such as
122 @code{flymake-goto-next-error}, to some keyboard shortcuts:
125 (global-set-key [f3] 'flymake-display-err-menu-for-current-line)
126 (global-set-key [f4] 'flymake-goto-next-error)
130 @chapter Using Flymake
131 @cindex Using Flymake
135 * Running the syntax check::
136 * Navigating to error lines::
137 * Viewing error messages::
138 * Syntax check statuses::
143 @section Flymake mode
146 Flymake is an Emacs minor mode. To use Flymake, you
147 must first activate @code{flymake-mode} by using the
148 @code{flymake-mode} function.
150 Instead of manually activating @code{flymake-mode}, you can configure
151 Flymake to automatically enable @code{flymake-mode} upon opening any
152 file for which syntax check is possible. To do so, place the following
153 line in @code{.emacs}:
156 (add-hook 'find-file-hook 'flymake-find-file-hook)
159 @node Running the syntax check
160 @section Running the syntax check
161 @cindex Manually starting the syntax check
163 When @code{flymake-mode} is active, syntax check is started
164 automatically on any of the three conditions mentioned above. Syntax
165 check can also be started manually by using the
166 @code{flymake-start-syntax-check-for-current-buffer} function. This
167 can be used, for example, when changes were made to some other buffer
168 affecting the current buffer.
170 @node Navigating to error lines
171 @section Navigating to error lines
172 @cindex Navigating to error lines
174 After syntax check is completed, lines for which at least one error or
175 warning has been reported are highlighted, and total number of errors
176 and warning is shown in the mode line. Use the following functions to
177 navigate the highlighted lines.
179 @multitable @columnfractions 0.25 0.75
181 @item @code{flymake-goto-next-error}
182 @tab Moves point to the next erroneous line, if any.
184 @item @code{flymake-goto-prev-error}
185 @tab Moves point to the previous erroneous line.
189 These functions treat erroneous lines as a linked list. Therefore,
190 @code{flymake-goto-next-error} will go to the first erroneous line
191 when invoked in the end of the buffer.
193 @node Viewing error messages
194 @section Viewing error messages
195 @cindex Viewing error messages
197 To view error messages belonging to the current line, use the
198 @code{flymake-display-err-menu-for-current-line} function. If there's
199 at least one error or warning reported for the current line, this
200 function will display a popup menu with error/warning texts.
201 Selecting the menu item whose error belongs to another file brings
202 forward that file with the help of the
203 @code{flymake-goto-file-and-line} function.
205 @node Syntax check statuses
206 @section Syntax check statuses
207 @cindex Syntax check statuses
209 After syntax check is finished, its status is displayed in the mode line.
210 The following statuses are defined.
212 @multitable @columnfractions 0.25 0.75
213 @item Flymake* or Flymake:E/W*
214 @tab Flymake is currently running. For the second case, E/W contains the
215 error and warning count for the previous run.
218 @tab Syntax check is not running. Usually this means syntax check was
219 successfully passed (no errors, no warnings). Other possibilities are:
220 syntax check was killed as a result of executing
221 @code{flymake-compile}, or syntax check cannot start as compilation
222 is currently in progress.
225 @tab Number of errors/warnings found by the syntax check process.
228 @tab Flymake was unable to find master file for the current buffer.
231 The following errors cause a warning message and switch flymake mode
234 @multitable @columnfractions 0.25 0.75
236 @tab Syntax check process returned nonzero exit code, but no
237 errors/warnings were reported. This indicates a possible configuration
238 error (for example, no suitable error message patterns for the
242 @tab Flymake was unable to find master file for the current buffer.
245 @tab Flymake was unable to find a suitable buildfile for the current buffer.
248 @tab Flymake was unable to launch a syntax check process.
252 @node Troubleshooting
253 @section Troubleshooting
255 @cindex Troubleshooting
257 Flymake uses a simple logging facility for indicating important points
258 in the control flow. The logging facility sends logging messages to
259 the @code{*Messages*} buffer. The information logged can be used for
260 resolving various problems related to Flymake.
262 Logging output is controlled by the @code{flymake-log-level}
263 variable. @code{3} is the most verbose level, and @code{-1} switches
266 @node Configuring Flymake
267 @chapter Configuring and Extending Flymake
268 @cindex Configuring and Extending Flymake
271 * Customizable variables::
272 * Adding support for a new syntax check tool::
275 Flymake was designed to be easily extended for supporting new syntax
276 check tools and error message patterns.
278 @node Customizable variables
279 @section Customizable variables
280 @cindex Customizable variables
282 This section summarizes variables used for Flymake
286 @item flymake-log-level
287 Controls logging output, see @ref{Troubleshooting}.
289 @item flymake-allowed-file-name-masks
290 A list of @code{(filename-regexp, init-function, cleanup-function
291 getfname-function)} for configuring syntax check tools. @xref{Adding
292 support for a new syntax check tool}.
295 @item flymake-buildfile-dirs
296 A list of directories (relative paths) for searching a
297 buildfile. @xref{Locating the buildfile}.
300 @item flymake-master-file-dirs
301 A list of directories for searching a master file. @xref{Locating a
304 @item flymake-get-project-include-dirs-function
305 A function used for obtaining a list of project include dirs (C/C++
306 specific). @xref{Getting the include directories}.
308 @item flymake-master-file-count-limit
309 @itemx flymake-check-file-limit
310 Used when looking for a master file. @xref{Locating a master file}.
312 @item flymake-err-line-patterns
313 Patterns for error/warning messages in the form @code{(regexp file-idx
314 line-idx col-idx err-text-idx)}. @xref{Parsing the output}.
316 @item flymake-warning-predicate
317 Predicate to classify error text as warning. @xref{Parsing the output}.
319 @item flymake-compilation-prevents-syntax-check
320 A flag indicating whether compilation and syntax check of the same
321 file cannot be run simultaneously.
323 @item flymake-no-changes-timeout
324 If any changes are made to the buffer, syntax check is automatically
325 started after @code{flymake-no-changes-timeout} seconds.
327 @item flymake-gui-warnings-enabled
328 A boolean flag indicating whether Flymake will show message boxes for
329 non-recoverable errors. If @code{flymake-gui-warnings-enabled} is
330 @code{nil}, these errors will only be logged to the @code{*Messages*}
333 @item flymake-start-syntax-check-on-newline
334 A boolean flag indicating whether to start syntax check after a
335 newline character is added to the buffer.
337 @item flymake-errline
338 A custom face for highlighting lines for which at least one error has
341 @item flymake-warnline
342 A custom face for highlighting lines for which at least one warning
343 and no errors have been reported.
345 @item flymake-error-bitmap
346 A bitmap used in the fringe to mark lines for which an error has
349 @item flymake-warning-bitmap
350 A bitmap used in the fringe to mark lines for which a warning has
353 @item flymake-fringe-indicator-position
354 Which fringe (if any) should show the warning/error bitmaps.
358 @node Adding support for a new syntax check tool
359 @section Adding support for a new syntax check tool
360 @cindex Adding support for a new syntax check tool
363 * Example---Configuring a tool called directly::
364 * Example---Configuring a tool called via make::
367 Syntax check tools are configured using the
368 @code{flymake-allowed-file-name-masks} list. Each item of this list
369 has the following format:
372 (filename-regexp, init-function, cleanup-function, getfname-function)
376 @item filename-regexp
377 This field is used as a key for locating init/cleanup/getfname
378 functions for the buffer. Items in
379 @code{flymake-allowed-file-name-masks} are searched sequentially. The
380 first item with @code{filename-regexp} matching buffer filename is
381 selected. If no match is found, @code{flymake-mode} is switched off.
384 @code{init-function} is required to initialize the syntax check,
385 usually by creating a temporary copy of the buffer contents. The
386 function must return @code{(list cmd-name arg-list)}. If
387 @code{init-function} returns null, syntax check is aborted, by
388 @code{flymake-mode} is not switched off.
390 @item cleanup-function
391 @code{cleanup-function} is called after the syntax check process is
392 complete and should take care of proper deinitialization, which is
393 usually deleting a temporary copy created by the @code{init-function}.
395 @item getfname-function
396 This function is used for translating filenames reported by the syntax
397 check tool into ``real'' filenames. Filenames reported by the tool
398 will be different from the real ones, as actually the tool works with
399 the temporary copy. In most cases, the default implementation
400 provided by Flymake, @code{flymake-get-real-file-name}, can be used as
401 @code{getfname-function}.
405 To add support for a new syntax check tool, write corresponding
406 @code{init-function}, and, optionally @code{cleanup-function} and
407 @code{getfname-function}. If the format of error messages reported by
408 the new tool is not yet supported by Flymake, add a new entry to
409 the @code{flymake-err-line-patterns} list.
411 The following sections contain some examples of configuring Flymake
412 support for various syntax check tools.
414 @node Example---Configuring a tool called directly
415 @subsection Example---Configuring a tool called directly
416 @cindex Adding support for perl
418 In this example, we will add support for @code{perl} as a syntax check
419 tool. @code{perl} supports the @code{-c} option which does syntax
422 First, we write the @code{init-function}:
425 (defun flymake-perl-init ()
426 (let* ((temp-file (flymake-init-create-temp-buffer-copy
427 'flymake-create-temp-inplace))
428 (local-file (file-relative-name
430 (file-name-directory buffer-file-name))))
431 (list "perl" (list "-wc " local-file))))
434 @code{flymake-perl-init} creates a temporary copy of the buffer
435 contents with the help of
436 @code{flymake-init-create-temp-buffer-copy}, and builds an appropriate
439 Next, we add a new entry to the
440 @code{flymake-allowed-file-name-masks}:
443 (setq flymake-allowed-file-name-masks
446 flymake-simple-cleanup
447 flymake-get-real-file-name)
448 flymake-allowed-file-name-masks))
451 Note that we use standard @code{cleanup-function} and
452 @code{getfname-function}.
454 Finally, we add an entry to @code{flymake-err-line-patterns}:
457 (setq flymake-err-line-patterns
458 (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]"
460 flymake-err-line-patterns))
463 @node Example---Configuring a tool called via make
464 @subsection Example---Configuring a tool called via make
465 @cindex Adding support for C (gcc+make)
467 In this example we will add support for C files syntax checked by
468 @command{gcc} called via @command{make}.
470 We're not required to write any new functions, as Flymake already has
471 functions for @command{make}. We just add a new entry to the
472 @code{flymake-allowed-file-name-masks}:
475 (setq flymake-allowed-file-name-masks
477 flymake-simple-make-init
478 flymake-simple-cleanup
479 flymake-get-real-file-name)
480 flymake-allowed-file-name-masks))
483 @code{flymake-simple-make-init} builds the following @command{make}
490 (concat "CHK_SOURCES=" source)
491 "SYNTAX_CHECK_MODE=1"
495 @code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}.
497 Thus, @code{Makefile} must contain the @code{check-syntax} target. In
498 our case this target might look like this:
502 gcc -o /dev/null -S ${CHK_SOURCES}
506 The format of error messages reported by @command{gcc} is already
507 supported by Flymake, so we don't have to add a new entry to
508 @code{flymake-err-line-patterns}. Note that if you are using
509 Automake, you may want to replace @code{gcc} with the standard
510 Automake variable @code{COMPILE}:
514 $(COMPILE) -o /dev/null -S ${CHK_SOURCES}
517 @node Flymake Implementation
518 @chapter Flymake Implementation
519 @cindex Implementation details
522 * Determining whether syntax check is possible::
523 * Making a temporary copy::
524 * Locating a master file::
525 * Getting the include directories::
526 * Locating the buildfile::
527 * Starting the syntax check process::
528 * Parsing the output::
529 * Highlighting erroneous lines::
530 * Interaction with other modes::
533 Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}.
534 Flymake first determines whether it is able to do syntax
535 check. It then saves a copy of the buffer in a temporary file in the
536 buffer's directory (or in the system temp directory, for java
537 files), creates a syntax check command and launches a process with
538 this command. The output is parsed using a list of error message patterns,
539 and error information (file name, line number, type and text) is
540 saved. After the process has finished, Flymake highlights erroneous
541 lines in the buffer using the accumulated error information.
543 @node Determining whether syntax check is possible
544 @section Determining whether syntax check is possible
545 @cindex Syntax check models
548 Syntax check is considered possible if there's an entry in
549 @code{flymake-allowed-file-name-masks} matching buffer's filename and
550 its @code{init-function} returns non-@code{nil} value.
552 Two syntax check modes are distinguished:
557 Buffer can be syntax checked in a standalone fashion, that is, the
558 file (its temporary copy, in fact) can be passed over to the compiler to
559 do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java)
563 Buffer can be syntax checked, but additional file, called master file,
564 is required to perform this operation. A master file is a file that
565 includes the current file, so that running a syntax check tool on it
566 will also check syntax in the current file. Examples are C/C++ (.h,
571 These modes are handled inside init/cleanup/getfname functions, see
572 @ref{Adding support for a new syntax check tool}.
574 Flymake contains implementations of all functionality required to
575 support different syntax check modes described above (making temporary
576 copies, finding master files, etc.), as well as some tool-specific
577 (routines for Make, Ant, etc.)@: code.
580 @node Making a temporary copy
581 @section Making a temporary copy
582 @cindex Temporary copy of the buffer
585 After the possibility of the syntax check has been determined, a
586 temporary copy of the current buffer is made so that the most recent
587 unsaved changes could be seen by the syntax check tool. Making a copy
588 is quite straightforward in a standalone case (mode @code{1}), as it's
589 just saving buffer contents to a temporary file.
591 Things get trickier, however, when master file is involved, as it
595 @item locate a master file
596 @item patch it to include the current file using its new (temporary)
600 Locating a master file is discussed in the following section.
602 Patching just changes all appropriate lines of the master file so that they
603 use the new (temporary) name of the current file. For example, suppose current
604 file name is @code{file.h}, the master file is @code{file.cpp}, and
605 it includes current file via @code{#include "file.h"}. Current file's copy
606 is saved to file @code{file_flymake.h}, so the include line must be
607 changed to @code{#include "file_flymake.h"}. Finally, patched master file
608 is saved to @code{file_flymake_master.cpp}, and the last one is passed to
609 the syntax check tool.
611 @node Locating a master file
612 @section Locating a master file
615 Master file is located in two steps.
617 First, a list of possible master files is built. A simple name
618 matching is used to find the files. For a C++ header @code{file.h},
619 Flymake searches for all @code{.cpp} files in the directories whose relative paths are
620 stored in a customizable variable @code{flymake-master-file-dirs}, which
621 usually contains something like @code{("." "./src")}. No more than
622 @code{flymake-master-file-count-limit} entries is added to the master file
623 list. The list is then sorted to move files with names @code{file.cpp} to
626 Next, each master file in a list is checked to contain the appropriate
627 include directives. No more than @code{flymake-check-file-limit} of each
630 For @code{file.h}, the include directives to look for are
631 @code{#include "file.h"}, @code{#include "../file.h"}, etc. Each
632 include is checked against a list of include directories
633 (see @ref{Getting the include directories}) to be sure it points to the
634 correct @code{file.h}.
636 First matching master file found stops the search. The master file is then
637 patched and saved to disk. In case no master file is found, syntax check is
638 aborted, and corresponding status (!) is reported in the mode line.
640 @node Getting the include directories
641 @section Getting the include directories
642 @cindex Include directories (C/C++ specific)
644 Two sets of include directories are distinguished: system include directories
645 and project include directories. The former is just the contents of the
646 @code{INCLUDE} environment variable. The latter is not so easy to obtain,
647 and the way it can be obtained can vary greatly for different projects.
648 Therefore, a customizable variable
649 @code{flymake-get-project-include-dirs-function} is used to provide the
650 way to implement the desired behavior.
652 The default implementation, @code{flymake-get-project-include-dirs-imp},
653 uses a @command{make} call. This requires a correct base directory, that is, a
654 directory containing a correct @file{Makefile}, to be determined.
656 As obtaining the project include directories might be a costly operation, its
657 return value is cached in the hash table. The cache is cleared in the beginning
658 of every syntax check attempt.
660 @node Locating the buildfile
661 @section Locating the buildfile
662 @cindex Locating the buildfile
663 @cindex buildfile, locating
664 @cindex Makefile, locating
666 Flymake can be configured to use different tools for performing syntax
667 checks. For example, it can use direct compiler call to syntax check a perl
668 script or a call to @command{make} for a more complicated case of a
669 @code{C/C++} source. The general idea is that simple files, like perl
670 scripts and html pages, can be checked by directly invoking a
671 corresponding tool. Files that are usually more complex and generally
672 used as part of larger projects, might require non-trivial options to
673 be passed to the syntax check tool, like include directories for
674 C++. The latter files are syntax checked using some build tool, like
677 All Make configuration data is usually stored in a file called
678 @code{Makefile}. To allow for future extensions, flymake uses a notion of
679 buildfile to reference the 'project configuration' file.
681 Special function, @code{flymake-find-buildfile} is provided for locating buildfiles.
682 Searching for a buildfile is done in a manner similar to that of searching
683 for possible master files.
685 A customizable variable
686 @code{flymake-buildfile-dirs} holds a list of relative paths to the
687 buildfile. They are checked sequentially until a buildfile is found.
689 In case there's no build file, syntax check is aborted.
691 Buildfile values are also cached.
693 @node Starting the syntax check process
694 @section Starting the syntax check process
695 @cindex Syntax check process
697 The command line (command name and the list of arguments) for launching a process is returned by the
698 initialization function. Flymake then just calls @code{start-process}
699 to start an asynchronous process and configures process filter and
700 sentinel which is used for processing the output of the syntax check
703 @node Parsing the output
704 @section Parsing the output
705 @cindex Parsing the output
707 The output generated by the syntax check tool is parsed in the process
708 filter/sentinel using the error message patterns stored in the
709 @code{flymake-err-line-patterns} variable. This variable contains a
710 list of items of the form @code{(regexp file-idx line-idx
711 err-text-idx)}, used to determine whether a particular line is an
712 error message and extract file name, line number and error text,
713 respectively. Error type (error/warning) is also guessed by matching
714 error text with the '@code{^[wW]arning}' pattern. Anything that was not
715 classified as a warning is considered an error. Type is then used to
716 sort error menu items, which shows error messages first.
718 Flymake is also able to interpret error message patterns missing err-text-idx
719 information. This is done by merely taking the rest of the matched line
720 (@code{(substring line (match-end 0))}) as error text. This trick allows
721 to make use of a huge collection of error message line patterns from
722 @code{compile.el}. All these error patterns are appended to
723 the end of @code{flymake-err-line-patterns}.
725 The error information obtained is saved in a buffer local
726 variable. The buffer for which the process output belongs is
727 determined from the process-id@w{}->@w{}buffer mapping updated
728 after every process launch/exit.
730 @node Highlighting erroneous lines
731 @section Highlighting erroneous lines
732 @cindex Erroneous lines, faces
734 Highlighting is implemented with overlays and happens in the process
735 sentinel, after calling the cleanup function. Two customizable faces
736 are used: @code{flymake-errline} and
737 @code{flymake-warnline}. Errors belonging outside the current
738 buffer are considered to belong to line 1 of the current buffer.
740 @c This manual does not use vindex.
741 @c @vindex flymake-fringe-indicator-position
742 @c @vindex flymake-error-bitmap
743 @c @vindex flymake-warning-bitmap
744 If the option @code{flymake-fringe-indicator-position} is non-@code{nil},
745 errors and warnings are also highlighted in the left or right fringe,
746 using the bitmaps specified by @code{flymake-error-bitmap}
747 and @code{flymake-warning-bitmap}.
749 @node Interaction with other modes
750 @section Interaction with other modes
751 @cindex Interaction with other modes
752 @cindex Interaction with compile mode
754 The only mode flymake currently knows about is @code{compile}.
756 Flymake can be configured to not start syntax check if it thinks the
757 compilation is in progress. The check is made by the
758 @code{flymake-compilation-is-running}, which tests the
759 @code{compilation-in-progress} variable. The reason why this might be
760 useful is saving CPU time in case both syntax check and compilation
761 are very CPU intensive. The original reason for adding this feature,
762 though, was working around a locking problem with MS Visual C++
765 Flymake also provides an alternative command for starting compilation,
766 @code{flymake-compile}:
769 (defun flymake-compile ()
770 "Kill all flymake syntax checks then start compilation."
772 (flymake-stop-all-syntax-checks)
773 (call-interactively 'compile))
776 It just kills all the active syntax check processes before calling
779 @node GNU Free Documentation License
780 @appendix GNU Free Documentation License
781 @include doclicense.texi