Loading
*******

Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects.  Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file.

The load functions evaluate all the expressions in a file just as the eval-buffer function evaluates all the expressions in a buffer.  The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer.

The loaded file must contain Lisp expressions, either as source code or as byte-compiled code.  Each form in the file is called a top-level form.  There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there.  (Indeed, most code is tested this way.)  Most often, the forms are function definitions and variable definitions.

A file containing Lisp code is often called a library.  Thus, the ``Rmail library'' is a file containing code for Rmail mode. Similarly, a ``Lisp library directory'' is a directory of files containing Lisp code.

How Programs Do Loading
=======================

Emacs Lisp has several interfaces for loading.  For example, autoload creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function's real definition (see Autoload).  require loads a file if it isn't already loaded (see Named Features).  Ultimately, all these facilities call the load function to do the work.

 -- Function: load filename &optional missing-ok nomessage nosuffix must-suffix
     This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

     To find the file, load first looks for a file named FILENAME.elc, that is, for a file whose name is FILENAME with the extension .elc appended.  If such a file exists, it is loaded.  If there is no file by that name, then load looks for a file named FILENAME.el.  If that file exists, it is loaded.  Finally, if neither of those names is found, load looks for a file named FILENAME with nothing appended, and loads it if it exists.  (The load function is not clever about looking at FILENAME.  In the perverse case of a file named foo.el.el, evaluation of (load "foo.el") will indeed find it.)

     If Auto Compression mode is enabled, as it is by default, then if load can not find a file, it searches for a compressed version of the file before trying other file names.  It decompresses and loads it if it exists.  It looks for compressed versions by appending each of the suffixes in jka-compr-load-suffixes to the file name. The value of this variable must be a list of strings. Its standard value is (".gz").

     If the optional argument NOSUFFIX is non-nil, then load does not try the suffixes .elc and .el.  In this case, you must specify the precise file name you want, except that, if Auto Compression mode is enabled, load will still use jka-compr-load-suffixes to find compressed versions.  By specifying the precise file name and using t for NOSUFFIX, you can prevent perverse file names such as foo.el.el from being tried.

     If the optional argument MUST-SUFFIX is non-nil, then load insists that the file name used must end in either .el or .elc (possibly extended with a compression suffix), unless it contains an explicit directory name.

     If FILENAME is a relative file name, such as foo or baz/foo.bar, load searches for the file using the variable load-path.  It appends FILENAME to each of the directories listed in load-path, and loads the first file it finds whose name matches.  The current default directory is tried only if it is specified in load-path, where nil stands for the default directory. load tries all three possible suffixes in the first directory in load-path, then all three suffixes in the second directory, and so on.  See Library Search.

     If you get a warning that foo.elc is older than foo.el, it means you should consider recompiling foo.el.  See Byte Compilation.

     When loading a source file (not compiled), load performs character set translation just as Emacs would do when visiting the file. See Coding Systems.

     Messages like Loading foo... and Loading foo...done appear in the echo area during loading unless NOMESSAGE is non-nil.

     Any unhandled errors while loading a file terminate loading.  If the load was done for the sake of autoload, any function definitions made during the loading are undone.

     If load can't find the file to load, then normally it signals the error file-error (with Cannot open load file FILENAME).  But if MISSING-OK is non-nil, then load just returns nil.

     You can use the variable load-read-function to specify a function for load to use instead of read for reading expressions. See below.

     load returns t if the file loads successfully.

 -- Command: load-file filename
     This command loads the file FILENAME.  If FILENAME is a relative file name, then the current default directory is assumed. This command does not use load-path, and does not append suffixes.  However, it does look for compressed versions (if Auto Compression Mode is enabled).  Use this command if you wish to specify precisely the file name to load.

 -- Command: load-library library
     This command loads the library named LIBRARY.  It is equivalent to load, except in how it reads its argument interactively.

 -- Variable: load-in-progress
     This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise.

 -- Variable: load-read-function
     This variable specifies an alternate expression-reading function for load and eval-region to use instead of read. The function should accept one argument, just as read does.

     Normally, the variable's value is nil, which means those functions should use read.

     Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the READ-FUNCTION argument to eval-region.  See Eval.

For information about how load is used in building Emacs, see Building Emacs.

Load Suffixes
=============

