GNU Info

(elisp)Named Features

---

Next: Unloading Prev: Repeated Loading Up: Loading

---

Enter node , (file) or (file)node

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.

   A feature name is a symbol that stands for a collection of functions,
variables, etc.  The file that defines them should "provide" the
feature.  Another program that uses them may ensure they are defined by
"requiring" the feature.  This loads the file of definitions if it
hasn't been loaded already.

   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'; if it fails to do so, `require' signals an error.

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

     (defun run-prolog ()
       "Run an inferior Prolog process, with I/O via buffer *prolog*."
       (interactive)
       (require 'comint)
       (switch-to-buffer (make-comint "prolog" prolog-program-name))
       (inferior-prolog-mode))

The expression `(require 'comint)' loads the file `comint.el' if it has
not yet been loaded.  This ensures that `make-comint' is defined.
Features are normally named after the files that provide them, so that
`require' need not be given the file name.

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

     (provide 'comint)

This adds `comint' to the global `features' list, so that `(require
'comint)' will henceforth know that nothing needs to be done.

   When `require' is used at top level in a file, it takes effect when
you byte-compile that file (Note: Byte Compilation) as well as when
you load it.  This is in case the required package contains macros that
the byte compiler must know about.  It also avoids byte-compiler
warnings for functions and variables defined in the file loaded with
`require'.

   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.

The compiler ignores the `provide', then processes the `require' by
loading the file in question.  Loading the file does execute the
`provide' call, so the subsequent `require' call does nothing when the
file is loaded.

 - 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)

     When a file is loaded to satisfy an autoload, and it stops due to
     an error in the evaluating its contents, any function definitions
     or `provide' calls that occurred during the load are undone.
     Note: Autoload.

 - Function: require feature &optional filename noerror
     This function checks whether FEATURE is present in the current
     Emacs session (using `(featurep FEATURE)'; see below).  The
     argument FEATURE must be a symbol.

     If the feature is not present, then `require' loads FILENAME with
     `load'.  If FILENAME is not supplied, then the name of the symbol
     FEATURE is used as the base file name to load.  However, in this
     case, `require' insists on finding FEATURE with an added suffix; a
     file whose name is just FEATURE won't be used.

     If loading the file fails to provide FEATURE, `require' signals an
     error, `Required feature FEATURE was not provided', unless NOERROR
     is non-`nil'.

 - Function: featurep feature
     This function returns `t' if FEATURE has been provided in the
     current Emacs session (i.e., if 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.