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