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