Go to the previous, next section.

Features

provide and require are an alternative to autoload for loading files automatically. They work in terms of named features. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name.

The use of named features simplifies the task of determining whether required definitions have been defined. A feature name is a symbol that stands for a collection of functions, variables, etc. A program that needs the collection may ensure that they are defined by requiring the feature. If the file that contains the feature has not yet been loaded, then it will be loaded (or an error will be signaled if it cannot be loaded). The file thus loaded must provide the required feature or an error will be signaled.

To require the presence of a feature, call require with the feature name as argument. require looks in the global variable features to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call provide at the top-level to add the feature to features.

Features are normally named after the files they are provided in so that require need not be given the file name.

For example, in `emacs/lisp/prolog.el', the definition for run-prolog includes the following code:

(defun run-prolog ()
  "Run an inferior Prolog process,\
 input and output via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))

The expression (require 'shell) loads the file `shell.el' if it has not yet been loaded. This ensures that make-shell is defined.

The `shell.el' file contains the following top-level expression:

(provide 'shell)

This adds shell to the global features list when the `shell' file is loaded, so that (require 'shell) will henceforth know that nothing needs to be done.

When require is used at top-level in a file, it takes effect if you byte-compile that file (see section Byte Compilation). This is in case the required package contains macros that the byte compiler must know about.

Although top-level calls to require are evaluated during byte compilation, provide calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a provide followed by a require for the same feature, as in the following example.

(provide 'my-feature)  ; Ignored by byte compiler,
                       ;   evaluated by load.
(require 'my-feature)  ; Evaluated by byte compiler.

Function: provide feature

This function announces that feature is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.

The direct effect of calling provide is to add feature to the front of the list features if it is not already in the list. The argument feature must be a symbol. provide returns feature.

features
     => (bar bish)

(provide 'foo)
     => foo
features
     => (foo bar bish)

During autoloading, 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. See section Autoload.

Function: require feature &optional filename

This function checks whether feature is present in the current Emacs session (using (featurep feature); see below). If it is not, then require loads filename with load. If filename is not supplied, then the name of the symbol feature is used as the file name to load.

If feature is not provided after the file has been loaded, Emacs will signal the error error (with data `Required feature feature was not provided').

Function: featurep feature

This function returns t if feature has been provided in the current Emacs session (i.e., feature is a member of features.)

Variable: features

The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to provide. The order of the elements in the features list is not significant.

Go to the previous, next section.