Go to the previous, next section.
The previous chapter discusses the Emacs commands that are useful for making changes in programs. This chapter deals with commands that assist in the larger process of developing and maintaining programs.
Emacs can run compilers for noninteractive languages such as C and Fortran as inferior processes, feeding the error log into an Emacs buffer. It can also parse the error messages and visit the files in which errors are found, moving point right to the line where the error occurred.
grep asynchronously under Emacs, with matching lines
listed in the buffer named `*compilation*'.
grep subprocess.
grep match.
To run make or another compiler, do M-x compile. This command
reads a shell command line using the minibuffer, and then executes the
specified command line in an inferior shell with output going to the buffer
named `*compilation*'. The current buffer's default directory is used
as the working directory for the execution of the command; normally,
therefore, the makefile comes from this directory.
When the shell command line is read, the minibuffer appears containing a
default command line, which is the command you used the last time you did
M-x compile. If you type just RET, the same command line is used
again. The first M-x compile provides make -k as the default.
The default is taken from the variable compile-command; if the
appropriate compilation command for a file is something other than
make -k, it can be useful to have the file specify a local value for
compile-command (see section Local Variables in Files).
Starting a compilation causes the buffer `*compilation*' to be displayed in another window but not selected. Its mode line tells you whether compilation is finished, with the word `run' or `exit' inside the parentheses. You do not have to keep this buffer visible; compilation continues in any case.
To kill the compilation process, do M-x kill-compilation. You will see that the mode line of the `*compilation*' buffer changes to say `signal' instead of `run'. Starting a new compilation also kills any running compilation, as only one can exist at any time. However, this requires confirmation before actually killing a compilation that is running.
To parse the compiler error messages, type C-x ` (next-error). The
character following the C-x is the grave accent, not the single
quote. This command displays the buffer `*compilation*' in one window
and the buffer in which the next error occurred in another window. Point
in that buffer is moved to the line where the error was found. The
corresponding error message is scrolled to the top of the window in which
`*compilation*' is displayed.
The first time C-x ` is used after the start of a compilation, it parses all the error messages, visits all the files that have error messages, and makes markers pointing at the lines that the error messages refer to. Then it moves to the first error message location. Subsequent uses of C-x ` advance down the data set up by the first use. When the preparsed error messages are exhausted, the next C-x ` checks for any more error messages that have come in; this is useful if you start editing the compiler errors while the compilation is still going on. If no more error messages have come in, C-x ` reports an error.
C-u C-x ` discards the preparsed error message data and parses the `*compilation*' buffer over again, then displaying the first error. This way, you can process the same set of errors again.
Instead of running a compiler, you can run grep and see the lines
on which matches were found. To do this, type M-x grep with an argument
line that contains the same arguments you would give grep when running
it normally: a grep-style regexp (usually in singlequotes to quote
the shell's special characters) followed by filenames which may use wildcards.
The output from grep goes in the `*compilation*' buffer and the
lines that matched can be found with C-x ` as if they were compilation
errors.
Note: a shell is used to run the compile command, but the shell is told that it should be noninteractive. This means in particular that the shell starts up 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 (`.cshrc' or `.shrc' or ...) by setting the prompt unconditionally. The shell init file should set the prompt only if there already is a prompt.
Here is how to do it in csh:
if ($?prompt) set prompt = ...
Here is how to do it in the Bourne-Again shell:
if [ ! "$PS1" ]; then PS1=... fi
Emacs has four different major modes for Lisp. They are the same in terms of editing commands, but differ in the commands for executing Lisp expressions.
Lisp code for Emacs editing commands is stored in files whose names conventionally end in `.el'. This ending tells Emacs to edit them in Emacs-Lisp mode (see section Major Modes for Lisp).
To execute a file of Emacs Lisp, use M-x load-file. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer.
Once a file of Lisp code is installed in the Emacs Lisp library
directories, users can load it using M-x load-library. Programs can
load it by calling load-library, or with load, a more primitive
function that is similar but accepts some additional arguments.
M-x load-library differs from M-x load-file in that it searches a sequence of directories and tries three file names in each directory. The three names are, first, the specified name with `.elc' appended; second, with `.el' appended; third, the specified name alone. A `.elc' file would be the result of compiling the Lisp file into byte code; it is loaded if possible in preference to the Lisp file itself because the compiled file will load and run faster.
Because the argument to load-library is usually not in itself
a valid file name, file name completion is not available. Indeed, when
using this command, you usually do not know exactly what file name
will be used.
The sequence of directories searched by M-x load-library is
specified by the variable load-path, a list of strings that are
directory names. The default value of the list contains the directory where
the Lisp code for Emacs itself is stored. If you have libraries of
your own, put them in a single directory and add that directory
to load-path. nil in this list stands for the current default
directory, but it is probably not a good idea to put nil in the
list. If you find yourself wishing that nil were in the list,
most likely what you really want to do is use M-x load-file
this once.
Often you do not have to give any command to load a library, because the
commands defined in the library are set up to autoload that library.
Running any of those commands causes load to be called to load the
library; this replaces the autoload definitions with the real ones from the
library.
If autoloading a file does not finish, either because of an error or
because of a C-g quit, all function definitions made by the file are
undone automatically. So are any calls to provide. As a consequence,
if you use one of the autoloadable commands again, the entire file will be
loaded a second time. This prevents problems where the command is no
longer autoloading but it works wrong because not all the file was loaded.
Function definitions are undone only for autoloading; explicit calls to
load do not undo anything if loading is not completed.
Emacs Lisp code can be compiled into byte-code which loads faster, takes up less space when loaded, and executes faster.
The way to make a byte-code compiled file from an Emacs-Lisp source file is with M-x byte-compile-file. The default argument for this function is the file visited in the current buffer. It reads the specified file, compiles it into byte code, and writes an output file whose name is made by appending `c' to the input file name. Thus, the file `rmail.el' would be compiled into `rmail.elc'.
To recompile the changed Lisp files in a directory, use M-x byte-recompile-directory. Specify just the directory name as an argument. Each `.el' file that has been byte-compiled before is byte-compiled again if it has changed since the previous compilation. A numeric argument to this command tells it to offer to compile each `.el' file that has not already been compiled. You must answer y or n to each offer.
Emacs can be invoked noninteractively from the shell to do byte compilation
with the aid of the function batch-byte-compile. In this case,
the files to be compiled are specified with command-line arguments.
Use a shell command of the form
emacs -batch -f batch-byte-compile files...
Directory names may also be given as arguments;
byte-recompile-directory is invoked (in effect) on each such directory.
batch-byte-compile uses all the remaining command-line arguments as
file or directory names, then kills the Emacs process.
M-x disassemble explains the result of byte compilation. Its argument is a function name. It displays the byte-compiled code in a help window in symbolic form, one instruction per line. If the instruction refers to a variable or constant, that is shown too.
GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first. To convert a Mocklisp file, visit it and then type M-x convert-mocklisp-buffer. Then save the resulting buffer of Lisp file in a file whose name ends in `.el' and use the new file as a Lisp library.
It does not currently work to byte-compile converted Mocklisp code. This is because converted Mocklisp code uses some special Lisp features to deal with Mocklisp's incompatible ideas of how arguments are evaluated and which values signify "true" or "false".
Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp mode; this will happen automatically for file names ending in `.el'. By contrast, Lisp mode itself is used for editing Lisp programs intended for other Lisp systems. Emacs-Lisp mode can be selected with the command M-x emacs-lisp-mode.
For testing of Lisp programs to run in Emacs, it is useful to be able to evaluate part of the program as it is found in the Emacs buffer. For example, after changing the text of a Lisp function definition, evaluating the definition installs the change for future calls to the function. Evaluation of Lisp expressions is also useful in any kind of editing task for invoking noninteractive functions (functions that are not commands).
eval-expression).
eval-last-sexp).
eval-defun).
M-ESC (eval-expression) is the most basic command for evaluating
a Lisp expression interactively. It reads the expression using the
minibuffer, so you can execute any expression on a buffer regardless of
what the buffer contains. When the expression is evaluated, the current
buffer is once again the buffer that was current when M-ESC was
typed.
M-ESC can easily confuse users who do not understand it,
especially on keyboards with autorepeat where it can result from holding
down the ESC key for too long. Therefore, eval-expression is
normally a disabled command. Attempting to use this command asks for
confirmation and gives you the option of enabling it; once you enable the
command, confirmation will no longer be required for it.
See section Disabling Commands.
In Emacs-Lisp mode, the key C-M-x is bound to the function eval-defun,
which parses the defun containing or following point as a Lisp expression
and evaluates it. The value is printed in the echo area. This command is
convenient for installing in the Lisp environment changes that you have
just made in the text of a function definition.
The command C-x C-e (eval-last-sexp) performs a similar job
but is available in all major modes, not just Emacs-Lisp mode. It finds
the sexp before point, reads it as a Lisp expression, evaluates it, and
prints the value in the echo area. It is sometimes useful to type in an
expression and then, with point still after it, type C-x C-e.
If C-M-x or C-x C-e is given a numeric argument, it prints the value by insertion into the current buffer at point, rather than in the echo area. The argument value does not matter.
The most general command for evaluating Lisp expressions from a buffer is
eval-region. M-x eval-region parses the text of the region as one or
more Lisp expressions, evaluating them one by one. M-x eval-current-buffer
is similar but evaluates the entire buffer. This is a reasonable way to
install the contents of a file of Lisp code that you are just ready to
test. After finding and fixing a bug, use C-M-x on each function
that you change, to keep the Lisp world in step with the source file.
GNU Emacs contains a debugger for Lisp programs executing inside it.
This debugger is normally not used; many commands frequently get Lisp
errors when invoked in inappropriate contexts (such as C-f at the end
of the buffer) and it would be very unpleasant for that to enter a special
debugging mode. When you want to make Lisp errors invoke the debugger, you
must set the variable debug-on-error to non-nil. Quitting
with C-g is not considered an error, and debug-on-error has no
effect on the handling of C-g. However, if you set
debug-on-quit non-nil, C-g will invoke the debugger.
This can be useful for debugging an infinite loop; type C-g once the
loop has had time to reach its steady state. debug-on-quit has no
effect on errors.
You can also cause the debugger to be entered when a specified function
is called, or at a particular place in Lisp code. Use M-x
debug-on-entry with argument fun-name to cause function
fun-name to enter the debugger as soon as it is called. Use
M-x cancel-debug-on-entry to make the function stop entering the
debugger when called. (Redefining the function also does this.) To enter
the debugger from some other place in Lisp code, you must insert the
expression (debug) there and install the changed code with
C-M-x. See section Evaluating Emacs-Lisp Expressions.
When the debugger is entered, it displays the previously selected buffer in one window and a buffer named `*Backtrace*' in another window. The backtrace buffer contains one line for each level of Lisp function execution currently going on. At the beginning of this buffer is a message describing the reason that the debugger was invoked (such as, what error message if it was invoked due to an error).
The backtrace buffer is read-only, and is in a special major mode, Backtrace mode, in which letters are defined as debugger commands. The usual Emacs editing commands are available; you can switch windows to examine the buffer that was being edited at the time of the error, and you can also switch buffers, visit files, and do any other sort of editing. However, the debugger is a recursive editing level (see section Recursive Editing Levels) and it is wise to go back to the backtrace buffer and exit the debugger officially when you don't want to use it any more. Exiting the debugger kills the backtrace buffer.
The contents of the backtrace buffer show you the functions that are executing and the arguments that were given to them. It has the additional purpose of allowing you to specify a stack frame by moving point to the line describing that frame. The frame whose line point is on is considered the current frame. Some of the debugger commands operate on the current frame. Debugger commands are mainly used for stepping through code an expression at a time. Here is a list of them.
The stack frame made for the function call which enters the debugger in this way will be flagged automatically for the debugger to be called when the frame is exited. You can use the u command to cancel this flag.
If the debugger was entered due to a C-g but you really want to quit, not to debug, use the q command.
The value returned by the debugger makes a difference when the debugger was invoked due to exit from a Lisp call frame (as requested with b); then the value specified in the r command is used as the value of that frame.
The debugger's return value also matters with many errors. For example,
wrong-type-argument errors will use the debugger's return value
instead of the invalid argument; no-catch errors will use the
debugger value as a throw tag instead of the tag that was not found.
If an error was signaled by calling the Lisp function signal,
the debugger's return value is returned as the value of signal.
The buffer `*scratch*' which is selected when Emacs starts up is provided for evaluating Lisp expressions interactively inside Emacs. Both the expressions you evaluate and their output goes in the buffer.
The `*scratch*' buffer's major mode is Lisp Interaction mode, which
is the same as Emacs-Lisp mode except for one command, LFD. In
Emacs-Lisp mode, LFD is an indentation command, as usual. In Lisp
Interaction mode, LFD is bound to eval-print-last-sexp. This
function reads the Lisp expression before point, evaluates it, and inserts
the value in printed representation before point.
Thus, the way to use the `*scratch*' buffer is to insert Lisp expressions at the end, ending each one with LFD so that it will be evaluated. The result is a complete typescript of the expressions you have evaluated and their values.
The rationale for this feature is that Emacs must have a buffer when it starts up, but that buffer is not useful for editing files since a new buffer is made for every file that you visit. The Lisp interpreter typescript is the most useful thing I can think of for the initial buffer to do. M-x lisp-interaction-mode will put any buffer in Lisp Interaction mode.
Emacs has facilities for running programs in other Lisp systems. You can run a Lisp process as an inferior of Emacs, and pass expressions to it to be evaluated. You can also pass changed function definitions directly from the Emacs buffers in which you edit the Lisp programs to the inferior Lisp process.
To run an inferior Lisp process, type M-x run-lisp. This runs the
program named lisp, the same program you would run by typing
lisp as a shell command, with both input and output going through an
Emacs buffer named `*lisp*'. That is to say, any "terminal output"
from Lisp will go into the buffer, advancing point, and any "terminal
input" for Lisp comes from text in the buffer. To give input to Lisp, go
to the end of the buffer and type the input, terminated by RET. The
`*lisp*' buffer is in Inferior Lisp mode, a mode which has all the
special characteristics of Lisp mode and Shell mode (see section Shell Mode).
For the source files of programs to run in external Lisps, use Lisp mode. This mode can be selected with M-x lisp-mode, and is used automatically for files whose names end in `.l' or `.lisp', as most Lisp systems usually expect.
When you edit a function in a Lisp program you are running, the easiest
way to send the changed definition to the inferior Lisp process is the key
C-M-x. In Lisp mode, this runs the function lisp-send-defun,
which finds the defun around or following point and sends it as input to
the Lisp process. (Emacs can send input to any inferior process regardless
of what buffer is current.)
Contrast the meanings of C-M-x in Lisp mode (for editing programs to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp programs to be run in Emacs): in both modes it has the effect of installing the function definition that point is in, but the way of doing so is different according to where the relevant Lisp environment is found. See section Major Modes for Lisp.
Go to the previous, next section.