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 idlwave.el, the definition for
idlwave-complete-filename
includes the following code:
(defun idlwave-complete-filename () "Use the comint stuff to complete a file name." (require 'comint) (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%={}\\-") (comint-completion-addsuffix nil) ...) (comint-dynamic-complete-filename)))
The expression (require 'comint)
loads the file comint.el
if it has not yet been loaded, ensuring that
comint-dynamic-complete-filename
is defined. Features are
normally named after the files that provide them, so that
require
need not be given the file name. (Note that it is
important that the require
statement be outside the body of the
let
. Loading a library while its variables are let-bound can
have unintended consequences, namely the variables becoming unbound
after the let exits.)
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 (see 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.
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 features
if it is not already in that list and
call any eval-after-load
code waiting for it (see Hooks for Loading). The argument feature must be a symbol.
provide
returns feature.
If provided, subfeatures should be a list of symbols indicating
a set of specific subfeatures provided by this version of
feature. You can test the presence of a subfeature using
featurep
. The idea of subfeatures is that you use them when a
package (which is one feature) is complex enough to make it
useful to give names to various parts or functionalities of the
package, which might or might not be loaded, or might or might not be
present in a given version. See Testing Availability of Network Features, for
an example.
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 evaluation of its contents, any function definitions or
provide
calls that occurred during the load are undone.
See Autoload.
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 ‘.el’ or ‘.elc’ suffix (possibly extended with
a compression suffix); a file whose name is just feature won’t
be used. (The variable load-suffixes
specifies the exact
required Lisp suffixes.)
If noerror is non-nil
, that suppresses errors from actual
loading of the file. In that case, require
returns nil
if loading the file fails. Normally, require
returns
feature.
If loading the file succeeds but does not provide feature,
require
signals an error about the missing feature.
This function returns t
if feature has been provided in
the current Emacs session (i.e., if feature is a member of
features
.) If subfeature is non-nil
, then the
function returns t
only if that subfeature is provided as well
(i.e., if subfeature is a member of the subfeature
property of the feature symbol.)
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.
The use-package
macro provides a convenient way of loading a
feature and configuring it for use. It provides a means to combine
requiring a feature, like require
does, with code to be run
when the feature is actually loaded, similar to load-time hooks
(see Hooks for Loading). The declarative syntax of
use-package
makes it exceptionally easy to use in user init
files.
This macro specifies how to load the named feature and how to configure and customize it for use. The arguments args are keyword-value pairs. Some of the important keywords and their values are:
:init forms
Specifies forms to execute before feature is loaded.
:config forms
Specifies forms to execute after loading feature.
:defer condition
If condition is non-nil
, it specifies to defer loading
feature until any of the autoloaded commands or variables of
feature are first used. If condition is a number n,
it specifies that feature should be loaded after n
seconds of idle time.
:commands commands…
Specifies commands of feature to be autoloaded.
:bind keybindings…
Specifies the keybindings for features commands. Each binding has the form
(key-sequence . command)
or
(:map keymap (key-sequence . command))
where key-sequence is in the form accepted by the kbd
macro (see Key Sequences).
For more details about use-package
, see use-package User Manual.