Mercurial > emacs
annotate man/flymake.texi @ 68082:dfbba4e99c09
*** empty log message ***
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 07 Jan 2006 15:12:32 +0000 |
parents | 3d53033a6d29 |
children | 0aad66a76c40 |
rev | line source |
---|---|
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 | |
64890
3723093a21fd
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
63952
diff
changeset
|
14 Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc. |
55822 | 15 |
16 @quotation | |
17 Permission is granted to copy, distribute and/or modify this document | |
65555
69b3598a61c5
Update all manuals to specify GFDL version 1.2.
Romain Francoise <romain@orebokech.com>
parents:
64890
diff
changeset
|
18 under the terms of the GNU Free Documentation License, Version 1.2 or |
55822 | 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}. | |
68071
3d53033a6d29
(Obtaining Flymake): Update Flymake's CVS repository URL.
Eli Zaretskii <eliz@gnu.org>
parents:
65555
diff
changeset
|
113 |
3d53033a6d29
(Obtaining Flymake): Update Flymake's CVS repository URL.
Eli Zaretskii <eliz@gnu.org>
parents:
65555
diff
changeset
|
114 You can also try the current development version available via CVS at |
3d53033a6d29
(Obtaining Flymake): Update Flymake's CVS repository URL.
Eli Zaretskii <eliz@gnu.org>
parents:
65555
diff
changeset
|
115 @url{https://sourceforge.net/cvs/?group_id=77501}. |
55822 | 116 |
117 Flymake's homepage is at @url{http://flymake.sourceforge.net}. | |
118 | |
119 @node Installing Flymake | |
120 @chapter Installing | |
121 @cindex Installing Flymake | |
122 | |
123 | |
124 Flymake is packaged in a single file, @code{flymake.el}. | |
125 | |
126 To install/update Flymake, place @code{flymake.el} to a directory | |
127 somewhere on Emacs load path. You might also want to byte-compile | |
128 @code{flymake.el} to improve performance. | |
129 | |
130 Also, place the following line in the @code{.emacs} file. | |
131 | |
132 @lisp | |
133 (require 'flymake) | |
134 @end lisp | |
135 | |
136 You might also map the most frequently used Flymake functions, such as | |
137 @code{flymake-goto-next-error}, to some keyboard shortcuts: | |
138 | |
139 @lisp | |
140 (global-set-key [f3] 'flymake-display-err-menu-for-current-line) | |
141 (global-set-key [f4] 'flymake-goto-next-error) | |
142 @end lisp | |
143 | |
144 @node Using Flymake | |
145 @chapter Using Flymake | |
146 @cindex Using Flymake | |
147 | |
148 @menu | |
149 * Flymake mode:: | |
150 * Running the syntax check:: | |
151 * Navigating to error lines:: | |
152 * Viewing error messages:: | |
153 * Syntax check statuses:: | |
154 * Troubleshooting:: | |
155 @end menu | |
156 | |
157 @node Flymake mode | |
158 @section Flymake mode | |
159 @cindex flymake-mode | |
160 | |
161 Flymake is an Emacs minor mode. To use Flymake, you | |
162 must first activate @code{flymake-mode} by using the | |
163 @code{flymake-mode} function. | |
164 | |
165 Instead of manually activating @code{flymake-mode}, you can configure | |
166 Flymake to automatically enable @code{flymake-mode} upon opening any | |
167 file for which syntax check is possible. To do so, place the following | |
168 line in @code{.emacs}: | |
169 | |
170 @lisp | |
171 (add-hook 'find-file-hooks 'flymake-find-file-hook) | |
172 @end lisp | |
173 | |
174 @node Running the syntax check | |
175 @section Running the syntax check | |
176 @cindex Manually starting the syntax check | |
177 | |
178 When @code{flymake-mode} is active, syntax check is started | |
179 automatically on any of the three conditions mentioned above. Syntax | |
180 check can also be started manually by using the | |
181 @code{flymake-start-syntax-check-for-current-buffer} function. This | |
182 can be used, for example, when changes were made to some other buffer | |
183 affecting the current buffer. | |
184 | |
185 @node Navigating to error lines | |
186 @section Navigating to error lines | |
187 @cindex Navigating to error lines | |
188 | |
189 After syntax check is completed, lines for which at least one error or | |
190 warning has been reported are highlighted, and total number of errors | |
191 and warning is shown in the mode line. Use the following functions to | |
192 navigate the highlighted lines. | |
193 | |
194 @multitable @columnfractions 0.25 0.75 | |
195 | |
196 @item @code{flymake-goto-next-error} | |
197 @tab Moves point to the next erroneous line, if any. | |
198 | |
199 @item @code{flymake-goto-prev-error} | |
200 @tab Moves point to the previous erroneous line. | |
201 | |
202 @end multitable | |
203 | |
204 These functions treat erroneous lines as a linked list. Therefore, | |
205 @code{flymake-goto-next-error} will go to the first erroneous line | |
206 when invoked in the end of the buffer. | |
207 | |
208 @node Viewing error messages | |
209 @section Viewing error messages | |
210 @cindex Viewing error messages | |
211 | |
212 To view error messages belonging to the current line, use the | |
213 @code{flymake-display-err-menu-for-current-line} function. If there's | |
214 at least one error or warning reported for the current line, this | |
215 function will display a popup menu with error/warning texts. | |
216 Selecting the menu item whose error belongs to another file brings | |
217 forward that file with the help of the | |
218 @code{flymake-goto-file-and-line} function. | |
219 | |
220 @node Syntax check statuses | |
221 @section Syntax check statuses | |
222 @cindex Syntax check statuses | |
223 | |
224 After syntax check is finished, its status is displayed in the mode line. | |
225 The following statuses are defined. | |
226 | |
227 @multitable @columnfractions 0.25 0.75 | |
228 @item Flymake* or Flymake:E/W* | |
229 @tab Flymake is currently running. For the second case, E/W contains the | |
230 error and warning count for the previous run. | |
231 | |
232 @item Flymake | |
233 @tab Syntax check is not running. Usually this means syntax check was | |
234 successfully passed (no errors, no warnings). Other possibilities are: | |
235 syntax check was killed as a result of executing | |
236 @code{flymake-compile}, or syntax check cannot start as compilation | |
237 is currently in progress. | |
238 | |
239 @item Flymake:E/W | |
240 @tab Number of errors/warnings found by the syntax check process. | |
241 | |
242 @item Flymake:! | |
243 @tab Flymake was unable to find master file for the current buffer. | |
244 @end multitable | |
245 | |
246 The following errors cause a warning message and switch flymake mode | |
247 OFF for the buffer. | |
248 | |
249 @multitable @columnfractions 0.25 0.75 | |
250 @item CFGERR | |
251 @tab Syntax check process returned nonzero exit code, but no | |
252 errors/warnings were reported. This indicates a possible configuration | |
253 error (for example, no suitable error message patterns for the | |
254 syntax check tool). | |
255 | |
256 @item NOMASTER | |
257 @tab Flymake was unable to find master file for the current buffer. | |
258 | |
259 @item NOMK | |
260 @tab Flymake was unable to find a suitable buildfile for the current buffer. | |
261 | |
262 @item PROCERR | |
263 @tab Flymake was unable to launch a syntax check process. | |
264 @end multitable | |
265 | |
266 | |
267 @node Troubleshooting | |
268 @section Troubleshooting | |
269 @cindex Logging | |
270 @cindex Troubleshooting | |
271 | |
272 Flymake uses a simple logging facility for indicating important points | |
273 in the control flow. The logging facility sends logging messages to | |
274 the @code{*Messages*} buffer. The information logged can be used for | |
275 resolving various problems related to Flymake. | |
276 | |
277 Logging output is controlled by the @code{flymake-log-level} | |
278 variable. @code{3} is the most verbose level, and @code{-1} switches | |
279 logging off. | |
280 | |
281 @node Configuring Flymake | |
282 @chapter Configuring and Extending Flymake | |
283 @cindex Configuring and Extending Flymake | |
284 | |
285 @menu | |
286 * Customizable variables:: | |
287 * Adding support for a new syntax check tool:: | |
288 @end menu | |
289 | |
290 Flymake was designed to be easily extended for supporting new syntax | |
291 check tools and error message patterns. | |
292 | |
293 @node Customizable variables | |
294 @section Customizable variables | |
295 @cindex Customizable variables | |
296 | |
63600 | 297 This section summarizes variables used for Flymake |
55822 | 298 configuration. |
299 | |
300 @table @code | |
301 @item flymake-log-level | |
302 Controls logging output, see @ref{Troubleshooting}. | |
303 | |
304 @item flymake-allowed-file-name-masks | |
305 A list of @code{(filename-regexp, init-function, cleanup-function | |
306 getfname-function)} for configuring syntax check tools. @xref{Adding | |
307 support for a new syntax check tool}. | |
308 | |
309 @item flymake-buildfile-dirs | |
310 A list of directories (relative paths) for searching a | |
311 buildfile. @xref{Locating the buildfile}. | |
312 | |
313 @item flymake-master-file-dirs | |
314 A list of directories for searching a master file. @xref{Locating a | |
315 master file}. | |
316 | |
317 @item flymake-get-project-include-dirs-function | |
318 A function used for obtaining a list of project include dirs (C/C++ | |
319 specific). @xref{Getting the include directories}. | |
320 | |
321 @item flymake-master-file-count-limit | |
322 @itemx flymake-check-file-limit | |
323 Used when looking for a master file. @xref{Locating a master file}. | |
324 | |
325 @item flymake-err-line-patterns | |
326 Patterns for error/warning messages in the form @code{(regexp file-idx | |
327 line-idx err-text-idx)}. @xref{Parsing the output}. | |
328 | |
329 @item flymake-compilation-prevents-syntax-check | |
330 A flag indicating whether compilation and syntax check of the same | |
331 file cannot be run simultaneously. | |
332 | |
333 @item flymake-no-changes-timeout | |
334 If any changes are made to the buffer, syntax check is automatically | |
335 started after @code{flymake-no-changes-timeout} seconds. | |
336 | |
337 @item flymake-gui-warnings-enabled | |
338 A boolean flag indicating whether Flymake will show message boxes for | |
339 non-recoverable errors. If @code{flymake-gui-warnings-enabled} is | |
340 @code{nil}, these errors will only be logged to the @code{*Messages*} | |
341 buffer. | |
342 | |
343 @item flymake-start-syntax-check-on-newline | |
344 A boolean flag indicating whether to start syntax check after a | |
345 newline character is added to the buffer. | |
346 | |
347 @item flymake-errline-face | |
348 A custom face for highlighting lines for which at least one error has | |
349 been reported. | |
350 | |
351 @item flymake-warnline-face | |
352 A custom face for highlighting lines for which at least one warning | |
353 and no errors have been reported. | |
354 | |
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 | |
362 * Example -- Configuring a tool called directly:: | |
363 * Example -- Configuring a tool called via make:: | |
364 @end menu | |
365 | |
366 Syntax check tools are configured using the | |
367 @code{flymake-allowed-file-name-masks} list. Each item of this list | |
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 | |
378 @code{flymake-allowed-file-name-masks} are searched sequentially. The | |
379 first item with @code{filename-regexp} matching buffer filename is | |
380 selected. If no match is found, @code{flymake-mode} is switched off. | |
381 | |
382 @item init-function | |
63600 | 383 @code{init-function} is required to initialize the syntax check, |
55822 | 384 usually by creating a temporary copy of the buffer contents. The |
385 function must return @code{(list cmd-name arg-list)}. If | |
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 | |
396 check tool into ``real'' filenames. Filenames reported by the tool | |
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 | |
413 @node Example -- Configuring a tool called directly | |
414 @subsection Example -- Configuring a tool called directly | |
415 @cindex Adding support for perl | |
416 | |
417 In this example, we will add support for @code{perl} as a syntax check | |
418 tool. @code{perl} supports the @code{-c} option which does syntax | |
419 checking. | |
420 | |
421 First, we write the @code{init-function}: | |
422 | |
423 @lisp | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
424 (defun flymake-perl-init (buffer) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
425 (let* ((temp-file (flymake-init-create-temp-buffer-copy |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
426 buffer 'flymake-create-temp-inplace)) |
63952
4133ed695908
(Example -- Configuring a tool called directly):
Richard M. Stallman <rms@gnu.org>
parents:
63600
diff
changeset
|
427 (local-file (concat (flymake-build-relative-filename |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
428 (file-name-directory |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
429 (buffer-file-name |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
430 (current-buffer))) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
431 (file-name-directory temp-file)) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
432 (file-name-nondirectory temp-file)))) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
433 (list "perl" (list "-wc " local-file)))) |
55822 | 434 @end lisp |
435 | |
436 @code{flymake-perl-init} creates a temporary copy of the buffer | |
437 contents with the help of | |
438 @code{flymake-init-create-temp-buffer-copy}, and builds an appropriate | |
439 command line. | |
440 | |
441 Next, we add a new entry to the | |
442 @code{flymake-allowed-file-name-masks}: | |
443 | |
444 @lisp | |
445 (setq flymake-allowed-file-name-masks | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
446 (cons '(".+\\.pl$" |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
447 flymake-perl-init |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
448 flymake-simple-cleanup |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
449 flymake-get-real-file-name) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
450 flymake-allowed-file-name-masks)) |
55822 | 451 @end lisp |
452 | |
453 Note that we use standard @code{cleanup-function} and | |
454 @code{getfname-function}. | |
455 | |
456 Finally, we add an entry to @code{flymake-err-line-patterns}: | |
457 | |
458 @lisp | |
459 (setq flymake-err-line-patterns | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
460 (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
461 2 3 nil 1) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
462 flymake-err-line-patterns)) |
55822 | 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 | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
478 (cons '(".+\\.c$" |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
479 flymake-simple-make-init |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
480 flymake-simple-cleanup |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
481 flymake-get-real-file-name) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
482 flymake-allowed-file-name-masks)) |
55822 | 483 @end lisp |
484 | |
485 @code{flymake-simple-make-init} builds the following @code{make} | |
486 command line: | |
487 | |
488 @lisp | |
489 (list "make" | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
490 (list "-s" "-C" |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
491 base-dir |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
492 (concat "CHK_SOURCES=" source) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
493 "SYNTAX_CHECK_MODE=1" |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
494 "check-syntax")) |
55822 | 495 @end lisp |
496 | |
497 @code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. | |
498 | |
499 Thus, @code{Makefile} must contain the @code{check-syntax} target. In | |
500 our case this target might look like this: | |
501 | |
502 @verbatim | |
503 check-syntax: | |
504 gcc -o nul -S ${CHK_SOURCES} | |
505 @end verbatim | |
506 | |
507 The format of error messages reported by @code{gcc} is already | |
508 supported by Flymake, so we don't have to add a new entry to | |
509 @code{flymake-err-line-patterns}. | |
510 | |
511 @node Flymake Implementation | |
512 @chapter Flymake Implementation | |
513 @cindex Implementation details | |
514 | |
515 @menu | |
516 * Determining whether syntax check is possible:: | |
517 * Making a temporary copy:: | |
518 * Locating a master file:: | |
519 * Getting the include directories:: | |
520 * Locating the buildfile:: | |
521 * Starting the syntax check process:: | |
522 * Parsing the output:: | |
523 * Highlighting erroneous lines:: | |
524 * Interaction with other modes:: | |
525 @end menu | |
526 | |
527 Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. | |
528 Flymake first determines whether it is able to do syntax | |
529 check. It then saves a copy of the buffer in a temporary file in the | |
530 buffer's directory (or in the system temp directory -- for java | |
531 files), creates a syntax check command and launches a process with | |
532 this command. The output is parsed using a list of error message patterns, | |
533 and error information (file name, line number, type and text) is | |
534 saved. After the process has finished, Flymake highlights erroneous | |
535 lines in the buffer using the accumulated error information. | |
536 | |
537 @node Determining whether syntax check is possible | |
538 @section Determining whether syntax check is possible | |
539 @cindex Syntax check models | |
540 @cindex Master file | |
541 | |
542 Syntax check is considered possible if there's an entry in | |
543 @code{flymake-allowed-file-name-masks} matching buffer's filename and | |
56279
b1ae5333057a
* ses.texi, viper.texi, search.texi, flymake.texi, faq.texi:
Jesper Harder <harder@ifa.au.dk>
parents:
55855
diff
changeset
|
544 its @code{init-function} returns non-@code{nil} value. |
55822 | 545 |
546 Two syntax check modes are distinguished: | |
547 | |
548 @enumerate | |
549 | |
550 @item | |
551 Buffer can be syntax checked in a standalone fashion, that is, the | |
552 file (its temporary copy, in fact) can be passed over to the compiler to | |
553 do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) | |
554 sources. | |
555 | |
556 @item | |
557 Buffer can be syntax checked, but additional file, called master file, | |
558 is required to perform this operation. A master file is a file that | |
559 includes the current file, so that running a syntax check tool on it | |
560 will also check syntax in the current file. Examples are C/C++ (.h, | |
561 .hpp) headers. | |
562 | |
563 @end enumerate | |
564 | |
565 These modes are handled inside init/cleanup/getfname functions, see | |
566 @ref{Adding support for a new syntax check tool}. | |
567 | |
568 Flymake contains implementations of all functionality required to | |
569 support different syntax check modes described above (making | |
570 temporary copies, finding master files, etc.), as well as some | |
571 tool-specific (routines for @code{make}, @code{Ant}, etc.) code. | |
572 | |
573 | |
574 @node Making a temporary copy | |
575 @section Making a temporary copy | |
576 @cindex Temporary copy of the buffer | |
577 @cindex Master file | |
578 | |
579 After the possibility of the syntax check has been determined, a | |
580 temporary copy of the current buffer is made so that the most recent | |
581 unsaved changes could be seen by the syntax check tool. Making a copy | |
582 is quite straightforward in a standalone case (mode @code{1}), as it's | |
583 just saving buffer contents to a temporary file. | |
584 | |
585 Things get trickier, however, when master file is involved, as it | |
586 requires to | |
587 | |
588 @itemize @bullet | |
589 @item locate a master file | |
590 @item patch it to include the current file using its new (temporary) | |
591 name. | |
592 @end itemize | |
593 | |
594 Locating a master file is discussed in the following section. | |
595 | |
596 Patching just changes all appropriate lines of the master file so that they | |
597 use the new (temporary) name of the current file. For example, suppose current | |
598 file name is @code{file.h}, the master file is @code{file.cpp}, and | |
599 it includes current file via @code{#include "file.h"}. Current file's copy | |
600 is saved to file @code{file_flymake.h}, so the include line must be | |
601 changed to @code{#include "file_flymake.h"}. Finally, patched master file | |
602 is saved to @code{file_flymake_master.cpp}, and the last one is passed to | |
603 the syntax check tool. | |
604 | |
605 @node Locating a master file | |
606 @section Locating a master file | |
607 @cindex Master file | |
608 | |
609 Master file is located in two steps. | |
610 | |
611 First, a list of possible master files is built. A simple name | |
612 matching is used to find the files. For a C++ header @code{file.h}, | |
613 Flymake searches for all @code{.cpp} files in the directories whose relative paths are | |
614 stored in a customizable variable @code{flymake-master-file-dirs}, which | |
615 usually contains something like @code{("." "./src")}. No more than | |
616 @code{flymake-master-file-count-limit} entries is added to the master file | |
617 list. The list is then sorted to move files with names @code{file.cpp} to | |
618 the top. | |
619 | |
620 Next, each master file in a list is checked to contain the appropriate | |
621 include directives. No more than @code{flymake-check-file-limit} of each | |
622 file are parsed. | |
623 | |
624 For @code{file.h}, the include directives to look for are | |
625 @code{#include "file.h"}, @code{#include "../file.h"}, etc. Each | |
626 include is checked against a list of include directories | |
627 (see @ref{Getting the include directories}) to be sure it points to the | |
628 correct @code{file.h}. | |
629 | |
630 First matching master file found stops the search. The master file is then | |
631 patched and saved to disk. In case no master file is found, syntax check is | |
632 aborted, and corresponding status (!) is reported in the mode line. | |
633 | |
634 @node Getting the include directories | |
635 @section Getting the include directories | |
636 @cindex Include directories (C/C++ specific) | |
637 | |
638 Two sets of include directories are distinguished: system include directories | |
639 and project include directories. The former is just the contents of the | |
640 @code{INCLUDE} environment variable. The latter is not so easy to obtain, | |
641 and the way it can be obtained can vary greatly for different projects. | |
642 Therefore, a customizable variable | |
643 @code{flymake-get-project-include-dirs-function} is used to provide the | |
63600 | 644 way to implement the desired behavior. |
55822 | 645 |
646 The default implementation, @code{flymake-get-project-include-dirs-imp}, | |
647 uses a @code{make} call. This requires a correct base directory, that is, a | |
648 directory containing a correct @code{Makefile}, to be determined. | |
649 | |
650 As obtaining the project include directories might be a costly operation, its | |
651 return value is cached in the hash table. The cache is cleared in the beginning | |
652 of every syntax check attempt. | |
653 | |
654 @node Locating the buildfile | |
655 @section Locating the buildfile | |
656 @cindex Locating the buildfile | |
657 @cindex buildfile, locating | |
658 @cindex Makefile, locating | |
659 | |
660 Flymake can be configured to use different tools for performing syntax | |
661 checks. For example, it can use direct compiler call to syntax check a perl | |
662 script or a call to @code{make} for a more complicated case of a | |
63600 | 663 @code{C/C++} source. The general idea is that simple files, like perl |
55822 | 664 scripts and html pages, can be checked by directly invoking a |
665 corresponding tool. Files that are usually more complex and generally | |
666 used as part of larger projects, might require non-trivial options to | |
667 be passed to the syntax check tool, like include directories for | |
668 C++. The latter files are syntax checked using some build tool, like | |
669 @code{make} or @code{Ant}. | |
670 | |
671 All @code{make} configuration data is usually stored in a file called | |
672 @code{Makefile}. To allow for future extensions, flymake uses a notion of | |
673 buildfile to reference the 'project configuration' file. | |
674 | |
675 Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. | |
676 Searching for a buildfile is done in a manner similar to that of searching | |
677 for possible master files. A customizable variable | |
678 @code{flymake-buildfile-dirs} holds a list of relative paths to the | |
679 buildfile. They are checked sequentially until a buildfile is found. In case | |
680 there's no build file, syntax check is aborted. | |
681 | |
682 Buildfile values are also cached. | |
683 | |
684 @node Starting the syntax check process | |
685 @section Starting the syntax check process | |
686 @cindex Syntax check process | |
687 | |
688 The command line (command name and the list of arguments) for launching a process is returned by the | |
689 initialization function. Flymake then just calls @code{start-process} | |
690 to start an asynchronous process and configures process filter and | |
691 sentinel which is used for processing the output of the syntax check | |
692 tool. | |
693 | |
694 @node Parsing the output | |
695 @section Parsing the output | |
696 @cindex Parsing the output | |
697 | |
698 The output generated by the syntax check tool is parsed in the process | |
699 filter/sentinel using the error message patterns stored in the | |
700 @code{flymake-err-line-patterns} variable. This variable contains a | |
701 list of items of the form @code{(regexp file-idx line-idx | |
702 err-text-idx)}, used to determine whether a particular line is an | |
703 error message and extract file name, line number and error text, | |
704 respectively. Error type (error/warning) is also guessed by matching | |
705 error text with the '@code{^[wW]arning}' pattern. Anything that was not | |
706 classified as a warning is considered an error. Type is then used to | |
707 sort error menu items, which shows error messages first. | |
708 | |
709 Flymake is also able to interpret error message patterns missing err-text-idx | |
710 information. This is done by merely taking the rest of the matched line | |
711 (@code{(substring line (match-end 0))}) as error text. This trick allows | |
712 to make use of a huge collection of error message line patterns from | |
713 @code{compile.el}. All these error patterns are appended to | |
714 the end of @code{flymake-err-line-patterns}. | |
715 | |
716 The error information obtained is saved in a buffer local | |
717 variable. The buffer for which the process output belongs is | |
718 determined from the process-id@w{}->@w{}buffer mapping updated | |
719 after every process launch/exit. | |
720 | |
721 @node Highlighting erroneous lines | |
722 @section Highlighting erroneous lines | |
723 @cindex Erroneous lines, faces | |
724 | |
725 Highlighting is implemented with overlays and happens in the process | |
726 sentinel, after calling the cleanup function. Two customizable faces | |
727 are used: @code{flymake-errline-face} and | |
728 @code{flymake-warnline-face}. Errors belonging outside the current | |
729 buffer are considered to belong to line 1 of the current buffer. | |
730 | |
731 @node Interaction with other modes | |
732 @section Interaction with other modes | |
733 @cindex Interaction with other modes | |
734 @cindex Interaction with compile mode | |
735 | |
736 The only mode flymake currently knows about is @code{compile}. | |
737 | |
738 Flymake can be configured to not start syntax check if it thinks the | |
739 compilation is in progress. The check is made by the | |
740 @code{flymake-compilation-is-running}, which tests the | |
741 @code{compilation-in-progress} variable. The reason why this might be | |
742 useful is saving CPU time in case both syntax check and compilation | |
743 are very CPU intensive. The original reason for adding this feature, | |
744 though, was working around a locking problem with MS Visual C++ compiler. | |
745 | |
746 Flymake also provides an alternative command for starting compilation, | |
747 @code{flymake-compile}: | |
748 | |
749 @lisp | |
60407
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
750 (defun flymake-compile () |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
751 "Kill all flymake syntax checks then start compilation." |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
752 (interactive) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
753 (flymake-stop-all-syntax-checks) |
7c70ab62c5d7
Refill and tweak style in @lisp blocks.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
56279
diff
changeset
|
754 (call-interactively 'compile)) |
55822 | 755 @end lisp |
756 | |
757 It just kills all the active syntax check processes before calling | |
758 @code{compile}. | |
759 | |
760 @node Index | |
761 @unnumbered Index | |
762 | |
763 @printindex cp | |
764 | |
765 @bye | |
55855
fea2f114cd7d
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
55822
diff
changeset
|
766 |
fea2f114cd7d
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
55822
diff
changeset
|
767 @ignore |
fea2f114cd7d
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
55822
diff
changeset
|
768 arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec |
fea2f114cd7d
Changes from arch/CVS synchronization
Miles Bader <miles@gnu.org>
parents:
55822
diff
changeset
|
769 @end ignore |