15.2 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/paths.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 section 40.1.2 The Init File, `.emacs') 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.