@c This is part of the Emacs manual.@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Building, Abbrevs, Programs, Top@chapter Compiling and Testing Programs@cindex building programs@cindex program building@cindex running Lisp functions The previous chapter discusses the Emacs commands that are useful formaking changes in programs. This chapter deals with commands that assistin the larger process of developing and maintaining programs.@menu* Compilation:: Compiling programs in languages other than Lisp (C, Pascal, etc.).* Grep Searching:: Running grep as if it were a compiler.* Compilation Mode:: The mode for visiting compiler errors.* Compilation Shell:: Customizing your shell properly for use in the compilation buffer.* Debuggers:: Running symbolic debuggers for non-Lisp programs. * Executing Lisp:: Various modes for editing Lisp programs, with different facilities for running the Lisp programs. * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.* External Lisp:: Communicating through Emacs with a separate Lisp. @end menu@node Compilation@section Running Compilations under Emacs@cindex inferior process@cindex make@cindex compilation errors@cindex error log Emacs can run compilers for noninteractive languages such as C andFortran as inferior processes, feeding the error log into an Emacs buffer.It can also parse the error messages and show you the source lines wherecompilation errors occurred.@table @kbd@item M-x compileRun a compiler asynchronously under Emacs, with error messages to@samp{*compilation*} buffer.@item M-x grepRun @code{grep} asynchronously under Emacs, with matching lineslisted in the buffer named @samp{*grep*}.@item M-x grep-findRun @code{grep} via @code{find}, with user-specified arguments, andcollect output in the buffer named @samp{*grep*}.@item M-x kill-compilation@itemx M-x kill-grepKill the running compilation or @code{grep} subprocess.@end table@findex compile To run @code{make} or another compilation command, do @kbd{M-xcompile}. This command reads a shell command line using the minibuffer,and then executes the command in an inferior shell, putting output inthe buffer named @samp{*compilation*}. The current buffer's defaultdirectory is used as the working directory for the execution of thecommand; normally, therefore, the compilation happens in thisdirectory.@vindex compile-command When the shell command line is read, the minibuffer appears containinga default command line, which is the command you used the last time youdid @kbd{M-x compile}. If you type just @key{RET}, the same commandline is used again. For the first @kbd{M-x compile}, the default is@samp{make -k}. The default compilation command comes from the variable@code{compile-command}; if the appropriate compilation command for afile is something other than @samp{make -k}, it can be useful for thefile to specify a local value for @code{compile-command} (@pxref{FileVariables}). Starting a compilation displays the buffer @samp{*compilation*} inanother window but does not select it. The buffer's mode line tells youwhether compilation is finished, with the word @samp{run} or @samp{exit}inside the parentheses. You do not have to keep this buffer visible;compilation continues in any case. While a compilation is going on, thestring @samp{Compiling} appears in the mode lines of all windows. Whenthis string disappears, the compilation is finished. If you want to watch the compilation transcript as it appears, switchto the @samp{*compilation*} buffer and move point to the end of thebuffer. When point is at the end, new compilation output is insertedabove point, which remains at the end. If point is not at the end ofthe buffer, it remains fixed while more compilation output is added atthe end of the buffer.@vindex compilation-scroll-output If you set the variable @code{compilation-scroll-output} to anon-@code{nil} value, then the compilation buffer always scrolls tofollow output as it comes in.@findex kill-compilation To kill the compilation process, do @kbd{M-x kill-compilation}. Whenthe compiler process terminates, the mode line of the@samp{*compilation*} buffer changes to say @samp{signal} instead of@samp{run}. Starting a new compilation also kills any runningcompilation, as only one can exist at any time. However, @kbd{M-xcompile} asks for confirmation before actually killing a compilationthat is running.@node Grep Searching@section Searching with Grep under Emacs@findex grep Just as you can run a compiler from Emacs and then visit the lineswhere there were compilation errors, you can also run @code{grep} andthen visit the lines on which matches were found. This works bytreating the matches reported by @code{grep} as if they were ``errors.'' To do this, type @kbd{M-x grep}, then enter a command line thatspecifies how to run @code{grep}. Use the same arguments you would give@code{grep} when running it normally: a @code{grep}-style regexp(usually in single-quotes to quote the shell's special characters)followed by file names, which may use wildcards. The output from@code{grep} goes in the @samp{*grep*} buffer. You can find thecorresponding lines in the original files using @kbd{C-x `} and@key{RET}, as with compilation errors. If you specify a prefix argument for @kbd{M-x grep}, it figures outthe tag (@pxref{Tags}) around point, and puts that into the default@code{grep} command.@findex grep-find The command @kbd{M-x grep-find} is similar to @kbd{M-x grep}, but itsupplies a different initial default for the command---one that runsboth @code{find} and @code{grep}, so as to search every file in adirectory tree. See also the @code{find-grep-dired} command,in @ref{Dired and Find}.@node Compilation Mode@section Compilation Mode@findex compile-goto-error@cindex Compilation mode@cindex mode, Compilation The @samp{*compilation*} buffer uses a special major mode, Compilationmode, whose main feature is to provide a convenient way to look at thesource line where the error happened.@table @kbd@item C-x `Visit the locus of the next compiler error message or @code{grep} match.@item @key{RET}Visit the locus of the error message that point is on.This command is used in the compilation buffer.@item Mouse-2Visit the locus of the error message that you click on.@end table@kindex C-x `@findex next-error You can visit the source for any particular error message by movingpoint in @samp{*compilation*} to that error message and typing @key{RET}(@code{compile-goto-error}). Or click @kbd{Mouse-2} on the error message;you need not switch to the @samp{*compilation*} buffer first. To parse the compiler error messages sequentially, type @kbd{C-x `}(@code{next-error}). The character following the @kbd{C-x} is thebackquote or ``grave accent,'' not the single-quote. This command isavailable in all buffers, not just in @samp{*compilation*}; it displaysthe next error message at the top of one window and source location ofthe error in another window. The first time @kbd{C-x `} is used after the start of a compilation,it moves to the first error's location. Subsequent uses of @kbd{C-x `}advance down to subsequent errors. If you visit a specific errormessage with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `}commands advance from there. When @kbd{C-x `} gets to the end of thebuffer and finds no more error messages to visit, it fails and signalsan Emacs error. @kbd{C-u C-x `} starts scanning from the beginning of the compilationbuffer. This is one way to process the same set of errors again. Compilation mode also redefines the keys @key{SPC} and @key{DEL} toscroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next orprevious error message. You can also use @kbd{M-@{} and @kbd{M-@}} tomove up or down to an error message for a different source file. The features of Compilation mode are also available in a minor modecalled Compilation Minor mode. This lets you parse error messages inany buffer, not just a normal compilation output buffer. Type @kbd{M-xcompilation-minor-mode} to enable the minor mode. This defines the keys@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. Compilation minor mode works in any buffer, as long as the contentsare in a format that it understands. In an Rlogin buffer (@pxref{RemoteHost}), Compilation minor mode automatically accesses remote sourcefiles by FTP (@pxref{File Names}).@node Compilation Shell@section Subshells for Compilation Emacs uses a shell to run the compilation command, but specifiesthe option for a noninteractive shell. This means, in particular, thatthe shell should start with no prompt. If you find your usual shellprompt making an unsightly appearance in the @samp{*compilation*}buffer, it means you have made a mistake in your shell's init file bysetting the prompt unconditionally. (This init file's name may be@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or variousother things, depending on the shell you use.) The shell init fileshould set the prompt only if there already is a prompt. In csh, hereis how to do it:@exampleif ($?prompt) set prompt = @dots{}@end example@noindentAnd here's how to do it in bash:@exampleif [ "$@{PS1+set@}" = set ]then PS1=@dots{}fi@end example There may well be other things that your shell's init fileought to do only for an interactive shell. You can use the samemethod to conditionalize them. The MS-DOS ``operating system'' does not support asynchronoussubprocesses; to work around this lack, @kbd{M-x compile} runs thecompilation command synchronously on MS-DOS. As a consequence, you mustwait until the command finishes before you can do anything else inEmacs. @xref{MS-DOS}.@node Debuggers@section Running Debuggers Under Emacs@cindex debuggers@cindex GUD library@cindex GDB@cindex DBX@cindex SDB@cindex XDB@cindex Perldb@cindex JDB@cindex PDB@c Do you believe in GUD?The GUD (Grand Unified Debugger) library provides an interface tovarious symbolic debuggers from within Emacs. We recommend the debuggerGDB, which is free software, but you can also run DBX, SDB or XDB if youhave them. GUD can also serve as an interface to the Perl's debuggingmode, the Python debugger PDB, and to JDB, the Java Debugger.@menu* Starting GUD:: How to start a debugger subprocess.* Debugger Operation:: Connection between the debugger and source buffers.* Commands of GUD:: Key bindings for common commands.* GUD Customization:: Defining your own commands for GUD.* GUD Tooltips:: Showing variable values by pointing with the mouse.@end menu@node Starting GUD@subsection Starting GUD There are several commands for starting a debugger, each correspondingto a particular debugger program.@table @kbd@item M-x gdb @key{RET} @var{file} @key{RET}@findex gdbRun GDB as a subprocess of Emacs. This command creates a buffer forinput and output to GDB, and switches to it. If a GDB buffer alreadyexists, it just switches to that buffer.@item M-x dbx @key{RET} @var{file} @key{RET}@findex dbxSimilar, but run DBX instead of GDB.@item M-x xdb @key{RET} @var{file} @key{RET}@findex xdb@vindex gud-xdb-directoriesSimilar, but run XDB instead of GDB. Use the variable@code{gud-xdb-directories} to specify directories to search for sourcefiles.@item M-x sdb @key{RET} @var{file} @key{RET}@findex sdbSimilar, but run SDB instead of GDB. Some versions of SDB do not mention source file names in theirmessages. When you use them, you need to have a valid tags table(@pxref{Tags}) in order for GUD to find functions in the source code.If you have not visited a tags table or the tags table doesn't list oneof the functions, you get a message saying @samp{The sdb supportrequires a valid tags table to work}. If this happens, generate a validtags table in the working directory and try again.@item M-x perldb @key{RET} @var{file} @key{RET}@findex perldbRun the Perl interpreter in debug mode to debug @var{file}, a Perl program.@item M-x jdb @key{RET} @var{file} @key{RET}@findex jdbRun the Java debugger to debug @var{file}.@item M-x pdb @key{RET} @var{file} @key{RET}@findex pdbRun the Python debugger to debug @var{file}.@end table Each of these commands takes one argument: a command line to invokethe debugger. In the simplest case, specify just the name of theexecutable file you want to debug. You may also use options that thedebugger supports. However, shell wildcards and variables are notallowed. GUD assumes that the first argument not starting with a@samp{-} is the executable file name. Emacs can only run one debugger process at a time.@node Debugger Operation@subsection Debugger Operation When you run a debugger with GUD, the debugger uses an Emacs bufferfor its ordinary input and output. This is called the GUD buffer. Thedebugger displays the source files of the program by visiting them inEmacs buffers. An arrow (@samp{=>}) in one of these buffers indicatesthe current execution line. Moving point in this buffer does not movethe arrow. You can start editing these source files at any time in the buffersthat were made to display them. The arrow is not part of the file'stext; it appears only on the screen. If you do modify a source file,keep in mind that inserting or deleting lines will throw off the arrow'spositioning; GUD has no way of figuring out which line correspondedbefore your changes to the line number in a debugger message. Also,you'll typically have to recompile and restart the program for yourchanges to be reflected in the debugger's tables. If you wish, you can control your debugger process entirely through thedebugger buffer, which uses a variant of Shell mode. All the usualcommands for your debugger are available, and you can use the Shell modehistory commands to repeat them. @xref{Shell Mode}.@node Commands of GUD@subsection Commands of GUD The GUD interaction buffer uses a variant of Shell mode, so thecommands of Shell mode are available (@pxref{Shell Mode}). GUD modealso provides commands for setting and clearing breakpoints, forselecting stack frames, and for stepping through the program. Thesecommands are available both in the GUD buffer and globally, but withdifferent key bindings. The breakpoint commands are usually used in source file buffers,because that is the way to specify where to set or clear the breakpoint.Here's the global command to set a breakpoint:@table @kbd@item C-x @key{SPC}@kindex C-x SPCSet a breakpoint on the source line that point is on.@end table@kindex C-x C-a @r{(GUD)} Here are the other special commands provided by GUD. The keysstarting with @kbd{C-c} are available only in the GUD interactionbuffer. The key bindings that start with @kbd{C-x C-a} are available inthe GUD interaction buffer and also in source files.@table @kbd@item C-c C-l@kindex C-c C-l @r{(GUD)}@itemx C-x C-a C-l@findex gud-refreshDisplay in another window the last line referred to in the GUDbuffer (that is, the line indicated in the last location message).This runs the command @code{gud-refresh}.@item C-c C-s@kindex C-c C-s @r{(GUD)}@itemx C-x C-a C-s@findex gud-stepExecute a single line of code (@code{gud-step}). If the line containsa function call, execution stops after entering the called function.@item C-c C-n@kindex C-c C-n @r{(GUD)}@itemx C-x C-a C-n@findex gud-nextExecute a single line of code, stepping across entire function callsat full speed (@code{gud-next}).@item C-c C-i@kindex C-c C-i @r{(GUD)}@itemx C-x C-a C-i@findex gud-stepiExecute a single machine instruction (@code{gud-stepi}).@need 3000@item C-c C-r@kindex C-c C-r @r{(GUD)}@itemx C-x C-a C-r@findex gud-contContinue execution without specifying any stopping point. The programwill run until it hits a breakpoint, terminates, or gets a signal thatthe debugger is checking for (@code{gud-cont}).@need 1000@item C-c C-d@kindex C-c C-d @r{(GUD)}@itemx C-x C-a C-d@findex gud-removeDelete the breakpoint(s) on the current source line, if any(@code{gud-remove}). If you use this command in the GUD interactionbuffer, it applies to the line where the program last stopped.@item C-c C-t@kindex C-c C-t @r{(GUD)}@itemx C-x C-a C-t@findex gud-tbreakSet a temporary breakpoint on the current source line, if any.If you use this command in the GUD interaction buffer,it applies to the line where the program last stopped.@end table The above commands are common to all supported debuggers. If you areusing GDB or (some versions of) DBX, these additional commands are available:@table @kbd@item C-c <@kindex C-c < @r{(GUD)}@itemx C-x C-a <@findex gud-upSelect the next enclosing stack frame (@code{gud-up}). This isequivalent to the @samp{up} command.@item C-c >@kindex C-c > @r{(GUD)}@itemx C-x C-a >@findex gud-downSelect the next inner stack frame (@code{gud-down}). This isequivalent to the @samp{down} command.@end table If you are using GDB, these additional key bindings are available:@table @kbd@item @key{TAB}@kindex TAB @r{(GUD)}@findex gud-gdb-complete-commandWith GDB, complete a symbol name (@code{gud-gdb-complete-command}).This key is available only in the GUD interaction buffer, and requiresGDB versions 4.13 and later.@item C-c C-f@kindex C-c C-f @r{(GUD)}@itemx C-x C-a C-f@findex gud-finishRun the program until the selected stack frame returns (or until itstops for some other reason).@end table These commands interpret a numeric argument as a repeat count, whenthat makes sense. Because @key{TAB} serves as a completion command, you can't use it toenter a tab as input to the program you are debugging with GDB.Instead, type @kbd{C-q @key{TAB}} to enter a tab.@node GUD Customization@subsection GUD Customization@vindex gdb-mode-hook@vindex dbx-mode-hook@vindex sdb-mode-hook@vindex xdb-mode-hook@vindex perldb-mode-hook@vindex pdb-mode-hook@vindex jdb-mode-hook On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if youare using XDB; @code{perldb-mode-hook}, for Perl debugging mode;@code{jdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You canuse these hooks to define custom key bindings for the debuggerinteraction buffer. @xref{Hooks}. Here is a convenient way to define a command that sends a particularcommand string to the debugger, and set up a key binding for it in thedebugger interaction buffer:@findex gud-def@example(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})@end example This defines a command named @var{function} which sends@var{cmdstring} to the debugger process, and gives it the documentationstring @var{docstring}. You can use the command thus defined in anybuffer. If @var{binding} is non-@code{nil}, @code{gud-def} also bindsthe command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to@kbd{C-x C-a @var{binding}} generally. The command string @var{cmdstring} may contain certain@samp{%}-sequences that stand for data to be filled in at the time@var{function} is called:@table @samp@item %fThe name of the current source file. If the current buffer is the GUDbuffer, then the ``current source file'' is the file that the programstopped in.@c This said, ``the name of the file the program counter was in at the last breakpoint.''@c But I suspect it is really the last stop file.@item %lThe number of the current source line. If the current buffer is the GUDbuffer, then the ``current source line'' is the line that the programstopped in.@item %eThe text of the C lvalue or function-call expression at or adjacent to point.@item %aThe text of the hexadecimal address at or adjacent to point.@item %pThe numeric argument of the called function, as a decimal number. Ifthe command is used without a numeric argument, @samp{%p} stands for theempty string.If you don't use @samp{%p} in the command string, the command you defineignores any numeric argument.@end table@node GUD Tooltips@subsection GUD Tooltips@cindex tooltips with GUDThe Tooltip facility (@pxref{Tooltips}) provides support for GUD@. IfGUD support is activated by customizing the @code{tooltip} group,variable values can be displayed in tooltips by pointing at them withthe mouse in the GUD buffer or in source buffers with major modes in thecustomizable list @code{tooltip-gud-modes}.@node Executing Lisp@section Executing Lisp Expressions Emacs has several different major modes for Lisp and Scheme. They arethe same in terms of editing commands, but differ in the commands forexecuting Lisp expressions. Each mode has its own purpose.@table @asis@item Emacs-Lisp modeThe mode for editing source files of programs to run in Emacs Lisp.This mode defines @kbd{C-M-x} to evaluate the current defun.@xref{Lisp Libraries}.@item Lisp Interaction modeThe mode for an interactive session with Emacs Lisp. It defines@kbd{C-j} to evaluate the sexp before point and insert its value in thebuffer. @xref{Lisp Interaction}.@item Lisp modeThe mode for editing source files of programs that run in Lisps otherthan Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defunto an inferior Lisp process. @xref{External Lisp}.@item Inferior Lisp modeThe mode for an interactive session with an inferior Lisp process.This mode combines the special features of Lisp mode and Shell mode(@pxref{Shell Mode}).@item Scheme modeLike Lisp mode but for Scheme programs.@item Inferior Scheme modeThe mode for an interactive session with an inferior Scheme process.@end table Most editing commands for working with Lisp programs are in factavailable globally. @xref{Programs}.@node Lisp Libraries@section Libraries of Lisp Code for Emacs@cindex libraries@cindex loading Lisp code Lisp code for Emacs editing commands is stored in files whose namesconventionally end in @file{.el}. This ending tells Emacs to edit them inEmacs-Lisp mode (@pxref{Executing Lisp}).@findex load-file To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. Thiscommand reads a file name using the minibuffer and then executes thecontents of that file as Lisp code. It is not necessary to visit thefile first; in any case, this command reads the file as found on disk,not text in an Emacs buffer.@findex load@findex load-library Once a file of Lisp code is installed in the Emacs Lisp librarydirectories, users can load it using @kbd{M-x load-library}. Programs canload it by calling @code{load-library}, or with @code{load}, a more primitivefunction that is similar but accepts some additional arguments. @kbd{M-x load-library} differs from @kbd{M-x load-file} in that itsearches a sequence of directories and tries three file names in eachdirectory. Suppose your argument is @var{lib}; the three names are@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by conventionthe result of compiling @file{@var{lib}.el}; it is better to load thecompiled file, since it will load and run faster. If @code{load-library} finds that @file{@var{lib}.el} is newer than@file{@var{lib}.elc} file, it prints a warning, because it's likely thatsomebody made changes to the @file{.el} file and forgot to recompileit. Because the argument to @code{load-library} is usually not in itselfa valid file name, file name completion is not available. Indeed, whenusing this command, you usually do not know exactly what file namewill be used.@vindex load-path The sequence of directories searched by @kbd{M-x load-library} isspecified by the variable @code{load-path}, a list of strings that aredirectory names. The default value of the list contains the directory wherethe Lisp code for Emacs itself is stored. If you have libraries ofyour own, put them in a single directory and add that directoryto @code{load-path}. @code{nil} in this list stands for the current defaultdirectory, but it is probably not a good idea to put @code{nil} in thelist. If you find yourself wishing that @code{nil} were in the list,most likely what you really want to do is use @kbd{M-x load-file}this once.@cindex autoload Often you do not have to give any command to load a library, becausethe commands defined in the library are set up to @dfn{autoload} thatlibrary. Trying to run any of those commands calls @code{load} to loadthe library; this replaces the autoload definitions with the real onesfrom the library.@cindex byte code Emacs Lisp code can be compiled into byte-code which loads faster,takes up less space when loaded, and executes faster. @xref{ByteCompilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}.By convention, the compiled code for a library goes in a separate filewhose name consists of the library source file with @samp{c} appended.Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}.That's why @code{load-library} searches for @samp{.elc} files first.@node Lisp Eval@section Evaluating Emacs-Lisp Expressions@cindex Emacs-Lisp mode@cindex mode, Emacs-Lisp@findex emacs-lisp-mode Lisp programs intended to be run in Emacs should be edited inEmacs-Lisp mode; this happens automatically for file names ending in@file{.el}. By contrast, Lisp mode itself is used for editing Lispprograms intended for other Lisp systems. To switch to Emacs-Lisp modeexplicitly, use the command @kbd{M-x emacs-lisp-mode}. For testing of Lisp programs to run in Emacs, it is often useful toevaluate part of the program as it is found in the Emacs buffer. Forexample, after changing the text of a Lisp function definition,evaluating the definition installs the change for future calls to thefunction. Evaluation of Lisp expressions is also useful in any kind ofediting, for invoking noninteractive functions (functions that arenot commands).@table @kbd@item M-:Read a single Lisp expression in the minibuffer, evaluate it, and printthe value in the echo area (@code{eval-expression}).@item C-x C-eEvaluate the Lisp expression before point, and print the value in theecho area (@code{eval-last-sexp}).@item C-M-xEvaluate the defun containing or after point, and print the value inthe echo area (@code{eval-defun}).@item M-x eval-regionEvaluate all the Lisp expressions in the region.@item M-x eval-current-bufferEvaluate all the Lisp expressions in the buffer.@end table@kindex M-:@findex eval-expression @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluatinga Lisp expression interactively. It reads the expression using theminibuffer, so you can execute any expression on a buffer regardless ofwhat the buffer contains. When the expression is evaluated, the currentbuffer is once again the buffer that was current when @kbd{M-:} wastyped.@kindex C-M-x @r{(Emacs-Lisp mode)}@findex eval-defun In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command@code{eval-defun}, which parses the defun containing or following pointas a Lisp expression and evaluates it. The value is printed in the echoarea. This command is convenient for installing in the Lisp environmentchanges that you have just made in the text of a function definition. @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,evaluating a @code{defvar} expression does nothing if the variable itdefines already has a value. But @kbd{C-M-x} unconditionally resets thevariable to the initial value specified in the @code{defvar} expression.This special feature is convenient for debugging Lisp programs.@kindex C-x C-e@findex eval-last-sexp The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lispexpression preceding point in the buffer, and displays the value in theecho area. It is available in all major modes, not just Emacs-Lispmode. It does not treat @code{defvar} specially. If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numericargument, it inserts the value into the current buffer at point, ratherthan displaying it in the echo area. The argument's value does notmatter.@findex eval-region@findex eval-current-buffer The most general command for evaluating Lisp expressions from a bufferis @code{eval-region}. @kbd{M-x eval-region} parses the text of theregion as one or more Lisp expressions, evaluating them one by one.@kbd{M-x eval-current-buffer} is similar but evaluates the entirebuffer. This is a reasonable way to install the contents of a file ofLisp code that you are just ready to test. Later, as you find bugs andchange individual functions, use @kbd{C-M-x} on each function that youchange. This keeps the Lisp world in step with the source file.@node Lisp Interaction@section Lisp Interaction Buffers The buffer @samp{*scratch*} which is selected when Emacs starts up isprovided for evaluating Lisp expressions interactively inside Emacs. The simplest way to use the @samp{*scratch*} buffer is to insert Lispexpressions and type @kbd{C-j} after each expression. This commandreads the Lisp expression before point, evaluates it, and inserts thevalue in printed representation before point. The result is a completetypescript of the expressions you have evaluated and their values. The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, whichis the same as Emacs-Lisp mode except for the binding of @kbd{C-j}.@findex lisp-interaction-mode The rationale for this feature is that Emacs must have a buffer whenit starts up, but that buffer is not useful for editing files since anew buffer is made for every file that you visit. The Lisp interpretertypescript is the most useful thing I can think of for the initialbuffer to do. Type @kbd{M-x lisp-interaction-mode} to put the currentbuffer in Lisp Interaction mode.@findex ielm An alternative way of evaluating Emacs Lisp expressions interactivelyis to use Inferior Emacs-Lisp mode, which provides an interface ratherlike Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lispexpressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} bufferwhich uses this mode.@node External Lisp@section Running an External Lisp Emacs has facilities for running programs in other Lisp systems. You canrun a Lisp process as an inferior of Emacs, and pass expressions to it tobe evaluated. You can also pass changed function definitions directly fromthe Emacs buffers in which you edit the Lisp programs to the inferior Lispprocess.@findex run-lisp@vindex inferior-lisp-program@kindex C-x C-z To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runsthe program named @code{lisp}, the same program you would run by typing@code{lisp} as a shell command, with both input and output going throughan Emacs buffer named @samp{*lisp*}. That is to say, any ``terminaloutput'' from Lisp will go into the buffer, advancing point, and any``terminal input'' for Lisp comes from text in the buffer. (You canchange the name of the Lisp executable file by setting the variable@code{inferior-lisp-program}.) To give input to Lisp, go to the end of the buffer and type the input,terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lispmode, which combines the special characteristics of Lisp mode with mostof the features of Shell mode (@pxref{Shell Mode}). The definition of@key{RET} to send a line to a subprocess is one of the features of Shellmode.@findex lisp-mode For the source files of programs to run in external Lisps, use Lispmode. This mode can be selected with @kbd{M-x lisp-mode}, and is usedautomatically for files whose names end in @file{.l}, @file{.lsp}, or@file{.lisp}, as most Lisp systems usually expect.@kindex C-M-x @r{(Lisp mode)}@findex lisp-eval-defun When you edit a function in a Lisp program you are running, the easiestway to send the changed definition to the inferior Lisp process is the key@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},which finds the defun around or following point and sends it as input tothe Lisp process. (Emacs can send input to any inferior process regardlessof what buffer is current.) Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programsto be run in another Lisp system) and Emacs-Lisp mode (for editing Lispprograms to be run in Emacs): in both modes it has the effect of installingthe function definition that point is in, but the way of doing so isdifferent according to where the relevant Lisp environment is found.@xref{Executing Lisp}.