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