GNU Info

Info Node: (elisp)Autoload


Next: Repeated Loading Prev: Loading Non-ASCII Up: Loading
Enter node , (file) or (file)node


   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 are the most convenient way to make a function autoload, for
packages installed along with Emacs.  These comments do nothing on
their own, but they serve as a guide for the command
`update-file-autoloads', which constructs calls to `autoload' and
arranges to execute them when Emacs is built.

 - Function: autoload function filename &optional docstring interactive
     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.

     If FILENAME does not contain either a directory name, or the
     suffix `.el' or `.elc', then `autoload' insists on adding one of
     these suffixes, and it will not load from a file whose name is
     just FILENAME with no added suffix.

     The argument DOCSTRING is the documentation string for the
     function.  Normally, this should be 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

     If INTERACTIVE is non-`nil', that says FUNCTION can be called
     interactively.  This lets completion in `M-x' work without loading
     FUNCTION's real definition.  The complete interactive
     specification is not 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
     Emacs need to know this information without loading the real

     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:


     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-VERSION'
     file (Note: 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 be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.

   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 consists of `;;;###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
Emacs 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-defining
form or a `defcustom' form, it is copied verbatim.  "Function-defining
forms" include `define-skeleton', `define-derived-mode',
`define-generic-mode' and `define-minor-mode' as well as `defun' and
`defmacro'.  To save space, a `defcustom' form is converted to a
`defvar' in `loaddefs.el', with some additional information if it uses

   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 `M-x
update-file-autoloads' copies it to `loaddefs.el', where it is executed
while building Emacs.

   The following example shows how `doctor' is prepared for autoloading
with a magic comment:

     (defun doctor ()
       "Switch to *doctor* buffer and start giving psychotherapy."
       (switch-to-buffer "*doctor*")

Here's what that produces in `loaddefs.el':

     (autoload 'doctor "doctor" "\
     Switch to *doctor* buffer and start giving psychotherapy."

The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
`loaddefs.el'; they tell `make-docfile' to put the documentation string
in the `etc/DOC' file.  Note: Building Emacs.  See also the
commentary in `lib-src/make-docfile.c'.

automatically generated by info2www version