27.2 Compilation Mode

The *compilation* buffer uses a major mode called Compilation mode. Compilation mode turns each error message in the buffer into a hyperlink; you can move point to it and type RET, or click on it with the mouse (see Following References with the Mouse), to visit the locus of the error message in a separate window. The locus is the specific position in a file where that error occurred.

The appearance of the *compilation* buffer can be controlled by customizing the faces which are used to highlight parts of the *compilation* buffer, e.g., compilation-error or compilation-warning, for error and warning messages respectively. Note that since those faces inherit from the error and warning faces, it is also possible to customize the parent face directly instead.

Use M-x customize-group RET compilation to see the entire list of customization variables and faces.

If you change the variable compilation-auto-jump-to-first-error to a non- nil value, Emacs automatically visits the locus of the first error message that appears in the *compilation* buffer.

Compilation mode provides the following additional commands. These commands can also be used in *grep* buffers, where the hyperlinks are search matches rather than error messages (see Searching with Grep under Emacs).

M-g M-n``M-g n```C-x ``

Visit the locus of the next error message or match ( next-error).

M-g M-p``M-g p

Visit the locus of the previous error message or match ( previous-error).

M-n

Move point to the next error message or match, without visiting its locus ( compilation-next-error).

M-p

Move point to the previous error message or match, without visiting its locus ( compilation-previous-error).

M-}

Move point to the next error message or match occurring in a different file ( compilation-next-file).

M-{

Move point to the previous error message or match occurring in a different file ( compilation-previous-file).

C-c C-f

Toggle Next Error Follow minor mode, which makes cursor motion in the compilation buffer produce automatic source display.

g

Re-run the last command whose output is shown in the *compilation* buffer.

M-x next-error-select-buffer

Select a buffer to be used by next invocation of next-error and previous-error.

To visit errors sequentially, type C-x ` ( next-error), or equivalently M-g M-n or M-g n. This command can be invoked from any buffer, not just a Compilation mode buffer. The first time you invoke it after a compilation, it visits the locus of the first error message. Each subsequent M-g M-n visits the next error, in a similar fashion. If you visit a specific error with RET or a mouse click in the *compilation* buffer, subsequent M-g M-n commands advance from there. When M-g M-n finds no more error messages to visit, it signals an error. C-u M-g M-n starts again from the beginning of the compilation buffer, and visits the first locus.

M-g M-p or M-g p ( previous-error) iterates through errors in the opposite direction.

The next-error and previous-error commands don’t just act on the errors or matches listed in *compilation* and *grep* buffers; they also know how to iterate through error or match lists produced by other commands, such as M-x occur (see Other Search-and-Loop Commands). If the current buffer contains error messages or matches, these commands will iterate through them; otherwise, Emacs looks for a buffer containing error messages or matches amongst the windows of the selected frame (if the variable next-error-find-buffer-function is customized to the value next-error-buffer-on-selected-frame), then for a buffer used previously by next-error or previous-error, and finally all other buffers. Any buffer these commands iterate through that is not currently displayed in a window will be displayed. You can use the next-error-select-buffer command to switch to a different buffer to be used by the subsequent invocation of next-error.

By default, the next-error and previous-error commands skip less important messages. The variable compilation-skip-threshold controls this. The default value, 1, means to skip anything less important than a warning. A value of 2 means to skip anything less important than an error, while 0 means not to skip any messages.

When Emacs visits the locus of an error message, it momentarily highlights the relevant source line. The duration of this highlight is determined by the variable next-error-highlight for the locus in the selected buffer, and next-error-highlight-no-select for the locus in non-selected buffers. Also you can customize the variable next-error-message-highlight that defines how to highlight the current error message in the buffer that contains messages.

If the *compilation* buffer is shown in a window with a left fringe (see Window Fringes), the locus-visiting commands put an arrow in the fringe, pointing to the current error message. If the window has no left fringe, such as on a text terminal, these commands scroll the window so that the current message is at the top of the window. If you change the variable compilation-context-lines to t, a visible arrow is inserted before column zero instead. If you change the variable to an integer value n, these commands scroll the window so that the current error message is n lines from the top, whether or not there is a fringe; the default value, nil, gives the behavior described above.

To parse messages from the compiler, Compilation mode uses the variable compilation-error-regexp-alist which lists various error message formats and tells Emacs how to extract the locus from each. A similar variable, grep-regexp-alist, tells Emacs how to parse output from a grep command (see Searching with Grep under Emacs).

Compilation mode also defines the keys SPC and DEL to scroll by screenfuls; M-n ( compilation-next-error) and M-p ( compilation-previous-error) to move to the next or previous error message; and M-{ ( compilation-next-file) and M-} ( compilation-previous-file) to move to the next or previous error message for a different source file.

You can type C-c C-f to toggle Next Error Follow mode. In this minor mode, ordinary cursor motion in the compilation buffer automatically updates the source buffer, i.e., moving the cursor over an error message causes the locus of that error to be displayed.

The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in any buffer, not just a normal compilation output buffer. Type M-x compilation-minor-mode to enable the minor mode. For instance, in an Rlogin buffer (see Remote Host Shell), Compilation minor mode automatically accesses remote source files by FTP (see File Names).