We now describe some technical details about the exact suffixes that load tries.

 -- Variable: load-suffixes
     This is a list of suffixes indicating (compiled or source) Emacs Lisp files.  It should not include the empty string.  load uses these suffixes in order when it appends Lisp suffixes to the specified file name.  The standard value is (".elc" ".el") which produces the behavior described in the previous section.

 -- Variable: load-file-rep-suffixes
     This is a list of suffixes that indicate representations of the same file.  This list should normally start with the empty string. When load searches for a file it appends the suffixes in this list, in order, to the file name, before searching for another file.

     Enabling Auto Compression mode appends the suffixes in jka-compr-load-suffixes to this list and disabling Auto Compression mode removes them again.  The standard value of load-file-rep-suffixes if Auto Compression mode is disabled is ("").  Given that the standard value of jka-compr-load-suffixes is (".gz"), the standard value of load-file-rep-suffixes if Auto Compression mode is enabled is ("" ".gz").

 -- Function: get-load-suffixes
     This function returns the list of all suffixes that load should try, in order, when its MUST-SUFFIX argument is non-nil. This takes both load-suffixes and load-file-rep-suffixes into account.  If load-suffixes, jka-compr-load-suffixes and load-file-rep-suffixes all have their standard values, this function returns (".elc" ".elc.gz" ".el" ".el.gz") if Auto Compression mode is enabled and (".elc" ".el") if Auto Compression mode is disabled.

To summarize, load normally first tries the suffixes in the value of (get-load-suffixes) and then those in load-file-rep-suffixes.  If NOSUFFIX is non-nil, it skips the former group, and if MUST-SUFFIX is non-nil, it skips the latter group.

Library Search
==============

When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable load-path.

 -- User Option: load-path
     The value of this variable is a list of directories to search when loading files with load.  Each element is a string (which must be a directory name) or nil (which stands for the current working directory).

The value of load-path is initialized from the environment variable EMACSLOADPATH, if that exists; otherwise its default value is specified in emacs/src/epaths.h when Emacs is built. Then the list is expanded by adding subdirectories of the directories in the list.

The syntax of EMACSLOADPATH is the same as used for PATH; : (or ;, according to the operating system) separates directory names, and . is used for the current default directory. Here is an example of how to set your EMACSLOADPATH variable from a csh .login file:

     setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp

Here is how to set it using sh:

     export EMACSLOADPATH
     EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp

Here is an example of code you can place in your init file (see Init File) to add several directories to the front of your default load-path:

     (setq load-path
           (append (list nil "/user/bil/emacs"
                         "/usr/local/lisplib"
                         "~/emacs")
                   load-path))

In this example, the path searches the current working directory first, followed then by the /user/bil/emacs directory, the /usr/local/lisplib directory, and the ~/emacs directory, which are then followed by the standard directories for Lisp code.

Dumping Emacs uses a special value of load-path.  If the value of load-path at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary load-path value when it starts up, as described above.  But if load-path has any other value at the end of dumping, that value is used for execution of the dumped Emacs also.

Therefore, if you want to change load-path temporarily for loading a few libraries in site-init.el or site-load.el, you should bind load-path locally with let around the calls to load.

The default value of load-path, when running an Emacs which has been installed on the system, includes two special directories (and their subdirectories as well):

     "/usr/local/share/emacs/VERSION/site-lisp"

and

     "/usr/local/share/emacs/site-lisp"

The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions.

There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another.  Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version.

Emacs finds these directories' subdirectories and adds them to load-path when it starts up.  Both immediate subdirectories and subdirectories multiple levels down are added to load-path.

Not all subdirectories are included, though.  Subdirectories whose names do not start with a letter or digit are excluded.  Subdirectories named RCS or CVS are excluded.  Also, a subdirectory which contains a file named .nosearch is excluded.  You can use these methods to prevent certain subdirectories of the site-lisp directories from being searched.

If you run Emacs from the directory where it was built---that is, an executable that has not been formally installed---then load-path normally contains two additional directories.  These are the lisp and site-lisp subdirectories of the main build directory.  (Both are represented as absolute file names.)

 -- Command: locate-library library &optional nosuffix path interactive-call
     This command finds the precise file name for library LIBRARY.  It searches for the library in the same way load does, and the argument NOSUFFIX has the same meaning as in load: don't add suffixes .elc or .el to the specified name LIBRARY.

     If the PATH is non-nil, that list of directories is used instead of load-path.

     When locate-library is called from a program, it returns the file name as a string.  When the user runs locate-library interactively, the argument INTERACTIVE-CALL is t, and this tells locate-library to display the file name in the echo area.

