Compiling and Testing Programs
******************************

The previous chapter discusses the Emacs commands that are useful for making changes in programs.  This chapter deals with commands that assist in the process of compiling and testing programs.

Running Compilations under Emacs
================================

Emacs can run compilers for languages such as C and Fortran, feeding the compilation log into an Emacs buffer.  It can also parse the error messages and show you where the errors occurred.

M-x compile
     Run a compiler asynchronously under Emacs, with error messages going to the *compilation* buffer.

M-x recompile
     Invoke a compiler with the same command as in the last invocation of M-x compile.

M-x kill-compilation
     Kill the running compilation subprocess.

To run make or another compilation command, type M-x compile.  This reads a shell command line using the minibuffer, and then executes the command by running a shell as a subprocess (or inferior process) of Emacs.  The output is inserted in a buffer named *compilation*.  The current buffer's default directory is used as the working directory for the execution of the command; normally, therefore, compilation takes place in this directory.

The default compilation command is make -k, which is usually correct for programs compiled using the make utility (the -k flag tells make to continue compiling as much as possible after an error).  See Make (GNU Make Manual). If you have done M-x compile before, the command that you specified is automatically stored in the variable compile-command; this is used as the default the next time you type M-x compile.  A file can also specify a file-local value for compile-command (see File Variables).

Starting a compilation displays the *compilation* buffer in another window but does not select it.  While the compilation is running, the word run is shown in the major mode indicator for the *compilation* buffer, and the word Compiling appears in all mode lines.  You do not have to keep the *compilation* buffer visible while compilation is running; it continues in any case. When the compilation ends, for whatever reason, the mode line of the *compilation* buffer changes to say exit (followed by the exit code: [0] for a normal exit), or signal (if a signal terminated the process).

If you want to watch the compilation transcript as it appears, switch to the *compilation* buffer and move point to the end of the buffer.  When point is at the end, new compilation output is inserted above point, which remains at the end.  Otherwise, point remains fixed while compilation output is added at the end of the buffer.

If you change the variable compilation-scroll-output to a non-nil value, the *compilation* buffer scrolls automatically to follow the output.  If the value is first-error, scrolling stops when the first error appears, leaving point at that error.  For any other non-nil value, scrolling continues until there is no more output.

To rerun the last compilation with the same command, type M-x recompile.  This reuses the compilation command from the last invocation of M-x compile.  It also reuses the *compilation* buffer and starts the compilation in its default directory, which is the directory in which the previous compilation was started.

Starting a new compilation also kills any compilation already running in *compilation*, as the buffer can only handle one compilation at any time.  However, M-x compile asks for confirmation before actually killing a compilation that is running. You can also kill the compilation process with M-x kill-compilation.

To run two compilations at once, start the first one, then rename the *compilation* buffer (perhaps using rename-uniquely; see Misc Buffer), then switch buffers and start the other compilation.  This will create a new *compilation* buffer.

You can control the environment passed to the compilation command with the variable compilation-environment.  Its value is a list of environment variable settings; each element should be a string of the form "ENVVARNAME=VALUE".  These environment variable settings override the usual ones.

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 Mouse References), 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.

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 Grep Searching).

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.

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 C-x ` 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 C-x ` commands advance from there.  When C-x ` finds no more error messages to visit, it signals an error.  C-u C-x ` 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 Repeating Search).  If you are already in a buffer containing error messages or matches, those are the ones that are iterated through; otherwise, Emacs looks for a buffer containing error messages or matches amongst the windows of the selected frame, then for one that next-error or previous-error previously iterated through, and finally amongst all other buffers.  If the buffer chosen for iterating through is not currently displayed in a window, it will be displayed.

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.

If the *compilation* buffer is shown in a window with a left fringe (see 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-only 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 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 Grep Searching).

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), Compilation minor mode automatically accesses remote source files by FTP (see File Names).

Subshells for Compilation
=========================

The M-x compile command uses a shell to run the compilation command, but specifies the option for a noninteractive shell.  This means, in particular, that the shell should start with no prompt.  If you find your usual shell prompt making an unsightly appearance in the *compilation* buffer, it means you have made a mistake in your shell's init file by setting the prompt unconditionally.  (This init file may be named .bashrc, .profile, .cshrc, .shrc, etc., depending on what shell you use.)  The shell init file should set the prompt only if there already is a prompt.  Here's how to do it in bash:

     if [ "${PS1+set}" = set ]
     then PS1=...
     fi

And here's how to do it in csh:

     if ($?prompt) set prompt = ...

Emacs does not expect a compiler process to launch asynchronous subprocesses; if it does, and they keep running after the main compiler process has terminated, Emacs may kill them or their output may not arrive in Emacs.  To avoid this problem, make the main compilation process wait for its subprocesses to finish.  In a shell script, you can do this using $! and wait, like this:

     (sleep 10; echo 2nd)& pid=$!  # Record pid of subprocess
     echo first message
     wait $pid                     # Wait for subprocess

If the background process does not output to the compilation buffer, so you only need to prevent it from being killed when the main compilation process terminates, this is sufficient:

     nohup COMMAND; sleep 1

On the MS-DOS ``operating system'', asynchronous subprocesses are not supported, so M-x compile runs the compilation command synchronously (i.e. you must wait until the command finishes before you can do anything else in Emacs).  See MS-DOS.

Searching with Grep under Emacs
===============================

Just as you can run a compiler from Emacs and then visit the lines with compilation errors, you can also run grep and then visit the lines on which matches were found.  This works by treating the matches reported by grep as if they were ``errors.'' The output buffer uses Grep mode, which is a variant of Compilation mode (see Compilation Mode).

