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