flymake.texi 27 KB

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