1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
3
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
4
@c Free Software Foundation, Inc.
5
@c See file emacs.texi for copying conditions.
6
@node Building, Maintaining, Programs, Top
7
@chapter Compiling and Testing Programs
8
@cindex building programs
9
@cindex program building
10
@cindex running Lisp functions
12
The previous chapter discusses the Emacs commands that are useful for
13
making changes in programs. This chapter deals with commands that assist
14
in the larger process of compiling and testing programs.
17
* Compilation:: Compiling programs in languages other
18
than Lisp (C, Pascal, etc.).
19
* Compilation Mode:: The mode for visiting compiler errors.
20
* Compilation Shell:: Customizing your shell properly
21
for use in the compilation buffer.
22
* Grep Searching:: Searching with grep.
23
* Flymake:: Finding syntax errors on the fly.
24
* Debuggers:: Running symbolic debuggers for non-Lisp programs.
25
* Executing Lisp:: Various modes for editing Lisp programs,
26
with different facilities for running
28
* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
29
* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
30
* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
31
* External Lisp:: Communicating through Emacs with a separate Lisp.
35
@section Running Compilations under Emacs
36
@cindex inferior process
38
@cindex compilation errors
41
Emacs can run compilers for noninteractive languages such as C and
42
Fortran as inferior processes, feeding the error log into an Emacs buffer.
43
It can also parse the error messages and show you the source lines where
44
compilation errors occurred.
48
Run a compiler asynchronously under Emacs, with error messages going to
49
the @samp{*compilation*} buffer.
51
Invoke a compiler with the same command as in the last invocation of
53
@item M-x kill-compilation
54
Kill the running compilation subprocess.
58
To run @code{make} or another compilation command, do @kbd{M-x
59
compile}. This command reads a shell command line using the minibuffer,
60
and then executes the command in an inferior shell, putting output in
61
the buffer named @samp{*compilation*}. The current buffer's default
62
directory is used as the working directory for the execution of the
63
command; normally, therefore, the compilation happens in this
66
@vindex compile-command
67
The default for the compilation command is normally @samp{make -k},
68
which is correct most of the time for nontrivial programs.
69
@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x
70
compile} before, the default each time is the command you used the
71
previous time. @code{compile} stores this command in the variable
72
@code{compile-command}, so setting that variable specifies the default
73
for the next use of @kbd{M-x compile}. If a file specifies a file
74
local value for @code{compile-command}, that provides the default when
75
you type @kbd{M-x compile} in that file's buffer. @xref{File
78
Starting a compilation displays the buffer @samp{*compilation*} in
79
another window but does not select it. The buffer's mode line tells
80
you whether compilation is finished, with the word @samp{run},
81
@samp{signal} or @samp{exit} inside the parentheses. You do not have
82
to keep this buffer visible; compilation continues in any case. While
83
a compilation is going on, the string @samp{Compiling} appears in the
84
mode lines of all windows. When this string disappears, the
85
compilation is finished.
87
If you want to watch the compilation transcript as it appears, switch
88
to the @samp{*compilation*} buffer and move point to the end of the
89
buffer. When point is at the end, new compilation output is inserted
90
above point, which remains at the end. If point is not at the end of
91
the buffer, it remains fixed while more compilation output is added at
92
the end of the buffer.
94
@cindex compilation buffer, keeping point at end
95
@vindex compilation-scroll-output
96
If you change the variable @code{compilation-scroll-output} to a
97
non-@code{nil} value, the compilation buffer will scroll automatically
98
to follow the output as it comes in. If the value is
99
@code{first-error}, the scrolling stops at the first error that
100
appears, leaving point at that error. For any other non-@code{nil}
101
value, the buffer continues scrolling until there is no more output.
104
To rerun the last compilation with the same command, type @kbd{M-x
105
recompile}. This automatically reuses the compilation command from
106
the last invocation of @kbd{M-x compile}. It also reuses the
107
@samp{*compilation*} buffer and starts the compilation in its default
108
directory, which is the directory in which the previous compilation
111
When the compiler process terminates, for whatever reason, the mode
112
line of the @samp{*compilation*} buffer changes to say @samp{exit}
113
(followed by the exit code, @samp{[0]} for a normal exit), or
114
@samp{signal} (if a signal terminated the process), instead of
117
@findex kill-compilation
118
Starting a new compilation also kills any compilation already
119
running in @samp{*compilation*}, as the buffer can only handle one
120
compilation at any time. However, @kbd{M-x compile} asks for
121
confirmation before actually killing a compilation that is running.
122
You can also kill the compilation process with @kbd{M-x
125
To run two compilations at once, start the first one, then rename
126
the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely};
127
@pxref{Misc Buffer}), then switch buffers and start the other
128
compilation. This will create a new @samp{*compilation*} buffer.
130
Emacs does not expect a compiler process to launch asynchronous
131
subprocesses; if it does, and they keep running after the main
132
compiler process has terminated, Emacs may kill them or their output
133
may not arrive in Emacs. To avoid this problem, make the main process
134
wait for its subprocesses to finish. In a shell script, you can do this
135
using @samp{$!} and @samp{wait}, like this:
138
(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess}
140
wait $pid # @r{Wait for subprocess}
143
If the background process does not output to the compilation buffer,
144
so you only need to prevent it from being killed when the main
145
compilation process terminates, this is sufficient:
148
nohup @var{command}; sleep 1
151
@vindex compilation-environment
152
You can control the environment passed to the compilation command
153
with the variable @code{compilation-environment}. Its value is a list
154
of environment variable settings; each element should be a string of
155
the form @code{"@var{envvarname}=@var{value}"}. These environment
156
variable settings override the usual ones.
158
@node Compilation Mode
159
@section Compilation Mode
161
@cindex Compilation mode
162
@cindex mode, Compilation
163
The @samp{*compilation*} buffer uses a special major mode,
164
Compilation mode, whose main feature is to provide a convenient way to
165
visit the source line corresponding to an error message. These
166
commands are also available in other special buffers that list
167
locations in files, including those made by @kbd{M-x grep} and
174
Visit the locus of the next error message or match.
177
Visit the locus of the previous error message or match.
179
Visit the locus of the error message that point is on.
180
This command is used in the compilation buffer.
182
Visit the locus of the error message that you click on.
184
Find and highlight the locus of the next error message, without
185
selecting the source buffer.
187
Find and highlight the locus of the previous error message, without
188
selecting the source buffer.
190
Move point to the next error for a different file than the current
193
Move point to the previous error for a different file than the current
196
Toggle Next Error Follow minor mode, which makes cursor motion in the
197
compilation buffer produce automatic source display.
200
@findex compile-goto-error
201
@vindex compilation-auto-jump-to-first-error
202
You can visit the source for any particular error message by moving
203
point in the @samp{*compilation*} buffer to that error message and
204
typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
205
click @kbd{Mouse-2} on the error message; you need not switch to the
206
@samp{*compilation*} buffer first. If you set the variable
207
@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
208
Emacs automatically jumps to the first error, if any, as soon as it
209
appears in the @samp{*compilation*} buffer.
215
@vindex next-error-highlight
216
To parse the compiler error messages sequentially, type @kbd{C-x `}
217
(@code{next-error}). The character following the @kbd{C-x} is the
218
backquote or ``grave accent,'' not the single-quote. This command is
219
available in all buffers, not just in @samp{*compilation*}; it
220
displays the next error message at the top of one window and source
221
location of the error in another window. It also temporarily
222
highlights the relevant source line, for a period controlled by the
223
variable @code{next-error-highlight}.
225
The first time @w{@kbd{C-x `}} is used after the start of a compilation,
226
it moves to the first error's location. Subsequent uses of @kbd{C-x
227
`} advance down to subsequent errors. If you visit a specific error
228
message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}}
229
commands advance from there. When @w{@kbd{C-x `}} gets to the end of the
230
buffer and finds no more error messages to visit, it fails and signals
231
an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of
232
the compilation buffer, and goes to the first error's location.
234
@vindex compilation-skip-threshold
235
By default, @w{@kbd{C-x `}} skips less important messages. The variable
236
@code{compilation-skip-threshold} controls this. If its value is 2,
237
@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less
238
than warning, and 0 doesn't skip any messages. The default is 1.
240
When the window has a left fringe, an arrow in the fringe points to
241
the current message in the compilation buffer. The variable
242
@code{compilation-context-lines} controls the number of lines of
243
leading context to display before the current message. Going to an
244
error message location scrolls the @samp{*compilation*} buffer to put
245
the message that far down from the top. The value @code{nil} is
246
special: if there's a left fringe, the window doesn't scroll at all
247
if the message is already visible. If there is no left fringe,
248
@code{nil} means display the message at the top of the window.
250
If you're not in the compilation buffer when you run
251
@code{next-error}, Emacs will look for a buffer that contains error
252
messages. First, it looks for one displayed in the selected frame,
253
then for one that previously had @code{next-error} called on it, and
254
then at the current buffer. Finally, Emacs looks at all the remaining
255
buffers. @code{next-error} signals an error if it can't find any such
258
@vindex compilation-error-regexp-alist
259
@vindex grep-regexp-alist
260
To parse messages from the compiler, Compilation mode uses the
261
variable @code{compilation-error-regexp-alist} which lists various
262
formats of error messages and tells Emacs how to extract the source file
263
and the line number from the text of a message. If your compiler isn't
264
supported, you can tailor Compilation mode to it by adding elements to
265
that list. A similar variable @code{grep-regexp-alist} tells Emacs how
266
to parse output of a @code{grep} command.
268
@findex compilation-next-error
269
@findex compilation-previous-error
270
@findex compilation-next-file
271
@findex compilation-previous-file
272
Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
273
scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
274
and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
275
or previous error message. You can also use @kbd{M-@{}
276
(@code{compilation-next-file} and @kbd{M-@}}
277
(@code{compilation-previous-file}) to move up or down to an error
278
message for a different source file.
280
@cindex Next Error Follow mode
281
@findex next-error-follow-minor-mode
282
You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
283
this minor mode, ordinary cursor motion in the compilation buffer
284
automatically updates the source buffer. For instance, moving the
285
cursor to the next error message causes the location of that error to
286
be displayed immediately.
288
The features of Compilation mode are also available in a minor mode
289
called Compilation Minor mode. This lets you parse error messages in
290
any buffer, not just a normal compilation output buffer. Type @kbd{M-x
291
compilation-minor-mode} to enable the minor mode. This defines the keys
292
@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
294
Compilation minor mode works in any buffer, as long as the contents
295
are in a format that it understands. In an Rlogin buffer (@pxref{Remote
296
Host}), Compilation minor mode automatically accesses remote source
297
files by FTP (@pxref{File Names}).
299
@node Compilation Shell
300
@section Subshells for Compilation
302
Emacs uses a shell to run the compilation command, but specifies the
303
option for a noninteractive shell. This means, in particular, that
304
the shell should start with no prompt. If you find your usual shell
305
prompt making an unsightly appearance in the @samp{*compilation*}
306
buffer, it means you have made a mistake in your shell's init file by
307
setting the prompt unconditionally. (This init file's name may be
308
@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or
309
various other things, depending on the shell you use.) The shell init
310
file should set the prompt only if there already is a prompt. Here's
311
how to do it in bash:
314
if [ "$@{PS1+set@}" = set ]
320
And here's how to do it in csh:
323
if ($?prompt) set prompt = @dots{}
326
There may well be other things that your shell's init file
327
ought to do only for an interactive shell. You can use the same
328
method to conditionalize them.
330
The MS-DOS ``operating system'' does not support asynchronous
331
subprocesses; to work around this lack, @kbd{M-x compile} runs the
332
compilation command synchronously on MS-DOS. As a consequence, you must
333
wait until the command finishes before you can do anything else in
336
@inforef{MS-DOS,,emacs-xtra}.
343
@section Searching with Grep under Emacs
345
Just as you can run a compiler from Emacs and then visit the lines
346
with compilation errors, you can also run @code{grep} and then visit
347
the lines on which matches were found. This works by treating the
348
matches reported by @code{grep} as if they were ``errors.'' The
349
buffer of matches uses Grep mode, which is a variant of Compilation
350
mode (@pxref{Compilation Mode}).
355
Run @code{grep} asynchronously under Emacs, with matching lines
356
listed in the buffer named @samp{*grep*}.
360
Run @code{grep} via @code{find}, and collect output in the buffer
363
Run @code{zgrep} and collect output in the buffer named @samp{*grep*}.
365
Kill the running @code{grep} subprocess.
369
To run @code{grep}, type @kbd{M-x grep}, then enter a command line
370
that specifies how to run @code{grep}. Use the same arguments you
371
would give @code{grep} when running it normally: a @code{grep}-style
372
regexp (usually in single-quotes to quote the shell's special
373
characters) followed by file names, which may use wildcards. If you
374
specify a prefix argument for @kbd{M-x grep}, it finds the tag
375
(@pxref{Tags}) in the buffer around point, and puts that into the
376
default @code{grep} command.
378
Your command need not simply run @code{grep}; you can use any shell
379
command that produces output in the same format. For instance, you
380
can chain @code{grep} commands, like this:
383
grep -nH -e foo *.el | grep bar | grep toto
386
The output from @code{grep} goes in the @samp{*grep*} buffer. You
387
can find the corresponding lines in the original files using @w{@kbd{C-x
388
`}}, @key{RET}, and so forth, just like compilation errors.
390
Some grep programs accept a @samp{--color} option to output special
391
markers around matches for the purpose of highlighting. You can make
392
use of this feature by setting @code{grep-highlight-matches} to
393
@code{t}. When displaying a match in the source buffer, the exact
394
match will be highlighted, instead of the entire source line.
398
The command @kbd{M-x grep-find} (also available as @kbd{M-x
399
find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
400
initial default for the command---one that runs both @code{find} and
401
@code{grep}, so as to search every file in a directory tree. See also
402
the @code{find-grep-dired} command, in @ref{Dired and Find}.
407
The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
408
(recursive grep) are more user-friendly versions of @code{grep} and
409
@code{grep-find}, which prompt separately for the regular expression
410
to match, the files to search, and the base directory for the search.
411
Case sensitivity of the search is controlled by the current value of
412
@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to
413
@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to
414
search the contents of gzipped files.
416
These commands build the shell commands based on the variables
417
@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
418
(for @code{rgrep}). The files to search can use aliases defined in
419
the variable @code{grep-files-aliases}.
421
Subdirectories listed in the variable
422
@code{grep-find-ignored-directories} such as those typically used by
423
various version control systems, like CVS and arch, are automatically
424
skipped by @code{rgrep}.
427
@section Finding Syntax Errors On The Fly
428
@cindex checking syntax
430
Flymake mode is a minor mode that performs on-the-fly syntax
431
checking for many programming and markup languages, including C, C++,
432
Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
433
mode, which performs spell checking for ordinary human languages in a
434
similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
435
runs an appropriate syntax checking tool in the background, using a
436
temporary copy of the buffer. It then parses the error and warning
437
messages, and highlights the erroneous lines in the buffer. The
438
syntax checking tool used depends on the language; for example, for
439
C/C++ files this is usually the C compiler. Flymake can also use
440
build tools such as @code{make} for checking complicated projects.
442
To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
443
to the errors spotted by Flymake mode with @kbd{M-x
444
flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
445
display any error messages associated with the current line, use
446
@kbd{M-x flymake-display-err-menu-for-current-line}.
448
For more details about using Flymake, see @ref{Top, Flymake,
449
Flymake, flymake, The Flymake Manual}.
452
@section Running Debuggers Under Emacs
463
@c Do you believe in GUD?
464
The GUD (Grand Unified Debugger) library provides an Emacs interface
465
to a wide variety of symbolic debuggers. Unlike the GDB graphical
466
interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
467
can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
468
PDB, or the Java Debugger JDB.
470
In addition, Emacs contains a built-in system for debugging Emacs
471
Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
472
Lisp Reference Manual}, for information on the Emacs Lisp debugger.
475
* Starting GUD:: How to start a debugger subprocess.
476
* Debugger Operation:: Connection between the debugger and source buffers.
477
* Commands of GUD:: Key bindings for common commands.
478
* GUD Customization:: Defining your own commands for GUD.
479
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
480
implement a graphical debugging environment through
485
@subsection Starting GUD
487
There are several commands for starting a debugger under GUD, each
488
corresponding to a particular debugger program.
491
@item M-x gdb @key{RET} @var{file} @key{RET}
493
Run GDB as a subprocess of Emacs. This uses an IDE-like graphical
494
interface; see @ref{GDB Graphical Interface}. Only GDB works with the
497
@item M-x gud-gdb @key{RET} @var{file} @key{RET}
499
Run GDB as a subprocess of Emacs. This command creates a buffer for
500
input and output to GDB, and switches to it. If a GDB buffer already
501
exists, it just switches to that buffer.
503
@item M-x dbx @key{RET} @var{file} @key{RET}
505
Run DBX as a subprocess of Emacs. Since Emacs does not implement a
506
graphical interface for DBX, communication with DBX works by typing
507
commands in the GUD interaction buffer. The same is true for all
508
the other supported debuggers.
510
@item M-x xdb @key{RET} @var{file} @key{RET}
512
@vindex gud-xdb-directories
513
Run XDB as a subprocess of Emacs. Use the variable
514
@code{gud-xdb-directories} to specify directories to search for source
517
@item M-x sdb @key{RET} @var{file} @key{RET}
519
Run SDB as a subprocess of Emacs.
521
Some versions of SDB do not mention source file names in their
522
messages. When you use them, you need to have a valid tags table
523
(@pxref{Tags}) in order for GUD to find functions in the source code.
524
If you have not visited a tags table or the tags table doesn't list
525
one of the functions, you get a message saying @samp{The sdb support
526
requires a valid tags table to work}. If this happens, generate a
527
valid tags table in the working directory and try again.
529
@item M-x perldb @key{RET} @var{file} @key{RET}
531
Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
533
@item M-x jdb @key{RET} @var{file} @key{RET}
535
Run the Java debugger to debug @var{file}.
537
@item M-x pdb @key{RET} @var{file} @key{RET}
539
Run the Python debugger to debug @var{file}.
542
Each of these commands takes one argument: a command line to invoke
543
the debugger. In the simplest case, specify just the name of the
544
executable file you want to debug. You may also use options that the
545
debugger supports. However, shell wildcards and variables are not
546
allowed. GUD assumes that the first argument not starting with a
547
@samp{-} is the executable file name.
549
@cindex remote host, debugging on
550
Tramp provides a facility to debug programs on remote hosts
551
(@pxref{Running a debugger on a remote host, Running a debugger on a
552
remote host,, tramp, The Tramp Manual}), whereby both the debugger and
553
the program being debugged are on the same remote host. This should
554
not be confused with debugging programs remotely, where the program
555
and the debugger run on different machines, as can be done using the
556
GDB remote debugging feature, for example (@pxref{Remote Debugging,,
557
Debugging Remote Programs, gdb, The GNU debugger}).
559
@node Debugger Operation
560
@subsection Debugger Operation
562
@cindex fringes, and current execution line in GUD
563
Generally when you run a debugger with GUD, the debugger uses an Emacs
564
buffer for its ordinary input and output. This is called the GUD
565
buffer. Input and output from the program you are debugging also use
566
this buffer. We call this @dfn{text command mode}. The GDB Graphical
567
Interface can use further buffers (@pxref{GDB Graphical Interface}).
569
The debugger displays the source files of the program by visiting
570
them in Emacs buffers. An arrow in the left fringe indicates the
571
current execution line.@footnote{On a text-only terminal, the arrow
572
appears as @samp{=>} and overlays the first two text columns.} Moving
573
point in this buffer does not move the arrow. The arrow is not part
574
of the file's text; it appears only on the screen.
576
You can start editing these source files at any time in the buffers
577
that display them. If you do modify a source file, keep in mind that
578
inserting or deleting lines will throw off the arrow's positioning;
579
GUD has no way of figuring out which line corresponded before your
580
changes to the line number in a debugger message. Also, you'll
581
typically have to recompile and restart the program for your changes
582
to be reflected in the debugger's tables.
584
@cindex tooltips with GUD
585
@vindex tooltip-gud-modes
586
@vindex gud-tooltip-mode
587
@vindex gud-tooltip-echo-area
588
The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
589
You activate this feature by turning on the minor mode
590
@code{gud-tooltip-mode}. Then you can display a variable's value in a
591
tooltip simply by pointing at it with the mouse. This operates in the
592
GUD buffer and in source buffers with major modes in the list
593
@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area}
594
is non-@code{nil} then the variable's value is displayed in the echo
595
area. When debugging a C program using the GDB Graphical Interface, you
596
can also display macro definitions associated with an identifier when
597
the program is not executing.
599
GUD tooltips are disabled when you use GDB in text command mode
600
(@pxref{GDB Graphical Interface}), because displaying an expression's
601
value in GDB can sometimes expand a macro and result in a side effect
602
that interferes with the program's operation. The GDB graphical
603
interface supports GUD tooltips and assures they will not cause side
606
@node Commands of GUD
607
@subsection Commands of GUD
609
The GUD interaction buffer uses a variant of Shell mode, so the
610
Emacs commands of Shell mode are available (@pxref{Shell Mode}). All
611
the usual commands for your debugger are available, and you can use
612
the Shell mode history commands to repeat them. If you wish, you can
613
control your debugger process entirely through this buffer.
615
GUD mode also provides commands for setting and clearing
616
breakpoints, for selecting stack frames, and for stepping through the
617
program. These commands are available both in the GUD buffer and
618
globally, but with different key bindings. It also has its own tool
619
bar from which you can invoke the more common commands by clicking on
620
the appropriate icon. This is particularly useful for repetitive
621
commands like @code{gud-next} and @code{gud-step}, and allows you to
622
keep the GUD buffer hidden.
624
The breakpoint commands are normally used in source file buffers,
625
because that is the easiest way to specify where to set or clear the
626
breakpoint. Here's the global command to set a breakpoint:
631
Set a breakpoint on the source line that point is on.
634
@kindex C-x C-a @r{(GUD)}
635
Here are the other special commands provided by GUD@. The keys
636
starting with @kbd{C-c} are available only in the GUD interaction
637
buffer. The key bindings that start with @kbd{C-x C-a} are available
638
in the GUD interaction buffer and also in source files. Some of these
639
commands are not available to all the supported debuggers.
643
@kindex C-c C-l @r{(GUD)}
646
Display in another window the last line referred to in the GUD
647
buffer (that is, the line indicated in the last location message).
648
This runs the command @code{gud-refresh}.
651
@kindex C-c C-s @r{(GUD)}
654
Execute a single line of code (@code{gud-step}). If the line contains
655
a function call, execution stops after entering the called function.
658
@kindex C-c C-n @r{(GUD)}
661
Execute a single line of code, stepping across entire function calls
662
at full speed (@code{gud-next}).
665
@kindex C-c C-i @r{(GUD)}
668
Execute a single machine instruction (@code{gud-stepi}).
671
@kindex C-c C-p @r{(GUD)}
674
Evaluate the expression at point (@code{gud-print}). If Emacs
675
does not print the exact expression that you want, mark it as a region
680
@kindex C-c C-r @r{(GUD)}
683
Continue execution without specifying any stopping point. The program
684
will run until it hits a breakpoint, terminates, or gets a signal that
685
the debugger is checking for (@code{gud-cont}).
689
@kindex C-c C-d @r{(GUD)}
692
Delete the breakpoint(s) on the current source line, if any
693
(@code{gud-remove}). If you use this command in the GUD interaction
694
buffer, it applies to the line where the program last stopped.
697
@kindex C-c C-t @r{(GUD)}
700
Set a temporary breakpoint on the current source line, if any
701
(@code{gud-tbreak}). If you use this command in the GUD interaction
702
buffer, it applies to the line where the program last stopped.
705
@kindex C-c < @r{(GUD)}
708
Select the next enclosing stack frame (@code{gud-up}). This is
709
equivalent to the GDB command @samp{up}.
712
@kindex C-c > @r{(GUD)}
715
Select the next inner stack frame (@code{gud-down}). This is
716
equivalent to the GDB command @samp{down}.
719
@kindex C-c C-u @r{(GUD)}
722
Continue execution to the current line (@code{gud-until}). The
723
program will run until it hits a breakpoint, terminates, gets a signal
724
that the debugger is checking for, or reaches the line on which the
725
cursor currently sits.
728
@kindex C-c C-f @r{(GUD)}
731
Run the program until the selected stack frame returns or
732
stops for some other reason (@code{gud-finish}).
735
If you are using GDB, these additional key bindings are available:
739
@kindex C-x C-a C-j @r{(GUD)}
741
Only useful in a source buffer, @code{gud-jump} transfers the
742
program's execution point to the current line. In other words, the
743
next line that the program executes will be the one where you gave the
744
command. If the new execution line is in a different function from
745
the previously one, GDB prompts for confirmation since the results may
746
be bizarre. See the GDB manual entry regarding @code{jump} for
750
@kindex TAB @r{(GUD)}
751
@findex gud-gdb-complete-command
752
With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
753
This key is available only in the GUD interaction buffer.
756
These commands interpret a numeric argument as a repeat count, when
759
Because @key{TAB} serves as a completion command, you can't use it to
760
enter a tab as input to the program you are debugging with GDB.
761
Instead, type @kbd{C-q @key{TAB}} to enter a tab.
763
@node GUD Customization
764
@subsection GUD Customization
766
@vindex gdb-mode-hook
767
@vindex dbx-mode-hook
768
@vindex sdb-mode-hook
769
@vindex xdb-mode-hook
770
@vindex perldb-mode-hook
771
@vindex pdb-mode-hook
772
@vindex jdb-mode-hook
773
On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
774
if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
775
@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
776
are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
777
@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
778
use these hooks to define custom key bindings for the debugger
779
interaction buffer. @xref{Hooks}.
781
Here is a convenient way to define a command that sends a particular
782
command string to the debugger, and set up a key binding for it in the
783
debugger interaction buffer:
787
(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
790
This defines a command named @var{function} which sends
791
@var{cmdstring} to the debugger process, and gives it the documentation
792
string @var{docstring}. You can then use the command @var{function} in any
793
buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
794
the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
795
@kbd{C-x C-a @var{binding}} generally.
797
The command string @var{cmdstring} may contain certain
798
@samp{%}-sequences that stand for data to be filled in at the time
799
@var{function} is called:
803
The name of the current source file. If the current buffer is the GUD
804
buffer, then the ``current source file'' is the file that the program
808
The number of the current source line. If the current buffer is the GUD
809
buffer, then the ``current source line'' is the line that the program
813
In transient-mark-mode the text in the region, if it is active.
814
Otherwise the text of the C lvalue or function-call expression at or
818
The text of the hexadecimal address at or adjacent to point.
821
The numeric argument of the called function, as a decimal number. If
822
the command is used without a numeric argument, @samp{%p} stands for the
825
If you don't use @samp{%p} in the command string, the command you define
826
ignores any numeric argument.
829
The name of the directory of the current source file.
832
Fully qualified class name derived from the expression surrounding point
836
@node GDB Graphical Interface
837
@subsection GDB Graphical Interface
839
The command @code{gdb} starts GDB in a graphical interface, using
840
Emacs windows for display program state information. With it, you do
841
not need to use textual GDB commands; you can control the debugging
842
session with the mouse. For example, you can click in the fringe of a
843
source buffer to set a breakpoint there, or on a stack frame in the
844
stack buffer to select that frame.
846
This mode requires telling GDB that its ``screen size'' is
847
unlimited, so it sets the height and width accordingly. For correct
848
operation you must not change these values during the GDB session.
850
@vindex gud-gdb-command-name
851
To run GDB in text command mode, like the other debuggers in Emacs,
852
use @kbd{M-x gud-gdb}. You need to use text command mode to debug
853
multiple programs within one Emacs session.
856
* GDB-UI Layout:: Control the number of displayed buffers.
857
* Source Buffers:: Use the mouse in the fringe/margin to
858
control your program.
859
* Breakpoints Buffer:: A breakpoint control panel.
860
* Stack Buffer:: Select a frame from the call stack.
861
* Other GDB-UI Buffers:: Input/output, locals, registers,
862
assembler, threads and memory buffers.
863
* Watch Expressions:: Monitor variable values in the speedbar.
864
* Reverse Debugging:: Execute and reverse debug your program.
868
@subsubsection GDB User Interface Layout
869
@cindex GDB User Interface layout
871
@vindex gdb-many-windows
872
If the variable @code{gdb-many-windows} is @code{nil} (the default
873
value) then @kbd{M-x gdb} normally displays only the GUD buffer.
874
However, if the variable @code{gdb-show-main} is also non-@code{nil},
875
it starts with two windows: one displaying the GUD buffer, and the
876
other showing the source for the @code{main} function of the program
879
If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
880
displays the following frame layout:
884
+--------------------------------+--------------------------------+
885
| GUD buffer (I/O of GDB) | Locals/Registers buffer |
886
|--------------------------------+--------------------------------+
887
| Primary Source buffer | I/O buffer for debugged pgm |
888
|--------------------------------+--------------------------------+
889
| Stack buffer | Breakpoints/Threads buffer |
890
+--------------------------------+--------------------------------+
894
However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
895
buffer does not appear and the primary source buffer occupies the full
898
@findex gdb-restore-windows
899
If you change the window layout, for example, while editing and
900
re-compiling your program, then you can restore this standard window
901
layout with the command @code{gdb-restore-windows}.
903
@findex gdb-many-windows
904
To switch between this standard layout and a simple layout
905
containing just the GUD buffer and a source file, type @kbd{M-x
908
You may also specify additional GDB-related buffers to display,
909
either in the same frame or a different one. Select the buffers you
910
want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames}
911
sub-menus. If the menu-bar is unavailable, type @code{M-x
912
gdb-display-@var{buffertype}-buffer} or @code{M-x
913
gdb-frame-@var{buffertype}-buffer} respectively, where
914
@var{buffertype} is the relevant buffer type, such as
915
@samp{breakpoints}. Most of these buffers are read-only, and typing
916
@kbd{q} in them kills them.
918
When you finish debugging, kill the GUD buffer with @kbd{C-x k},
919
which will also kill all the buffers associated with the session.
920
However you need not do this if, after editing and re-compiling your
921
source code within Emacs, you wish continue debugging. When you
922
restart execution, GDB will automatically find your new executable.
923
Keeping the GUD buffer has the advantage of keeping the shell history
924
as well as GDB's breakpoints. You do need to check that the
925
breakpoints in recently edited source files are still in the right
929
@subsubsection Source Buffers
930
@cindex GDB commands in Fringe
932
@c @findex gdb-mouse-set-clear-breakpoint
933
@c @findex gdb-mouse-toggle-breakpoint
934
Many GDB commands can be entered using key bindings or the tool bar but
935
sometimes it is quicker to use the fringe. These commands either
936
manipulate breakpoints or control program execution. When there is no
937
fringe, you can use the margin but this is only present when the
938
source file already has a breakpoint.
940
You can click @kbd{Mouse-1} in the fringe or display margin of a
941
source buffer to set a breakpoint there and, on a graphical display, a
942
red bullet will appear on that line. If a breakpoint already exists
943
on that line, the same click will remove it. You can also enable or
944
disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
946
A solid arrow in the left fringe of a source buffer indicates the line
947
of the innermost frame where the debugged program has stopped. A
948
hollow arrow indicates the current execution line of higher level
951
If you drag the arrow in the fringe with @kbd{Mouse-1}
952
(@code{gdb-mouse-until}), execution will continue to the line where
953
you release the button, provided it is still in the same frame.
954
Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
955
of this buffer and execution will advance to there. A similar command
956
(@code{gdb-mouse-jump}) allows you to jump to a source line without
957
executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
958
command allows you to go backwards which can be useful for running
959
through code that has already executed, in order to examine its
960
execution in more detail.
964
Set or clear a breakpoint.
967
Enable or disable a breakpoint.
970
Continue execution to here.
976
If the variable @code{gdb-find-source-frame} is non-@code{nil} and
977
execution stops in a frame for which there is no source code e.g after
978
an interrupt, then Emacs finds and displays the first frame further up
979
stack for which there is source. If it is @code{nil} then the source
980
buffer continues to display the last frame which maybe more useful,
981
for example, when re-setting a breakpoint.
983
@node Breakpoints Buffer
984
@subsubsection Breakpoints Buffer
986
The breakpoints buffer shows the existing breakpoints, watchpoints and
987
catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
988
these special commands, which mostly apply to the @dfn{current
989
breakpoint}, the breakpoint which point is on.
993
@kindex SPC @r{(GDB breakpoints buffer)}
994
@findex gdb-toggle-breakpoint
995
Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
996
On a graphical display, this changes the color of a bullet in the
997
margin of a source buffer at the relevant line. This is red when
998
the breakpoint is enabled and grey when it is disabled. Text-only
999
terminals correspondingly display a @samp{B} or @samp{b}.
1002
@kindex D @r{(GDB breakpoints buffer)}
1003
@findex gdb-delete-breakpoint
1004
Delete the current breakpoint (@code{gdb-delete-breakpoint}).
1007
@kindex RET @r{(GDB breakpoints buffer)}
1008
@findex gdb-goto-breakpoint
1009
Visit the source line for the current breakpoint
1010
(@code{gdb-goto-breakpoint}).
1013
@kindex Mouse-2 @r{(GDB breakpoints buffer)}
1014
Visit the source line for the breakpoint you click on.
1017
When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer
1018
shares its window with the threads buffer. To switch from one to the
1019
other click with @kbd{Mouse-1} on the relevant button in the header
1023
@subsubsection Stack Buffer
1025
The stack buffer displays a @dfn{call stack}, with one line for each
1026
of the nested subroutine calls (@dfn{stack frames}) now active in the
1027
program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
1029
@findex gdb-frames-select
1030
An arrow in the fringe points to the selected frame or, if the fringe is
1031
not present, the number of the selected frame is displayed in reverse
1032
contrast. To select a frame in GDB, move point in the stack buffer to
1033
that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
1034
@kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
1035
selecting a stack frame updates it to display the local variables of the
1038
@node Other GDB-UI Buffers
1039
@subsubsection Other Buffers
1042
@item Input/Output Buffer
1043
@vindex gdb-use-separate-io-buffer
1044
If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
1045
the program being debugged takes its input and displays its output
1046
here. Otherwise it uses the GUD buffer for that. To toggle whether
1047
GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
1048
This takes effect when you next restart the program you are debugging.
1050
The history and replay commands from Shell mode are available here,
1051
as are the commands to send signals to the debugged program.
1055
The locals buffer displays the values of local variables of the
1056
current frame for simple data types (@pxref{Frame Info, Frame Info,
1057
Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
1058
click @kbd{Mouse-2} on the value if you want to edit it.
1060
Arrays and structures display their type only. With GDB 6.4 or later,
1061
move point to their name and press @key{RET}, or alternatively click
1062
@kbd{Mouse-2} there, to examine their values. With earlier versions
1063
of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
1064
(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
1066
@item Registers Buffer
1067
@findex toggle-gdb-all-registers
1068
The registers buffer displays the values held by the registers
1069
(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
1070
click @kbd{Mouse-2} on a register if you want to edit its value.
1071
With GDB 6.4 or later, recently changed register values display with
1072
@code{font-lock-warning-face}. With earlier versions of GDB, you can
1073
press @key{SPC} to toggle the display of floating point registers
1074
(@code{toggle-gdb-all-registers}).
1076
@item Assembler Buffer
1077
The assembler buffer displays the current frame as machine code. An
1078
arrow points to the current instruction, and you can set and remove
1079
breakpoints as in a source buffer. Breakpoint icons also appear in
1080
the fringe or margin.
1082
@item Threads Buffer
1083
@findex gdb-threads-select
1084
The threads buffer displays a summary of all threads currently in your
1085
program (@pxref{Threads, Threads, Debugging programs with multiple
1086
threads, gdb, The GNU debugger}). Move point to any thread in the
1087
list and press @key{RET} to select it (@code{gdb-threads-select}) and
1088
display the associated source in the primary source buffer.
1089
Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
1090
locals buffer is visible, its contents update to display the variables
1091
that are local in the new thread.
1093
When there is more than one main thread and the threads buffer is
1094
present, Emacs displays the selected thread number in the mode line of
1095
many of the GDB-UI Buffers.
1098
The memory buffer lets you examine sections of program memory
1099
(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}).
1100
Click @kbd{Mouse-1} on the appropriate part of the header line to
1101
change the starting address or number of data items that the buffer
1102
displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click
1103
@kbd{Mouse-3} on the header line to select the display format or unit
1104
size for these data items.
1107
When @code{gdb-many-windows} is non-@code{nil}, the threads buffer
1108
shares its window with the breakpoints buffer, and the locals buffer
1109
with the registers buffer. To switch from one to the other click with
1110
@kbd{Mouse-1} on the relevant button in the header line.
1112
@node Watch Expressions
1113
@subsubsection Watch Expressions
1114
@cindex Watching expressions in GDB
1117
@kindex C-x C-a C-w @r{(GUD)}
1118
If you want to see how a variable changes each time your program
1119
stops, move point into the variable name and click on the watch icon
1120
in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
1121
specify a prefix argument, you can enter the variable name in the
1124
Each watch expression is displayed in the speedbar. Complex data
1125
types, such as arrays, structures and unions are represented in a tree
1126
format. Leaves and simple data types show the name of the expression
1127
and its value and, when the speedbar frame is selected, display the
1128
type as a tooltip. Higher levels show the name, type and address
1129
value for pointers and just the name and type otherwise. Root expressions
1130
also display the frame address as a tooltip to help identify the frame
1131
in which they were defined.
1133
To expand or contract a complex data type, click @kbd{Mouse-2} or
1134
press @key{SPC} on the tag to the left of the expression. Emacs asks
1135
for confirmation before expanding the expression if its number of
1136
immediate children exceeds the value of the variable
1137
@code{gdb-max-children}.
1139
@kindex D @r{(GDB speedbar)}
1140
@findex gdb-var-delete
1141
To delete a complex watch expression, move point to the root
1142
expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
1144
@kindex RET @r{(GDB speedbar)}
1145
@findex gdb-edit-value
1146
To edit a variable with a simple data type, or a simple element of a
1147
complex data type, move point there in the speedbar and type @key{RET}
1148
(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
1149
edit it. Either way, this reads the new value using the minibuffer.
1151
@vindex gdb-show-changed-values
1152
If you set the variable @code{gdb-show-changed-values} to
1153
non-@code{nil} (the default value), Emacs uses
1154
@code{font-lock-warning-face} to highlight values that have recently
1155
changed and @code{shadow} face to make variables which have gone out of
1156
scope less noticeable. When a variable goes out of scope you can't
1159
@vindex gdb-delete-out-of-scope
1160
If the variable @code{gdb-delete-out-of-scope} is non-@code{nil}
1161
(the default value), Emacs automatically deletes watch expressions
1162
which go out of scope. Sometimes, when re-entering the same function,
1163
it may be useful to set this value to @code{nil} so that you don't
1164
need to recreate the watch expression.
1166
@vindex gdb-use-colon-colon-notation
1167
If the variable @code{gdb-use-colon-colon-notation} is
1168
non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
1169
format. This allows the user to display watch expressions which share
1170
the same variable name. The default value is @code{nil}.
1172
@vindex gdb-speedbar-auto-raise
1173
To automatically raise the speedbar every time the display of watch
1174
expressions updates, set @code{gdb-speedbar-auto-raise} to
1175
non-@code{nil}. This can be useful if you are debugging with a full
1178
@node Reverse Debugging
1179
@subsubsection Reverse Debugging
1181
The GDB tool bar shares many buttons with the other GUD debuggers
1182
for tasks like stepping and printing expressions. It also has a
1183
further set of buttons that allow reverse debugging (@pxref{Process
1184
Record and Replay, , ,gdb, The GNU debugger}). This is useful when it
1185
takes a long time to reproduce the conditions where your program fails
1186
or for transient problems, like race conditions in multi-threaded
1187
programs, where a failure might otherwise be hard to reproduce.
1189
To use reverse debugging, set a breakpoint slightly before the
1190
location of interest and run your program to that point. Enable
1191
process recording by clicking on the record button. At this point, a
1192
new set of buttons appear. These buttons allow program execution in
1193
the reverse direction. Run your program over the code where the
1194
problem occurs, and then use the new set of buttons to retrace your
1195
steps, examine values, and analyze the problem. When analysis is
1196
complete, turn off process recording by clicking on the record button
1199
@node Executing Lisp
1200
@section Executing Lisp Expressions
1202
Emacs has several different major modes for Lisp and Scheme. They are
1203
the same in terms of editing commands, but differ in the commands for
1204
executing Lisp expressions. Each mode has its own purpose.
1207
@item Emacs-Lisp mode
1208
The mode for editing source files of programs to run in Emacs Lisp.
1209
This mode defines @kbd{C-M-x} to evaluate the current defun.
1210
@xref{Lisp Libraries}.
1211
@item Lisp Interaction mode
1212
The mode for an interactive session with Emacs Lisp. It defines
1213
@kbd{C-j} to evaluate the sexp before point and insert its value in the
1214
buffer. @xref{Lisp Interaction}.
1216
The mode for editing source files of programs that run in Lisps other
1217
than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
1218
to an inferior Lisp process. @xref{External Lisp}.
1219
@item Inferior Lisp mode
1220
The mode for an interactive session with an inferior Lisp process.
1221
This mode combines the special features of Lisp mode and Shell mode
1222
(@pxref{Shell Mode}).
1224
Like Lisp mode but for Scheme programs.
1225
@item Inferior Scheme mode
1226
The mode for an interactive session with an inferior Scheme process.
1229
Most editing commands for working with Lisp programs are in fact
1230
available globally. @xref{Programs}.
1232
@node Lisp Libraries
1233
@section Libraries of Lisp Code for Emacs
1235
@cindex loading Lisp code
1237
Lisp code for Emacs editing commands is stored in files whose names
1238
conventionally end in @file{.el}. This ending tells Emacs to edit them in
1239
Emacs-Lisp mode (@pxref{Executing Lisp}).
1242
Emacs Lisp code can be compiled into byte-code, which loads faster,
1243
takes up less space, and executes faster. @xref{Byte Compilation,,
1244
Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By
1245
convention, the compiled code for a library goes in a separate file
1246
whose name ends in @samp{.elc}. Thus, the compiled code for
1247
@file{foo.el} goes in @file{foo.elc}.
1250
To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
1251
command reads a file name using the minibuffer and then executes the
1252
contents of that file as Lisp code. It is not necessary to visit the
1253
file first; in any case, this command reads the file as found on disk,
1254
not text in an Emacs buffer.
1257
@findex load-library
1258
Once a file of Lisp code is installed in the Emacs Lisp library
1259
directories, users can load it using @kbd{M-x load-library}. Programs
1260
can load it by calling @code{load}, a more primitive function that is
1261
similar but accepts some additional arguments.
1263
@kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
1264
searches a sequence of directories and tries three file names in each
1265
directory. Suppose your argument is @var{lib}; the three names are
1266
@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
1267
@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
1268
the result of compiling @file{@var{lib}.el}; it is better to load the
1269
compiled file, since it will load and run faster.
1271
If @code{load-library} finds that @file{@var{lib}.el} is newer than
1272
@file{@var{lib}.elc} file, it issues a warning, because it's likely
1273
that somebody made changes to the @file{.el} file and forgot to
1274
recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is
1275
because people often leave unfinished edits the source file, and don't
1276
recompile it until they think it is ready to use.
1279
The variable @code{load-path} specifies the sequence of directories
1280
searched by @kbd{M-x load-library}. Its value should be a list of
1281
strings that are directory names; in addition, @code{nil} in this list
1282
stands for the current default directory. (Generally, it is not a
1283
good idea to put @code{nil} in the list; if you find yourself wishing
1284
that @code{nil} were in the list, most likely what you really want is
1285
to do @kbd{M-x load-file} this once.)
1287
The default value of @code{load-path} is a list of directories where
1288
the Lisp code for Emacs itself is stored. If you have libraries of
1289
your own, put them in a single directory and add that directory to
1290
@code{load-path}, by adding a line like this to your init file
1291
(@pxref{Init File}):
1294
(add-to-list 'load-path "/path/to/lisp/libraries")
1298
Some commands are @dfn{autoloaded}: when you run them, Emacs will
1299
automatically load the associated library first. For instance, the
1300
@code{compile} and @code{compilation-mode} commands
1301
(@pxref{Compilation}) are autoloaded; if you call either command,
1302
Emacs automatically loads the @code{compile} library. In contrast,
1303
the command @code{recompile} is not autoloaded, so it is unavailable
1304
until you load the @code{compile} library.
1306
@vindex load-dangerous-libraries
1307
@cindex Lisp files byte-compiled by XEmacs
1308
By default, Emacs refuses to load compiled Lisp files which were
1309
compiled with XEmacs, a modified versions of Emacs---they can cause
1310
Emacs to crash. Set the variable @code{load-dangerous-libraries} to
1311
@code{t} if you want to try loading them.
1314
@section Evaluating Emacs Lisp Expressions
1315
@cindex Emacs-Lisp mode
1316
@cindex mode, Emacs-Lisp
1318
@findex emacs-lisp-mode
1319
Lisp programs intended to be run in Emacs should be edited in
1320
Emacs-Lisp mode; this happens automatically for file names ending in
1321
@file{.el}. By contrast, Lisp mode itself is used for editing Lisp
1322
programs intended for other Lisp systems. To switch to Emacs-Lisp mode
1323
explicitly, use the command @kbd{M-x emacs-lisp-mode}.
1325
For testing of Lisp programs to run in Emacs, it is often useful to
1326
evaluate part of the program as it is found in the Emacs buffer. For
1327
example, after changing the text of a Lisp function definition,
1328
evaluating the definition installs the change for future calls to the
1329
function. Evaluation of Lisp expressions is also useful in any kind of
1330
editing, for invoking noninteractive functions (functions that are
1335
Read a single Lisp expression in the minibuffer, evaluate it, and print
1336
the value in the echo area (@code{eval-expression}).
1338
Evaluate the Lisp expression before point, and print the value in the
1339
echo area (@code{eval-last-sexp}).
1341
Evaluate the defun containing or after point, and print the value in
1342
the echo area (@code{eval-defun}).
1343
@item M-x eval-region
1344
Evaluate all the Lisp expressions in the region.
1345
@item M-x eval-buffer
1346
Evaluate all the Lisp expressions in the buffer.
1350
@c This uses ``colon'' instead of a literal `:' because Info cannot
1351
@c cope with a `:' in a menu
1352
@kindex M-@key{colon}
1357
@findex eval-expression
1358
@kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
1359
a Lisp expression interactively. It reads the expression using the
1360
minibuffer, so you can execute any expression on a buffer regardless of
1361
what the buffer contains. When the expression is evaluated, the current
1362
buffer is once again the buffer that was current when @kbd{M-:} was
1365
@kindex C-M-x @r{(Emacs-Lisp mode)}
1367
In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
1368
@code{eval-defun}, which parses the defun containing or following point
1369
as a Lisp expression and evaluates it. The value is printed in the echo
1370
area. This command is convenient for installing in the Lisp environment
1371
changes that you have just made in the text of a function definition.
1373
@kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
1374
evaluating a @code{defvar} expression does nothing if the variable it
1375
defines already has a value. But @kbd{C-M-x} unconditionally resets the
1376
variable to the initial value specified in the @code{defvar} expression.
1377
@code{defcustom} expressions are treated similarly.
1378
This special feature is convenient for debugging Lisp programs.
1379
Typing @kbd{C-M-x} on a @code{defface} expression reinitializes
1380
the face according to the @code{defface} specification.
1383
@findex eval-last-sexp
1384
The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
1385
expression preceding point in the buffer, and displays the value in the
1386
echo area. It is available in all major modes, not just Emacs-Lisp
1387
mode. It does not treat @code{defvar} specially.
1389
When the result of an evaluation is an integer, you can type
1390
@kbd{C-x C-e} a second time to display the value of the integer result
1391
in additional formats (octal, hexadecimal, and character).
1393
If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it
1394
inserts the value into the current buffer at point, rather than
1395
displaying it in the echo area. The argument's value does not matter.
1396
@kbd{C-M-x} with a numeric argument instruments the function
1397
definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
1401
The most general command for evaluating Lisp expressions from a buffer
1402
is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
1403
region as one or more Lisp expressions, evaluating them one by one.
1404
@kbd{M-x eval-buffer} is similar but evaluates the entire
1405
buffer. This is a reasonable way to install the contents of a file of
1406
Lisp code that you are ready to test. Later, as you find bugs and
1407
change individual functions, use @kbd{C-M-x} on each function that you
1408
change. This keeps the Lisp world in step with the source file.
1410
@vindex eval-expression-print-level
1411
@vindex eval-expression-print-length
1412
@vindex eval-expression-debug-on-error
1413
The two customizable variables @code{eval-expression-print-level} and
1414
@code{eval-expression-print-length} control the maximum depth and length
1415
of lists to print in the result of the evaluation commands before
1416
abbreviating them. @code{eval-expression-debug-on-error} controls
1417
whether evaluation errors invoke the debugger when these commands are
1418
used; its default is @code{t}.
1420
@node Lisp Interaction
1421
@section Lisp Interaction Buffers
1423
When Emacs starts up, it contains a buffer named @samp{*scratch*},
1424
which is provided for evaluating Lisp expressions interactively inside
1425
Emacs. Its major mode is Lisp Interaction mode.
1427
@findex eval-print-last-sexp
1428
@kindex C-j @r{(Lisp Interaction mode)}
1429
The simplest way to use the @samp{*scratch*} buffer is to insert
1430
Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp})
1431
after each expression. This command reads the Lisp expression before
1432
point, evaluates it, and inserts the value in printed representation
1433
before point. The result is a complete typescript of the expressions
1434
you have evaluated and their values.
1436
@vindex initial-scratch-message
1437
At startup, the @samp{*scratch*} buffer contains a short message, in
1438
the form of a Lisp comment, that explains what it is for. This
1439
message is controlled by the variable @code{initial-scratch-message},
1440
which should be either a string or @code{nil}. If you set it to the
1441
empty string, or @code{nil}, the initial message is suppressed.
1443
@findex lisp-interaction-mode
1444
All other commands in Lisp Interaction mode are the same as in Emacs
1445
Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x
1446
lisp-interaction-mode}.
1449
An alternative way of evaluating Emacs Lisp expressions interactively
1450
is to use Inferior Emacs-Lisp mode, which provides an interface rather
1451
like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
1452
expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
1453
which uses this mode. For more information see that command's
1457
@section Running an External Lisp
1459
Emacs has facilities for running programs in other Lisp systems. You can
1460
run a Lisp process as an inferior of Emacs, and pass expressions to it to
1461
be evaluated. You can also pass changed function definitions directly from
1462
the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
1466
@vindex inferior-lisp-program
1468
To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
1469
the program named @code{lisp}, the same program you would run by typing
1470
@code{lisp} as a shell command, with both input and output going through
1471
an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
1472
output'' from Lisp will go into the buffer, advancing point, and any
1473
``terminal input'' for Lisp comes from text in the buffer. (You can
1474
change the name of the Lisp executable file by setting the variable
1475
@code{inferior-lisp-program}.)
1477
To give input to Lisp, go to the end of the buffer and type the input,
1478
terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
1479
mode, which combines the special characteristics of Lisp mode with most
1480
of the features of Shell mode (@pxref{Shell Mode}). The definition of
1481
@key{RET} to send a line to a subprocess is one of the features of Shell
1485
For the source files of programs to run in external Lisps, use Lisp
1486
mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is
1487
used automatically for files whose names end in @file{.l},
1488
@file{.lsp}, or @file{.lisp}.
1490
@kindex C-M-x @r{(Lisp mode)}
1491
@findex lisp-eval-defun
1492
When you edit a function in a Lisp program you are running, the easiest
1493
way to send the changed definition to the inferior Lisp process is the key
1494
@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
1495
which finds the defun around or following point and sends it as input to
1496
the Lisp process. (Emacs can send input to any inferior process regardless
1497
of what buffer is current.)
1499
Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing
1500
programs to be run in another Lisp system) and Emacs-Lisp mode (for
1501
editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in
1502
both modes it has the effect of installing the function definition
1503
that point is in, but the way of doing so is different according to
1504
where the relevant Lisp environment is found.
1508
arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed
added
removed
doc/emacs/building.texi
