@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Loading
@samp{.el} or @samp{.elc} (possibly extended with a compression
suffix), unless it contains an explicit directory name.
+If the option @code{load-prefer-newer} is non-@code{nil}, then when
+searching suffixes, @code{load} selects whichever version of a file
+(@samp{.elc}, @samp{.el}, etc.) has been modified most recently.
+
If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}. It appends @var{filename} to each of the directories
it skips the former group, and if @var{must-suffix} is non-@code{nil},
it skips the latter group.
+@defopt load-prefer-newer
+If this option is non-@code{nil}, then rather than stopping at the
+first suffix that exists, @code{load} tests them all, and uses
+whichever file is the newest.
+@end defopt
+
@node Library Search
@section Library Search
@cindex library search
"/usr/local/share/emacs/@var{version}/lisp"
@end example
-followed by a similarly named @file{leim} directory.
(In this and the following examples, replace @file{/usr/local} with
the installation prefix appropriate for your Emacs.)
These directories contain the standard Lisp files that come with
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---Emacs instead
-initializes @code{load-path} using the @file{lisp} and @file{leim}
-directories in the directory containing the sources from which it
-was built. If you built Emacs in a separate directory from the
-sources, it also adds those directories from the build directory.
+initializes @code{load-path} using the @file{lisp}
+directory in the directory containing the sources from which it
+was built.
+@c Though there should be no *.el files in builddir/lisp, so it's pointless.
+If you built Emacs in a separate directory from the
+sources, it also adds the lisp directories from the build directory.
(In all cases, elements are represented as absolute file names.)
@cindex site-lisp directories
@file{site-lisp} directories.)
@cindex @env{EMACSLOADPATH} environment variable
-If the environment variable @env{EMACSLOADPATH} is set, it overrides
-the above initialization procedure. That is, Emacs initializes
-@code{load-path} based solely on the value of the environment
-variable. You must therefore include the directory containing the
-standard Lisp files, else Emacs will not function. In most
-situations, it is better to use the @option{-L} command-line option
-(see below) to add elements to @code{load-path}.
+If the environment variable @env{EMACSLOADPATH} is set, it modifies
+the above initialization procedure. Emacs initializes
+@code{load-path} based on the value of the environment variable.
The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH};
directory names are separated by @samp{:} (or @samp{;}, on some
-operating systems), and @samp{.} stands for the current default
-directory. Here is an example of how to set @env{EMACSLOADPATH}
-variable (from a @command{sh}-style shell):
+operating systems).
+@ignore
+@c AFAICS, does not (yet) work right to specify non-absolute elements.
+and @samp{.} stands for the current default directory.
+@end ignore
+Here is an example of how to set @env{EMACSLOADPATH} variable (from a
+@command{sh}-style shell):
@example
-export EMACSLOADPATH
-EMACSLOADPATH=/home/foo/.emacs.d/lisp:/usr/local/emacs/24.3/lisp
+export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
@end example
+An empty element in the value of the environment variable, whether
+trailing (as in the above example), leading, or embedded, is replaced
+by the default value of @code{load-path} as determined by the standard
+initialization procedure. If there are no such empty elements, then
+@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must
+include either an empty element, or the explicit path to the directory
+containing the standard Lisp files, else Emacs will not function.
+(Another way to modify @code{load-path} is to use the @option{-L}
+command-line option when starting Emacs; see below.)
+
For each directory in @code{load-path}, Emacs then checks to see if
it contains a file @file{subdirs.el}, and if so, loads it. The
@file{subdirs.el} file is created when Emacs is built/installed,
(push "~/.emacs.d/lisp" load-path)
@end example
- Dumping Emacs uses a special value of @code{load-path}. If the
-value of @code{load-path} at the end of dumping is unchanged (that is,
-still the same special value), the dumped Emacs switches to the
-ordinary @code{load-path} value when it starts up, as described above.
-But if @code{load-path} has any other value at the end of dumping,
-that value is used for execution of the dumped Emacs also.
+ Dumping Emacs uses a special value of @code{load-path}. If you use
+a @file{site-load.el} or @file{site-init.el} file to customize the
+dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path}
+that these files make will be lost after dumping.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters
+@cindex loading, and non-ASCII characters
+@cindex non-ASCII characters in loaded files
When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
characters, these can be represented within Emacs either as unibyte
@node Where Defined
@section Which File Defined a Certain Symbol
+@cindex symbol, where defined
+@cindex where was a symbol defined
@defun symbol-file symbol &optional type
This function returns the name of the file that defined @var{symbol}.