From dde9d149af3281f7ed3d3b9d8a4fd7caa238d0f9 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 26 Feb 2023 19:51:59 +0200 Subject: [PATCH] ; Improve documentation of loading *.eln files * doc/lispref/loading.texi (How Programs Do Loading): * doc/emacs/building.texi (Lisp Libraries): Some additional details about what happens with natively-compiled files. --- doc/emacs/building.texi | 37 +++++++++++++++++++++++++------------ doc/lispref/loading.texi | 25 ++++++++++++++----------- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 3f6a418de1a..f82b605598e 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1556,18 +1556,26 @@ command prompts for a @dfn{library name} rather than a file name; it searches through each directory in the Emacs Lisp load path, trying to find a file matching that library name. If the library name is @samp{@var{foo}}, it tries looking for files named -@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The -default behavior is to load the first file found. This command -prefers @file{.elc} files over @file{.el} files because compiled files -load and run faster. If it finds that @file{@var{lib}.el} is newer -than @file{@var{lib}.elc}, it issues a warning, in case someone made -changes to the @file{.el} file and forgot to recompile it, but loads -the @file{.elc} file anyway. (Due to this behavior, you can save -unfinished edits to Emacs Lisp source files, and not recompile until -your changes are ready for use.) If you set the option -@code{load-prefer-newer} to a non-@code{nil} value, however, then -rather than the procedure described above, Emacs loads whichever -version of the file is newest. +@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. (If +Emacs was built with native compilation enabled, @code{load-library} +looks for a @samp{.eln} file that corresponds to @file{@var{foo}.el} +and loads it instead of @file{@var{foo}.elc}.) The default behavior +is to load the first file found. This command prefers @file{.eln} +files over @file{.elc} files, and prefers @file{.elc} files over +@file{.el} files, because compiled files load and run faster. If it +finds that @file{@var{lib}.el} is newer than @file{@var{lib}.elc}, it +issues a warning, in case someone made changes to the @file{.el} file +and forgot to recompile it, but loads the @file{.elc} file anyway. +(Due to this behavior, you can save unfinished edits to Emacs Lisp +source files, and not recompile until your changes are ready for use.) +If you set the option @code{load-prefer-newer} to a non-@code{nil} +value, however, then rather than the procedure described above, Emacs +loads whichever version of the file is newest. If Emacs was built +with native compilation, and it cannot find the @samp{.eln} file +corresponding to @file{@var{lib}.el}, it will load a +@file{@var{lib}.elc} and start native compilation of +@file{@var{lib}.el} in the background, then load the @samp{.eln} file +when it finishes compilation. Emacs Lisp programs usually load Emacs Lisp files using the @code{load} function. This is similar to @code{load-library}, but is @@ -1604,6 +1612,11 @@ It is customary to put locally installed libraries in the @code{load-path}, or in some subdirectory of @file{site-lisp}. This way, you don't need to modify the default value of @code{load-path}. +@vindex native-comp-eln-load-path + Similarly to @code{load-path}, the list of directories where Emacs +looks for @file{*.eln} files with natively-compiled Lisp code is +specified by the variable @code{native-comp-eln-load-path}. + @cindex autoload Some commands are @dfn{autoloaded}; when you run them, Emacs automatically loads the associated library first. For instance, the diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index dbbdc767738..5c84ba4b1eb 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -75,17 +75,20 @@ file exists, and Emacs was compiled with native-compilation support (@pxref{Native Compilation}), @code{load} attempts to find a corresponding @samp{.eln} file, and if found, loads it instead of @file{@var{filename}.elc}. Otherwise, it loads -@file{@var{filename}.elc}. If there is no file by that name, then -@code{load} looks for a file named @file{@var{filename}.el}. If that -file exists, it is loaded. If Emacs was compiled with support for -dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for -a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a -system-dependent file-name extension of shared libraries. Finally, if -neither of those names is found, @code{load} looks for a file named -@var{filename} with nothing appended, and loads it if it exists. (The -@code{load} function is not clever about looking at @var{filename}. -In the perverse case of a file named @file{foo.el.el}, evaluation of -@code{(load "foo.el")} will indeed find it.) +@file{@var{filename}.elc} (and starts a background native compilation +to produce the missing @samp{.eln} file, followed by loading that +file). If there is no @file{@var{filename}.elc}, then @code{load} +looks for a file named @file{@var{filename}.el}. If that file exists, +it is loaded. If Emacs was compiled with support for dynamic modules +(@pxref{Dynamic Modules}), @code{load} next looks for a file named +@file{@var{filename}.@var{ext}}, where @var{ext} is a system-dependent +file-name extension of shared libraries (@samp{.so} on GNU and Unix +systems). Finally, if neither of those names is found, @code{load} +looks for a file named @var{filename} with nothing appended, and loads +it if it exists. (The @code{load} function is not clever about +looking at @var{filename}. In the perverse case of a file named +@file{foo.el.el}, evaluation of @code{(load "foo.el")} will indeed +find it.) If Auto Compression mode is enabled, as it is by default, then if @code{load} can not find a file, it searches for a compressed version -- 2.39.5