Commit | Line | Data |
---|---|---|
4009494e GM |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header | |
29993416 | 3 | @setfilename ../../info/flymake.info |
4009494e GM |
4 | @set VERSION 0.3 |
5 | @set UPDATED April 2004 | |
6 | @settitle GNU Flymake @value{VERSION} | |
7 | @syncodeindex pg cp | |
c6ab4664 | 8 | @documentencoding UTF-8 |
4009494e GM |
9 | @comment %**end of header |
10 | ||
11 | @copying | |
12 | This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), | |
13 | which is a universal on-the-fly syntax checker for GNU Emacs. | |
14 | ||
6bc383b1 | 15 | Copyright @copyright{} 2004--2014 Free Software Foundation, Inc. |
4009494e GM |
16 | |
17 | @quotation | |
18 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 19 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e | 20 | any later version published by the Free Software Foundation; with no |
551a89e1 | 21 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' |
4009494e | 22 | and with the Back-Cover Texts as in (a) below. A copy of the license |
debf4439 | 23 | is included in the section entitled ``GNU Free Documentation License''. |
4009494e | 24 | |
6f093307 | 25 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 26 | modify this GNU manual.'' |
4009494e GM |
27 | @end quotation |
28 | @end copying | |
29 | ||
0c973505 | 30 | @dircategory Emacs misc features |
4009494e | 31 | @direntry |
62e034c2 | 32 | * Flymake: (flymake). A universal on-the-fly syntax checker. |
4009494e GM |
33 | @end direntry |
34 | ||
35 | @titlepage | |
36 | @title GNU Flymake | |
37 | @subtitle for version @value{VERSION}, @value{UPDATED} | |
38 | @author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) | |
39 | @page | |
40 | @vskip 0pt plus 1filll | |
41 | @insertcopying | |
42 | @end titlepage | |
43 | ||
44 | @contents | |
45 | ||
46 | @ifnottex | |
47 | @node Top | |
48 | @top GNU Flymake | |
1df7defd | 49 | @insertcopying |
4009494e GM |
50 | @end ifnottex |
51 | ||
52 | @menu | |
53 | * Overview of Flymake:: | |
54 | * Installing Flymake:: | |
55 | * Using Flymake:: | |
56 | * Configuring Flymake:: | |
57 | * Flymake Implementation:: | |
58 | * GNU Free Documentation License:: | |
59 | * Index:: | |
60 | @end menu | |
61 | ||
62 | @node Overview of Flymake | |
63 | @chapter Overview | |
64 | @cindex Overview of Flymake | |
65 | ||
66 | Flymake is a universal on-the-fly syntax checker implemented as an | |
5d028165 | 67 | Emacs minor mode. Flymake runs the pre-configured syntax check tool |
65e7ca35 | 68 | (compiler for C++ files, @code{perl} for perl files, etc.)@: in the |
4009494e | 69 | background, passing it a temporary copy of the current buffer, and |
5d028165 | 70 | parses the output for known error/warning message patterns. Flymake |
1df7defd | 71 | then highlights erroneous lines (i.e., lines for which at least one |
4009494e | 72 | error or warning has been reported by the syntax check tool), and |
5d028165 | 73 | displays an overall buffer status in the mode line. Status information |
4009494e GM |
74 | displayed by Flymake contains total number of errors and warnings |
75 | reported for the buffer during the last syntax check. | |
76 | ||
77 | @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} | |
78 | functions allow for easy navigation to the next/previous erroneous | |
79 | line, respectively. | |
80 | ||
81 | Calling @code{flymake-display-err-menu-for-current-line} will popup a | |
82 | menu containing error messages reported by the syntax check tool for | |
5d028165 | 83 | the current line. Errors/warnings belonging to another file, such as a |
4009494e | 84 | @code{.h} header file included by a @code{.c} file, are shown in the |
5d028165 XF |
85 | current buffer as belonging to the first line. Menu items for such |
86 | messages also contain a filename and a line number. Selecting such a | |
4009494e GM |
87 | menu item will automatically open the file and jump to the line with |
88 | error. | |
89 | ||
237166b3 | 90 | Syntax check is done ``on-the-fly''. It is started whenever |
4009494e GM |
91 | |
92 | @itemize @bullet | |
93 | @item buffer is loaded | |
94 | @item a newline character is added to the buffer | |
95 | @item some changes were made to the buffer more than @code{0.5} seconds ago (the | |
96 | delay is configurable). | |
97 | @end itemize | |
98 | ||
99 | Flymake is a universal syntax checker in the sense that it's easily | |
100 | extended to support new syntax check tools and error message | |
5d028165 | 101 | patterns. @xref{Configuring Flymake}. |
4009494e GM |
102 | |
103 | @node Installing Flymake | |
104 | @chapter Installing | |
105 | @cindex Installing Flymake | |
106 | ||
107 | ||
108 | Flymake is packaged in a single file, @code{flymake.el}. | |
109 | ||
110 | To install/update Flymake, place @code{flymake.el} to a directory | |
5d028165 | 111 | somewhere on Emacs load path. You might also want to byte-compile |
4009494e GM |
112 | @code{flymake.el} to improve performance. |
113 | ||
114 | Also, place the following line in the @code{.emacs} file. | |
115 | ||
116 | @lisp | |
117 | (require 'flymake) | |
118 | @end lisp | |
119 | ||
120 | You might also map the most frequently used Flymake functions, such as | |
121 | @code{flymake-goto-next-error}, to some keyboard shortcuts: | |
122 | ||
123 | @lisp | |
124 | (global-set-key [f3] 'flymake-display-err-menu-for-current-line) | |
125 | (global-set-key [f4] 'flymake-goto-next-error) | |
126 | @end lisp | |
127 | ||
128 | @node Using Flymake | |
129 | @chapter Using Flymake | |
130 | @cindex Using Flymake | |
131 | ||
132 | @menu | |
133 | * Flymake mode:: | |
134 | * Running the syntax check:: | |
135 | * Navigating to error lines:: | |
136 | * Viewing error messages:: | |
137 | * Syntax check statuses:: | |
138 | * Troubleshooting:: | |
139 | @end menu | |
140 | ||
141 | @node Flymake mode | |
142 | @section Flymake mode | |
143 | @cindex flymake-mode | |
144 | ||
5d028165 | 145 | Flymake is an Emacs minor mode. To use Flymake, you |
4009494e GM |
146 | must first activate @code{flymake-mode} by using the |
147 | @code{flymake-mode} function. | |
148 | ||
149 | Instead of manually activating @code{flymake-mode}, you can configure | |
150 | Flymake to automatically enable @code{flymake-mode} upon opening any | |
5d028165 | 151 | file for which syntax check is possible. To do so, place the following |
4009494e GM |
152 | line in @code{.emacs}: |
153 | ||
154 | @lisp | |
155 | (add-hook 'find-file-hook 'flymake-find-file-hook) | |
156 | @end lisp | |
157 | ||
158 | @node Running the syntax check | |
159 | @section Running the syntax check | |
160 | @cindex Manually starting the syntax check | |
161 | ||
162 | When @code{flymake-mode} is active, syntax check is started | |
5d028165 | 163 | automatically on any of the three conditions mentioned above. Syntax |
4009494e | 164 | check can also be started manually by using the |
5d028165 | 165 | @code{flymake-start-syntax-check-for-current-buffer} function. This |
4009494e GM |
166 | can be used, for example, when changes were made to some other buffer |
167 | affecting the current buffer. | |
168 | ||
169 | @node Navigating to error lines | |
170 | @section Navigating to error lines | |
171 | @cindex Navigating to error lines | |
172 | ||
173 | After syntax check is completed, lines for which at least one error or | |
174 | warning has been reported are highlighted, and total number of errors | |
5d028165 | 175 | and warning is shown in the mode line. Use the following functions to |
4009494e GM |
176 | navigate the highlighted lines. |
177 | ||
178 | @multitable @columnfractions 0.25 0.75 | |
179 | ||
180 | @item @code{flymake-goto-next-error} | |
181 | @tab Moves point to the next erroneous line, if any. | |
182 | ||
183 | @item @code{flymake-goto-prev-error} | |
184 | @tab Moves point to the previous erroneous line. | |
185 | ||
186 | @end multitable | |
187 | ||
5d028165 | 188 | These functions treat erroneous lines as a linked list. Therefore, |
4009494e GM |
189 | @code{flymake-goto-next-error} will go to the first erroneous line |
190 | when invoked in the end of the buffer. | |
191 | ||
192 | @node Viewing error messages | |
193 | @section Viewing error messages | |
194 | @cindex Viewing error messages | |
195 | ||
196 | To view error messages belonging to the current line, use the | |
5d028165 | 197 | @code{flymake-display-err-menu-for-current-line} function. If there's |
4009494e GM |
198 | at least one error or warning reported for the current line, this |
199 | function will display a popup menu with error/warning texts. | |
200 | Selecting the menu item whose error belongs to another file brings | |
201 | forward that file with the help of the | |
202 | @code{flymake-goto-file-and-line} function. | |
203 | ||
204 | @node Syntax check statuses | |
205 | @section Syntax check statuses | |
206 | @cindex Syntax check statuses | |
207 | ||
208 | After syntax check is finished, its status is displayed in the mode line. | |
209 | The following statuses are defined. | |
210 | ||
211 | @multitable @columnfractions 0.25 0.75 | |
212 | @item Flymake* or Flymake:E/W* | |
5d028165 | 213 | @tab Flymake is currently running. For the second case, E/W contains the |
6800ff8d | 214 | error and warning count for the previous run. |
4009494e GM |
215 | |
216 | @item Flymake | |
5d028165 XF |
217 | @tab Syntax check is not running. Usually this means syntax check was |
218 | successfully passed (no errors, no warnings). Other possibilities are: | |
6800ff8d GM |
219 | syntax check was killed as a result of executing |
220 | @code{flymake-compile}, or syntax check cannot start as compilation | |
221 | is currently in progress. | |
4009494e GM |
222 | |
223 | @item Flymake:E/W | |
224 | @tab Number of errors/warnings found by the syntax check process. | |
225 | ||
226 | @item Flymake:! | |
227 | @tab Flymake was unable to find master file for the current buffer. | |
228 | @end multitable | |
229 | ||
230 | The following errors cause a warning message and switch flymake mode | |
231 | OFF for the buffer. | |
232 | ||
233 | @multitable @columnfractions 0.25 0.75 | |
234 | @item CFGERR | |
235 | @tab Syntax check process returned nonzero exit code, but no | |
5d028165 | 236 | errors/warnings were reported. This indicates a possible configuration |
6800ff8d GM |
237 | error (for example, no suitable error message patterns for the |
238 | syntax check tool). | |
4009494e GM |
239 | |
240 | @item NOMASTER | |
241 | @tab Flymake was unable to find master file for the current buffer. | |
242 | ||
243 | @item NOMK | |
244 | @tab Flymake was unable to find a suitable buildfile for the current buffer. | |
245 | ||
246 | @item PROCERR | |
247 | @tab Flymake was unable to launch a syntax check process. | |
248 | @end multitable | |
249 | ||
250 | ||
251 | @node Troubleshooting | |
252 | @section Troubleshooting | |
253 | @cindex Logging | |
254 | @cindex Troubleshooting | |
255 | ||
256 | Flymake uses a simple logging facility for indicating important points | |
5d028165 | 257 | in the control flow. The logging facility sends logging messages to |
d29fbf47 | 258 | the @file{*Messages*} buffer. The information logged can be used for |
4009494e GM |
259 | resolving various problems related to Flymake. |
260 | ||
261 | Logging output is controlled by the @code{flymake-log-level} | |
5d028165 | 262 | variable. @code{3} is the most verbose level, and @code{-1} switches |
4009494e GM |
263 | logging off. |
264 | ||
265 | @node Configuring Flymake | |
266 | @chapter Configuring and Extending Flymake | |
267 | @cindex Configuring and Extending Flymake | |
268 | ||
269 | @menu | |
270 | * Customizable variables:: | |
271 | * Adding support for a new syntax check tool:: | |
272 | @end menu | |
273 | ||
274 | Flymake was designed to be easily extended for supporting new syntax | |
275 | check tools and error message patterns. | |
276 | ||
277 | @node Customizable variables | |
278 | @section Customizable variables | |
279 | @cindex Customizable variables | |
280 | ||
281 | This section summarizes variables used for Flymake | |
282 | configuration. | |
283 | ||
284 | @table @code | |
285 | @item flymake-log-level | |
286 | Controls logging output, see @ref{Troubleshooting}. | |
287 | ||
288 | @item flymake-allowed-file-name-masks | |
289 | A list of @code{(filename-regexp, init-function, cleanup-function | |
5d028165 | 290 | getfname-function)} for configuring syntax check tools. @xref{Adding |
4009494e GM |
291 | support for a new syntax check tool}. |
292 | ||
9b97b143 | 293 | @ignore |
4009494e GM |
294 | @item flymake-buildfile-dirs |
295 | A list of directories (relative paths) for searching a | |
5d028165 | 296 | buildfile. @xref{Locating the buildfile}. |
9b97b143 | 297 | @end ignore |
4009494e GM |
298 | |
299 | @item flymake-master-file-dirs | |
5d028165 | 300 | A list of directories for searching a master file. @xref{Locating a |
4009494e GM |
301 | master file}. |
302 | ||
303 | @item flymake-get-project-include-dirs-function | |
304 | A function used for obtaining a list of project include dirs (C/C++ | |
5d028165 | 305 | specific). @xref{Getting the include directories}. |
4009494e GM |
306 | |
307 | @item flymake-master-file-count-limit | |
308 | @itemx flymake-check-file-limit | |
5d028165 | 309 | Used when looking for a master file. @xref{Locating a master file}. |
4009494e GM |
310 | |
311 | @item flymake-err-line-patterns | |
312 | Patterns for error/warning messages in the form @code{(regexp file-idx | |
5d028165 | 313 | line-idx col-idx err-text-idx)}. @xref{Parsing the output}. |
4009494e | 314 | |
c5b0993e EW |
315 | @item flymake-warning-predicate |
316 | Predicate to classify error text as warning. @xref{Parsing the output}. | |
317 | ||
4009494e GM |
318 | @item flymake-compilation-prevents-syntax-check |
319 | A flag indicating whether compilation and syntax check of the same | |
320 | file cannot be run simultaneously. | |
321 | ||
322 | @item flymake-no-changes-timeout | |
323 | If any changes are made to the buffer, syntax check is automatically | |
324 | started after @code{flymake-no-changes-timeout} seconds. | |
325 | ||
326 | @item flymake-gui-warnings-enabled | |
327 | A boolean flag indicating whether Flymake will show message boxes for | |
5d028165 | 328 | non-recoverable errors. If @code{flymake-gui-warnings-enabled} is |
d29fbf47 | 329 | @code{nil}, these errors will only be logged to the @file{*Messages*} |
4009494e GM |
330 | buffer. |
331 | ||
332 | @item flymake-start-syntax-check-on-newline | |
333 | A boolean flag indicating whether to start syntax check after a | |
334 | newline character is added to the buffer. | |
335 | ||
176c6903 | 336 | @item flymake-errline |
4009494e GM |
337 | A custom face for highlighting lines for which at least one error has |
338 | been reported. | |
339 | ||
176c6903 | 340 | @item flymake-warnline |
4009494e GM |
341 | A custom face for highlighting lines for which at least one warning |
342 | and no errors have been reported. | |
343 | ||
24c38527 GM |
344 | @item flymake-error-bitmap |
345 | A bitmap used in the fringe to mark lines for which an error has | |
346 | been reported. | |
347 | ||
348 | @item flymake-warning-bitmap | |
349 | A bitmap used in the fringe to mark lines for which a warning has | |
350 | been reported. | |
351 | ||
352 | @item flymake-fringe-indicator-position | |
353 | Which fringe (if any) should show the warning/error bitmaps. | |
354 | ||
4009494e GM |
355 | @end table |
356 | ||
357 | @node Adding support for a new syntax check tool | |
358 | @section Adding support for a new syntax check tool | |
359 | @cindex Adding support for a new syntax check tool | |
360 | ||
361 | @menu | |
f99f1641 PE |
362 | * Example---Configuring a tool called directly:: |
363 | * Example---Configuring a tool called via make:: | |
4009494e GM |
364 | @end menu |
365 | ||
366 | Syntax check tools are configured using the | |
5d028165 | 367 | @code{flymake-allowed-file-name-masks} list. Each item of this list |
4009494e GM |
368 | has the following format: |
369 | ||
370 | @lisp | |
371 | (filename-regexp, init-function, cleanup-function, getfname-function) | |
372 | @end lisp | |
373 | ||
374 | @table @code | |
375 | @item filename-regexp | |
376 | This field is used as a key for locating init/cleanup/getfname | |
377 | functions for the buffer. Items in | |
5d028165 | 378 | @code{flymake-allowed-file-name-masks} are searched sequentially. The |
4009494e | 379 | first item with @code{filename-regexp} matching buffer filename is |
5d028165 | 380 | selected. If no match is found, @code{flymake-mode} is switched off. |
4009494e GM |
381 | |
382 | @item init-function | |
383 | @code{init-function} is required to initialize the syntax check, | |
5d028165 XF |
384 | usually by creating a temporary copy of the buffer contents. The |
385 | function must return @code{(list cmd-name arg-list)}. If | |
4009494e GM |
386 | @code{init-function} returns null, syntax check is aborted, by |
387 | @code{flymake-mode} is not switched off. | |
388 | ||
389 | @item cleanup-function | |
390 | @code{cleanup-function} is called after the syntax check process is | |
391 | complete and should take care of proper deinitialization, which is | |
392 | usually deleting a temporary copy created by the @code{init-function}. | |
393 | ||
394 | @item getfname-function | |
395 | This function is used for translating filenames reported by the syntax | |
5d028165 | 396 | check tool into ``real'' filenames. Filenames reported by the tool |
4009494e GM |
397 | will be different from the real ones, as actually the tool works with |
398 | the temporary copy. In most cases, the default implementation | |
399 | provided by Flymake, @code{flymake-get-real-file-name}, can be used as | |
400 | @code{getfname-function}. | |
401 | ||
402 | @end table | |
403 | ||
404 | To add support for a new syntax check tool, write corresponding | |
405 | @code{init-function}, and, optionally @code{cleanup-function} and | |
406 | @code{getfname-function}. If the format of error messages reported by | |
407 | the new tool is not yet supported by Flymake, add a new entry to | |
408 | the @code{flymake-err-line-patterns} list. | |
409 | ||
410 | The following sections contain some examples of configuring Flymake | |
411 | support for various syntax check tools. | |
412 | ||
f99f1641 PE |
413 | @node Example---Configuring a tool called directly |
414 | @subsection Example---Configuring a tool called directly | |
4009494e GM |
415 | @cindex Adding support for perl |
416 | ||
417 | In this example, we will add support for @code{perl} as a syntax check | |
5d028165 | 418 | tool. @code{perl} supports the @code{-c} option which does syntax |
4009494e GM |
419 | checking. |
420 | ||
421 | First, we write the @code{init-function}: | |
422 | ||
423 | @lisp | |
176c6903 | 424 | (defun flymake-perl-init () |
4009494e | 425 | (let* ((temp-file (flymake-init-create-temp-buffer-copy |
176c6903 | 426 | 'flymake-create-temp-inplace)) |
9360256a | 427 | (local-file (file-relative-name |
5ef5ef3f RS |
428 | temp-file |
429 | (file-name-directory buffer-file-name)))) | |
4009494e GM |
430 | (list "perl" (list "-wc " local-file)))) |
431 | @end lisp | |
432 | ||
433 | @code{flymake-perl-init} creates a temporary copy of the buffer | |
434 | contents with the help of | |
435 | @code{flymake-init-create-temp-buffer-copy}, and builds an appropriate | |
436 | command line. | |
437 | ||
438 | Next, we add a new entry to the | |
439 | @code{flymake-allowed-file-name-masks}: | |
440 | ||
441 | @lisp | |
442 | (setq flymake-allowed-file-name-masks | |
443 | (cons '(".+\\.pl$" | |
444 | flymake-perl-init | |
445 | flymake-simple-cleanup | |
446 | flymake-get-real-file-name) | |
447 | flymake-allowed-file-name-masks)) | |
448 | @end lisp | |
449 | ||
450 | Note that we use standard @code{cleanup-function} and | |
451 | @code{getfname-function}. | |
452 | ||
453 | Finally, we add an entry to @code{flymake-err-line-patterns}: | |
454 | ||
455 | @lisp | |
456 | (setq flymake-err-line-patterns | |
457 | (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" | |
458 | 2 3 nil 1) | |
459 | flymake-err-line-patterns)) | |
460 | @end lisp | |
461 | ||
f99f1641 PE |
462 | @node Example---Configuring a tool called via make |
463 | @subsection Example---Configuring a tool called via make | |
4009494e GM |
464 | @cindex Adding support for C (gcc+make) |
465 | ||
466 | In this example we will add support for C files syntax checked by | |
8ae818e4 | 467 | @command{gcc} called via @command{make}. |
4009494e GM |
468 | |
469 | We're not required to write any new functions, as Flymake already has | |
5d028165 | 470 | functions for @command{make}. We just add a new entry to the |
4009494e GM |
471 | @code{flymake-allowed-file-name-masks}: |
472 | ||
473 | @lisp | |
474 | (setq flymake-allowed-file-name-masks | |
475 | (cons '(".+\\.c$" | |
476 | flymake-simple-make-init | |
477 | flymake-simple-cleanup | |
478 | flymake-get-real-file-name) | |
479 | flymake-allowed-file-name-masks)) | |
480 | @end lisp | |
481 | ||
8ae818e4 | 482 | @code{flymake-simple-make-init} builds the following @command{make} |
4009494e GM |
483 | command line: |
484 | ||
485 | @lisp | |
486 | (list "make" | |
487 | (list "-s" "-C" | |
488 | base-dir | |
489 | (concat "CHK_SOURCES=" source) | |
490 | "SYNTAX_CHECK_MODE=1" | |
491 | "check-syntax")) | |
492 | @end lisp | |
493 | ||
494 | @code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. | |
495 | ||
5d028165 | 496 | Thus, @code{Makefile} must contain the @code{check-syntax} target. In |
4009494e GM |
497 | our case this target might look like this: |
498 | ||
499 | @verbatim | |
500 | check-syntax: | |
064e2d08 | 501 | gcc -o /dev/null -S ${CHK_SOURCES} |
4009494e GM |
502 | @end verbatim |
503 | ||
8ae818e4 CY |
504 | @noindent |
505 | The format of error messages reported by @command{gcc} is already | |
4009494e | 506 | supported by Flymake, so we don't have to add a new entry to |
8ae818e4 CY |
507 | @code{flymake-err-line-patterns}. Note that if you are using |
508 | Automake, you may want to replace @code{gcc} with the standard | |
509 | Automake variable @code{COMPILE}: | |
510 | ||
511 | @verbatim | |
512 | check-syntax: | |
513 | $(COMPILE) -o /dev/null -S ${CHK_SOURCES} | |
514 | @end verbatim | |
4009494e GM |
515 | |
516 | @node Flymake Implementation | |
517 | @chapter Flymake Implementation | |
518 | @cindex Implementation details | |
519 | ||
520 | @menu | |
521 | * Determining whether syntax check is possible:: | |
522 | * Making a temporary copy:: | |
523 | * Locating a master file:: | |
524 | * Getting the include directories:: | |
525 | * Locating the buildfile:: | |
526 | * Starting the syntax check process:: | |
527 | * Parsing the output:: | |
528 | * Highlighting erroneous lines:: | |
529 | * Interaction with other modes:: | |
530 | @end menu | |
531 | ||
532 | Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. | |
533 | Flymake first determines whether it is able to do syntax | |
5d028165 | 534 | check. It then saves a copy of the buffer in a temporary file in the |
f99f1641 | 535 | buffer's directory (or in the system temp directory, for java |
4009494e | 536 | files), creates a syntax check command and launches a process with |
5d028165 | 537 | this command. The output is parsed using a list of error message patterns, |
4009494e | 538 | and error information (file name, line number, type and text) is |
5d028165 | 539 | saved. After the process has finished, Flymake highlights erroneous |
4009494e GM |
540 | lines in the buffer using the accumulated error information. |
541 | ||
542 | @node Determining whether syntax check is possible | |
543 | @section Determining whether syntax check is possible | |
544 | @cindex Syntax check models | |
545 | @cindex Master file | |
546 | ||
547 | Syntax check is considered possible if there's an entry in | |
548 | @code{flymake-allowed-file-name-masks} matching buffer's filename and | |
549 | its @code{init-function} returns non-@code{nil} value. | |
550 | ||
551 | Two syntax check modes are distinguished: | |
552 | ||
553 | @enumerate | |
554 | ||
555 | @item | |
556 | Buffer can be syntax checked in a standalone fashion, that is, the | |
557 | file (its temporary copy, in fact) can be passed over to the compiler to | |
5d028165 | 558 | do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) |
4009494e GM |
559 | sources. |
560 | ||
561 | @item | |
562 | Buffer can be syntax checked, but additional file, called master file, | |
5d028165 | 563 | is required to perform this operation. A master file is a file that |
4009494e | 564 | includes the current file, so that running a syntax check tool on it |
5d028165 | 565 | will also check syntax in the current file. Examples are C/C++ (.h, |
4009494e GM |
566 | .hpp) headers. |
567 | ||
568 | @end enumerate | |
569 | ||
570 | These modes are handled inside init/cleanup/getfname functions, see | |
571 | @ref{Adding support for a new syntax check tool}. | |
572 | ||
573 | Flymake contains implementations of all functionality required to | |
8ae818e4 CY |
574 | support different syntax check modes described above (making temporary |
575 | copies, finding master files, etc.), as well as some tool-specific | |
65e7ca35 | 576 | (routines for Make, Ant, etc.)@: code. |
4009494e GM |
577 | |
578 | ||
579 | @node Making a temporary copy | |
580 | @section Making a temporary copy | |
581 | @cindex Temporary copy of the buffer | |
582 | @cindex Master file | |
583 | ||
584 | After the possibility of the syntax check has been determined, a | |
585 | temporary copy of the current buffer is made so that the most recent | |
5d028165 | 586 | unsaved changes could be seen by the syntax check tool. Making a copy |
4009494e GM |
587 | is quite straightforward in a standalone case (mode @code{1}), as it's |
588 | just saving buffer contents to a temporary file. | |
589 | ||
590 | Things get trickier, however, when master file is involved, as it | |
591 | requires to | |
592 | ||
593 | @itemize @bullet | |
594 | @item locate a master file | |
595 | @item patch it to include the current file using its new (temporary) | |
596 | name. | |
597 | @end itemize | |
598 | ||
599 | Locating a master file is discussed in the following section. | |
600 | ||
601 | Patching just changes all appropriate lines of the master file so that they | |
5d028165 | 602 | use the new (temporary) name of the current file. For example, suppose current |
4009494e | 603 | file name is @code{file.h}, the master file is @code{file.cpp}, and |
5d028165 | 604 | it includes current file via @code{#include "file.h"}. Current file's copy |
4009494e | 605 | is saved to file @code{file_flymake.h}, so the include line must be |
5d028165 | 606 | changed to @code{#include "file_flymake.h"}. Finally, patched master file |
4009494e GM |
607 | is saved to @code{file_flymake_master.cpp}, and the last one is passed to |
608 | the syntax check tool. | |
609 | ||
610 | @node Locating a master file | |
611 | @section Locating a master file | |
612 | @cindex Master file | |
613 | ||
614 | Master file is located in two steps. | |
615 | ||
5d028165 XF |
616 | First, a list of possible master files is built. A simple name |
617 | matching is used to find the files. For a C++ header @code{file.h}, | |
4009494e GM |
618 | Flymake searches for all @code{.cpp} files in the directories whose relative paths are |
619 | stored in a customizable variable @code{flymake-master-file-dirs}, which | |
5d028165 | 620 | usually contains something like @code{("." "./src")}. No more than |
4009494e | 621 | @code{flymake-master-file-count-limit} entries is added to the master file |
5d028165 | 622 | list. The list is then sorted to move files with names @code{file.cpp} to |
4009494e GM |
623 | the top. |
624 | ||
625 | Next, each master file in a list is checked to contain the appropriate | |
5d028165 | 626 | include directives. No more than @code{flymake-check-file-limit} of each |
4009494e GM |
627 | file are parsed. |
628 | ||
629 | For @code{file.h}, the include directives to look for are | |
5d028165 | 630 | @code{#include "file.h"}, @code{#include "../file.h"}, etc. Each |
4009494e GM |
631 | include is checked against a list of include directories |
632 | (see @ref{Getting the include directories}) to be sure it points to the | |
633 | correct @code{file.h}. | |
634 | ||
5d028165 XF |
635 | First matching master file found stops the search. The master file is then |
636 | patched and saved to disk. In case no master file is found, syntax check is | |
4009494e GM |
637 | aborted, and corresponding status (!) is reported in the mode line. |
638 | ||
639 | @node Getting the include directories | |
640 | @section Getting the include directories | |
641 | @cindex Include directories (C/C++ specific) | |
642 | ||
643 | Two sets of include directories are distinguished: system include directories | |
5d028165 XF |
644 | and project include directories. The former is just the contents of the |
645 | @code{INCLUDE} environment variable. The latter is not so easy to obtain, | |
4009494e GM |
646 | and the way it can be obtained can vary greatly for different projects. |
647 | Therefore, a customizable variable | |
648 | @code{flymake-get-project-include-dirs-function} is used to provide the | |
649 | way to implement the desired behavior. | |
650 | ||
651 | The default implementation, @code{flymake-get-project-include-dirs-imp}, | |
5d028165 | 652 | uses a @command{make} call. This requires a correct base directory, that is, a |
8ae818e4 | 653 | directory containing a correct @file{Makefile}, to be determined. |
4009494e GM |
654 | |
655 | As obtaining the project include directories might be a costly operation, its | |
5d028165 | 656 | return value is cached in the hash table. The cache is cleared in the beginning |
4009494e GM |
657 | of every syntax check attempt. |
658 | ||
659 | @node Locating the buildfile | |
660 | @section Locating the buildfile | |
661 | @cindex Locating the buildfile | |
662 | @cindex buildfile, locating | |
663 | @cindex Makefile, locating | |
664 | ||
665 | Flymake can be configured to use different tools for performing syntax | |
5d028165 | 666 | checks. For example, it can use direct compiler call to syntax check a perl |
8ae818e4 | 667 | script or a call to @command{make} for a more complicated case of a |
5d028165 | 668 | @code{C/C++} source. The general idea is that simple files, like perl |
4009494e | 669 | scripts and html pages, can be checked by directly invoking a |
5d028165 | 670 | corresponding tool. Files that are usually more complex and generally |
4009494e GM |
671 | used as part of larger projects, might require non-trivial options to |
672 | be passed to the syntax check tool, like include directories for | |
5d028165 | 673 | C++. The latter files are syntax checked using some build tool, like |
8ae818e4 | 674 | Make or Ant. |
4009494e | 675 | |
8ae818e4 | 676 | All Make configuration data is usually stored in a file called |
5d028165 | 677 | @code{Makefile}. To allow for future extensions, flymake uses a notion of |
4009494e GM |
678 | buildfile to reference the 'project configuration' file. |
679 | ||
680 | Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. | |
681 | Searching for a buildfile is done in a manner similar to that of searching | |
9b97b143 GM |
682 | for possible master files. |
683 | @ignore | |
684 | A customizable variable | |
4009494e | 685 | @code{flymake-buildfile-dirs} holds a list of relative paths to the |
5d028165 | 686 | buildfile. They are checked sequentially until a buildfile is found. |
9b97b143 GM |
687 | @end ignore |
688 | In case there's no build file, syntax check is aborted. | |
4009494e GM |
689 | |
690 | Buildfile values are also cached. | |
691 | ||
692 | @node Starting the syntax check process | |
693 | @section Starting the syntax check process | |
694 | @cindex Syntax check process | |
695 | ||
696 | The command line (command name and the list of arguments) for launching a process is returned by the | |
5d028165 | 697 | initialization function. Flymake then just calls @code{start-process} |
458e643b GM |
698 | to start an asynchronous process and configures a process filter and |
699 | sentinel, which are used for processing the output of the syntax check | |
4009494e GM |
700 | tool. |
701 | ||
702 | @node Parsing the output | |
703 | @section Parsing the output | |
704 | @cindex Parsing the output | |
705 | ||
706 | The output generated by the syntax check tool is parsed in the process | |
707 | filter/sentinel using the error message patterns stored in the | |
5d028165 | 708 | @code{flymake-err-line-patterns} variable. This variable contains a |
4009494e GM |
709 | list of items of the form @code{(regexp file-idx line-idx |
710 | err-text-idx)}, used to determine whether a particular line is an | |
711 | error message and extract file name, line number and error text, | |
5d028165 XF |
712 | respectively. Error type (error/warning) is also guessed by matching |
713 | error text with the '@code{^[wW]arning}' pattern. Anything that was not | |
714 | classified as a warning is considered an error. Type is then used to | |
4009494e GM |
715 | sort error menu items, which shows error messages first. |
716 | ||
717 | Flymake is also able to interpret error message patterns missing err-text-idx | |
5d028165 XF |
718 | information. This is done by merely taking the rest of the matched line |
719 | (@code{(substring line (match-end 0))}) as error text. This trick allows | |
4009494e | 720 | to make use of a huge collection of error message line patterns from |
5d028165 | 721 | @code{compile.el}. All these error patterns are appended to |
4009494e GM |
722 | the end of @code{flymake-err-line-patterns}. |
723 | ||
724 | The error information obtained is saved in a buffer local | |
5d028165 | 725 | variable. The buffer for which the process output belongs is |
4009494e GM |
726 | determined from the process-id@w{}->@w{}buffer mapping updated |
727 | after every process launch/exit. | |
728 | ||
729 | @node Highlighting erroneous lines | |
730 | @section Highlighting erroneous lines | |
731 | @cindex Erroneous lines, faces | |
732 | ||
733 | Highlighting is implemented with overlays and happens in the process | |
5d028165 | 734 | sentinel, after calling the cleanup function. Two customizable faces |
176c6903 RS |
735 | are used: @code{flymake-errline} and |
736 | @code{flymake-warnline}. Errors belonging outside the current | |
4009494e GM |
737 | buffer are considered to belong to line 1 of the current buffer. |
738 | ||
24c38527 GM |
739 | @c This manual does not use vindex. |
740 | @c @vindex flymake-fringe-indicator-position | |
741 | @c @vindex flymake-error-bitmap | |
742 | @c @vindex flymake-warning-bitmap | |
743 | If the option @code{flymake-fringe-indicator-position} is non-@code{nil}, | |
744 | errors and warnings are also highlighted in the left or right fringe, | |
745 | using the bitmaps specified by @code{flymake-error-bitmap} | |
746 | and @code{flymake-warning-bitmap}. | |
747 | ||
4009494e GM |
748 | @node Interaction with other modes |
749 | @section Interaction with other modes | |
750 | @cindex Interaction with other modes | |
751 | @cindex Interaction with compile mode | |
752 | ||
753 | The only mode flymake currently knows about is @code{compile}. | |
754 | ||
755 | Flymake can be configured to not start syntax check if it thinks the | |
5d028165 | 756 | compilation is in progress. The check is made by the |
4009494e | 757 | @code{flymake-compilation-is-running}, which tests the |
5d028165 | 758 | @code{compilation-in-progress} variable. The reason why this might be |
4009494e | 759 | useful is saving CPU time in case both syntax check and compilation |
5d028165 XF |
760 | are very CPU intensive. The original reason for adding this feature, |
761 | though, was working around a locking problem with MS Visual C++ | |
762 | compiler. | |
4009494e GM |
763 | |
764 | Flymake also provides an alternative command for starting compilation, | |
765 | @code{flymake-compile}: | |
766 | ||
767 | @lisp | |
768 | (defun flymake-compile () | |
769 | "Kill all flymake syntax checks then start compilation." | |
770 | (interactive) | |
771 | (flymake-stop-all-syntax-checks) | |
772 | (call-interactively 'compile)) | |
773 | @end lisp | |
774 | ||
775 | It just kills all the active syntax check processes before calling | |
776 | @code{compile}. | |
777 | ||
778 | @node GNU Free Documentation License | |
779 | @appendix GNU Free Documentation License | |
780 | @include doclicense.texi | |
781 | ||
782 | @node Index | |
783 | @unnumbered Index | |
784 | ||
785 | @printindex cp | |
786 | ||
787 | @bye |