Next: Repeated Loading, Previous: How Programs Do Loading, Up: Loading [Contents][Index]
The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
autoload
, and by writing a special “magic” comment in the
source before the real definition. autoload
is the low-level
primitive for autoloading; any Lisp program can call autoload
at
any time. Magic comments do nothing on their own; they serve as a guide
for the command update-file-autoloads
, which constructs calls to
autoload
and arranges to execute them when SXEmacs is built. Magic
comments are the most convenient way to make a function autoload, but
only for packages installed along with SXEmacs.
This function defines the function (or macro) named function so as to load automatically from filename. The string filename specifies the file to load to get the real definition of function.
The argument docstring is the documentation string for the
function. Normally, this is identical to the documentation string in
the function definition itself. Specifying the documentation string in
the call to autoload
makes it possible to look at the
documentation without loading the function’s real definition.
If interactive is non-nil
, then the function can be called
interactively. This lets completion in M-x work without loading
the function’s real definition. The complete interactive specification
need not be given here; it’s not needed unless the user actually calls
function, and when that happens, it’s time to load the real
definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify type as macro
if function is really a macro.
Specify type as keymap
if function is really a keymap.
Various parts of SXEmacs need to know this information without loading the
real definition.
An autoloaded keymap loads automatically during key lookup when a prefix
key’s binding is the symbol function. Autoloading does not occur
for other kinds of access to the keymap. In particular, it does not
happen when a Lisp program gets the keymap from the value of a variable
and calls define-key
; not even if the variable name is the same
symbol function.
If function already has a non-void function definition that is not
an autoload object, autoload
does nothing and returns nil
.
If the function cell of function is void, or is already an autoload
object, then it is defined as an autoload object like this:
(autoload filename docstring interactive type)
For example,
(symbol-function 'run-prolog) ⇒ (autoload "prolog" 169681 t nil)
In this case, "prolog"
is the name of the file to load, 169681
refers to the documentation string in the DOC file
(see Documentation Basics), t
means the function is
interactive, and nil
that it is not a macro or a keymap.
The autoloaded file usually contains other definitions and may require
or provide one or more features. If the file is not completely loaded
(due to an error in the evaluation of its contents), any function
definitions or provide
calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
this, then some of the functions in the file might appear defined, but
they might fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.
SXEmacs as distributed comes with many autoloaded functions.
The calls to autoload
are in the file loaddefs.el.
There is a convenient way of updating them automatically.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data "Autoloading failed to
define function function-name"
.
A magic autoload comment looks like ‘;;;###autoload’, on a line
by itself, just before the real definition of the function in its
autoloadable source file. The command M-x update-file-autoloads
writes a corresponding autoload
call into loaddefs.el.
Building SXEmacs loads loaddefs.el and thus calls autoload
.
M-x update-directory-autoloads is even more powerful; it updates
autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
loaddefs.el. If the form following the magic comment is not a
function definition, it is copied verbatim. You can also use a magic
comment to execute a form at build time without executing it when
the file itself is loaded. To do this, write the form on the same
line as the magic comment. Since it is in a comment, it does nothing
when you load the source file; but update-file-autoloads
copies
it to loaddefs.el, where it is executed while building SXEmacs.
The following example shows how doctor
is prepared for
autoloading with a magic comment:
;;;###autoload (defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode))
Here’s what that produces in loaddefs.el:
(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t)
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as
loaddefs.el; they tell make-docfile
to put the
documentation string in the DOC file. See Building SXEmacs.
Next: Repeated Loading, Previous: How Programs Do Loading, Up: Loading [Contents][Index]