Go to the previous, next section.
The autoload facility allows you to make a function or macro available but put off loading its actual definition. An attempt to call a symbol whose definition is an autoload object automatically reads the file to install the real definition and its other associated code, and then calls the real definition.
To prepare a function or macro for autoloading, you must call
autoload, specifying the function name and the name of the file
to be loaded. A file such as `emacs/lisp/loaddefs.el' usually does
this when Emacs is first built.
The following example shows how doctor is prepared for
autoloading 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 cause the documentation string to be put in the `etc/DOC' file. (See section Building Emacs.) In any other source file, you would write just this:
(autoload 'doctor "doctor" "Switch to *doctor* buffer and start giving psychotherapy." t)
Calling autoload creates an autoload object containing the name
of the file and some other information, and makes this the function
definition of the specified symbol. When you later try to call that
symbol as a function or macro, the file is loaded; the loading should
redefine that symbol with its proper definition. After the file
completes loading, the function or macro is called as if it had been
there originally.
If, at the end of loading the file, the desired Lisp function or macro
has not been defined, then the error error is signaled (with data
"Autoloading failed to define function function-name").
The autoloaded file may, of course, contain 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 the 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 may fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.
Emacs 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.
Write `;;;###autoload' on a line by itself before the real
definition of the function, in its autoloadable source file; then the
command M-x update-file-autoloads automatically puts the
autoload call into `loaddefs.el'. M-x
update-directory-autoloads is more powerful; it updates autoloads for
all files in the current directory.
You can also put other kinds of forms into `loaddefs.el', by writing `;;;###autoload' followed on the same line by the form. M-x update-file-autoloads copies the form from that line.
The commands for updating autoloads work by visiting and editing the file `loaddefs.el'. To make the result take effect, you must save that file's buffer.
Function: autoload symbol filename &optional docstring interactive type
This function defines the function (or macro) named symbol so as
to load automatically from filename. The string filename is
a file name which will be passed to load when the function is
called.
The argument docstring is the documentation string for the function. Normally, this is the same string that is in the function definition itself. This makes it possible to look at the documentation without loading the 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. If type is macro,
then the function is really a macro. If type is keymap,
then the function is really a keymap.
If symbol already has a non-nil function definition that
is not an autoload object, autoload does nothing and returns
nil. If the function cell of symbol is void, or is already
an autoload object, then it is set to an autoload object that looks 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 `emacs/etc/DOC'
file (see section Documentation Basics), t means the function is
interactive, and nil that it is not a macro.
Go to the previous, next section.