Next: Loading Non-ASCII, Previous: How Programs Do Loading, Up: Loading
When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable 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) ornil
(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 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.)
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 inload
: 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 ofload-path
.When
locate-library
is called from a program, it returns the file name as a string. When the user runslocate-library
interactively, the argument interactive-call ist
, and this tellslocate-library
to display the file name in the echo area.