M-x grep
M-x lgrep
     Run grep asynchronously under Emacs, listing matching lines in the buffer named *grep*.

M-x grep-find
M-x find-grep
M-x rgrep
     Run grep via find, and collect output in the *grep* buffer.

M-x zrgrep
     Run zgrep and collect output in the *grep* buffer.

M-x kill-grep
     Kill the running grep subprocess.

To run grep, type M-x grep, then enter a command line that specifies how to run grep.  Use the same arguments you would give grep when running it normally: a grep-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names, which may use wildcards.  If you specify a prefix argument for M-x grep, it finds the tag (see Tags) in the buffer around point, and puts that into the default grep command.

Your command need not simply run grep; you can use any shell command that produces output in the same format.  For instance, you can chain grep commands, like this:

     grep -nH -e foo *.el | grep bar | grep toto

The output from grep goes in the *grep* buffer.  You can find the corresponding lines in the original files using C-x `, RET, and so forth, just like compilation errors.

Some grep programs accept a --color option to output special markers around matches for the purpose of highlighting.  You can make use of this feature by setting grep-highlight-matches to t.  When displaying a match in the source buffer, the exact match will be highlighted, instead of the entire source line.

The command M-x grep-find (also available as M-x find-grep) is similar to M-x grep, but it supplies a different initial default for the command---one that runs both find and grep, so as to search every file in a directory tree.  See also the find-grep-dired command, in Dired and Find.

The commands M-x lgrep (local grep) and M-x rgrep (recursive grep) are more user-friendly versions of grep and grep-find, which prompt separately for the regular expression to match, the files to search, and the base directory for the search. Case sensitivity of the search is controlled by the current value of case-fold-search.  The command M-x zrgrep is similar to M-x rgrep, but it calls zgrep instead of grep to search the contents of gzipped files.

These commands build the shell commands based on the variables grep-template (for lgrep) and grep-find-template (for rgrep).  The files to search can use aliases defined in the variable grep-files-aliases.

Directories listed in the variable grep-find-ignored-directories are automatically skipped by M-x rgrep.  The default value includes the data directories used by various version control systems.

Finding Syntax Errors On The Fly
================================

Flymake mode is a minor mode that performs on-the-fly syntax checking for many programming and markup languages, including C, C++, Perl, HTML, and TeX/LaTeX.  It is somewhat analogous to Flyspell mode, which performs spell checking for ordinary human languages in a similar fashion (see Spelling).  As you edit a file, Flymake mode runs an appropriate syntax checking tool in the background, using a temporary copy of the buffer.  It then parses the error and warning messages, and highlights the erroneous lines in the buffer.  The syntax checking tool used depends on the language; for example, for C/C++ files this is usually the C compiler.  Flymake can also use build tools such as make for checking complicated projects.

To enable Flymake mode, type M-x flymake-mode.  You can go to the errors found by Flymake mode with M-x flymake-goto-next-error and M-x flymake-goto-prev-error.  To display any error messages associated with the current line, use M-x flymake-display-err-menu-for-current-line.

For more details about using Flymake, see Flymake (The Flymake Manual).

Running Debuggers Under Emacs
=============================

The GUD (Grand Unified Debugger) library provides an Emacs interface to a wide variety of symbolic debuggers.  It can run the GNU Debugger (GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python debugger PDB, and the Java Debugger JDB.

Emacs provides a special interface to GDB, which uses extra Emacs windows to display the state of the debugged program.  See GDB Graphical Interface.

Emacs also has a built-in debugger for Emacs Lisp programs. See The Lisp Debugger (the Emacs Lisp Reference Manual).

Starting GUD
------------

There are several commands for starting a debugger subprocess, each corresponding to a particular debugger program.

M-x gdb
     Run GDB as a subprocess, and interact with it via an IDE-like Emacs interface.  See GDB Graphical Interface, for more information about this command.

M-x gud-gdb
     Run GDB, using a GUD interaction buffer for input and output to the GDB subprocess (see Debugger Operation).  If such a buffer already exists, switch to it; otherwise, create the buffer and switch to it.

     The other commands in this list do the same, for other debugger programs.

M-x perldb
     Run the Perl interpreter in debug mode.

M-x jdb
     Run the Java debugger.

M-x pdb
     Run the Python debugger.

M-x dbx
     Run the DBX debugger.

M-x xdb
     Run the XDB debugger.

M-x sdb
     Run the SDB debugger.

Each of these commands reads a command line to invoke the debugger, using the minibuffer.  The minibuffer's initial contents contain the standard executable name and options for the debugger, and sometimes also a guess for the name of the executable file you want to debug. Shell wildcards and variables are not allowed in this command line. Emacs assumes that the first command argument which does not start with a - is the executable file name.

Tramp provides a facility for remote debugging, whereby both the debugger and the program being debugged are on the same remote host. See Running a debugger on a remote host (The Tramp Manual), for details.  This is separate from GDB's remote debugging feature, where the program and the debugger run on different machines (see Debugging Remote Programs (The GNU debugger)).

Debugger Operation
------------------

The GUD interaction buffer is an Emacs buffer which is used to send text commands to a debugger subprocess, and record its output. This is the basic interface for interacting with a debugger, used by M-x gud-gdb and other commands listed in Starting GUD. The M-x gdb command extends this interface with additional specialized buffers for controlling breakpoints, stack frames, and other aspects of the debugger state (see GDB Graphical Interface).

The GUD interaction buffer uses a variant of Shell mode, so the Emacs commands defined by Shell mode are available (see Shell Mode).  Completion is available for most debugger commands (see Completion), and you can use the usual Shell mode history commands to repeat them.