gnu.org (original) (raw)

16.7 Features

provide and require are an alternative toautoload 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 variablefeatures 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 tofeatures; if it fails to do so, require signals an error.

For example, in idlwave.el, the definition foridlwave-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.elif it has not yet been loaded, ensuring thatcomint-dynamic-complete-filename is defined. Features are normally named after the files that provide them, so thatrequire need not be given the file name. (Note that it is important that the require statement be outside the body of thelet. 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:

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 withrequire.

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 therequire 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 &optional subfeatures ¶

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 offeature. You can test the presence of a subfeature usingfeaturep. 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 orprovide calls that occurred during the load are undone. See 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 filenamewith 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 featurewith 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 nilif loading the file fails. Normally, require returnsfeature.

If loading the file succeeds but does not provide feature,require signals an error about the missing feature.

Function: require-with-check feature &optional filename noerror ¶

This function works like require, except if feature is already loaded (i.e. is already a member of the list infeatures, see below). If feature is already loaded, this function checks if feature was provided by a file different fromfilename, and if so, it by default signals an error. If the value of the optional argument noerror is reload, the function doesn’t signal an error, but instead forcibly reloadsfilename; if noerror is some other non-nil value, the function emits a warning about feature being already provided by another file.

Function: featurep feature &optional subfeature ¶

This function returns t if feature has been provided in the current Emacs session (i.e., if feature is a member offeatures.) 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 subfeatureproperty of the feature symbol.)

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 thefeatures 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 ofuse-package makes it exceptionally easy to use in user init files.

Macro: use-package feature &rest args ¶

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 loadingfeature until any of the autoloaded commands or variables offeature are first used. If condition is a number n, it specifies that feature should be loaded after nseconds 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

or

(:map keymap (key-sequence . command))

where key-sequence is in the form accepted by the kbdmacro (see Key Sequences).

For more details about use-package, see use-package User Manual.