16.5 Autoload ¶

The autoload facility lets you register the existence of a function or macro, but put off loading the file that defines it. The first call to the function automatically loads the proper library, in order to install the real definition and other associated code, then runs the real definition as if it had been loaded all along. Autoloading can also be triggered by looking up the documentation of the function or macro (see Documentation Basics), and completion of variable and function names (see Autoload by Prefix below).

There are two ways to set up an autoloaded function: by calling autoload, and by writing a “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 loaddefs-generate, which constructs calls to autoload and arranges to execute them when Emacs is built.

Function: autoload function filename &optional docstring interactive type ¶

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, this function 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 variable load-suffixes specifies the exact required suffixes.)

The argument docstring is the documentation string for the function. Specifying the documentation string in the call to autoload makes it possible to look at the documentation without loading the function’s real definition. Normally, this should be identical to the documentation string in the function definition itself. If it isn’t, the function definition’s documentation string takes effect when it is loaded.

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.

If interactive is a list, it is interpreted as a list of modes this command is applicable for.

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 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 keymap-set; 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, this function does nothing and returns nil. Otherwise, it constructs an autoload object (see Autoload Type), and stores it as the function definition for function. The autoload object has this form:

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

Function: autoloadp object ¶

This function returns non-nil if object is an autoload object. For example, to check if run-prolog is defined as an autoloaded function, evaluate

(autoloadp (symbol-function 'run-prolog))

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 (often called an autoload cookie) consists of ‘;;;###autoload’, on a line by itself, just before the real definition of the function in its autoloadable source file. The function loaddefs-generate writes a corresponding autoload call into loaddefs.el. (The string that serves as the autoload cookie and the name of the file generated by loaddefs-generate can be changed from the above defaults, see below.) Building Emacs loads loaddefs.el and thus calls autoload.

The same magic comment can copy any kind of form into loaddefs.el. The form following the magic comment is copied verbatim, unless it is a form which the autoload facility handles specially, by conversion directly into an autoload call, or by recursively expanding the macro. Any macro can request expansion of autoloads which call it during generation; See autoload-macro expand.

The following forms are handled specially:

Definitions for function or function-like objects:

defun and defmacro; also cl-defun and cl-defmacro (see Argument Lists in Common Lisp Extensions), and define-overloadable-function (see the commentary in mode-local.el).

Definitions for major or minor modes:

define-minor-mode, define-globalized-minor-mode, define-generic-mode, define-derived-mode, and define-compilation-mode.

Other definition types:

defcustom, defgroup, deftheme, defclass (see EIEIO in EIEIO), define-skeleton (see Autotyping in Autotyping), transient-define-prefix, transient-define-suffix, transient-define-infix, transient-define-argument, and transient-define-group (see Transient in Transient User and Developer Manual).

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 loaddefs-generate 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:

;;;###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.

\(fn)" t nil)

While the loaddefs.el isn’t for editing, we try to keep it somewhat readable for people. For instance, control characters in defvar values are escaped, and we insert a backslash and newline immediately following the double-quote of the doc string to keep the line length down. ‘(fn)’ in the usage part of the documentation string is replaced with the function’s name when the various help functions (see Help Functions) display it.

If you write a function definition with an unusual macro that is not one of the known and recognized function definition methods, using an ordinary magic autoload comment with a call to the macro would require autoloading the macro definition itself to work. Doing so copies the whole macro definition into the autoload file. If that is not desired, you can use the special declare form (autoload-macro expand) in your macro definition (see The declare Form), instead of autoloading it. This indicates to the autoload system that calls to your macro following ‘;;;###autoload’ should be expanded, similar to how the special functions listed above are handled. For example, a macro which wraps define-minor-mode can request expansion, so that proper autoload calls for the function it defines are generated.

The keyword symbol :autoload-end can be used in the expansion of a macro to prevent including unwanted forms in the autoload output. Its presence causes any further elements within the form where it appears to be silently skipped. For example, if during autoload generation, a macro’s expansion includes:

(progn
  (put my-mode 'visible-prop t)
  :autoload-end
  (put my-mode 'hidden-prop nil))

the final form ((put my-mode 'hidden-prop nil)) will not be copied into the autoload file.

Note that, if a symbol in the car of an autoloaded form is found to be undefined during autoload generation, the file in which the associated ‘;;;###autoload’ appears will itself be loaded, to give the macro a chance to be defined. Packages which use special loading mechanisms, including loading their own package-loaddefs.el file, should therefore gracefully handle load errors, since these files may not yet exist during autoload generation. This can be done, e.g., by setting the no-error argument of require non-nil (see Features)).

Alternatively, instead of expansion, you can put the desired autoload call into loaddefs.el by writing this:

;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)

You can use a non-default string as the autoload cookie and have the corresponding autoload calls written into a file whose name is different from the default loaddefs.el. Emacs provides two variables to control this:

Variable: lisp-mode-autoload-regexp ¶

The value of this constant is a regexp that matches autoload cookies. loaddefs-generate copies the Lisp form that follows the cookie into the autoload file it generates. This will match comments like ‘;;;###autoload’ and ‘;;;###calc-autoload’.

Variable: generated-autoload-file ¶

The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is loaddefs.el, but you can override that, e.g., in the local variables section of a .el file (see File Local Variables). The autoload file is assumed to contain a trailer starting with a formfeed character.

The following function may be used to explicitly load the library specified by an autoload object:

Function: autoload-do-load autoload &optional name macro-only ¶

This function performs the loading specified by autoload, which should be an autoload object. The optional argument name, if non-nil, should be a symbol whose function value is autoload; in that case, the return value of this function is the symbol’s new function value. If the value of the optional argument macro-only is macro, this function avoids loading a function, only a macro.

• Autoload by Prefix
• When to Use Autoload