15.7 Unloading

You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function unload-feature:

Command: unload-feature feature &optional force

This command unloads the library that provided feature feature. It undefines all functions, macros, and variables defined in that library with defun, defalias, defsubst, defmacro, defconst, defvar, and defcustom. It then restores any autoloads formerly associated with those symbols. (Loading saves these in the autoload property of the symbol.)

Before restoring the previous definitions, unload-feature runs remove-hook to remove functions in the library from certain hooks. These hooks include variables whose names end in `hook' or `-hooks', plus those listed in loadhist-special-hooks. This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined.

If these measures are not sufficient to prevent malfunction, a library can define an explicit unload hook. If feature-unload-hook is defined, it is run as a normal hook before restoring the previous definitions, instead of the usual hook-removing actions. The unload hook ought to undo all the global state changes made by the library that might cease to work once the library is unloaded. unload-feature can cause problems with libraries that fail to do this, so it should be used with caution.

Ordinarily, unload-feature refuses to unload a library on which other loaded libraries depend. (A library a depends on library b if a contains a require for b.) If the optional argument force is non-nil, dependencies are ignored and you can unload any library.

The unload-feature function is written in Lisp; its actions are based on the variable load-history.

Variable: load-history

This variable's value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.

Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:

• Symbols that were defined by this library.
• Cons cells of the form (require . feature) indicating features that were required.
• Cons cells of the form (provide . feature) indicating features that were provided.

The value of load-history may have one element whose CAR is nil. This element describes definitions made with eval-buffer on a buffer that is not visiting a file.

The command eval-region updates load-history, but does so by adding the symbols defined to the element for the file being visited, rather than replacing that element. See section 9.4 Eval.

Preloaded libraries don't contribute initially to load-history. Instead, preloading writes information about preloaded libraries into a file, which can be loaded later on to add information to load-history describing the preloaded files. This file is installed in exec-directory and has a name of the form `fns-emacsversion.el'.

See the source for the function symbol-file, for an example of code that loads this file to find functions in preloaded libraries.

Variable: loadhist-special-hooks

This variable holds a list of hooks to be scanned before unloading a library, to remove functions defined in the library.