GNU Info

(elisp)Library Search

---

Next: Loading Non-ASCII Prev: How Programs Do Loading Up: Loading

---

Enter node , (file) or (file)node

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