path: root/devdocs/elisp/how-programs-do-loading.html

 <h3 class="section">How Programs Do Loading</h3> <p>Emacs Lisp has several interfaces for loading. For example, <code>autoload</code> creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function’s real definition (see <a href="autoload">Autoload</a>). <code>require</code> loads a file if it isn’t already loaded (see <a href="named-features">Named Features</a>). Ultimately, all these facilities call the <code>load</code> function to do the work. </p> <dl> <dt id="load">Function: <strong>load</strong> <em>filename &amp;optional missing-ok nomessage nosuffix must-suffix</em>
</dt> <dd>
<p>This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file. </p> <p>To find the file, <code>load</code> first looks for a file named <samp><var>filename</var>.elc</samp>, that is, for a file whose name is <var>filename</var> with the extension ‘<samp>.elc</samp>’ appended. If such a file exists, and Emacs was compiled with native-compilation support (see <a href="native-compilation">Native Compilation</a>), <code>load</code> attempts to find a corresponding ‘<samp>.eln</samp>’ file, and if found, loads it instead of <samp><var>filename</var>.elc</samp>. Otherwise, it loads <samp><var>filename</var>.elc</samp>. If there is no file by that name, then <code>load</code> looks for a file named <samp><var>filename</var>.el</samp>. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (see <a href="dynamic-modules">Dynamic Modules</a>), <code>load</code> next looks for a file named <samp><var>filename</var>.<var>ext</var></samp>, where <var>ext</var> is a system-dependent file-name extension of shared libraries. Finally, if neither of those names is found, <code>load</code> looks for a file named <var>filename</var> with nothing appended, and loads it if it exists. (The <code>load</code> function is not clever about looking at <var>filename</var>. In the perverse case of a file named <samp>foo.el.el</samp>, evaluation of <code>(load "foo.el")</code> will indeed find it.) </p> <p>If Auto Compression mode is enabled, as it is by default, then if <code>load</code> can not find a file, it searches for a compressed version of the file before trying other file names. It decompresses and loads it if it exists. It looks for compressed versions by appending each of the suffixes in <code>jka-compr-load-suffixes</code> to the file name. The value of this variable must be a list of strings. Its standard value is <code>(".gz")</code>. </p> <p>If the optional argument <var>nosuffix</var> is non-<code>nil</code>, then <code>load</code> does not try the suffixes ‘<samp>.elc</samp>’ and ‘<samp>.el</samp>’. In this case, you must specify the precise file name you want, except that, if Auto Compression mode is enabled, <code>load</code> will still use <code>jka-compr-load-suffixes</code> to find compressed versions. By specifying the precise file name and using <code>t</code> for <var>nosuffix</var>, you can prevent file names like <samp>foo.el.el</samp> from being tried. </p> <p>If the optional argument <var>must-suffix</var> is non-<code>nil</code>, then <code>load</code> insists that the file name used must end in either ‘<samp>.el</samp>’ or ‘<samp>.elc</samp>’ (possibly extended with a compression suffix) or the shared-library extension, unless it contains an explicit directory name. </p> <p>If the option <code>load-prefer-newer</code> is non-<code>nil</code>, then when searching suffixes, <code>load</code> selects whichever version of a file (‘<samp>.elc</samp>’, ‘<samp>.el</samp>’, etc.) has been modified most recently. In this case, <code>load</code> doesn’t load the ‘<samp>.eln</samp>’ natively-compiled file even if it exists. </p> <p>If <var>filename</var> is a relative file name, such as <samp>foo</samp> or <samp>baz/foo.bar</samp>, <code>load</code> searches for the file using the variable <code>load-path</code>. It appends <var>filename</var> to each of the directories listed in <code>load-path</code>, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in <code>load-path</code>, where <code>nil</code> stands for the default directory. <code>load</code> tries all three possible suffixes in the first directory in <code>load-path</code>, then all three suffixes in the second directory, and so on. See <a href="library-search">Library Search</a>. </p> <p>Whatever the name under which the file is eventually found, and the directory where Emacs found it, Emacs sets the value of the variable <code>load-file-name</code> to that file’s name. </p> <p>If you get a warning that <samp>foo.elc</samp> is older than <samp>foo.el</samp>, it means you should consider recompiling <samp>foo.el</samp>. See <a href="byte-compilation">Byte Compilation</a>. </p> <p>When loading a source file (not compiled), <code>load</code> performs character set translation just as Emacs would do when visiting the file. See <a href="coding-systems">Coding Systems</a>. </p>  <p>When loading an uncompiled file, Emacs tries to expand any macros that the file contains (see <a href="macros">Macros</a>). We refer to this as <em>eager macro expansion</em>. Doing this (rather than deferring the expansion until the relevant code runs) can significantly speed up the execution of uncompiled code. Sometimes, this macro expansion cannot be done, owing to a cyclic dependency. In the simplest example of this, the file you are loading refers to a macro defined in another file, and that file in turn requires the file you are loading. This is generally harmless. Emacs prints a warning (‘<samp>Eager macro-expansion skipped due to cycle…</samp>’) giving details of the problem, but it still loads the file, just leaving the macro unexpanded for now. You may wish to restructure your code so that this does not happen. Loading a compiled file does not cause macroexpansion, because this should already have happened during compilation. See <a href="compiling-macros">Compiling Macros</a>. </p> <p>Messages like ‘<samp>Loading foo...</samp>’ and ‘<samp>Loading foo...done</samp>’ appear in the echo area during loading unless <var>nomessage</var> is non-<code>nil</code>. If a natively-compiled ‘<samp>.eln</samp>’ file is loaded, the message says so. </p>  <p>Any unhandled errors while loading a file terminate loading. If the load was done for the sake of <code>autoload</code>, any function definitions made during the loading are undone. </p>  <p>If <code>load</code> can’t find the file to load, then normally it signals a <code>file-error</code> (with ‘<samp>Cannot open load file <var>filename</var></samp>’). But if <var>missing-ok</var> is non-<code>nil</code>, then <code>load</code> just returns <code>nil</code>. </p> <p>You can use the variable <code>load-read-function</code> to specify a function for <code>load</code> to use instead of <code>read</code> for reading expressions. See below. </p> <p><code>load</code> returns <code>t</code> if the file loads successfully. </p>
</dd>
</dl> <dl> <dt id="load-file">Command: <strong>load-file</strong> <em>filename</em>
</dt> <dd><p>This command loads the file <var>filename</var>. If <var>filename</var> is a relative file name, then the current default directory is assumed. This command does not use <code>load-path</code>, and does not append suffixes. However, it does look for compressed versions (if Auto Compression Mode is enabled). Use this command if you wish to specify precisely the file name to load. </p></dd>
</dl> <dl> <dt id="load-library">Command: <strong>load-library</strong> <em>library</em>
</dt> <dd><p>This command loads the library named <var>library</var>. It is equivalent to <code>load</code>, except for the way it reads its argument interactively. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html#Lisp-Libraries">Lisp Libraries</a> in <cite>The GNU Emacs Manual</cite>. </p></dd>
</dl> <dl> <dt id="load-in-progress">Variable: <strong>load-in-progress</strong>
</dt> <dd><p>This variable is non-<code>nil</code> if Emacs is in the process of loading a file, and it is <code>nil</code> otherwise. </p></dd>
</dl> <dl> <dt id="load-file-name">Variable: <strong>load-file-name</strong>
</dt> <dd><p>When Emacs is in the process of loading a file, this variable’s value is the name of that file, as Emacs found it during the search described earlier in this section. </p></dd>
</dl> <dl> <dt id="load-read-function">Variable: <strong>load-read-function</strong>
</dt> <dd>
<p>This variable specifies an alternate expression-reading function for <code>load</code> and <code>eval-region</code> to use instead of <code>read</code>. The function should accept one argument, just as <code>read</code> does. </p> <p>By default, this variable’s value is <code>read</code>. See <a href="input-functions">Input Functions</a>. </p> <p>Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the <var>read-function</var> argument to <code>eval-region</code>. See <a href="eval#Definition-of-eval_002dregion">Eval</a>. </p>
</dd>
</dl> <p>For information about how <code>load</code> is used in building Emacs, see <a href="building-emacs">Building Emacs</a>. </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/How-Programs-Do-Loading.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/How-Programs-Do-Loading.html</a>
  </p>
</div>