(lispref.info)Autoload


Next: Repeated Loading Prev: How Programs Do Loading Up: Loading

Autoload
========

   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.
(Note: 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
     (Note: Documentation Basics.), `t' means the function is
     interactive, and `nil' that it is not a macro.


automatically generated by info2www