update.
[chise/xemacs-chise.git.1] / man / xemacs / building.texi
1
2 @node Running, Abbrevs, Programs, Top
3 @chapter Compiling and Testing Programs
4
5   The previous chapter discusses the Emacs commands that are useful for
6 making changes in programs.  This chapter deals with commands that assist
7 in the larger process of developing and maintaining programs.
8
9 @menu
10 * Compilation::        Compiling programs in languages other than Lisp
11                         (C, Pascal, etc.)
12 * Modes: Lisp Modes.   Various modes for editing Lisp programs, with
13                        different facilities for running the Lisp programs.
14 * Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
15 * Eval: Lisp Eval.     Executing a single Lisp expression in Emacs.
16 * Debug: Lisp Debug.   Debugging Lisp programs running in Emacs.
17 * Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
18 * External Lisp::      Communicating through Emacs with a separate Lisp.
19 @end menu
20
21 @node Compilation, Lisp Modes, Running, Running
22 @section Running ``make'', or Compilers Generally
23 @cindex inferior process
24 @cindex make
25 @cindex compilation errors
26 @cindex error log
27
28   Emacs can run compilers for non-interactive languages like C and
29 Fortran as inferior processes, feeding the error log into an Emacs buffer.
30 It can also parse the error messages and visit the files in which errors
31 are found, moving point to the line where the error occurred.
32
33 @table @kbd
34 @item M-x compile
35 Run a compiler asynchronously under Emacs, with error messages to
36 @samp{*compilation*} buffer.
37 @item M-x grep
38 Run @code{grep} asynchronously under Emacs, with matching lines
39 listed in the buffer named @samp{*compilation*}.
40 @item M-x kill-compilation
41 Kill the process made by the @code{M-x compile} command.
42 @item M-x kill-grep
43 Kill the running compilation or @code{grep} subprocess.
44 @item C-x `
45 Visit the next compiler error message or @code{grep} match.
46 @end table
47
48 @findex compile
49   To run @code{make} or another compiler, type @kbd{M-x compile}.  This
50 command reads a shell command line using the minibuffer, then executes
51 the specified command line in an inferior shell with output going to the
52 buffer named @samp{*compilation*}.  By default, the current buffer's
53 default directory is used as the working directory for the execution of
54 the command; therefore, the makefile comes from this directory.
55
56 @vindex compile-command
57   When the shell command line is read, the minibuffer appears containing a
58 default command line (the command you used the last time you typed
59 @kbd{M-x compile}).  If you type just @key{RET}, the same command line is used
60 again.  The first @kbd{M-x compile} provides @code{make -k} as the default.
61 The default is taken from the variable @code{compile-command}; if the
62 appropriate compilation command for a file is something other than
63 @code{make -k}, it can be useful to have the file specify a local value for
64 @code{compile-command} (@pxref{File Variables}).
65
66 @cindex compiling files
67   When you start a compilation, the buffer @samp{*compilation*} is
68 displayed in another window but not selected.  Its mode line displays
69 the word @samp{run} or @samp{exit} in the parentheses to tell you whether
70 compilation is finished.  You do not have to keep this buffer visible;
71 compilation continues in any case.
72
73 @findex kill-compilation
74   To kill the compilation process, type @kbd{M-x kill-compilation}.  The mode
75 line of the @samp{*compilation*} buffer changes to say @samp{signal}
76 instead of @samp{run}.  Starting a new compilation also kills any
77 running compilation, as only one can occur at any time.  Starting a new
78 compilation prompts for confirmation before actually killing a
79 compilation that is running.@refill
80
81 @kindex C-x `
82 @findex next-error
83   To parse the compiler error messages, type @kbd{C-x `}
84 (@code{next-error}).  The character following @kbd{C-x} is the grave
85 accent, not the single quote.  The command displays the buffer
86 @samp{*compilation*} in one window and the buffer in which the next
87 error occurred in another window.  Point in that buffer is moved to the
88 line where the error was found.  The corresponding error message is
89 scrolled to the top of the window in which @samp{*compilation*} is
90 displayed.
91
92   The first time you use @kbd{C-x `} after the start of a compilation, it
93 parses all the error messages, visits all the files that have error
94 messages, and creates markers pointing at the lines the error messages
95 refer to.  It then moves to the first error message location.  Subsequent
96 uses of @kbd{C-x `} advance down the data set up by the first use.  When
97 the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
98 any more error messages that have come in; this is useful if you start
99 editing compiler errors while compilation is still going on.  If no
100 additional error messages have come in, @kbd{C-x `} reports an error.
101
102   @kbd{C-u C-x `} discards the preparsed error message data and parses the
103 @samp{*compilation*} buffer again, then displays the first error.
104 This way, you can process the same set of errors again.
105
106   Instead of running a compiler, you can run @code{grep} and see the
107 lines on which matches were found.  To do this, type @kbd{M-x grep} with
108 an argument line that contains the same arguments you would give to
109 @code{grep}: a @code{grep}-style regexp (usually in single quotes to
110 quote the shell's special characters) followed by filenames, which may
111 use wildcard characters.  The output from @code{grep} goes in the
112 @samp{*compilation*} buffer.  You can use @kbd{C-x `} to find the lines that
113 match as if they were compilation errors.
114
115   Note: a shell is used to run the compile command, but the shell is not
116 run in interactive mode.  In particular, this means that the shell starts
117 up with no prompt.  If you find your usual shell prompt making an
118 unsightly appearance in the @samp{*compilation*} buffer, it means you
119 have made a mistake in your shell's initialization file (@file{.cshrc}
120 or @file{.shrc} or @dots{}) by setting the prompt unconditionally.  The
121 shell initialization file should set the prompt only if there already is
122 a prompt.  Here's how to do it in @code{csh}:
123
124 @example
125 if ($?prompt) set prompt = ...
126 @end example
127
128 @node Lisp Modes, Lisp Libraries, Compilation, Running
129 @section Major Modes for Lisp
130
131   Emacs has four different major modes for Lisp.  They are the same in
132 terms of editing commands, but differ in the commands for executing Lisp
133 expressions.
134
135 @table @asis
136 @item Emacs-Lisp mode
137 The mode for editing source files of programs to run in Emacs Lisp.
138 This mode defines @kbd{C-M-x} to evaluate the current defun.
139 @xref{Lisp Libraries}.
140 @item Lisp Interaction mode
141 The mode for an interactive session with Emacs Lisp.  It defines
142 @key{LFD} to evaluate the sexp before point and insert its value in the
143 buffer.  @xref{Lisp Interaction}.
144 @item Lisp mode
145 The mode for editing source files of programs that run in other dialects
146 of Lisp than Emacs Lisp.  This mode defines @kbd{C-M-x} to send the
147 current defun to an inferior Lisp process.  @xref{External Lisp}.
148 @item Inferior Lisp mode
149 The mode for an interactive session with an inferior Lisp process.
150 This mode combines the special features of Lisp mode and Shell mode
151 (@pxref{Shell Mode}).
152 @item Scheme mode
153 Like Lisp mode but for Scheme programs.
154 @item Inferior Scheme mode
155 The mode for an interactive session with an inferior Scheme process.
156 @end table
157
158 @node Lisp Libraries, Lisp Eval, Lisp Modes, Running
159 @section Libraries of Lisp Code for Emacs
160 @cindex libraries
161 @cindex loading Lisp code
162
163   Lisp code for Emacs editing commands is stored in files whose names
164 conventionally end in @file{.el}.  This ending tells Emacs to edit them in
165 Emacs-Lisp mode (@pxref{Lisp Modes}).
166
167 @menu
168 * Loading::             Loading libraries of Lisp code into Emacs for use.
169 * Compiling Libraries:: Compiling a library makes it load and run faster.
170 * Mocklisp::            Converting Mocklisp to Lisp so XEmacs can run it.
171 @end menu
172
173 @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries
174 @subsection Loading Libraries
175
176 @table @kbd
177 @item M-x load-file @var{file}
178 Load the file @var{file} of Lisp code.
179 @item M-x load-library @var{library}
180 Load the library named @var{library}.
181 @item M-x locate-library @var{library} &optional @var{nosuffix}
182 Show the full path name of Emacs library @var{library}.
183 @end table
184
185 @findex load-file
186   To execute a file of Emacs Lisp, use @kbd{M-x load-file}.  This
187 command reads the file name you provide in the minibuffer, then executes
188 the contents of that file as Lisp code.  It is not necessary to visit
189 the file first; in fact, this command reads the file as found on
190 disk, not the text in an Emacs buffer.
191
192 @findex load
193 @findex load-library
194   Once a file of Lisp code is installed in the Emacs Lisp library
195 directories, users can load it using @kbd{M-x load-library}.  Programs can
196 load it by calling @code{load-library}, or with @code{load}, a more primitive
197 function that is similar but accepts some additional arguments.
198
199   @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
200 searches a sequence of directories and tries three file names in each
201 directory.  The three names are: first, the specified name with @file{.elc}
202 appended; second, the name with @file{.el} appended; third, the specified
203 name alone.  A @file{.elc} file would be the result of compiling the Lisp
204 file into byte code;  if possible, it is loaded in preference to the Lisp
205 file itself because the compiled file loads and runs faster.
206
207 @cindex loading libraries
208   Because the argument to @code{load-library} is usually not in itself
209 a valid file name, file name completion is not available.  In fact, when
210 using this command, you usually do not know exactly what file name
211 will be used.
212
213 @vindex load-path
214   The sequence of directories searched by @kbd{M-x load-library} is
215 specified by the variable @code{load-path}, a list of strings that are
216 directory names.  The elements of this list may not begin with "@samp{~}",
217 so you must call @code{expand-file-name} on them before adding them to
218 the list.  The default value of the list contains the directory where
219 the Lisp code for Emacs itself is stored.  If you have libraries of your
220 own, put them in a single directory and add that directory to
221 @code{load-path}.  @code{nil} in this list stands for the current
222 default directory, but it is probably not a good idea to put @code{nil}
223 in the list.  If you start wishing that @code{nil} were in the list, you
224 should probably use @kbd{M-x load-file} for this case.
225
226 The variable is initialized by the @b{EMACSLOADPATH} environment
227 variable. If no value is specified, the variable takes the default value
228 specified in the file @file{paths.h} when Emacs was built. If a path
229 isn't specified in @file{paths.h}, a default value is obtained from the
230 file system, near the directory in which the Emacs executable resides.
231
232 @findex locate-library
233  Like @kbd{M-x load-library}, @kbd{M-x locate-library} searches the 
234 directories in @code{load-path} to find the file that @kbd{M-x load-library}
235 would load.  If the optional second argument @var{nosuffix} is
236 non-@code{nil}, the suffixes @file{.elc} or @file{.el} are not added to
237 the specified name @var{library} (like calling @code{load} instead of
238 @code{load-library}).
239
240 @cindex autoload
241    You often do not have to give any command to load a library, because the
242 commands defined in the library are set up to @dfn{autoload} that library.
243 Running any of those commands causes @code{load} to be called to load the
244 library; this replaces the autoload definitions with the real ones from the
245 library.
246
247   If autoloading a file does not finish, either because of an error or
248 because of a @kbd{C-g} quit, all function definitions made by the file
249 are undone automatically.  So are any calls to @code{provide}.  As a
250 consequence, the entire file is loaded a second time if you use one of
251 the autoloadable commands again.  This prevents problems when the
252 command is no longer autoloading but is working incorrectly because the file
253 was only partially loaded.  Function definitions are undone only for
254 autoloading; explicit calls to @code{load} do not undo anything if
255 loading is not completed.
256
257 @vindex after-load-alist
258 The variable @code{after-load-alist} takes an alist of expressions to be
259 evaluated when particular files are loaded.  Each element has the form
260 @code{(@var{filename} forms...)}.  When @code{load} is run and the filename
261 argument is @var{filename}, the forms in the corresponding element are
262 executed at the end of loading.
263
264 @var{filename} must match exactly.  Normally @var{filename} is the
265 name of a library, with no directory specified, since that is how load
266 is normally called.  An error in @code{forms} does not undo the load, but
267 it does prevent execution of the rest of the @code{forms}.
268
269 @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries
270 @subsection Compiling Libraries
271
272 @cindex byte code
273   Emacs Lisp code can be compiled into byte-code which loads faster,
274 takes up less space when loaded, and executes faster.
275
276 @table @kbd
277 @item M-x batch-byte-compile
278 Run byte-compile-file on the files remaining on the command line.
279 @item M-x byte-compile-buffer &optional @var{buffer}
280 Byte-compile and evaluate contents of @var{buffer} (default is current 
281 buffer).
282 @item M-x byte-compile-file
283 Compile a file of Lisp code named @var{filename} into a file of byte code.
284 @item M-x byte-compile-and-load-file @var{filename}
285 Compile a file of Lisp code named @var{filename} into a file of byte
286 code and load it.
287 @item M-x byte-recompile-directory @var{directory}
288 Recompile every @file{.el} file in @var{directory} that needs recompilation.
289 @item M-x disassemble
290 Print disassembled code for @var{object} on (optional) @var{stream}.
291 @findex make-obsolete
292 @item M-x make-obsolete @var{function new} 
293 Make the byte-compiler warn that @var{function} is obsolete and @var{new} 
294 should be used instead.
295 @end table
296
297 @findex byte-compile-file
298 @findex byte-compile-and-load-file
299 @findex byte-compile-buffer
300  @kbd{byte-compile-file} creates a byte-code compiled file from an
301 Emacs-Lisp source file.  The default argument for this function is the
302 file visited in the current buffer.  The function reads the specified
303 file, compiles it into byte code, and writes an output file whose name
304 is made by appending @file{c} to the input file name.  Thus, the file
305 @file{rmail.el} would be compiled into @file{rmail.elc}. To compile a
306 file of Lisp code named @var{filename} into a file of byte code and
307 then load it, use @code{byte-compile-and-load-file}. To compile and
308 evaluate Lisp code in a given buffer, use @code{byte-compile-buffer}.
309
310 @findex byte-recompile-directory
311   To recompile all changed Lisp files in a directory, use @kbd{M-x
312 byte-recompile-directory}.  Specify just the directory name as an argument.
313 Each @file{.el} file that has been byte-compiled before is byte-compiled
314 again if it has changed since the previous compilation.  A numeric argument
315 to this command tells it to offer to compile each @file{.el} file that has
316 not been compiled yet.  You must answer @kbd{y} or @kbd{n} to each
317 offer.
318
319 @findex batch-byte-compile
320   You can use the function @code{batch-byte-compile} to invoke Emacs
321 non-interactively from the shell to do byte compilation.  When you use
322 this function, the files to be compiled are specified with command-line
323 arguments.  Use a shell command of the form:
324
325 @example
326 emacs -batch -f batch-byte-compile @var{files}...
327 @end example
328
329   Directory names may also be given as arguments; in that case,
330 @code{byte-recompile-directory} is invoked on each such directory.
331 @code{batch-byte-compile} uses all remaining command-line arguments as
332 file or directory names, then kills the Emacs process.
333
334 @findex disassemble
335   @kbd{M-x disassemble} explains the result of byte compilation.  Its
336 argument is a function name.  It displays the byte-compiled code in a help
337 window in symbolic form, one instruction per line.  If the instruction
338 refers to a variable or constant, that is shown, too.
339
340 @node Mocklisp,,Compiling Libraries,Lisp Libraries
341 @subsection Converting Mocklisp to Lisp
342
343 @cindex mocklisp
344 @findex convert-mocklisp-buffer
345   XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
346 To convert a Mocklisp file, visit it and then type @kbd{M-x
347 convert-mocklisp-buffer}.  Then save the resulting buffer of Lisp file in a
348 file whose name ends in @file{.el} and use the new file as a Lisp library.
349
350   You cannot currently byte-compile converted Mocklisp code.
351 The reason is that converted Mocklisp code uses some special Lisp features
352 to deal with Mocklisp's incompatible ideas of how arguments are evaluated
353 and which values signify ``true'' or ``false''.
354
355 @node Lisp Eval, Lisp Debug, Lisp Libraries, Running
356 @section Evaluating Emacs-Lisp Expressions
357 @cindex Emacs-Lisp mode
358
359 @findex emacs-lisp-mode
360   Lisp programs intended to be run in Emacs should be edited in
361 Emacs-Lisp mode; this will happen automatically for file names ending in
362 @file{.el}.  By contrast, Lisp mode itself should be used for editing
363 Lisp programs intended for other Lisp systems.  Emacs-Lisp mode can be
364 selected with the command @kbd{M-x emacs-lisp-mode}.
365
366   For testing of Lisp programs to run in Emacs, it is useful to be able
367 to evaluate part of the program as it is found in the Emacs buffer.  For
368 example, if you change the text of a Lisp function definition and then
369 evaluate the definition, Emacs installs the change for future calls to the
370 function.  Evaluation of Lisp expressions is also useful in any kind of
371 editing task for invoking non-interactive functions (functions that are
372 not commands).
373
374 @table @kbd
375 @item M-:
376 Read a Lisp expression in the minibuffer, evaluate it, and print the
377 value in the minibuffer (@code{eval-expression}).
378 @item C-x C-e
379 Evaluate the Lisp expression before point, and print the value in the
380 minibuffer (@code{eval-last-sexp}).
381 @item C-M-x
382 Evaluate the defun containing point or after point, and print the value in
383 the minibuffer (@code{eval-defun}).
384 @item M-x eval-region
385 Evaluate all the Lisp expressions in the region.
386 @item M-x eval-current-buffer
387 Evaluate all the Lisp expressions in the buffer.
388 @end table
389
390 @kindex M-:
391 @findex eval-expression
392   @kbd{M-:} (@code{eval-expression}) is the most basic command
393 for evaluating a Lisp expression interactively.  It reads the expression
394 using the minibuffer, so you can execute any expression on a buffer
395 regardless of what the buffer contains.  When evaluation is complete,
396 the current buffer is once again the buffer that was current when
397 @kbd{M-:} was typed.
398
399 @kindex C-M-x
400 @findex eval-defun
401   In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function
402 @code{eval-defun}, which parses the defun containing point or following point
403 as a Lisp expression and evaluates it.  The value is printed in the echo
404 area.  This command is convenient for installing in the Lisp environment
405 changes that you have just made in the text of a function definition.
406
407 @kindex C-x C-e
408 @findex eval-last-sexp
409   The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
410 but is available in all major modes, not just Emacs-Lisp mode.  It finds
411 the sexp before point, reads it as a Lisp expression, evaluates it, and
412 prints the value in the echo area.  It is sometimes useful to type in an
413 expression and then, with point still after it, type @kbd{C-x C-e}.
414
415   If @kbd{C-M-x} or @kbd{C-x C-e} are given a numeric argument, they
416 print the value by inserting it into the current buffer at point, rather
417 than in the echo area.  The argument value does not matter.
418
419 @findex eval-region
420 @findex eval-current-buffer
421   The most general command for evaluating Lisp expressions from a buffer
422 is @code{eval-region}.  @kbd{M-x eval-region} parses the text of the
423 region as one or more Lisp expressions, evaluating them one by one.
424 @kbd{M-x eval-current-buffer} is similar, but it evaluates the entire
425 buffer.  This is a reasonable way to install the contents of a file of
426 Lisp code that you are just ready to test.  After finding and fixing a
427 bug, use @kbd{C-M-x} on each function that you change, to keep the Lisp
428 world in step with the source file.
429
430 @node Lisp Debug, Lisp Interaction, Lisp Eval, Running
431 @section The Emacs-Lisp Debugger
432 @cindex debugger
433
434 @vindex debug-on-error
435 @vindex debug-on-quit
436   XEmacs contains a debugger for Lisp programs executing inside it.
437 This debugger is normally not used; many commands frequently get Lisp
438 errors when invoked in inappropriate contexts (such as @kbd{C-f} at the
439 end of the buffer) and it would be unpleasant to enter a special
440 debugging mode in this case.  When you want to make Lisp errors invoke
441 the debugger, you must set the variable @code{debug-on-error} to
442 non-@code{nil}.  Quitting with @kbd{C-g} is not considered an error, and
443 @code{debug-on-error} has no effect on the handling of @kbd{C-g}.
444 However, if you set @code{debug-on-quit} to be non-@code{nil}, @kbd{C-g} will
445 invoke the debugger.  This can be useful for debugging an infinite loop;
446 type @kbd{C-g} once the loop has had time to reach its steady state.
447 @code{debug-on-quit} has no effect on errors.@refill
448
449 @findex debug-on-entry
450 @findex cancel-debug-on-entry
451 @findex debug
452   You can make Emacs enter the debugger when a specified function
453 is called or at a particular place in Lisp code.  Use @kbd{M-x
454 debug-on-entry} with argument @var{fun-name} to have Emacs enter the
455 debugger as soon as @var{fun-name} is called. Use
456 @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
457 debugger when called.  (Redefining the function also does this.)  To enter
458 the debugger from some other place in Lisp code, you must insert the
459 expression @code{(debug)} there and install the changed code with
460 @kbd{C-M-x}.  @xref{Lisp Eval}.@refill
461
462   When the debugger is entered, it displays the previously selected buffer
463 in one window and a buffer named @samp{*Backtrace*} in another window.  The
464 backtrace buffer contains one line for each level of Lisp function
465 execution currently going on.  At the beginning of the buffer is a message
466 describing the reason that the debugger was invoked, for example, an
467 error message if it was invoked due to an error.
468
469   The backtrace buffer is read-only and is in Backtrace mode, a special
470 major mode in which letters are defined as debugger commands.  The
471 usual Emacs editing commands are available; you can switch windows to
472 examine the buffer that was being edited at the time of the error, and
473 you can switch buffers, visit files, and perform any other editing
474 operations.  However, the debugger is a recursive editing level
475 (@pxref{Recursive Edit}); it is a good idea to return to the backtrace
476 buffer and explicitly exit the debugger when you don't want to use it any
477 more.  Exiting the debugger kills the backtrace buffer.
478
479 @cindex current stack frame
480   The contents of the backtrace buffer show you the functions that are
481 executing and the arguments that were given to them.  It also allows you
482 to specify a stack frame by moving point to the line describing that
483 frame.  The frame whose line point is on is considered the @dfn{current
484 frame}.  Some of the debugger commands operate on the current frame.
485 Debugger commands are mainly used for stepping through code one
486 expression at a time.  Here is a list of them:
487
488 @table @kbd
489 @item c
490 Exit the debugger and continue execution.  In most cases, execution of
491 the program continues as if the debugger had never been entered (aside
492 from the effect of any variables or data structures you may have changed
493 while inside the debugger).  This includes entry to the debugger due to
494 function entry or exit, explicit invocation, and quitting or certain
495 errors.  Most errors cannot be continued; trying to continue an error usually
496 causes the same error to occur again.
497 @item d
498 Continue execution, but enter the debugger the next time a Lisp
499 function is called.  This allows you to step through the
500 subexpressions of an expression, and see what the subexpressions do and
501 what values they compute.
502
503 When you enter the debugger this way, Emacs flags the stack frame for the
504 function call from which you entered.  The same function is then called
505 when you exit the frame.  To cancel this flag, use @kbd{u}.
506 @item b
507 Set up to enter the debugger when the current frame is exited.  Frames
508 that invoke the debugger on exit are flagged with stars.
509 @item u
510 Don't enter the debugger when the current frame is exited.  This
511 cancels a @kbd{b} command on a frame.
512 @item e
513 Read a Lisp expression in the minibuffer, evaluate it, and print the
514 value in the echo area.  This is equivalent to the command @kbd{M-:}.
515 @item q
516 Terminate the program being debugged; return to top-level Emacs
517 command execution.
518
519 If the debugger was entered due to a @kbd{C-g} but you really want
520 to quit, not to debug, use the @kbd{q} command.
521 @item r
522 Return a value from the debugger.  The value is computed by reading an
523 expression with the minibuffer and evaluating it.
524
525 The value returned by the debugger makes a difference when the debugger
526 was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
527 then the value specified in the @kbd{r} command is used as the value of
528 that frame.
529
530 The debugger's return value also matters with many errors.  For example,
531 @code{wrong-type-argument} errors will use the debugger's return value
532 instead of the invalid argument; @code{no-catch} errors will use the
533 debugger value as a throw tag instead of the tag that was not found.
534 If an error was signaled by calling the Lisp function @code{signal},
535 the debugger's return value is returned as the value of @code{signal}.
536 @end table
537
538 @node Lisp Interaction, External Lisp, Lisp Debug, Running
539 @section Lisp Interaction Buffers
540
541   The buffer @samp{*scratch*}, which is selected when Emacs starts up, is
542 provided for evaluating Lisp expressions interactively inside Emacs.  Both
543 the expressions you evaluate and their output goes in the buffer.
544
545   The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
546 is the same as Emacs-Lisp mode except for one command, @key{LFD}.  In
547 Emacs-Lisp mode, @key{LFD} is an indentation command.  In Lisp
548 Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}.  This
549 function reads the Lisp expression before point, evaluates it, and inserts
550 the value in printed representation before point.
551
552  The way to use the @samp{*scratch*} buffer is to insert Lisp
553 expressions at the end, ending each one with @key{LFD} so that it will
554 be evaluated.  The result is a complete typescript of the expressions
555 you have evaluated and their values.
556
557 @findex lisp-interaction-mode
558   The rationale for this feature is that Emacs must have a buffer when it
559 starts up, but that buffer is not useful for editing files since a new
560 buffer is made for every file that you visit.  The Lisp interpreter
561 typescript is the most useful thing I can think of for the initial buffer
562 to do.  @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
563 Interaction mode.
564
565 @node External Lisp,, Lisp Interaction, Running
566 @section Running an External Lisp
567
568   Emacs has facilities for running programs in other Lisp systems.  You can
569 run a Lisp process as an inferior of Emacs, and pass expressions to it to
570 be evaluated.  You can also pass changed function definitions directly from
571 the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
572 process.
573
574 @findex run-lisp
575   To run an inferior Lisp process, type @kbd{M-x run-lisp}.  This runs the
576 program named @code{lisp}, the same program you would run by typing
577 @code{lisp} as a shell command, with both input and output going through an
578 Emacs buffer named @samp{*lisp*}.  In other words, any ``terminal output''
579 from Lisp will go into the buffer, advancing point, and any ``terminal
580 input'' for Lisp comes from text in the buffer.  To give input to Lisp, go
581 to the end of the buffer and type the input, terminated by @key{RET}.  The
582 @samp{*lisp*} buffer is in Inferior Lisp mode, which has all the
583 special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}).
584
585 @findex lisp-mode
586   Use Lisp mode to run the source files of programs in external Lisps.
587 You can select this mode with @kbd{M-x lisp-mode}.  It is used automatically
588 for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
589 systems usually expect.
590
591 @kindex C-M-x
592 @findex lisp-send-defun
593   When you edit a function in a Lisp program you are running, the easiest
594 way to send the changed definition to the inferior Lisp process is the key
595 @kbd{C-M-x}.  In Lisp mode, this key runs the function @code{lisp-send-defun},
596 which finds the defun around or following point and sends it as input to
597 the Lisp process.  (Emacs can send input to any inferior process regardless
598 of what buffer is current.)
599
600   Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
601 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
602 programs to be run in Emacs): in both modes it has the effect of installing
603 the function definition that point is in, but the way of doing so is
604 different according to where the relevant Lisp environment is found.
605 @xref{Lisp Modes}.