procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Improve documentation of loading *.eln files

Browse source 
* doc/lispref/loading.texi (How Programs Do Loading):
* doc/emacs/building.texi (Lisp Libraries): Some additional
details about what happens with natively-compiled files.
This commit is contained in:
Eli Zaretskii 2023-02-26 19:51:59 +02:00
parent 7c552be89d
commit dde9d149af
2 changed files with 39 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
doc/emacs/building.texi
View file

@ -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

25
doc/lispref/loading.texi
View file

@ -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