annotate man/xemacs/building.texi @ 5922:4b055de36bb9 cygwin

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