Loading Non-ASCII Characters
============================

When Emacs Lisp programs contain string constants with non-ASCII characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (see Text Representations).  Which representation is used depends on how the file is read into Emacs.  If it is read with decoding into multibyte representation, the text of the Lisp program will be multibyte text, and its string constants will be multibyte strings.  If a file containing Latin-1 characters (for example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. See Coding Systems.

To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the --unibyte option.  This means that string constants with non-ASCII characters translate into multibyte strings.  The only exception is when a particular file specifies no decoding.

The reason Emacs is designed this way is so that Lisp programs give predictable results, regardless of how Emacs was started.  In addition, this enables programs that depend on using multibyte text to work even in a unibyte Emacs.  Of course, such programs should be designed to notice whether the user prefers unibyte or multibyte text, by checking default-enable-multibyte-characters, and convert representations appropriately.

In most Emacs Lisp programs, the fact that non-ASCII strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically.  However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing -*-unibyte: t;-*- in a comment on the file's first line.  With that designator, the file will unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session.  This can matter when making keybindings to non-ASCII characters written as ?vLITERAL.

Autoload
========

The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it.  The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.

There are two ways to set up an autoloaded function: by calling autoload, and by writing a special ``magic'' comment in the source before the real definition.  autoload is the low-level primitive for autoloading; any Lisp program can call autoload at any time.  Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs.  These comments do nothing on their own, but they serve as a guide for the command update-file-autoloads, which constructs calls to autoload and arranges to execute them when Emacs is built.

 -- Function: autoload function filename &optional docstring interactive type
     This function defines the function (or macro) named FUNCTION so as to load automatically from FILENAME.  The string FILENAME specifies the file to load to get the real definition of FUNCTION.

     If FILENAME does not contain either a directory name, or the suffix .el or .elc, then autoload insists on adding one of these suffixes, and it will not load from a file whose name is just FILENAME with no added suffix.  (The variable load-suffixes specifies the exact required suffixes.)

     The argument DOCSTRING is the documentation string for the function.  Specifying the documentation string in the call to autoload makes it possible to look at the documentation without loading the function's real definition.  Normally, this should be identical to the documentation string in the function definition itself.  If it isn't, the function definition's documentation string takes effect when it is loaded.

     If INTERACTIVE is non-nil, that says FUNCTION can be called interactively.  This lets completion in M-x work without loading FUNCTION's real definition.  The complete interactive specification is not given here; it's not needed unless the user actually calls FUNCTION, and when that happens, it's time to load the real definition.

     You can autoload macros and keymaps as well as ordinary functions. Specify TYPE as macro if FUNCTION is really a macro. Specify TYPE as keymap if FUNCTION is really a keymap.  Various parts of Emacs need to know this information without loading the real definition.

     An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol FUNCTION.  Autoloading does not occur for other kinds of access to the keymap.  In particular, it does not happen when a Lisp program gets the keymap from the value of a variable and calls define-key; not even if the variable name is the same symbol FUNCTION.

     If FUNCTION already has a non-void function definition that is not an autoload object, autoload does nothing and returns nil. If the function cell of FUNCTION is void, or is already an autoload object, then it is defined as an autoload object like this:

          (autoload FILENAME DOCSTRING INTERACTIVE TYPE)

     For example,

          (symbol-function 'run-prolog)
               => (autoload "prolog" 169681 t nil)

     In this case, "prolog" is the name of the file to load, 169681 refers to the documentation string in the emacs/etc/DOC-VERSION file (see Documentation Basics), t means the function is interactive, and nil that it is not a macro or a keymap.

The autoloaded file usually contains other definitions and may require or provide one or more features.  If the file is not completely loaded (due to an error in the evaluation of its contents), any function definitions or provide calls that occurred during the load are undone.  This is to ensure that the next attempt to call any function autoloading from this file will try again to load the file.  If not for this, then some of the functions in the file might be defined by the aborted load, but fail to work properly for the lack of certain subroutines not loaded successfully because they come later in the file.

If the autoloaded file fails to define the desired Lisp function or macro, then an error is signaled with data "Autoloading failed to define function FUNCTION-NAME".

A magic autoload comment (often called an autoload cookie) consists of ;;;###autoload, on a line by itself, just before the real definition of the function in its autoloadable source file.  The command M-x update-file-autoloads writes a corresponding autoload call into loaddefs.el. (The string that serves as the autoload cookie and the name of the file generated by update-file-autoloads can be changed from the above defaults, see below.) Building Emacs loads loaddefs.el and thus calls autoload. M-x update-directory-autoloads is even more powerful; it updates autoloads for all files in the current directory.

The same magic comment can copy any kind of form into loaddefs.el.  If the form following the magic comment is not a function-defining form or a defcustom form, it is copied verbatim.  ``Function-defining forms'' include define-skeleton, define-derived-mode, define-generic-mode and define-minor-mode as well as defun and defmacro.  To save space, a defcustom form is converted to a defvar in loaddefs.el, with some additional information if it uses :require.

You can also use a magic comment to execute a form at build time without executing it when the file itself is loaded.  To do this, write the form on the same line as the magic comment.  Since it is in a comment, it does nothing when you load the source file; but M-x update-file-autoloads copies it to loaddefs.el, where it is executed while building Emacs.

The following example shows how doctor is prepared for autoloading with a magic comment:

     ;;;###autoload
     (defun doctor ()
       "Switch to *doctor* buffer and start giving psychotherapy."
       (interactive)
       (switch-to-buffer "*doctor*")
       (doctor-mode))

Here's what that produces in loaddefs.el:

     (autoload (quote doctor) "doctor" "\
     Switch to *doctor* buffer and start giving psychotherapy.

     \(fn)" t nil)

The backslash and newline immediately following the double-quote are a convention used only in the preloaded uncompiled Lisp files such as loaddefs.el; they tell make-docfile to put the documentation string in the etc/DOC file.  See Building Emacs. See also the commentary in lib-src/make-docfile.c.  (fn) in the usage part of the documentation string is replaced with the function's name when the various help functions (see Help Functions) display it.

If you write a function definition with an unusual macro that is not one of the known and recognized function definition methods, use of an ordinary magic autoload comment would copy the whole definition into loaddefs.el.  That is not desirable.  You can put the desired autoload call into loaddefs.el instead by writing this:

     ;;;###autoload (autoload 'foo "myfile")
     (mydefunmacro foo
       ...)

You can use a non-default string as the autoload cookie and have the corresponding autoload calls written into a file whose name is different from the default loaddefs.el.  Emacs provides two variables to control this:

 -- Variable: generate-autoload-cookie
     The value of this variable should be a string whose syntax is a Lisp comment.  M-x update-file-autoloads copies the Lisp form that follows the cookie into the autoload file it generates.  The default value of this variable is ";;;###autoload".

 -- Variable: generated-autoload-file
     The value of this variable names an Emacs Lisp file where the autoload calls should go.  The default value is loaddefs.el, but you can override that, e.g., in the ``Local Variables'' section of a .el file (see File Local Variables).  The autoload file is assumed to contain a trailer starting with a formfeed character.

Repeated Loading
================

You can load a given file more than once in an Emacs session.  For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from.

When you load or reload files, bear in mind that the load and load-library functions automatically load a byte-compiled file rather than a non-compiled file of similar name.  If you rewrite a file that you intend to save and reinstall, you need to byte-compile the new version; otherwise Emacs will load the older, byte-compiled file instead of your newer, non-compiled file!  If that happens, the message displayed when loading the file includes, (compiled; note, source is newer), to remind you to recompile it.

When writing the forms in a Lisp library file, keep in mind that the file might be loaded more than once.  For example, think about whether each variable should be reinitialized when you reload the library; defvar does not change the value if the variable is already initialized.  (see Defining Variables.)

The simplest way to add an element to an alist is like this:

     (push '(leif-mode " Leif") minor-mode-alist)

But this would add multiple elements if the library is reloaded.  To avoid the problem, use add-to-list (see List Variables):

     (add-to-list 'minor-mode-alist '(leif-mode " Leif"))

Occasionally you will want to test explicitly whether a library has already been loaded.  If the library uses provide to provide a named feature, you can use featurep earlier in the file to test whether the provide call has been executed before (see Named Features).  Alternatively, you could use something like this:

     (defvar foo-was-loaded nil)

     (unless foo-was-loaded
       EXECUTE-FIRST-TIME-ONLY
       (setq foo-was-loaded t))

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

 -- 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 if not already in FEATURES then to add FEATURE to the front of 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 Network Feature Testing, 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.

 -- 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 .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, Required feature FEATURE was not provided.

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

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

Which File Defined a Certain Symbol
===================================

 -- Function: symbol-file symbol &optional type
     This function returns the name of the file that defined SYMBOL. If TYPE is nil, then any kind of definition is acceptable. If TYPE is defun, defvar, or defface, that specifies function definition, variable definition, or face definition only.

     The value is normally an absolute file name.  It can also be nil, if the definition is not associated with any file.  If SYMBOL specifies an autoloaded function, the value can be a relative file name without extension.

The basis for symbol-file is the data in the variable load-history.

 -- Variable: load-history
     This variable's value is an alist connecting library file 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 absolute file name of the library, as a string.  The rest of the list elements have these forms:

     VAR
          The symbol VAR was defined as a variable.

     (defun . FUN)
          The function FUN was defined.

     (t . FUN)
          The function FUN was previously an autoload before this library redefined it as a function.  The following element is always (defun . FUN), which represents defining FUN as a function.

     (autoload . FUN)
          The function FUN was defined as an autoload.

     (defface . FACE)
          The face FACE was defined.

     (require . FEATURE)
          The feature FEATURE was required.

     (provide . FEATURE)
          The feature FEATURE was 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 Eval.

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 unload-feature-special-hooks, as well as auto-mode-alist.  This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined.

     Standard unloading activities also undoes ELP profiling of functions in that library, unprovides any features provided by the library, and cancels timers held in variables defined by the library.

     If these measures are not sufficient to prevent malfunction, a library can define an explicit unloader named FEATURE-unload-function. If that symbol is defined as a function, unload-feature calls it with no arguments before doing anything else.  It can do whatever is appropriate to unload the library.  If it returns nil, unload-feature proceeds to take the normal unload actions. Otherwise it considers the job to be done.

     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: unload-feature-special-hooks
     This variable holds a list of hooks to be scanned before unloading a library, to remove functions defined in the library.

Hooks for Loading
=================

You can ask for code to be executed if and when a particular library is loaded, by calling eval-after-load.

 -- Function: eval-after-load library form
     This function arranges to evaluate FORM at the end of loading the file LIBRARY, each time LIBRARY is loaded.  If LIBRARY is already loaded, it evaluates FORM right away. Don't forget to quote FORM!

     You don't need to give a directory or extension in the file name LIBRARY---normally you just give a bare file name, like this:

          (eval-after-load "edebug" '(def-edebug-spec c-point t))

     To restrict which files can trigger the evaluation, include a directory or an extension or both in LIBRARY.  Only a file whose absolute true name (i.e., the name with all symbolic links chased out) matches all the given name components will match.  In the following example, my_inst.elc or my_inst.elc.gz in some directory ..../foo/bar will trigger the evaluation, but not my_inst.el:

          (eval-after-load "foo/bar/my_inst.elc" ...)

     LIBRARY can also be a feature (i.e. a symbol), in which case FORM is evaluated when (provide LIBRARY) is called.

     An error in FORM does not undo the load, but does prevent execution of the rest of FORM.

In general, well-designed Lisp programs should not use this feature. The clean and modular ways to interact with a Lisp library are (1) examine and set the library's variables (those which are meant for outside use), and (2) call the library's functions.  If you wish to do (1), you can do it immediately---there is no need to wait for when the library is loaded.  To do (2), you must load the library (preferably with require).

But it is OK to use eval-after-load in your personal customizations if you don't feel they must meet the design standards for programs meant for wider use.

 -- Variable: after-load-alist
     This variable, an alist built by eval-after-load, holds the expressions to evaluate when particular libraries are loaded.  Each element looks like this:

          (REGEXP-OR-FEATURE FORMS...)

     The key REGEXP-OR-FEATURE is either a regular expression or a symbol, and the value is a list of forms.  The forms are evaluated when the key matches the absolute true name of the file being loaded or the symbol being provided.