diff options
Diffstat (limited to 'devdocs/elisp/library-search.html')
| -rw-r--r-- | devdocs/elisp/library-search.html | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/devdocs/elisp/library-search.html b/devdocs/elisp/library-search.html new file mode 100644 index 00000000..533ead2a --- /dev/null +++ b/devdocs/elisp/library-search.html @@ -0,0 +1,30 @@ + <h3 class="section">Library Search</h3> <p>When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable <code>load-path</code>. </p> <dl> <dt id="load-path">Variable: <strong>load-path</strong> +</dt> <dd><p>The value of this variable is a list of directories to search when loading files with <code>load</code>. Each element is a string (which must be a directory) or <code>nil</code> (which stands for the current working directory). </p></dd> +</dl> <p>When Emacs starts up, it sets up the value of <code>load-path</code> in several steps. First, it initializes <code>load-path</code> using default locations set when Emacs was compiled. Normally, this is a directory something like </p> <div class="example"> <pre class="example">"/usr/local/share/emacs/<var>version</var>/lisp" +</pre> +</div> <p>(In this and the following examples, replace <samp>/usr/local</samp> with the installation prefix appropriate for your Emacs.) These directories contain the standard Lisp files that come with Emacs. If Emacs cannot find them, it will not start correctly. </p> <p>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</code> using the <samp>lisp</samp> directory 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 the lisp directories from the build directory. (In all cases, elements are represented as absolute file names.) </p> <p>Unless you start Emacs with the <samp>--no-site-lisp</samp> option, it then adds two more <samp>site-lisp</samp> directories to the front of <code>load-path</code>. These are intended for locally installed Lisp files, and are normally of the form: </p> <div class="example"> <pre class="example">"/usr/local/share/emacs/<var>version</var>/site-lisp" +</pre> +</div> <p>and </p> <div class="example"> <pre class="example">"/usr/local/share/emacs/site-lisp" +</pre> +</div> <p>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 <samp>site-lisp</samp> directories from the source and build directories, if they exist. Normally these directories do not contain <samp>site-lisp</samp> directories.) </p> <p>If the environment variable <code>EMACSLOADPATH</code> is set, it modifies the above initialization procedure. Emacs initializes <code>load-path</code> based on the value of the environment variable. </p> <p>The syntax of <code>EMACSLOADPATH</code> is the same as used for <code>PATH</code>; directories are separated by ‘<samp>:</samp>’ (or ‘<samp>;</samp>’, on some operating systems). Here is an example of how to set <code>EMACSLOADPATH</code> variable (from a <code>sh</code>-style shell): </p> <div class="example"> <pre class="example">export EMACSLOADPATH=/home/foo/.emacs.d/lisp: +</pre> +</div> <p>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</code> as determined by the standard initialization procedure. If there are no such empty elements, then <code>EMACSLOADPATH</code> specifies the entire <code>load-path</code>. 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</code> is to use the <samp>-L</samp> command-line option when starting Emacs; see below.) </p> <p>For each directory in <code>load-path</code>, Emacs then checks to see if it contains a file <samp>subdirs.el</samp>, and if so, loads it. The <samp>subdirs.el</samp> 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</code>. 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 <samp>RCS</samp> or <samp>CVS</samp>, and subdirectories containing a file named <samp>.nosearch</samp>. </p> <p>Next, Emacs adds any extra load directories that you specify using the <samp>-L</samp> command-line option (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Action-Arguments.html#Action-Arguments">Action Arguments</a> in <cite>The GNU Emacs Manual</cite>). It also adds the directories where optional packages are installed, if any (see <a href="packaging-basics">Packaging Basics</a>). </p> <p>It is common to add code to one’s init file (see <a href="init-file">Init File</a>) to add one or more directories to <code>load-path</code>. For example: </p> <div class="example"> <pre class="example">(push "~/.emacs.d/lisp" load-path) +</pre> +</div> <p>Dumping Emacs uses a special value of <code>load-path</code>. If you use a <samp>site-load.el</samp> or <samp>site-init.el</samp> file to customize the dumped Emacs (see <a href="building-emacs">Building Emacs</a>), any changes to <code>load-path</code> that these files make will be lost after dumping. </p> <dl> <dt id="locate-library">Command: <strong>locate-library</strong> <em>library &optional nosuffix path interactive-call</em> +</dt> <dd> +<p>This command finds the precise file name for library <var>library</var>. It searches for the library in the same way <code>load</code> does, and the argument <var>nosuffix</var> has the same meaning as in <code>load</code>: don’t add suffixes ‘<samp>.elc</samp>’ or ‘<samp>.el</samp>’ to the specified name <var>library</var>. </p> <p>If the <var>path</var> is non-<code>nil</code>, that list of directories is used instead of <code>load-path</code>. </p> <p>When <code>locate-library</code> is called from a program, it returns the file name as a string. When the user runs <code>locate-library</code> interactively, the argument <var>interactive-call</var> is <code>t</code>, and this tells <code>locate-library</code> to display the file name in the echo area. </p> +</dd> +</dl> <dl> <dt id="list-load-path-shadows">Command: <strong>list-load-path-shadows</strong> <em>&optional stringp</em> +</dt> <dd> +<p>This command shows a list of <em>shadowed</em> Emacs Lisp files. A shadowed file is one that will not normally be loaded, despite being in a directory on <code>load-path</code>, due to the existence of another similarly-named file in a directory earlier on <code>load-path</code>. </p> <p>For instance, suppose <code>load-path</code> is set to </p> <div class="example"> <pre class="example"> ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") +</pre> +</div> <p>and that both these directories contain a file named <samp>foo.el</samp>. Then <code>(require 'foo)</code> never loads the file in the second directory. Such a situation might indicate a problem in the way Emacs was installed. </p> <p>When called from Lisp, this function prints a message listing the shadowed files, instead of displaying them in a buffer. If the optional argument <code>stringp</code> is non-<code>nil</code>, it instead returns the shadowed files as a string. </p> +</dd> +</dl> <p>If Emacs was compiled with support for native compilation (see <a href="native-compilation">Native Compilation</a>), then when a ‘<samp>.elc</samp>’ byte-compiled file is found by searching <code>load-path</code>, Emacs will try to look for a corresponding ‘<samp>.eln</samp>’ file holding the corresponding natively-compiled code. The natively-compiled files are looked up in the directories listed by the <code>native-comp-eln-load-path</code>. </p> <dl> <dt id="native-comp-eln-load-path">Variable: <strong>native-comp-eln-load-path</strong> +</dt> <dd><p>This variable holds a list of directories where Emacs looks for natively-compiled ‘<samp>.eln</samp>’ files. File names in the list that are not absolute are interpreted as relative to <code>invocation-directory</code> (see <a href="system-environment">System Environment</a>). The last directory in the list is the system directory, i.e. the directory with ‘<samp>.eln</samp>’ files installed by the Emacs build and installation procedure. In each of the directories in the list, Emacs looks for ‘<samp>.eln</samp>’ files in a subdirectory whose name is constructed from the Emacs version and an 8-character hash that depends on the current native-compilation <acronym>ABI</acronym>; the name of this subdirectory is stored in the variable <code>comp-native-version-dir</code>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Library-Search.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Library-Search.html</a> + </p> +</div> |