1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
55 How Programs Do Loading
56 =======================
58 XEmacs Lisp has several interfaces for loading. For example,
59 `autoload' creates a placeholder object for a function in a file;
60 trying to call the autoloading function loads the file to get the
61 function's real definition (*note Autoload::). `require' loads a file
62 if it isn't already loaded (*note Named Features::). Ultimately, all
63 these facilities call the `load' function to do the work.
65 - Function: load filename &optional missing-ok nomessage nosuffix
66 This function finds and opens a file of Lisp code, evaluates all
67 the forms in it, and closes the file.
69 To find the file, `load' first looks for a file named
70 `FILENAME.elc', that is, for a file whose name is FILENAME with
71 `.elc' appended. If such a file exists, it is loaded. If there
72 is no file by that name, then `load' looks for a file named
73 `FILENAME.el'. If that file exists, it is loaded. Finally, if
74 neither of those names is found, `load' looks for a file named
75 FILENAME with nothing appended, and loads it if it exists. (The
76 `load' function is not clever about looking at FILENAME. In the
77 perverse case of a file named `foo.el.el', evaluation of `(load
78 "foo.el")' will indeed find it.)
80 If the optional argument NOSUFFIX is non-`nil', then the suffixes
81 `.elc' and `.el' are not tried. In this case, you must specify
82 the precise file name you want.
84 If FILENAME is a relative file name, such as `foo' or
85 `baz/foo.bar', `load' searches for the file using the variable
86 `load-path'. It appends FILENAME to each of the directories
87 listed in `load-path', and loads the first file it finds whose name
88 matches. The current default directory is tried only if it is
89 specified in `load-path', where `nil' stands for the default
90 directory. `load' tries all three possible suffixes in the first
91 directory in `load-path', then all three suffixes in the second
94 If you get a warning that `foo.elc' is older than `foo.el', it
95 means you should consider recompiling `foo.el'. *Note Byte
98 Messages like `Loading foo...' and `Loading foo...done' appear in
99 the echo area during loading unless NOMESSAGE is non-`nil'.
101 Any unhandled errors while loading a file terminate loading. If
102 the load was done for the sake of `autoload', any function
103 definitions made during the loading are undone.
105 If `load' can't find the file to load, then normally it signals the
106 error `file-error' (with `Cannot open load file FILENAME'). But
107 if MISSING-OK is non-`nil', then `load' just returns `nil'.
109 You can use the variable `load-read-function' to specify a function
110 for `load' to use instead of `read' for reading expressions. See
113 `load' returns `t' if the file loads successfully.
115 - User Option: load-path
116 The value of this variable is a list of directories to search when
117 loading files with `load'. Each element is a string (which must be
118 a directory name) or `nil' (which stands for the current working
119 directory). The value of `load-path' is initialized from the
120 environment variable `EMACSLOADPATH', if that exists; otherwise its
121 default value is specified in `emacs/src/paths.h' when XEmacs is
124 The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
125 (or `;', according to the operating system) separates directory
126 names, and `.' is used for the current default directory. Here is
127 an example of how to set your `EMACSLOADPATH' variable from a
130 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
132 Here is how to set it using `sh':
135 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
137 Here is an example of code you can place in a `.emacs' file to add
138 several directories to the front of your default `load-path':
141 (append (list nil "/user/bil/emacs"
146 In this example, the path searches the current working directory
147 first, followed then by the `/user/bil/emacs' directory, the
148 `/usr/local/lisplib' directory, and the `~/emacs' directory, which
149 are then followed by the standard directories for Lisp code.
151 The command line options `-l' or `-load' specify a Lisp library to
152 load as part of Emacs startup. Since this file might be in the
153 current directory, Emacs 18 temporarily adds the current directory
154 to the front of `load-path' so the file can be found there. Newer
155 Emacs versions also find such files in the current directory, but
156 without altering `load-path'.
158 Dumping Emacs uses a special value of `load-path'. If the value of
159 `load-path' at the end of dumping is unchanged (that is, still the
160 same special value), the dumped Emacs switches to the ordinary
161 `load-path' value when it starts up, as described above. But if
162 `load-path' has any other value at the end of dumping, that value
163 is used for execution of the dumped Emacs also.
165 Therefore, if you want to change `load-path' temporarily for
166 loading a few libraries in `site-init.el' or `site-load.el', you
167 should bind `load-path' locally with `let' around the calls to
170 - Function: locate-file filename path-list &optional suffixes mode
171 This function searches for a file in the same way that `load' does,
172 and returns the file found (if any). (In fact, `load' uses this
173 function to search through `load-path'.) It searches for FILENAME
174 through PATH-LIST, expanded by one of the optional SUFFIXES
175 (string of suffixes separated by `:'s), checking for access MODE
176 (0|1|2|4 = exists|executable|writable|readable), default readable.
178 `locate-file' keeps hash tables of the directories it searches
179 through, in order to speed things up. It tries valiantly to not
180 get confused in the face of a changing and unpredictable
181 environment, but can occasionally get tripped up. In this case,
182 you will have to call `locate-file-clear-hashing' to get it back
183 on track. See that function for details.
185 - Function: locate-file-clear-hashing path
186 This function clears the hash records for the specified list of
187 directories. `locate-file' uses a hashing scheme to speed lookup,
188 and will correctly track the following environmental changes:
190 * changes of any sort to the list of directories to be searched.
192 * addition and deletion of non-shadowing files (see below) from
193 the directories in the list.
195 * byte-compilation of a .el file into a .elc file.
197 `locate-file' will primarily get confused if you add a file that
198 shadows (i.e. has the same name as) another file further down in
199 the directory list. In this case, you must call
200 `locate-file-clear-hashing'.
202 - Variable: load-in-progress
203 This variable is non-`nil' if Emacs is in the process of loading a
204 file, and it is `nil' otherwise.
206 - Variable: load-read-function
207 This variable specifies an alternate expression-reading function
208 for `load' and `eval-region' to use instead of `read'. The
209 function should accept one argument, just as `read' does.
211 Normally, the variable's value is `nil', which means those
212 functions should use `read'.
214 - User Option: load-warn-when-source-newer
215 This variable specifies whether `load' should check whether the
216 source is newer than the binary. If this variable is true, then
217 when a `.elc' file is being loaded and the corresponding `.el' is
218 newer, a warning message will be printed. The default is `nil',
219 but it is bound to `t' during the initial loadup.
221 - User Option: load-warn-when-source-only
222 This variable specifies whether `load' should warn when loading a
223 `.el' file instead of an `.elc'. If this variable is true, then
224 when `load' is called with a filename without an extension, and
225 the `.elc' version doesn't exist but the `.el' version does, then
226 a message will be printed. If an explicit extension is passed to
227 `load', no warning will be printed. The default is `nil', but it
228 is bound to `t' during the initial loadup.
230 - User Option: load-ignore-elc-files
231 This variable specifies whether `load' should ignore `.elc' files
232 when a suffix is not given. This is normally used only to
233 bootstrap the `.elc' files when building XEmacs, when you use the
234 command `make all-elc'. (This forces the `.el' versions to be
235 loaded in the process of compiling those same files, so that
236 existing out-of-date `.elc' files do not make it mess things up.)
238 To learn how `load' is used to build XEmacs, see *Note Building
242 File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading
247 The "autoload" facility allows you to make a function or macro known
248 in Lisp, but put off loading the file that defines it. The first call
249 to the function automatically reads the proper file to install the real
250 definition and other associated code, then runs the real definition as
251 if it had been loaded all along.
253 There are two ways to set up an autoloaded function: by calling
254 `autoload', and by writing a special "magic" comment in the source
255 before the real definition. `autoload' is the low-level primitive for
256 autoloading; any Lisp program can call `autoload' at any time. Magic
257 comments do nothing on their own; they serve as a guide for the command
258 `update-file-autoloads', which constructs calls to `autoload' and
259 arranges to execute them when Emacs is built. Magic comments are the
260 most convenient way to make a function autoload, but only for packages
261 installed along with Emacs.
263 - Function: autoload function filename &optional docstring interactive
265 This function defines the function (or macro) named FUNCTION so as
266 to load automatically from FILENAME. The string FILENAME
267 specifies the file to load to get the real definition of FUNCTION.
269 The argument DOCSTRING is the documentation string for the
270 function. Normally, this is identical to the documentation string
271 in the function definition itself. Specifying the documentation
272 string in the call to `autoload' makes it possible to look at the
273 documentation without loading the function's real definition.
275 If INTERACTIVE is non-`nil', then the function can be called
276 interactively. This lets completion in `M-x' work without loading
277 the function's real definition. The complete interactive
278 specification need not be given here; it's not needed unless the
279 user actually calls FUNCTION, and when that happens, it's time to
280 load the real definition.
282 You can autoload macros and keymaps as well as ordinary functions.
283 Specify TYPE as `macro' if FUNCTION is really a macro. Specify
284 TYPE as `keymap' if FUNCTION is really a keymap. Various parts of
285 Emacs need to know this information without loading the real
288 An autoloaded keymap loads automatically during key lookup when a
289 prefix key's binding is the symbol FUNCTION. Autoloading does not
290 occur for other kinds of access to the keymap. In particular, it
291 does not happen when a Lisp program gets the keymap from the value
292 of a variable and calls `define-key'; not even if the variable
293 name is the same symbol FUNCTION.
295 If FUNCTION already has a non-void function definition that is not
296 an autoload object, `autoload' does nothing and returns `nil'. If
297 the function cell of FUNCTION is void, or is already an autoload
298 object, then it is defined as an autoload object like this:
300 (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
304 (symbol-function 'run-prolog)
305 => (autoload "prolog" 169681 t nil)
307 In this case, `"prolog"' is the name of the file to load, 169681
308 refers to the documentation string in the `DOC' file (*note
309 Documentation Basics::), `t' means the function is interactive,
310 and `nil' that it is not a macro or a keymap.
312 The autoloaded file usually contains other definitions and may
313 require or provide one or more features. If the file is not completely
314 loaded (due to an error in the evaluation of its contents), any function
315 definitions or `provide' calls that occurred during the load are
316 undone. This is to ensure that the next attempt to call any function
317 autoloading from this file will try again to load the file. If not for
318 this, then some of the functions in the file might appear defined, but
319 they might fail to work properly for the lack of certain subroutines
320 defined later in the file and not loaded successfully.
322 XEmacs as distributed comes with many autoloaded functions. The
323 calls to `autoload' are in the file `loaddefs.el'. There is a
324 convenient way of updating them automatically.
326 If the autoloaded file fails to define the desired Lisp function or
327 macro, then an error is signaled with data `"Autoloading failed to
328 define function FUNCTION-NAME"'.
330 A magic autoload comment looks like `;;;###autoload', on a line by
331 itself, just before the real definition of the function in its
332 autoloadable source file. The command `M-x update-file-autoloads'
333 writes a corresponding `autoload' call into `loaddefs.el'. Building
334 Emacs loads `loaddefs.el' and thus calls `autoload'. `M-x
335 update-directory-autoloads' is even more powerful; it updates autoloads
336 for all files in the current directory.
338 The same magic comment can copy any kind of form into `loaddefs.el'.
339 If the form following the magic comment is not a function definition,
340 it is copied verbatim. You can also use a magic comment to execute a
341 form at build time _without_ executing it when the file itself is
342 loaded. To do this, write the form "on the same line" as the magic
343 comment. Since it is in a comment, it does nothing when you load the
344 source file; but `update-file-autoloads' copies it to `loaddefs.el',
345 where it is executed while building Emacs.
347 The following example shows how `doctor' is prepared for autoloading
348 with a magic comment:
352 "Switch to *doctor* buffer and start giving psychotherapy."
354 (switch-to-buffer "*doctor*")
357 Here's what that produces in `loaddefs.el':
359 (autoload 'doctor "doctor"
361 Switch to *doctor* buffer and start giving psychotherapy."
364 The backslash and newline immediately following the double-quote are a
365 convention used only in the preloaded Lisp files such as `loaddefs.el';
366 they tell `make-docfile' to put the documentation string in the `DOC'
367 file. *Note Building XEmacs::.
370 File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading
375 You may load one file more than once in an Emacs session. For
376 example, after you have rewritten and reinstalled a function definition
377 by editing it in a buffer, you may wish to return to the original
378 version; you can do this by reloading the file it came from.
380 When you load or reload files, bear in mind that the `load' and
381 `load-library' functions automatically load a byte-compiled file rather
382 than a non-compiled file of similar name. If you rewrite a file that
383 you intend to save and reinstall, remember to byte-compile it if
384 necessary; otherwise you may find yourself inadvertently reloading the
385 older, byte-compiled file instead of your newer, non-compiled file!
387 When writing the forms in a Lisp library file, keep in mind that the
388 file might be loaded more than once. For example, the choice of
389 `defvar' vs. `defconst' for defining a variable depends on whether it
390 is desirable to reinitialize the variable if the library is reloaded:
391 `defconst' does so, and `defvar' does not. (*Note Defining
394 The simplest way to add an element to an alist is like this:
396 (setq minor-mode-alist
397 (cons '(leif-mode " Leif") minor-mode-alist))
399 But this would add multiple elements if the library is reloaded. To
400 avoid the problem, write this:
402 (or (assq 'leif-mode minor-mode-alist)
403 (setq minor-mode-alist
404 (cons '(leif-mode " Leif") minor-mode-alist)))
406 To add an element to a list just once, use `add-to-list' (*note
407 Setting Variables::).
409 Occasionally you will want to test explicitly whether a library has
410 already been loaded. Here's one way to test, in a library, whether it
411 has been loaded before:
413 (defvar foo-was-loaded)
415 (if (not (boundp 'foo-was-loaded))
416 EXECUTE-FIRST-TIME-ONLY)
418 (setq foo-was-loaded t)
420 If the library uses `provide' to provide a named feature, you can use
421 `featurep' to test whether the library has been loaded. *Note Named
425 File: lispref.info, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading
430 `provide' and `require' are an alternative to `autoload' for loading
431 files automatically. They work in terms of named "features".
432 Autoloading is triggered by calling a specific function, but a feature
433 is loaded the first time another program asks for it by name.
435 A feature name is a symbol that stands for a collection of functions,
436 variables, etc. The file that defines them should "provide" the
437 feature. Another program that uses them may ensure they are defined by
438 "requiring" the feature. This loads the file of definitions if it
439 hasn't been loaded already.
441 To require the presence of a feature, call `require' with the
442 feature name as argument. `require' looks in the global variable
443 `features' to see whether the desired feature has been provided
444 already. If not, it loads the feature from the appropriate file. This
445 file should call `provide' at the top level to add the feature to
446 `features'; if it fails to do so, `require' signals an error.
448 Features are normally named after the files that provide them, so
449 that `require' need not be given the file name.
451 For example, in `emacs/lisp/prolog.el', the definition for
452 `run-prolog' includes the following code:
455 "Run an inferior Prolog process, input and output via buffer *prolog*."
458 (switch-to-buffer (make-comint "prolog" prolog-program-name))
459 (inferior-prolog-mode))
461 The expression `(require 'comint)' loads the file `comint.el' if it has
462 not yet been loaded. This ensures that `make-comint' is defined.
464 The `comint.el' file contains the following top-level expression:
468 This adds `comint' to the global `features' list, so that `(require
469 'comint)' will henceforth know that nothing needs to be done.
471 When `require' is used at top level in a file, it takes effect when
472 you byte-compile that file (*note Byte Compilation::) as well as when
473 you load it. This is in case the required package contains macros that
474 the byte compiler must know about.
476 Although top-level calls to `require' are evaluated during byte
477 compilation, `provide' calls are not. Therefore, you can ensure that a
478 file of definitions is loaded before it is byte-compiled by including a
479 `provide' followed by a `require' for the same feature, as in the
482 (provide 'my-feature) ; Ignored by byte compiler,
483 ; evaluated by `load'.
484 (require 'my-feature) ; Evaluated by byte compiler.
486 The compiler ignores the `provide', then processes the `require' by
487 loading the file in question. Loading the file does execute the
488 `provide' call, so the subsequent `require' call does nothing while
491 - Function: provide feature
492 This function announces that FEATURE is now loaded, or being
493 loaded, into the current XEmacs session. This means that the
494 facilities associated with FEATURE are or will be available for
497 The direct effect of calling `provide' is to add FEATURE to the
498 front of the list `features' if it is not already in the list.
499 The argument FEATURE must be a symbol. `provide' returns FEATURE.
509 When a file is loaded to satisfy an autoload, and it stops due to
510 an error in the evaluating its contents, any function definitions
511 or `provide' calls that occurred during the load are undone.
514 - Function: require feature &optional filename
515 This function checks whether FEATURE is present in the current
516 XEmacs session (using `(featurep FEATURE)'; see below). If it is
517 not, then `require' loads FILENAME with `load'. If FILENAME is
518 not supplied, then the name of the symbol FEATURE is used as the
521 If loading the file fails to provide FEATURE, `require' signals an
522 error, `Required feature FEATURE was not provided'.
524 - Function: featurep fexp
525 This function returns `t' if feature FEXP is present in this
526 Emacs. Use this to conditionalize execution of lisp code based on
527 the presence or absence of emacs or environment extensions.
529 FEXP can be a symbol, a number, or a list.
531 If FEXP is a symbol, it is looked up in the `features' variable,
532 and `t' is returned if it is found, `nil' otherwise.
534 If FEXP is a number, the function returns `t' if this Emacs has an
535 equal or greater number than FEXP, `nil' otherwise. Note that
536 minor Emacs version is expected to be 2 decimal places wide, so
537 `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write
538 `(featurep 20.04)', unless you wish to match for XEmacs 20.40.
540 If FEXP is a list whose car is the symbol `and', the function
541 returns `t' if all the features in its cdr are present, `nil'
544 If FEXP is a list whose car is the symbol `or', the function
545 returns `t' if any the features in its cdr are present, `nil'
548 If FEXP is a list whose car is the symbol `not', the function
549 returns `t' if the feature is not present, `nil' otherwise.
556 (featurep '(and xemacs gnus))
557 => ; t on XEmacs with Gnus loaded.
559 (featurep '(or tty-frames (and emacs 19.30)))
560 => ; t if this Emacs supports TTY frames.
562 (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
563 => ; t on XEmacs 19.15 and later, or on
564 ; FSF Emacs 19.34 and later.
566 *Please note:* The advanced arguments of this function (anything
567 other than a symbol) are not yet supported by FSF Emacs. If you
568 feel they are useful for supporting multiple Emacs variants, lobby
569 Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
572 The value of this variable is a list of symbols that are the
573 features loaded in the current XEmacs session. Each symbol was
574 put in this list with a call to `provide'. The order of the
575 elements in the `features' list is not significant.
578 File: lispref.info, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading
583 You can discard the functions and variables loaded by a library to
584 reclaim memory for other Lisp objects. To do this, use the function
587 - Command: unload-feature feature &optional force
588 This command unloads the library that provided feature FEATURE.
589 It undefines all functions, macros, and variables defined in that
590 library with `defconst', `defvar', `defun', `defmacro',
591 `defsubst', `define-function' and `defalias'. It then restores
592 any autoloads formerly associated with those symbols. (Loading
593 saves these in the `autoload' property of the symbol.)
595 Ordinarily, `unload-feature' refuses to unload a library on which
596 other loaded libraries depend. (A library A depends on library B
597 if A contains a `require' for B.) If the optional argument FORCE
598 is non-`nil', dependencies are ignored and you can unload any
601 The `unload-feature' function is written in Lisp; its actions are
602 based on the variable `load-history'.
604 - Variable: load-history
605 This variable's value is an alist connecting library names with the
606 names of functions and variables they define, the features they
607 provide, and the features they require.
609 Each element is a list and describes one library. The CAR of the
610 list is the name of the library, as a string. The rest of the
611 list is composed of these kinds of objects:
613 * Symbols that were defined by this library.
615 * Lists of the form `(require . FEATURE)' indicating features
618 * Lists of the form `(provide . FEATURE)' indicating features
621 The value of `load-history' may have one element whose CAR is
622 `nil'. This element describes definitions made with `eval-buffer'
623 on a buffer that is not visiting a file.
625 The command `eval-region' updates `load-history', but does so by
626 adding the symbols defined to the element for the file being visited,
627 rather than replacing that element.
630 File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading
635 - Variable: after-load-alist
636 An alist of expressions to evaluate if and when particular
637 libraries are loaded. Each element looks like this:
641 When `load' is run and the file-name argument is FILENAME, the
642 FORMS in the corresponding element are executed at the end of
645 FILENAME must match exactly! Normally FILENAME is the name of a
646 library, with no directory specified, since that is how `load' is
647 normally called. An error in FORMS does not undo the load, but
648 does prevent execution of the rest of the FORMS.
652 File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top
657 XEmacs Lisp has a "compiler" that translates functions written in
658 Lisp into a special representation called "byte-code" that can be
659 executed more efficiently. The compiler replaces Lisp function
660 definitions with byte-code. When a byte-coded function is called, its
661 definition is evaluated by the "byte-code interpreter".
663 Because the byte-compiled code is evaluated by the byte-code
664 interpreter, instead of being executed directly by the machine's
665 hardware (as true compiled code is), byte-code is completely
666 transportable from machine to machine without recompilation. It is not,
667 however, as fast as true compiled code.
669 In general, any version of Emacs can run byte-compiled code produced
670 by recent earlier versions of Emacs, but the reverse is not true. In
671 particular, if you compile a program with XEmacs 20, the compiled code
672 may not run in earlier versions.
674 The first time a compiled-function object is executed, the byte-code
675 instructions are validated and the byte-code is further optimized. An
676 `invalid-byte-code' error is signaled if the byte-code is invalid, for
677 example if it contains invalid opcodes. This usually means a bug in
680 *Note Compilation Errors::, for how to investigate errors occurring
685 * Speed of Byte-Code:: An example of speedup from byte compilation.
686 * Compilation Functions:: Byte compilation functions.
687 * Docs and Compilation:: Dynamic loading of documentation strings.
688 * Dynamic Loading:: Dynamic loading of individual functions.
689 * Eval During Compile:: Code to be evaluated when you compile.
690 * Compiled-Function Objects:: The data type used for byte-compiled functions.
691 * Disassembly:: Disassembling byte-code; how to read byte-code.
692 * Different Behavior:: When compiled code gives different results.
695 File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation
697 Performance of Byte-Compiled Code
698 =================================
700 A byte-compiled function is not as efficient as a primitive function
701 written in C, but runs much faster than the version written in Lisp.
704 (defun silly-loop (n)
705 "Return time before and after N iterations of a loop."
706 (let ((t1 (current-time-string)))
707 (while (> (setq n (1- n))
709 (list t1 (current-time-string))))
713 => ("Mon Sep 14 15:51:49 1998"
714 "Mon Sep 14 15:52:07 1998") ; 18 seconds
716 (byte-compile 'silly-loop)
717 => #<compiled-function
720 [current-time-string t1 n 0]
722 "Return time before and after N iterations of a loop.">
725 => ("Mon Sep 14 15:53:43 1998"
726 "Mon Sep 14 15:53:49 1998") ; 6 seconds
728 In this example, the interpreted code required 18 seconds to run,
729 whereas the byte-compiled code required 6 seconds. These results are
730 representative, but actual results will vary greatly.
733 File: lispref.info, Node: Compilation Functions, Next: Docs and Compilation, Prev: Speed of Byte-Code, Up: Byte Compilation
735 The Compilation Functions
736 =========================
738 You can byte-compile an individual function or macro definition with
739 the `byte-compile' function. You can compile a whole file with
740 `byte-compile-file', or several files with `byte-recompile-directory'
741 or `batch-byte-compile'.
743 When you run the byte compiler, you may get warnings in a buffer
744 called `*Compile-Log*'. These report things in your program that
745 suggest a problem but are not necessarily erroneous.
747 Be careful when byte-compiling code that uses macros. Macro calls
748 are expanded when they are compiled, so the macros must already be
749 defined for proper compilation. For more details, see *Note Compiling
752 Normally, compiling a file does not evaluate the file's contents or
753 load the file. But it does execute any `require' calls at top level in
754 the file. One way to ensure that necessary macro definitions are
755 available during compilation is to `require' the file that defines them
756 (*note Named Features::). To avoid loading the macro definition files
757 when someone _runs_ the compiled program, write `eval-when-compile'
758 around the `require' calls (*note Eval During Compile::).
760 - Function: byte-compile symbol
761 This function byte-compiles the function definition of SYMBOL,
762 replacing the previous definition with the compiled one. The
763 function definition of SYMBOL must be the actual code for the
764 function; i.e., the compiler does not follow indirection to
765 another symbol. `byte-compile' returns the new, compiled
766 definition of SYMBOL.
768 If SYMBOL's definition is a compiled-function object,
769 `byte-compile' does nothing and returns `nil'. Lisp records only
770 one function definition for any symbol, and if that is already
771 compiled, non-compiled code is not available anywhere. So there
772 is no way to "compile the same definition again."
774 (defun factorial (integer)
775 "Compute factorial of INTEGER."
777 (* integer (factorial (1- integer)))))
780 (byte-compile 'factorial)
781 => #<compiled-function
784 [integer 1 factorial]
786 "Compute factorial of INTEGER.">
788 The result is a compiled-function object. The string it contains
789 is the actual byte-code; each character in it is an instruction or
790 an operand of an instruction. The vector contains all the
791 constants, variable names and function names used by the function,
792 except for certain primitives that are coded as special
795 - Command: compile-defun &optional arg
796 This command reads the defun containing point, compiles it, and
797 evaluates the result. If you use this on a defun that is actually
798 a function definition, the effect is to install a compiled version
801 If ARG is non-`nil', the result is inserted in the current buffer
802 after the form; otherwise, it is printed in the minibuffer.
804 - Command: byte-compile-file filename &optional load
805 This function compiles a file of Lisp code named FILENAME into a
806 file of byte-code. The output file's name is made by appending
807 `c' to the end of FILENAME.
809 If `load' is non-`nil', the file is loaded after having been
812 Compilation works by reading the input file one form at a time.
813 If it is a definition of a function or macro, the compiled
814 function or macro definition is written out. Other forms are
815 batched together, then each batch is compiled, and written so that
816 its compiled code will be executed when the file is read. All
817 comments are discarded when the input file is read.
819 This command returns `t'. When called interactively, it prompts
823 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
825 (byte-compile-file "~/emacs/push.el")
829 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
830 -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
832 - Command: byte-recompile-directory directory &optional flag
834 This function recompiles every `.el' file in DIRECTORY that needs
835 recompilation. A file needs recompilation if a `.elc' file exists
836 but is older than the `.el' file.
838 Files in subdirectories of DIRECTORY are also processed unless
839 optional argument NORECURSION is non-`nil'.
841 When a `.el' file has no corresponding `.elc' file, then FLAG says
842 what to do. If it is `nil', these files are ignored. If it is
843 non-`nil', the user is asked whether to compile each such file.
845 If the fourth optional argument FORCE is non-`nil', recompile
846 every `.el' file that already has a `.elc' file.
848 The return value of this command is unpredictable.
850 - Function: batch-byte-compile
851 This function runs `byte-compile-file' on files specified on the
852 command line. This function must be used only in a batch
853 execution of Emacs, as it kills Emacs on completion. An error in
854 one file does not prevent processing of subsequent files. (The
855 file that gets the error will not, of course, produce any compiled
858 % xemacs -batch -f batch-byte-compile *.el
860 - Function: batch-byte-recompile-directory
861 This function is similar to `batch-byte-compile' but runs the
862 command `byte-recompile-directory' on the files remaining on the
865 - Variable: byte-recompile-directory-ignore-errors-p
866 If non-`nil', this specifies that `byte-recompile-directory' will
867 continue compiling even when an error occurs in a file. This is
868 normally `nil', but is bound to `t' by
869 `batch-byte-recompile-directory'.
871 - Function: byte-code instructions constants stack-depth
872 This function actually interprets byte-code. Don't call this
873 function yourself. Only the byte compiler knows how to generate
874 valid calls to this function.
876 In newer Emacs versions (19 and up), byte code is usually executed
877 as part of a compiled-function object, and only rarely due to an
878 explicit call to `byte-code'. A byte-compiled function was once
879 actually defined with a body that calls `byte-code', but in recent
880 versions of Emacs `byte-code' is only used to run isolated
881 fragments of lisp code without an associated argument list.
884 File: lispref.info, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Functions, Up: Byte Compilation
886 Documentation Strings and Compilation
887 =====================================
889 Functions and variables loaded from a byte-compiled file access their
890 documentation strings dynamically from the file whenever needed. This
891 saves space within Emacs, and makes loading faster because the
892 documentation strings themselves need not be processed while loading the
893 file. Actual access to the documentation strings becomes slower as a
894 result, but normally not enough to bother users.
896 Dynamic access to documentation strings does have drawbacks:
898 * If you delete or move the compiled file after loading it, Emacs
899 can no longer access the documentation strings for the functions
900 and variables in the file.
902 * If you alter the compiled file (such as by compiling a new
903 version), then further access to documentation strings in this
904 file will give nonsense results.
906 If your site installs Emacs following the usual procedures, these
907 problems will never normally occur. Installing a new version uses a new
908 directory with a different name; as long as the old version remains
909 installed, its files will remain unmodified in the places where they are
912 However, if you have built Emacs yourself and use it from the
913 directory where you built it, you will experience this problem
914 occasionally if you edit and recompile Lisp files. When it happens, you
915 can cure the problem by reloading the file after recompiling it.
917 Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs
918 19.28 do not support the dynamic docstrings feature, and so will not be
919 able to load bytecode created by more recent Emacs versions. You can
920 turn off the dynamic docstring feature by setting
921 `byte-compile-dynamic-docstrings' to `nil'. Once this is done, you can
922 compile files that will load into older Emacs versions. You can do
923 this globally, or for one source file by specifying a file-local
924 binding for the variable. Here's one way to do that:
926 -*-byte-compile-dynamic-docstrings: nil;-*-
928 - Variable: byte-compile-dynamic-docstrings
929 If this is non-`nil', the byte compiler generates compiled files
930 that are set up for dynamic loading of documentation strings.
932 The dynamic documentation string feature writes compiled files that
933 use a special Lisp reader construct, `#@COUNT'. This construct skips
934 the next COUNT characters. It also uses the `#$' construct, which
935 stands for "the name of this file, as a string." It is best not to use
936 these constructs in Lisp source files.
939 File: lispref.info, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation
941 Dynamic Loading of Individual Functions
942 =======================================
944 When you compile a file, you can optionally enable the "dynamic
945 function loading" feature (also known as "lazy loading"). With dynamic
946 function loading, loading the file doesn't fully read the function
947 definitions in the file. Instead, each function definition contains a
948 place-holder which refers to the file. The first time each function is
949 called, it reads the full definition from the file, to replace the
952 The advantage of dynamic function loading is that loading the file
953 becomes much faster. This is a good thing for a file which contains
954 many separate commands, provided that using one of them does not imply
955 you will soon (or ever) use the rest. A specialized mode which provides
956 many keyboard commands often has that usage pattern: a user may invoke
957 the mode, but use only a few of the commands it provides.
959 The dynamic loading feature has certain disadvantages:
961 * If you delete or move the compiled file after loading it, Emacs
962 can no longer load the remaining function definitions not already
965 * If you alter the compiled file (such as by compiling a new
966 version), then trying to load any function not already loaded will
967 get nonsense results.
969 If you compile a new version of the file, the best thing to do is
970 immediately load the new compiled file. That will prevent any future
973 The byte compiler uses the dynamic function loading feature if the
974 variable `byte-compile-dynamic' is non-`nil' at compilation time. Do
975 not set this variable globally, since dynamic loading is desirable only
976 for certain files. Instead, enable the feature for specific source
977 files with file-local variable bindings, like this:
979 -*-byte-compile-dynamic: t;-*-
981 - Variable: byte-compile-dynamic
982 If this is non-`nil', the byte compiler generates compiled files
983 that are set up for dynamic function loading.
985 - Function: fetch-bytecode function
986 This immediately finishes loading the definition of FUNCTION from
987 its byte-compiled file, if it is not fully loaded already. The
988 argument FUNCTION may be a compiled-function object or a function
992 File: lispref.info, Node: Eval During Compile, Next: Compiled-Function Objects, Prev: Dynamic Loading, Up: Byte Compilation
994 Evaluation During Compilation
995 =============================
997 These features permit you to write code to be evaluated during
998 compilation of a program.
1000 - Special Form: eval-and-compile body
1001 This form marks BODY to be evaluated both when you compile the
1002 containing code and when you run it (whether compiled or not).
1004 You can get a similar result by putting BODY in a separate file
1005 and referring to that file with `require'. Using `require' is
1006 preferable if there is a substantial amount of code to be executed
1009 - Special Form: eval-when-compile body
1010 This form marks BODY to be evaluated at compile time and not when
1011 the compiled program is loaded. The result of evaluation by the
1012 compiler becomes a constant which appears in the compiled program.
1013 When the program is interpreted, not compiled at all, BODY is
1016 At top level, this is analogous to the Common Lisp idiom
1017 `(eval-when (compile eval) ...)'. Elsewhere, the Common Lisp `#.'
1018 reader macro (but not when interpreting) is closer to what
1019 `eval-when-compile' does.
1022 File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation
1024 Compiled-Function Objects
1025 =========================
1027 Byte-compiled functions have a special data type: they are
1028 "compiled-function objects". The evaluator handles this data type
1029 specially when it appears as a function to be called.
1031 The printed representation for a compiled-function object normally
1032 begins with `#<compiled-function' and ends with `>'. However, if the
1033 variable `print-readably' is non-`nil', the object is printed beginning
1034 with `#[' and ending with `]'. This representation can be read
1035 directly by the Lisp reader, and is used in byte-compiled files (those
1038 In Emacs version 18, there was no compiled-function object data type;
1039 compiled functions used the function `byte-code' to run the byte code.
1041 A compiled-function object has a number of different attributes.
1045 The list of argument symbols.
1048 The string containing the byte-code instructions.
1051 The vector of Lisp objects referenced by the byte code. These
1052 include symbols used as function names and variable names.
1055 The maximum stack size this function needs.
1058 The documentation string (if any); otherwise, `nil'. The value may
1059 be a number or a list, in case the documentation string is stored
1060 in a file. Use the function `documentation' to get the real
1061 documentation string (*note Accessing Documentation::).
1064 The interactive spec (if any). This can be a string or a Lisp
1065 expression. It is `nil' for a function that isn't interactive.
1068 The domain (if any). This is only meaningful if I18N3
1069 (message-translation) support was compiled into XEmacs. This is a
1070 string defining which domain to find the translation for the
1071 documentation string and interactive prompt. *Note Domain
1074 Here's an example of a compiled-function object, in printed
1075 representation. It is the definition of the command `backward-sexp'.
1077 (symbol-function 'backward-sexp)
1078 => #<compiled-function
1080 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
1082 The primitive way to create a compiled-function object is with
1085 - Function: make-byte-code arglist instructions constants stack-depth
1086 &optional doc-string interactive
1087 This function constructs and returns a compiled-function object
1088 with the specified attributes.
1090 _Please note:_ Unlike all other Emacs-lisp functions, calling this
1091 with five arguments is _not_ the same as calling it with six
1092 arguments, the last of which is `nil'. If the INTERACTIVE arg is
1093 specified as `nil', then that means that this function was defined
1094 with `(interactive)'. If the arg is not specified, then that means
1095 the function is not interactive. This is terrible behavior which
1096 is retained for compatibility with old `.elc' files which expected
1099 You should not try to come up with the elements for a
1100 compiled-function object yourself, because if they are inconsistent,
1101 XEmacs may crash when you call the function. Always leave it to the
1102 byte compiler to create these objects; it makes the elements consistent
1105 The following primitives are provided for accessing the elements of
1106 a compiled-function object.
1108 - Function: compiled-function-arglist function
1109 This function returns the argument list of compiled-function object
1112 - Function: compiled-function-instructions function
1113 This function returns a string describing the byte-code
1114 instructions of compiled-function object FUNCTION.
1116 - Function: compiled-function-constants function
1117 This function returns the vector of Lisp objects referenced by
1118 compiled-function object FUNCTION.
1120 - Function: compiled-function-stack-depth function
1121 This function returns the maximum stack size needed by
1122 compiled-function object FUNCTION.
1124 - Function: compiled-function-doc-string function
1125 This function returns the doc string of compiled-function object
1126 FUNCTION, if available.
1128 - Function: compiled-function-interactive function
1129 This function returns the interactive spec of compiled-function
1130 object FUNCTION, if any. The return value is `nil' or a
1131 two-element list, the first element of which is the symbol
1132 `interactive' and the second element is the interactive spec (a
1133 string or Lisp form).
1135 - Function: compiled-function-domain function
1136 This function returns the domain of compiled-function object
1137 FUNCTION, if any. The result will be a string or `nil'. *Note
1138 Domain Specification::.
projects / chise / xemacs-chise.git- / blob