Mercurial > emacs
changeset 84225:6a0fe540610a
Move here from ../../man
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:44:24 +0000 |
| parents | 39a5a93baadb |
| children | 8ad299ffcbc5 |
| files | doc/emacs/building.texi |
| diffstat | 1 files changed, 1440 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/building.texi Thu Sep 06 04:44:24 2007 +0000 @@ -0,0 +1,1440 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Building, Maintaining, 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 for +making changes in programs. This chapter deals with commands that assist +in the larger process of compiling and testing programs. + +@menu +* Compilation:: Compiling programs in languages other + than Lisp (C, Pascal, etc.). +* Compilation Mode:: The mode for visiting compiler errors. +* Compilation Shell:: Customizing your shell properly + for use in the compilation buffer. +* Grep Searching:: Searching with grep. +* Flymake:: Finding syntax errors on the fly. +* 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. +* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. +* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. +* 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 and +Fortran as inferior processes, feeding the error log into an Emacs buffer. +It can also parse the error messages and show you the source lines where +compilation errors occurred. + +@table @kbd +@item M-x compile +Run a compiler asynchronously under Emacs, with error messages going to +the @samp{*compilation*} buffer. +@item M-x recompile +Invoke a compiler with the same command as in the last invocation of +@kbd{M-x compile}. +@item M-x kill-compilation +Kill the running compilation subprocess. +@end table + +@findex compile + To run @code{make} or another compilation command, do @kbd{M-x +compile}. This command reads a shell command line using the minibuffer, +and then executes the command in an inferior shell, putting output in +the buffer named @samp{*compilation*}. The current buffer's default +directory is used as the working directory for the execution of the +command; normally, therefore, the compilation happens in this +directory. + +@vindex compile-command + The default for the compilation command is normally @samp{make -k}, +which is correct most of the time for nontrivial programs. +(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x +compile} before, the default each time is the command you used the +previous time. @code{compile} stores this command in the variable +@code{compile-command}, so setting that variable specifies the default +for the next use of @kbd{M-x compile}. If a file specifies a file +local value for @code{compile-command}, that provides the default when +you type @kbd{M-x compile} in that file's buffer. @xref{File +Variables}. + + Starting a compilation displays the buffer @samp{*compilation*} in +another window but does not select it. The buffer's mode line tells +you whether compilation is finished, with the word @samp{run}, +@samp{signal} 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, the string @samp{Compiling} appears in the +mode lines of all windows. When this string disappears, the +compilation is finished. + + If you want to watch the compilation transcript as it appears, switch +to the @samp{*compilation*} buffer and move point to the end of the +buffer. When point is at the end, new compilation output is inserted +above point, which remains at the end. If point is not at the end of +the buffer, it remains fixed while more compilation output is added at +the end of the buffer. + +@cindex compilation buffer, keeping point at end +@vindex compilation-scroll-output + If you set the variable @code{compilation-scroll-output} to a +non-@code{nil} value, then the compilation buffer always scrolls to +follow output as it comes in. + +@findex recompile + To rerun the last compilation with the same command, type @kbd{M-x +recompile}. This automatically reuses the compilation command from +the last invocation of @kbd{M-x compile}. It also reuses the +@samp{*compilation*} buffer and starts the compilation in its default +directory, which is the directory in which the previous compilation +was started. + + When the compiler process terminates, for whatever reason, the mode +line of the @samp{*compilation*} buffer changes to say @samp{exit} +(followed by the exit code, @samp{[0]} for a normal exit), or +@samp{signal} (if a signal terminated the process), instead of +@samp{run}. + +@findex kill-compilation + Starting a new compilation also kills any compilation already +running in @samp{*compilation*}, as the buffer can only handle one +compilation at any time. However, @kbd{M-x compile} asks for +confirmation before actually killing a compilation that is running. +You can also kill the compilation process with @kbd{M-x +kill-compilation}. + + If you want to run two compilations at once, you should start the +first one, then rename the @samp{*compilation*} buffer (perhaps using +@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other +compilation. That will create a new @samp{*compilation*} buffer. + + Emacs does not expect a compiler process to launch asynchronous +subprocesses; if it does, and they keep running after the main +compiler process has terminated, Emacs may kill them or their output +may not arrive in Emacs. To avoid this problem, make the main process +wait for its subprocesses to finish. In a shell script, you can do this +using @samp{$!} and @samp{wait}, like this: + +@example +(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} +echo first message +wait $pid # @r{Wait for subprocess} +@end example + + If the background process does not output to the compilation buffer, +so you only need to prevent it from being killed when the main +compilation process terminates, this is sufficient: + +@example +nohup @var{command}; sleep 1 +@end example + +@vindex compilation-environment + You can control the environment passed to the compilation command +with the variable @code{compilation-environment}. Its value is a list +of environment variable settings; each element should be a string of +the form @code{"@var{envvarname}=@var{value}"}. These environment +variable settings override the usual ones. + +@node Compilation Mode +@section Compilation Mode + +@cindex Compilation mode +@cindex mode, Compilation + The @samp{*compilation*} buffer uses a special major mode, +Compilation mode, whose main feature is to provide a convenient way to +visit the source line corresponding to an error message. These +commands are also available in other special buffers that list +locations in files, including those made by @kbd{M-x grep} and +@kbd{M-x occur}. + +@table @kbd +@item M-g M-n +@itemx M-g n +@itemx C-x ` +Visit the locus of the next error message or match. +@item M-g M-p +@itemx M-g p +Visit the locus of the previous error message or 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-2 +Visit the locus of the error message that you click on. +@item M-n +Find and highlight the locus of the next error message, without +selecting the source buffer. +@item M-p +Find and highlight the locus of the previous error message, without +selecting the source buffer. +@item M-@} +Move point to the next error for a different file than the current +one. +@item M-@{ +Move point to the previous error for a different file than the current +one. +@item C-c C-f +Toggle Next Error Follow minor mode, which makes cursor motion in the +compilation buffer produce automatic source display. +@end table + +@findex compile-goto-error + You can visit the source for any particular error message by moving +point in the @samp{*compilation*} buffer to that error message and +typing @key{RET} (@code{compile-goto-error}). Alternatively, you can +click @kbd{Mouse-2} on the error message; you need not switch to the +@samp{*compilation*} buffer first. + +@kindex M-g M-n +@kindex M-g n +@kindex C-x ` +@findex next-error +@vindex next-error-highlight + To parse the compiler error messages sequentially, type @kbd{C-x `} +(@code{next-error}). The character following the @kbd{C-x} is the +backquote or ``grave accent,'' not the single-quote. This command is +available in all buffers, not just in @samp{*compilation*}; it +displays the next error message at the top of one window and source +location of the error in another window. It also temporarily +highlights the relevant source line, for a period controlled by the +variable @code{next-error-highlight}. + + The first time @w{@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 error +message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}} +commands advance from there. When @w{@kbd{C-x `}} gets to the end of the +buffer and finds no more error messages to visit, it fails and signals +an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of +the compilation buffer, and goes to the first error's location. + +@vindex compilation-skip-threshold + By default, @w{@kbd{C-x `}} skips less important messages. The variable +@code{compilation-skip-threshold} controls this. If its value is 2, +@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less +than warning, and 0 doesn't skip any messages. The default is 1. + + When the window has a left fringe, an arrow in the fringe points to +the current message in the compilation buffer. The variable +@code{compilation-context-lines} controls the number of lines of +leading context to display before the current message. Going to an +error message location scrolls the @samp{*compilation*} buffer to put +the message that far down from the top. The value @code{nil} is +special: if there's a left fringe, the window doesn't scroll at all +if the message is already visible. If there is no left fringe, +@code{nil} means display the message at the top of the window. + + If you're not in the compilation buffer when you run +@code{next-error}, Emacs will look for a buffer that contains error +messages. First, it looks for one displayed in the selected frame, +then for one that previously had @code{next-error} called on it, and +then at the current buffer. Finally, Emacs looks at all the remaining +buffers. @code{next-error} signals an error if it can't find any such +buffer. + +@vindex compilation-error-regexp-alist +@vindex grep-regexp-alist + To parse messages from the compiler, Compilation mode uses the +variable @code{compilation-error-regexp-alist} which lists various +formats of error messages and tells Emacs how to extract the source file +and the line number from the text of a message. If your compiler isn't +supported, you can tailor Compilation mode to it by adding elements to +that list. A similar variable @code{grep-regexp-alist} tells Emacs how +to parse output of a @code{grep} command. + +@findex compilation-next-error +@findex compilation-previous-error +@findex compilation-next-file +@findex compilation-previous-file + Compilation mode also redefines the keys @key{SPC} and @key{DEL} to +scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) +and @kbd{M-p} (@code{compilation-previous-error}) to move to the next +or previous error message. You can also use @kbd{M-@{} +(@code{compilation-next-file} and @kbd{M-@}} +(@code{compilation-previous-file}) to move up or down to an error +message for a different source file. + +@cindex Next Error Follow mode +@findex next-error-follow-minor-mode + You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In +this minor mode, ordinary cursor motion in the compilation buffer +automatically updates the source buffer. For instance, moving the +cursor to the next error message causes the location of that error to +be displayed immediately. + + The features of Compilation mode are also available in a minor mode +called Compilation Minor mode. This lets you parse error messages in +any buffer, not just a normal compilation output buffer. Type @kbd{M-x +compilation-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 contents +are in a format that it understands. In an Rlogin buffer (@pxref{Remote +Host}), Compilation minor mode automatically accesses remote source +files by FTP (@pxref{File Names}). + +@node Compilation Shell +@section Subshells for Compilation + + Emacs uses a shell to run the compilation command, but specifies the +option for a noninteractive shell. This means, in particular, that +the shell should start with no prompt. If you find your usual shell +prompt making an unsightly appearance in the @samp{*compilation*} +buffer, it means you have made a mistake in your shell's init file by +setting the prompt unconditionally. (This init file's name may be +@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or +various other things, depending on the shell you use.) The shell init +file should set the prompt only if there already is a prompt. Here's +how to do it in bash: + +@example +if [ "$@{PS1+set@}" = set ] +then PS1=@dots{} +fi +@end example + +@noindent +And here's how to do it in csh: + +@example +if ($?prompt) set prompt = @dots{} +@end example + + There may well be other things that your shell's init file +ought to do only for an interactive shell. You can use the same +method to conditionalize them. + + The MS-DOS ``operating system'' does not support asynchronous +subprocesses; to work around this lack, @kbd{M-x compile} runs the +compilation command synchronously on MS-DOS. As a consequence, you must +wait until the command finishes before you can do anything else in +Emacs. +@iftex +@inforef{MS-DOS,,emacs-xtra}. +@end iftex +@ifnottex +@xref{MS-DOS}. +@end ifnottex + +@node Grep Searching +@section Searching with Grep under Emacs + + Just as you can run a compiler from Emacs and then visit the lines +with compilation errors, you can also run @code{grep} and then visit +the lines on which matches were found. This works by treating the +matches reported by @code{grep} as if they were ``errors.'' The +buffer of matches uses Grep mode, which is a variant of Compilation +mode (@pxref{Compilation Mode}). + +@table @kbd +@item M-x grep +@item M-x lgrep +Run @code{grep} asynchronously under Emacs, with matching lines +listed in the buffer named @samp{*grep*}. +@item M-x grep-find +@itemx M-x find-grep +@itemx M-x rgrep +Run @code{grep} via @code{find}, with user-specified arguments, and +collect output in the buffer named @samp{*grep*}. +@item M-x kill-grep +Kill the running @code{grep} subprocess. +@end table + +@findex grep + To run @code{grep}, type @kbd{M-x grep}, then enter a command line +that specifies 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. If you +specify a prefix argument for @kbd{M-x grep}, it finds the tag +(@pxref{Tags}) in the buffer around point, and puts that into the +default @code{grep} command. + + Your command need not simply run @code{grep}; you can use any shell +command that produces output in the same format. For instance, you +can chain @code{grep} commands, like this: + +@example +grep -nH -e foo *.el | grep bar | grep toto +@end example + + The output from @code{grep} goes in the @samp{*grep*} buffer. You +can find the corresponding lines in the original files using @w{@kbd{C-x +`}}, @key{RET}, and so forth, just like compilation errors. + + Some grep programs accept a @samp{--color} option to output special +markers around matches for the purpose of highlighting. You can make +use of this feature by setting @code{grep-highlight-matches} to +@code{t}. When displaying a match in the source buffer, the exact +match will be highlighted, instead of the entire source line. + +@findex grep-find +@findex find-grep + The command @kbd{M-x grep-find} (also available as @kbd{M-x +find-grep}) is similar to @kbd{M-x grep}, but it supplies a different +initial default for the command---one that runs both @code{find} and +@code{grep}, so as to search every file in a directory tree. See also +the @code{find-grep-dired} command, in @ref{Dired and Find}. + +@findex lgrep +@findex rgrep + The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} +(recursive grep) are more user-friendly versions of @code{grep} and +@code{grep-find}, which prompt separately for the regular expression +to match, the files to search, and the base directory for the search. +Case sensitivity of the search is controlled by the +current value of @code{case-fold-search}. + +These commands build the shell commands based on the variables +@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} +(for @code{rgrep}). + +The files to search can use aliases defined in the variable +@code{grep-files-aliases}. + +Subdirectories listed in the variable +@code{grep-find-ignored-directories} such as those typically used by +various version control systems, like CVS and arch, are automatically +skipped by @code{rgrep}. + +@node Flymake +@section Finding Syntax Errors On The Fly +@cindex checking syntax + + Flymake mode is a minor mode that performs on-the-fly syntax +checking for many programming and markup languages, including C, C++, +Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell +mode, which performs spell checking for ordinary human languages in a +similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode +runs an appropriate syntax checking tool in the background, using a +temporary copy of the buffer. It then parses the error and warning +messages, and highlights the erroneous lines in the buffer. The +syntax checking tool used depends on the language; for example, for +C/C++ files this is usually the C compiler. Flymake can also use +build tools such as @code{make} for checking complicated projects. + + To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move +to the errors spotted by Flymake mode with @kbd{M-x +flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To +display any error messages associated with the current line, use +@kbd{M-x flymake-display-err-menu-for-current-line}. + + For more details about using Flymake, see @ref{Top, Flymake, +Flymake, flymake, The Flymake Manual}. + +@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 to +various symbolic debuggers from within Emacs. We recommend the +debugger GDB, which is free software, but GUD can also run DBX, SDB or +XDB. GUD can also serve as an interface to Perl's debugging mode, the +Python debugger PDB, and to JDB, the Java Debugger. +@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference +Manual}, for information on debugging Emacs Lisp programs. + +@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. +* GDB Graphical Interface:: An enhanced mode that uses GDB features to + implement a graphical debugging environment through + Emacs. +@end menu + +@node Starting GUD +@subsection Starting GUD + + There are several commands for starting a debugger, each corresponding +to a particular debugger program. + +@table @kbd +@item M-x gdb @key{RET} @var{file} @key{RET} +@findex gdb +Run GDB as a subprocess of Emacs. By default, this uses an IDE-like +graphical interface; see @ref{GDB Graphical Interface}. Only GDB +works with the graphical interface. + +@item M-x dbx @key{RET} @var{file} @key{RET} +@findex dbx +Run DBX as a subprocess of Emacs. Since Emacs does not implement a +graphical interface for DBX, communication with DBX works by typing +commands in the GUD interaction buffer. The same is true for all +the other supported debuggers. + +@item M-x xdb @key{RET} @var{file} @key{RET} +@findex xdb +@vindex gud-xdb-directories +Similar, but run XDB. Use the variable +@code{gud-xdb-directories} to specify directories to search for source +files. + +@item M-x sdb @key{RET} @var{file} @key{RET} +@findex sdb +Similar, but run SDB. + + Some versions of SDB do not mention source file names in their +messages. 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 one +of the functions, you get a message saying @samp{The sdb support +requires a valid tags table to work}. If this happens, generate a valid +tags table in the working directory and try again. + +@item M-x perldb @key{RET} @var{file} @key{RET} +@findex perldb +Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. + +@item M-x jdb @key{RET} @var{file} @key{RET} +@findex jdb +Run the Java debugger to debug @var{file}. + +@item M-x pdb @key{RET} @var{file} @key{RET} +@findex pdb +Run the Python debugger to debug @var{file}. +@end table + + Each of these commands takes one argument: a command line to invoke +the debugger. In the simplest case, specify just the name of the +executable file you want to debug. You may also use options that the +debugger supports. However, shell wildcards and variables are not +allowed. GUD assumes that the first argument not starting with a +@samp{-} is the executable file name. + +Tramp provides a facility to debug programs on remote hosts. +@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}. +@c Running a debugger on a remote host + +@node Debugger Operation +@subsection Debugger Operation + +@cindex fringes, and current execution line in GUD + Generally when you run a debugger with GUD, the debugger uses an Emacs +buffer for its ordinary input and output. This is called the GUD +buffer. Input and output from the program you are debugging also use +this buffer. We call this @dfn{text command mode}. The GDB Graphical +Interface can use further buffers (@pxref{GDB Graphical Interface}). + + The debugger displays the source files of the program by visiting +them in Emacs buffers. An arrow in the left fringe indicates the +current execution line.@footnote{On a text-only terminal, the arrow +appears as @samp{=>} and overlays the first two text columns.} Moving +point in this buffer does not move the arrow. The arrow is not part +of the file's text; it appears only on the screen. + + You can start editing these source files at any time in the buffers +that display them. If you do modify a source file, keep in mind that +inserting or deleting lines will throw off the arrow's positioning; +GUD has no way of figuring out which line corresponded before your +changes to the line number in a debugger message. Also, you'll +typically have to recompile and restart the program for your changes +to be reflected in the debugger's tables. + +@cindex tooltips with GUD +@vindex tooltip-gud-modes +@vindex gud-tooltip-mode +@vindex gud-tooltip-echo-area + The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. +You activate this feature by turning on the minor mode +@code{gud-tooltip-mode}. Then you can display a variable's value in a +tooltip simply by pointing at it with the mouse. This operates in the +GUD buffer and in source buffers with major modes in the list +@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} +is non-@code{nil} then the variable's value is displayed in the echo +area. When debugging a C program using the GDB Graphical Interface, you +can also display macro definitions associated with an identifier when +the program is not executing. + + GUD tooltips are disabled when you use GDB in text command mode +(@pxref{GDB Graphical Interface}), because displaying an expression's +value in GDB can sometimes expand a macro and result in a side effect +that interferes with the program's operation. The GDB graphical +interface supports GUD tooltips and assures they will not cause side +effects. + +@node Commands of GUD +@subsection Commands of GUD + + The GUD interaction buffer uses a variant of Shell mode, so the +Emacs commands of Shell mode are available (@pxref{Shell Mode}). All +the usual commands for your debugger are available, and you can use +the Shell mode history commands to repeat them. If you wish, you can +control your debugger process entirely through this buffer. + + GUD mode also provides commands for setting and clearing +breakpoints, for selecting stack frames, and for stepping through the +program. These commands are available both in the GUD buffer and +globally, but with different key bindings. It also has its own tool +bar from which you can invoke the more common commands by clicking on +the appropriate icon. This is particularly useful for repetitive +commands like @code{gud-next} and @code{gud-step}, and allows you to +keep the GUD buffer hidden. + + The breakpoint commands are normally used in source file buffers, +because that is the easiest 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 SPC +Set 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 keys +starting with @kbd{C-c} are available only in the GUD interaction +buffer. The key bindings that start with @kbd{C-x C-a} are available +in the GUD interaction buffer and also in source files. Some of these +commands are not available to all the supported debuggers. + +@table @kbd +@item C-c C-l +@kindex C-c C-l @r{(GUD)} +@itemx C-x C-a C-l +@findex gud-refresh +Display in another window the last line referred to in the GUD +buffer (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-step +Execute a single line of code (@code{gud-step}). If the line contains +a 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-next +Execute a single line of code, stepping across entire function calls +at 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-stepi +Execute a single machine instruction (@code{gud-stepi}). + +@item C-c C-p +@kindex C-c C-p @r{(GUD)} +@itemx C-x C-a C-p +@findex gud-print +Evaluate the expression at point (@code{gud-print}). If Emacs +does not print the exact expression that you want, mark it as a region +first. + +@need 3000 +@item C-c C-r +@kindex C-c C-r @r{(GUD)} +@itemx C-x C-a C-r +@findex gud-cont +Continue execution without specifying any stopping point. The program +will run until it hits a breakpoint, terminates, or gets a signal that +the 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-remove +Delete the breakpoint(s) on the current source line, if any +(@code{gud-remove}). If you use this command in the GUD interaction +buffer, 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-tbreak +Set a temporary breakpoint on the current source line, if any +(@code{gud-tbreak}). If you use this command in the GUD interaction +buffer, it applies to the line where the program last stopped. + +@item C-c < +@kindex C-c < @r{(GUD)} +@itemx C-x C-a < +@findex gud-up +Select the next enclosing stack frame (@code{gud-up}). This is +equivalent to the GDB command @samp{up}. + +@item C-c > +@kindex C-c > @r{(GUD)} +@itemx C-x C-a > +@findex gud-down +Select the next inner stack frame (@code{gud-down}). This is +equivalent to the GDB command @samp{down}. + +@item C-c C-u +@kindex C-c C-u @r{(GUD)} +@itemx C-x C-a C-u +@findex gud-until +Continue execution to the current line (@code{gud-until}). The +program will run until it hits a breakpoint, terminates, gets a signal +that the debugger is checking for, or reaches the line on which the +cursor currently sits. + +@item C-c C-f +@kindex C-c C-f @r{(GUD)} +@itemx C-x C-a C-f +@findex gud-finish +Run the program until the selected stack frame returns or +stops for some other reason (@code{gud-finish}). +@end table + + If you are using GDB, these additional key bindings are available: + +@table @kbd +@item C-x C-a C-j +@kindex C-x C-a C-j @r{(GUD)} +@findex gud-jump +Only useful in a source buffer, @code{gud-jump} transfers the +program's execution point to the current line. In other words, the +next line that the program executes will be the one where you gave the +command. If the new execution line is in a different function from +the previously one, GDB prompts for confirmation since the results may +be bizarre. See the GDB manual entry regarding @code{jump} for +details. + +@item @key{TAB} +@kindex TAB @r{(GUD)} +@findex gud-gdb-complete-command +With GDB, complete a symbol name (@code{gud-gdb-complete-command}). +This key is available only in the GUD interaction buffer. +@end table + + These commands interpret a numeric argument as a repeat count, when +that makes sense. + + Because @key{TAB} serves as a completion command, you can't use it to +enter 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 you +are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; +@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can +use these hooks to define custom key bindings for the debugger +interaction buffer. @xref{Hooks}. + + Here is a convenient way to define a command that sends a particular +command string to the debugger, and set up a key binding for it in the +debugger 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 documentation +string @var{docstring}. You can then use the command @var{function} in any +buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds +the 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 %f +The name of the current source file. If the current buffer is the GUD +buffer, then the ``current source file'' is the file that the program +stopped in. + +@item %l +The number of the current source line. If the current buffer is the GUD +buffer, then the ``current source line'' is the line that the program +stopped in. + +@item %e +In transient-mark-mode the text in the region, if it is active. +Otherwise the text of the C lvalue or function-call expression at or +adjacent to point. + +@item %a +The text of the hexadecimal address at or adjacent to point. + +@item %p +The numeric argument of the called function, as a decimal number. If +the command is used without a numeric argument, @samp{%p} stands for the +empty string. + +If you don't use @samp{%p} in the command string, the command you define +ignores any numeric argument. + +@item %d +The name of the directory of the current source file. + +@item %c +Fully qualified class name derived from the expression surrounding point +(jdb only). +@end table + +@node GDB Graphical Interface +@subsection GDB Graphical Interface + + By default, the command @code{gdb} starts GDB using a graphical +interface, using Emacs windows for display program state information. +In effect, this makes Emacs into an IDE (interactive development +environment). With it, you do not need to use textual GDB commands; +you can control the debugging session with the mouse. For example, +you can click in the fringe of a source buffer to set a breakpoint +there, or on a stack frame in the stack buffer to select that frame. + + This mode requires telling GDB that its ``screen size'' is +unlimited, so it sets the height and width accordingly. For correct +operation you must not change these values during the GDB session. + +@vindex gud-gdb-command-name +@findex gdba + You can also run GDB in text command mode, like other debuggers. To +do this, replace the GDB @code{"--annotate=3"} option with +@code{"--fullname"} either in the minibuffer for the current Emacs +session, or the custom variable @code{gud-gdb-command-name} for all +future sessions. You need to use text command mode to debug multiple +programs within one Emacs session. If you have customized +@code{gud-gdb-command-name} in this way, you can use @kbd{M-x gdba} to +invoke GDB in graphical mode. Moreover, this command succeeds where +@kbd{M-x gdb} fails, such as when your @file{.gdbinit} file contains +executable GDB commands. + +@menu +* GDB-UI Layout:: Control the number of displayed buffers. +* Source Buffers:: Use the mouse in the fringe/margin to + control your program. +* Breakpoints Buffer:: A breakpoint control panel. +* Stack Buffer:: Select a frame from the call stack. +* Other GDB-UI Buffers:: Input/output, locals, registers, + assembler, threads and memory buffers. +* Watch Expressions:: Monitor variable values in the speedbar. +@end menu + +@node GDB-UI Layout +@subsubsection GDB User Interface Layout +@cindex GDB User Interface layout + +@vindex gdb-many-windows + If the variable @code{gdb-many-windows} is @code{nil} (the default +value) then @kbd{M-x gdb} normally displays only the GUD buffer. +However, if the variable @code{gdb-show-main} is also non-@code{nil}, +it starts with two windows: one displaying the GUD buffer, and the +other showing the source for the @code{main} function of the program +you are debugging. + + If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} +displays the following frame layout: + +@smallexample +@group ++--------------------------------+--------------------------------+ +| GUD buffer (I/O of GDB) | Locals buffer | +|--------------------------------+--------------------------------+ +| Primary Source buffer | I/O buffer for debugged pgm | +|--------------------------------+--------------------------------+ +| Stack buffer | Breakpoints buffer | ++--------------------------------+--------------------------------+ +@end group +@end smallexample + + However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O +buffer does not appear and the primary source buffer occupies the full +width of the frame. + +@findex gdb-restore-windows + If you change the window layout, for example, while editing and +re-compiling your program, then you can restore this standard window +layout with the command @code{gdb-restore-windows}. + +@findex gdb-many-windows + To switch between this standard layout and a simple layout +containing just the GUD buffer and a source file, type @kbd{M-x +gdb-many-windows}. + + You may also specify additional GDB-related buffers to display, +either in the same frame or a different one. Select the buffers you +want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} +sub-menus. If the menu-bar is unavailable, type @code{M-x +gdb-display-@var{buffertype}-buffer} or @code{M-x +gdb-frame-@var{buffertype}-buffer} respectively, where +@var{buffertype} is the relevant buffer type, such as +@samp{breakpoints}. Most of these buffers are read-only, and typing +@kbd{q} in them kills them. + + When you finish debugging, kill the GUD buffer with @kbd{C-x k}, +which will also kill all the buffers associated with the session. +However you need not do this if, after editing and re-compiling your +source code within Emacs, you wish continue debugging. When you +restart execution, GDB will automatically find your new executable. +Keeping the GUD buffer has the advantage of keeping the shell history +as well as GDB's breakpoints. You do need to check that the +breakpoints in recently edited source files are still in the right +places. + +@node Source Buffers +@subsubsection Source Buffers +@cindex GDB commands in Fringe + +@c @findex gdb-mouse-set-clear-breakpoint +@c @findex gdb-mouse-toggle-breakpoint +Many GDB commands can be entered using keybindings or the tool bar but +sometimes it is quicker to use the fringe. These commands either +manipulate breakpoints or control program execution. When there is no +fringe, you can use the margin but this is only present when the +source file already has a breakpoint. + +You can click @kbd{Mouse-1} in the fringe or display margin of a +source buffer to set a breakpoint there and, on a graphical display, a +red bullet will appear on that line. If a breakpoint already exists +on that line, the same click will remove it. You can also enable or +disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. + +A solid arrow in the left fringe of a source buffer indicates the line +of the innermost frame where the debugged program has stopped. A +hollow arrow indicates the current execution line of higher level +frames. + +If you drag the arrow in the fringe with @kbd{Mouse-1} +(@code{gdb-mouse-until}), execution will continue to the line where +you release the button, provided it is still in the same frame. +Alternatively, you can click @kbd{Mouse-3} at some point in the fringe +of this buffer and execution will advance to there. A similar command +(@code{gdb-mouse-jump}) allows you to jump to a source line without +executing the intermediate lines by clicking @kbd{C-Mouse-3}. This +command allows you to go backwards which can be useful for running +through code that has already executed, in order to examine its +execution in more detail. + +@table @kbd +@item Mouse-1 +Set or clear a breakpoint. + +@item C-Mouse-1 +Enable or disable a breakpoint. + +@item Mouse-3 +Continue execution to here. + +@item C-Mouse-3 +Jump to here. +@end table + +If the variable @code{gdb-find-source-frame} is non-@code{nil} and +execution stops in a frame for which there is no source code e.g after +an interrupt, then Emacs finds and displays the first frame further up +stack for which there is source. If it is @code{nil} then the source +buffer continues to display the last frame which maybe more useful, +for example, when re-setting a breakpoint. + +@node Breakpoints Buffer +@subsubsection Breakpoints Buffer + + The breakpoints buffer shows the existing breakpoints, watchpoints and +catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has +these special commands, which mostly apply to the @dfn{current +breakpoint}, the breakpoint which point is on. + +@table @kbd +@item @key{SPC} +@kindex SPC @r{(GDB breakpoints buffer)} +@findex gdb-toggle-breakpoint +Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). +On a graphical display, this changes the color of a bullet in the +margin of a source buffer at the relevant line. This is red when +the breakpoint is enabled and grey when it is disabled. Text-only +terminals correspondingly display a @samp{B} or @samp{b}. + +@item D +@kindex D @r{(GDB breakpoints buffer)} +@findex gdb-delete-breakpoint +Delete the current breakpoint (@code{gdb-delete-breakpoint}). + +@item @key{RET} +@kindex RET @r{(GDB breakpoints buffer)} +@findex gdb-goto-breakpoint +Visit the source line for the current breakpoint +(@code{gdb-goto-breakpoint}). + +@item Mouse-2 +@kindex Mouse-2 @r{(GDB breakpoints buffer)} +Visit the source line for the breakpoint you click on. +@end table + +@node Stack Buffer +@subsubsection Stack Buffer + + The stack buffer displays a @dfn{call stack}, with one line for each +of the nested subroutine calls (@dfn{stack frames}) now active in the +program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. + +@findex gdb-frames-select +An arrow in the fringe points to the selected frame or, if the fringe is +not present, the number of the selected frame is displayed in reverse +contrast. To select a frame in GDB, move point in the stack buffer to +that stack frame and type @key{RET} (@code{gdb-frames-select}), or click +@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, +selecting a stack frame updates it to display the local variables of the +new frame. + +@node Other GDB-UI Buffers +@subsubsection Other Buffers + +@table @asis +@item Input/Output Buffer +@vindex gdb-use-separate-io-buffer +If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, +the program being debugged takes its input and displays its output +here. Otherwise it uses the GUD buffer for that. To toggle whether +GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. +This takes effect when you next restart the program you are debugging. + +The history and replay commands from Shell mode are available here, +as are the commands to send signals to the debugged program. +@xref{Shell Mode}. + +@item Locals Buffer +The locals buffer displays the values of local variables of the +current frame for simple data types (@pxref{Frame Info, Frame Info, +Information on a frame, gdb, The GNU debugger}). Press @key{RET} or +click @kbd{Mouse-2} on the value if you want to edit it. + +Arrays and structures display their type only. With GDB 6.4 or later, +move point to their name and press @key{RET}, or alternatively click +@kbd{Mouse-2} there, to examine their values. With earlier versions +of GDB, use @kbd{Mouse-2} or @key{RET} on the type description +(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. + +@item Registers Buffer +@findex toggle-gdb-all-registers +The registers buffer displays the values held by the registers +(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or +click @kbd{Mouse-2} on a register if you want to edit its value. +With GDB 6.4 or later, recently changed register values display with +@code{font-lock-warning-face}. With earlier versions of GDB, you can +press @key{SPC} to toggle the display of floating point registers +(@code{toggle-gdb-all-registers}). + +@item Assembler Buffer +The assembler buffer displays the current frame as machine code. An +arrow points to the current instruction, and you can set and remove +breakpoints as in a source buffer. Breakpoint icons also appear in +the fringe or margin. + +@item Threads Buffer +@findex gdb-threads-select +The threads buffer displays a summary of all threads currently in your +program (@pxref{Threads, Threads, Debugging programs with multiple +threads, gdb, The GNU debugger}). Move point to any thread in the +list and press @key{RET} to select it (@code{gdb-threads-select}) and +display the associated source in the primary source buffer. +Alternatively, click @kbd{Mouse-2} on a thread to select it. If the +locals buffer is visible, its contents update to display the variables +that are local in the new thread. + +@item Memory Buffer +The memory buffer lets you examine sections of program memory +(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). +Click @kbd{Mouse-1} on the appropriate part of the header line to +change the starting address or number of data items that the buffer +displays. Click @kbd{Mouse-3} on the header line to select the +display format or unit size for these data items. +@end table + +@node Watch Expressions +@subsubsection Watch Expressions +@cindex Watching expressions in GDB + +@findex gud-watch +@kindex C-x C-a C-w @r{(GUD)} + If you want to see how a variable changes each time your program +stops, move point into the variable name and click on the watch icon +in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you +specify a prefix argument, you can enter the variable name in the +minibuffer. + + Each watch expression is displayed in the speedbar. Complex data +types, such as arrays, structures and unions are represented in a tree +format. Leaves and simple data types show the name of the expression +and its value and, when the speedbar frame is selected, display the +type as a tooltip. Higher levels show the name, type and address +value for pointers and just the name and type otherwise. Root expressions +also display the frame address as a tooltip to help identify the frame +in which they were defined. + + To expand or contract a complex data type, click @kbd{Mouse-2} or +press @key{SPC} on the tag to the left of the expression. Emacs asks +for confirmation before expanding the expression if its number of +immediate children exceeds the value of the variable +@code{gdb-max-children}. + +@kindex D @r{(GDB speedbar)} +@findex gdb-var-delete + To delete a complex watch expression, move point to the root +expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). + +@kindex RET @r{(GDB speedbar)} +@findex gdb-edit-value + To edit a variable with a simple data type, or a simple element of a +complex data type, move point there in the speedbar and type @key{RET} +(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to +edit it. Either way, this reads the new value using the minibuffer. + +@vindex gdb-show-changed-values + If you set the variable @code{gdb-show-changed-values} to +non-@code{nil} (the default value), Emacs uses +@code{font-lock-warning-face} to highlight values that have recently +changed and @code{shadow} face to make variables which have gone out of +scope less noticeable. When a variable goes out of scope you can't +edit its value. + +@vindex gdb-use-colon-colon-notation + If the variable @code{gdb-use-colon-colon-notation} is +non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} +format. This allows the user to display watch expressions which share +the same variable name. The default value is @code{nil}. + +@vindex gdb-speedbar-auto-raise +To automatically raise the speedbar every time the display of watch +expressions updates, set @code{gdb-speedbar-auto-raise} to +non-@code{nil}. This can be useful if you are debugging with a full +screen Emacs frame. + +@node Executing Lisp +@section Executing Lisp Expressions + + Emacs has several different major modes for Lisp and Scheme. They are +the same in terms of editing commands, but differ in the commands for +executing Lisp expressions. Each mode has its own purpose. + +@table @asis +@item Emacs-Lisp mode +The 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 mode +The mode for an interactive session with Emacs Lisp. It defines +@kbd{C-j} to evaluate the sexp before point and insert its value in the +buffer. @xref{Lisp Interaction}. +@item Lisp mode +The mode for editing source files of programs that run in Lisps other +than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun +to an inferior Lisp process. @xref{External Lisp}. +@item Inferior Lisp mode +The 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 mode +Like Lisp mode but for Scheme programs. +@item Inferior Scheme mode +The mode for an interactive session with an inferior Scheme process. +@end table + + Most editing commands for working with Lisp programs are in fact +available 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 names +conventionally end in @file{.el}. This ending tells Emacs to edit them in +Emacs-Lisp mode (@pxref{Executing Lisp}). + +@cindex byte code + Emacs Lisp code can be compiled into byte-code, which loads faster, +takes up less space, and executes faster. @xref{Byte Compilation,, +Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By +convention, the compiled code for a library goes in a separate file +whose name ends in @samp{.elc}. Thus, the compiled code for +@file{foo.el} goes in @file{foo.elc}. + +@findex load-file + To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This +command reads a file name using the minibuffer and then executes the +contents of that file as Lisp code. It is not necessary to visit the +file first; in any case, this command reads the file as found on disk, +not text in an Emacs buffer. + +@findex load +@findex load-library + Once a file of Lisp code is installed in the Emacs Lisp library +directories, users can load it using @kbd{M-x load-library}. Programs +can load it by calling @code{load}, a more primitive function that is +similar but accepts some additional arguments. + + @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it +searches a sequence of directories and tries three file names in each +directory. 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 convention +the result of compiling @file{@var{lib}.el}; it is better to load the +compiled 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 issues a warning, because it's likely +that somebody made changes to the @file{.el} file and forgot to +recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is +because people often leave unfinished edits the source file, and don't +recompile it until they think it is ready to use. + + Because the argument to @code{load-library} is usually not in itself +a valid file name, file name completion is not available. Indeed, when +using this command, you usually do not know exactly what file name +will be used. + +@vindex load-path + The sequence of directories searched by @kbd{M-x load-library} is +specified by the variable @code{load-path}, a list of strings that are +directory names. The default value of the list contains the directories where +the Lisp code for Emacs itself is stored. If you have libraries of +your own, put them in a single directory and add that directory +to @code{load-path}. @code{nil} in this list stands for the current default +directory, but it is probably not a good idea to put @code{nil} in the +list. 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, because +the commands defined in the library are set up to @dfn{autoload} that +library. Trying to run any of those commands calls @code{load} to load +the library; this replaces the autoload definitions with the real ones +from the library. + +@vindex load-dangerous-libraries +@cindex Lisp files byte-compiled by XEmacs + By default, Emacs refuses to load compiled Lisp files which were +compiled with XEmacs, a modified versions of Emacs---they can cause +Emacs to crash. Set the variable @code{load-dangerous-libraries} to +@code{t} if you want to try loading them. + +@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 in +Emacs-Lisp mode; this happens automatically for file names ending in +@file{.el}. By contrast, Lisp mode itself is used for editing Lisp +programs intended for other Lisp systems. To switch to Emacs-Lisp mode +explicitly, use the command @kbd{M-x emacs-lisp-mode}. + + For testing of Lisp programs to run in Emacs, it is often useful to +evaluate part of the program as it is found in the Emacs buffer. For +example, after changing the text of a Lisp function definition, +evaluating the definition installs the change for future calls to the +function. Evaluation of Lisp expressions is also useful in any kind of +editing, for invoking noninteractive functions (functions that are +not commands). + +@table @kbd +@item M-: +Read a single Lisp expression in the minibuffer, evaluate it, and print +the value in the echo area (@code{eval-expression}). +@item C-x C-e +Evaluate the Lisp expression before point, and print the value in the +echo area (@code{eval-last-sexp}). +@item C-M-x +Evaluate the defun containing or after point, and print the value in +the echo area (@code{eval-defun}). +@item M-x eval-region +Evaluate all the Lisp expressions in the region. +@item M-x eval-buffer +Evaluate all the Lisp expressions in the buffer. +@end table + +@ifinfo +@c This uses ``colon'' instead of a literal `:' because Info cannot +@c cope with a `:' in a menu +@kindex M-@key{colon} +@end ifinfo +@ifnotinfo +@kindex M-: +@end ifnotinfo +@findex eval-expression + @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating +a Lisp expression interactively. It reads the expression using the +minibuffer, so you can execute any expression on a buffer regardless of +what the buffer contains. When the expression is evaluated, the current +buffer is once again the buffer that was current when @kbd{M-:} was +typed. + +@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 point +as a Lisp expression and evaluates it. The value is printed in the echo +area. This command is convenient for installing in the Lisp environment +changes that you have just made in the text of a function definition. + + @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, +evaluating a @code{defvar} expression does nothing if the variable it +defines already has a value. But @kbd{C-M-x} unconditionally resets the +variable to the initial value specified in the @code{defvar} expression. +@code{defcustom} expressions are treated similarly. +This special feature is convenient for debugging Lisp programs. +Typing @kbd{C-M-x} on a @code{defface} expression reinitializes +the face according to the @code{defface} specification. + +@kindex C-x C-e +@findex eval-last-sexp + The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp +expression preceding point in the buffer, and displays the value in the +echo area. It is available in all major modes, not just Emacs-Lisp +mode. It does not treat @code{defvar} specially. + + When the result of an evaluation is an integer, you can type +@kbd{C-x C-e} a second time to display the value of the integer result +in additional formats (octal, hexadecimal, and character). + + If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it +inserts the value into the current buffer at point, rather than +displaying it in the echo area. The argument's value does not matter. +@kbd{C-M-x} with a numeric argument instruments the function +definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). + +@findex eval-region +@findex eval-buffer + The most general command for evaluating Lisp expressions from a buffer +is @code{eval-region}. @kbd{M-x eval-region} parses the text of the +region as one or more Lisp expressions, evaluating them one by one. +@kbd{M-x eval-buffer} is similar but evaluates the entire +buffer. This is a reasonable way to install the contents of a file of +Lisp code that you are ready to test. Later, as you find bugs and +change individual functions, use @kbd{C-M-x} on each function that you +change. This keeps the Lisp world in step with the source file. + +@vindex eval-expression-print-level +@vindex eval-expression-print-length +@vindex eval-expression-debug-on-error + The two customizable variables @code{eval-expression-print-level} and +@code{eval-expression-print-length} control the maximum depth and length +of lists to print in the result of the evaluation commands before +abbreviating them. @code{eval-expression-debug-on-error} controls +whether evaluation errors invoke the debugger when these commands are +used; its default is @code{t}. + +@node Lisp Interaction +@section Lisp Interaction Buffers + + The buffer @samp{*scratch*} which is selected when Emacs starts up is +provided for evaluating Lisp expressions interactively inside Emacs. + + The simplest way to use the @samp{*scratch*} buffer is to insert Lisp +expressions and type @kbd{C-j} after each expression. This command +reads the Lisp expression before point, evaluates it, and inserts the +value in printed representation before point. The result is a complete +typescript of the expressions you have evaluated and their values. + + The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which +is 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 when +it starts up, but that buffer is not useful for editing files since a +new buffer is made for every file that you visit. The Lisp interpreter +typescript is the most useful thing I can think of for the initial +buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current +buffer in Lisp Interaction mode. + +@findex ielm + An alternative way of evaluating Emacs Lisp expressions interactively +is to use Inferior Emacs-Lisp mode, which provides an interface rather +like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp +expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer +which uses this mode. For more information see that command's +documentation. + +@node External Lisp +@section Running an External Lisp + + Emacs has facilities for running programs in other Lisp systems. You can +run a Lisp process as an inferior of Emacs, and pass expressions to it to +be evaluated. You can also pass changed function definitions directly from +the Emacs buffers in which you edit the Lisp programs to the inferior Lisp +process. + +@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 runs +the program named @code{lisp}, the same program you would run by typing +@code{lisp} as a shell command, with both input and output going through +an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal +output'' from Lisp will go into the buffer, advancing point, and any +``terminal input'' for Lisp comes from text in the buffer. (You can +change 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 Lisp +mode, which combines the special characteristics of Lisp mode with most +of 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 Shell +mode. + +@findex lisp-mode + For the source files of programs to run in external Lisps, use Lisp +mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is +used automatically for files whose names end in @file{.l}, +@file{.lsp}, or @file{.lisp}. + +@kindex C-M-x @r{(Lisp mode)} +@findex lisp-eval-defun + When you edit a function in a Lisp program you are running, the easiest +way to send the changed definition to the inferior Lisp process is the key +@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 to +the Lisp process. (Emacs can send input to any inferior process regardless +of what buffer is current.) + + Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing +programs to be run in another Lisp system) and Emacs-Lisp mode (for +editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in +both modes it has the effect of installing the function definition +that point is in, but the way of doing so is different according to +where the relevant Lisp environment is found. + + +@ignore + arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed +@end ignore