From 90794abbf92f3cb206e69f054928847044427220 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Thu, 14 Nov 2013 00:38:50 -0800 Subject: [PATCH] * doc/lispref/loading.texi (Library Search): Update section. --- doc/lispref/ChangeLog | 4 ++ doc/lispref/loading.texi | 96 ++++++++++++++++++++++++---------------- 2 files changed, 62 insertions(+), 38 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 7c4fb4e9c6d..520f87f2f8b 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2013-11-14 Glenn Morris + + * loading.texi (Library Search): Update section. + 2013-11-11 Xue Fuqiao * os.texi (User Identification, Time of Day, Time Conversion): diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index dab8e8d1255..637057c99b0 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -253,37 +253,38 @@ it skips the latter group. in a list of directories specified by the variable @code{load-path}. @defvar load-path -@cindex @env{EMACSLOADPATH} environment variable The value of this variable is a list of directories to search when loading files with @code{load}. Each element is a string (which must be a directory name) or @code{nil} (which stands for the current working directory). @end defvar - Each time Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} to the -directories specified by the environment variable @env{EMACSLOADPATH}, -if that exists. 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 @command{sh}: + When Emacs starts up, it sets up the value of @code{load-path} +in several steps. First, it initializes @code{load-path} using +default locations set when Emacs was compiled. Normally, this +is a directory something like @example -export EMACSLOADPATH -EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp +"/usr/local/share/emacs/@var{version}/lisp" @end example -@noindent -Here is how to set it from @code{csh}: +followed by a similarly named @file{leim} directory. These +directories contain the standard Lisp files that come with Emacs. +If Emacs cannot find them, it will not start correctly. -@example -setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp -@end example +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. +(In all cases, elements are represented as absolute file names.) @cindex site-lisp directories - If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs -initializes @code{load-path} with the following two directories: +Unless you start Emacs with the @option{--no-site-lisp} option, +it then adds two more @file{site-lisp} directories to the front of +@code{load-path}. These are intended for locally installed Lisp files, +and are normally of the form: @example "/usr/local/share/emacs/@var{version}/site-lisp" @@ -297,26 +298,45 @@ and @end example @noindent -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. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs puts two more -directories in @code{load-path}. These are the @code{lisp} and -@code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - - Next, Emacs ``expands'' the initial list of directories in -@code{load-path} by adding the subdirectories of those directories. -Both immediate subdirectories and subdirectories multiple levels down -are added. But it excludes subdirectories whose names do not start -with a letter or digit, and subdirectories named @file{RCS} or -@file{CVS}, and subdirectories containing a file named -@file{.nosearch}. - - Next, Emacs adds any extra load directory that you specify using the -@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The +The first one is for locally installed files for a specific Emacs +version; the second is for locally installed files meant for use +with all installed Emacs versions. (If Emacs is running uninstalled, +it also adds @file{site-lisp} directories from the source and build +directories, if they exist. Normally these directories do not contain +@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}. + +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): + +@example +export EMACSLOADPATH +EMACSLOADPATH=/home/foo/.emacs.d/lisp:/usr/local/emacs/24.3/lisp +@end example + + 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, +and contains code that causes Emacs to add any subdirectories of those +directories to @code{load-path}. Both immediate subdirectories and +subdirectories multiple levels down are added. But it excludes +subdirectories whose names do not start with a letter or digit, and +subdirectories named @file{RCS} or @file{CVS}, and subdirectories +containing a file named @file{.nosearch}. + + Next, Emacs adds any extra load directories that you specify using the +@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The GNU Emacs Manual}). It also adds the directories where optional packages are installed, if any (@pxref{Packaging Basics}). -- 2.39.2